The last two Simple Tricks posts looked at subclasses of built-in Python classes, in particular the tuple class, as well as the built-in class methods Python supports for any user-defined class. [See Simple Tricks #10 and Simple Tricks #11.]

This time I narrow the focus to real and virtual object attributes, the “x”, “y”, “z” elements of our vector objects. Python offers many ways to implement these, depending (as always) on what you want.

To simplify the discussion, a vector instance here always has three, and only three, elements, the canonical “x”, “y”, and “z”. In other words, we’re dealing with 3D vectors.

As before, we’ll subclass the tuple object so vectors will be immutable and inherit the indexing and length behaviors of sequence types. But I’ll start with a simpler user-defined class that implements the three vector elements explicitly:

The vector0 class (lines #3 to #12) defines self.x, self.y, and self.z instance attributes, and provides default values. There is also a fmt (format) parameter that controls the string returned by the __repr__ method (lines #10 to #12).

(Remember, you should always define __repr__ and/or __str__.)

The rest of the code creates and exercises a new instance. I used try-except blocks to isolate code expected to raise an exception. Lines #14 to #19 create and print the new vector object. Lines #21 to #25 attempt to print an attribute that doesn’t exist. Lines #27 to #30 (successfully) assign a new value to the x element. Lines #32 to #35 create and print a new attribute. Finally, lines #37 to #42 attempts to delete a defined attribute (which succeeds) and then print it.

When run, this prints:

v = [2.718, 3.142, 6.626]
v.x = 2.71828
v.y = 3.14159
v.z = 6.62607

'vector0' object has no attribute 'w'

v = [42.000, 3.142, 6.626]
v.x = 42

v = [42.000, 3.142, 6.626]
v.a = 21

'vector0' object has no attribute 'z'

As expected, trying to access an attribute that doesn’t exist correctly raises an exception. Given the class design, we’d expect assigning a new value to x to work (but recall that we want our vectors to be immutable, so this is not correct behavior). We’re also free to assign new attributes to given instances. That’s the usual default behavior, but — as you’ll see below — we can interdict it if we want. Finally, because we deleted the z element, accessing it raises the same error as with any non-existent attribute.

We can do better, but first I want to move all that vector exercise code — which is the bulk of the code above — into its own function. I want to add a bit more to the exercise, so all the more reason to make it a function. It would otherwise add a lot of code to the examples below.

Here’s our vector exercise function:

The comments should make it self-explanatory. We’ll try to access an element that doesn’t exist, we’ll try two ways of changing an element’s value, and we’ll try both adding new and deleting existing elements.

The problem with our vector0 class was that the attributes were directly accessible. Normally, a class design should hide the data attributes and control access. Here’s a different implementation of vector0 that does that. Most importantly, it introduces the built-in methods used for customized attribute access:

The vector1.__init__ method is similar to the one for vector0, but here the instance attributes have a leading underscore. This is the conventional way of saying an attribute or method is private to the class. Note that some designers believe Python classes should (almost) always take this approach, but (as always) it depends.

What matters here are the four built-in methods for access to instance properties:

Python always calls the __getattribute__ method (lines #10 to #14) to get the value of a property or method. The return value is the (possibly computed) value of the property or a reference to the method. If this method fails, it should raise AttributeError — which is expected when a property or method does not exist. Most user classes won’t need to implement __getattribute__. It’s included here for completeness and just passes control to the parent (line #14).

Python calls the __getattr__ method (lines #16 to #24) if __getattribute__ raises AttributeError. Generally speaking, in alignment with the next two methods, this is the method usually implemented for virtual properties. We use the value of name to return one of the three vector elements (lines #20 to #22). Any other name we pass to the parent (line #24).

Python calls the __setattr__ method (lines #26 to #33) to set a property value. This includes creating them (which always involves setting them). We want to prevent modifying vector elements, but allow setting others, so we check the name and raise NotImplemented if it’s an element name (lines #30 and #31). Otherwise, we pass the name and value to the parent (line #33).

Python calls the __delattr__ method (lines #35 to #42) when deleting a property. The treatment here is nearly identical to that for __setattr__.

Each of these four methods has a print statement to document when Python calls them. When run, this prints (line numbers added for reference):

01|setattr(_x, 2.71828)
02|setattr(_y, 3.14159)
03|setattr(_z, 6.62607)
04|setattr(_fmt, .3f)
05|
06|getattribute(_fmt)
07|getattribute(x)
08|getattr(x)
09|getattribute(_x)
10|getattribute(y)
11|getattr(y)
12|getattribute(_y)
13|getattribute(z)
14|getattr(z)
15|getattribute(_z)
16|v = [2.718, 3.142, 6.626]
17|
18|getattribute(x)
19|getattr(x)
20|getattribute(_x)
21|v.x = 2.71828
22|getattribute(y)
23|getattr(y)
24|getattribute(_y)
25|v.y = 3.14159
26|getattribute(z)
27|getattr(z)
28|getattribute(_z)
29|v.z = 6.62607
30|
31|getattribute(w)
32|getattr(w)
33|'super' object has no attribute '__getattr__'
34|
35|setattr(x, 42)
36|Attributes are read-only.
37|
38|setattr(a, 21)
39|getattribute(a)
40|v.a = 21
41|
42|delattr(z)
43|Attributes are read-only.
44|
45|'vector1' object does not support item assignment
46|
47|'vector1' object doesn't support item deletion

The first four lines come from creating the four properties in the __init__ method. The first thing the exercise_vector function does is print the vector, which invokes its __repr__ method (code lines #44 to #46), which reads all four of the vector properties in preparing a return string. In the output (lines #6 to #15), note how the _fmt property exists, so __getattribute__ returns it. But no x or y or z property actually exists, so __getattribute__ fails, which makes Python call __getattr__. Each call to __getattr__ causes a call to __getattribute__ to get the corresponding _x or _y or _z property. Finally, we get and print the result string (line #16). It’s a bit twisty but stick with it.

Next, exercise_vector prints the individual properties (lines #18 to #29). These work the same as discussed above.

When exercise_vector tries to access a property that does exist, __getattr__ fails. Note that we let Python raise the exception in this case (line #33). The code also fails trying to modify the value of a vector element (lines #35 and #36), but __setattr__ raises the exception. Likewise, __delattr__ raises an exception when the exercise function tries to delete an element (lines #42 and #43).

The test adds a new property without issue (lines #38 to #40). The last two tests expect a sequence object, and Python raises an exception because vector1 objects don’t support any sequence methods.

This example, with its print statements, is intended for exploring how these methods work.

Speaking of sequence objects, before we subclass the immutable tuple, let’s create a vector class that subclasses list:

This class is similar to vector1 except that it uses the underlying list to store the elements rather than named instance properties. The ElementNames class variable (line #4) is another change. It’s a list of virtual property names. The attribute methods use this to determine whether name refers to a property. This avoids having to repeat the names in each method.

The __init__ method still takes explicit x, y, and z parameters but combines them into a list to initialize the parent list object with those values. The only property now is the self._fmt property used by the __repr__ method.

The instrumentation print statements from vector1 have all been removed for clearer output. When run, this prints:

v = [2.718, 3.142, 6.626]

v.x = 2.71828
v.y = 3.14159
v.z = 6.62607

'super' object has no attribute '__getattr__'

Attributes are read-only.

v.a = 21

Attributes are read-only.

v.x = 42

list index out of range

The first thing to notice is that our attempt to call the parent.__getattr__ method fails. The list class doesn’t define this method, so we should remove line #21 and replace it with a line that raises an exception:

The second thing is that we can see that our virtual attributes are protected, they can’t be modified or deleted, but any properties the user adds work as expected.

However, the third thing is our vector can be modified through the mutable list. We could override the built-in __getitem__ and __setitem__ and __delitem__ methods (see last example below), but it’s easier to use the immutable tuple class (creating our own sequence class is a post for another time).

Here, finally, is a vector implementation that subclasses tuple:

Because tuples are immutable, we must implement the __new__ method (lines #6 to #10). See previous post for details. We should validate for numeric values, but I left that out for brevity. The rest is essentially identical to vector2.

The key difference shows up when we run it:

v = [2.718, 3.142, 6.626]

v.x = 2.71828
v.y = 3.14159
v.z = 6.62607

No such Attribute "w".

Attributes are read-only.

v.a = 21

Attributes are read-only.

'vector3' object does not support item assignment

'vector3' object doesn't support item deletion

It’s no longer possible to modify elements using the underlying object.

We now have a useful vector class that solves key issues from the version in the previous post. But we can do even better. Or perhaps at least be more Pythonish.

The first improvement is that we can use Python’s @property decorator:

Using the @property decorator (lines #13, #16, and #19) makes the x, y, and z methods act like data properties rather than callable methods. When used as shown above, the properties only have a get method, so are read-only. Note that each method returns the appropriate sequence member.

When run, this prints:

v = [2.718, 3.142, 6.626]

v.x = 2.71828
v.y = 3.14159
v.z = 6.62607

'vector4' object has no attribute 'w'

can't set attribute 'x'

v.a = 21

can't delete attribute 'z'

'vector4' object does not support item assignment

'vector4' object doesn't support item deletion

This is the simplest implementation. Python generates all the errors; the code doesn’t raise any exceptions on its own. The set and delete errors are because the property descriptors Python creates don’t have set or delete methods. As with vector3, attempts to modify the underlying tuple fail.

We can expand on vector4 by supplying the missing set and delete methods:

Since modifying a property always raises an exception, we can use generic _setany and _delany methods (lines #23 to #27) for all three properties. Using @property this way (lines #29 to #31) lets us control the exception and add doc strings to the properties.

We also implement the __getattr__ method (lines #13 to #17) to handle attempted access to properties that don’t exist. When run, this prints:

v = [2.718, 3.142, 6.626]

v.x = 2.71828
v.y = 3.14159
v.z = 6.62607

Unknown attribute "w"

Attributes cannot be modified.

v.a = 21

Attributes cannot be deleted.

'vector5' object does not support item assignment

'vector5' object doesn't support item deletion

Essentially the same as vector4 but now we control the attribute error text. But in trying to access a property that doesn’t exist, note how we use the name of the property, w. We can’t do that for the set and delete errors because the generic functions don’t know which property is accessed. A minor detail, perhaps, but we can have it all.

To take this to the next level, we create our own descriptor class:

I’ve instrumented the vector_element descriptor (lines #3 to #25) with print statements so we can see how this interacts with vector6 (see Python Descriptors, part 1 and Python Descriptors, part 2 for more information on descriptors).

Of note is the __set_name__ method (lines #8 to #11), which tells the property instance what its name is. We store the name (line #10) for use in error messages and determine the sequence index value corresponding to the vector element represented (line #11).

The __get__ method uses the index to return the appropriate tuple element.

When run, this prints:

init()
init()
init()
setname(x, cls=vector6)
setname(y, cls=vector6)
setname(z, cls=vector6)

get(1424131852464)
get(1424131852464)
get(1424131852464)
v = [2.718, 3.142, 6.626]

get(1424131852464)
v.x = 2.71828
get(1424131852464)
v.y = 3.14159
get(1424131852464)
v.z = 6.62607

Unknown attribute "w"

set(1424131852464, 42)
Vector element "x" is read-only!

v.a = 21

del(1424131852464)
Vector element "z" cannot be deleted!

'vector6' object does not support item assignment

'vector6' object doesn't support item deletion

The first six lines come from the creation of the vector6 class as the three properties are created. In the four lines after, the get method is called three times to obtain the three vector elements. The six lines below show the same thing, access to a vector element goes through the get method.

The set and delete methods raise appropriate errors (which now include the element name). And, as always, we can add and access new attributes. The only error messages we don’t control involve accessing the underlying tuple. Let’s tackle those next.

Our last version of a vector class completely manages access to its elements:

In addition to the properties (lines #15 to #17), which we defined for vector6, we also implement the indexing methods, __getitem__ (lines #25 to #29), __setitem__ (lines #31 to #33), and __delitem__ (lines #35 to #37). These methods come into play when we index an object as a sequence.

Note the additional exercise code designed to test indexing (lines #47 to #53).

When run, this prints:

v = [2.718, 3.142, 6.626]

v.x = 2.71828
v.y = 3.14159
v.z = 6.62607

Unknown attribute "w"

Vector element "x" is read-only!

v.a = 21

Vector element "z" cannot be deleted!

Vector element vec[0] is read-only!

Vector element vec[1] cannot be deleted!

v[0] = 2.71828
v[1] = 3.14159
v[2] = 6.62607
Vector element vec[3] does not exist!

Note how we handle all exceptions and that our error messages reference the element in question.

Hopefully this and the previous post give you a good idea how to make your own powerful classes as well as how to do it by subclassing existing Python classes.

The ZIP file linked below contains an expanded version of vector3d that includes everything from this post as well as the vector math methods from last time, so it’s a fully featured, fully managed class you can explore and use as a template for your own projects.

Link: Zip file containing all code fragments used in this post.

∅