Python has the useful notion of descriptor objects, which give object attributes control over how they are accessed. Descriptors enable calculated-on-the-fly attribute values and can prevent or control modification of data values.

The previous post covered the basics. In this post, I’ll dig deeper into Python descriptors with some more involved examples. This post assumes the basics covered in the previous post.

In previous examples, the get, set, and delete methods were in the class defining the data attributes (or in a subclass). I’ll call such attributes managed. We needed all three methods for each fully managed attribute. A project with many classes, each with managed data attributes, ends up with a lot of duplicated code. It would be nice to have a general descriptor class (something like what was indicated in the first examples in the last post):

Which works fine in form, but what are the get, set, and delete methods acting on? As shown here they have no knowledge of the class using them, nor of the attributes of instances of that class. When run, this just prints:

object.get()
object.get()
None None

set(42)
set(21)
object.get()
object.get()
None None

Nope!
Nope!

The descriptor methods get called but are blind to what owns them. We need a bigger code.

§

One approach a descriptor class can take is to make assumptions about the class using it. It can access an attribute it expects to exist. Of course, that restricts its use to classes with the right attributes, but that may not be an issue if you have related classes that need the same managed attributes.

Here’s an example of a descriptor that assumes the _x and _y attributes from the PointBaseClass from the previous post:

One big change from previous examples is the __init__ method (lines #4-#6) that takes a parameter (expected to be a pair of numbers) and uses it to set an attribute, default.

The __get__ method (lines #8-#12) returns the default parameter when called by the class but returns both the assumed _x and _y attributes in a tuple if called by the object.

The __delete__ method (lines #19-#22) resets the assumed _x and _y attributes to the default value. Previously, we used the delete operation to clear the attribute’s value to zero, but here we can provide a default other than zero (note the default is still zero if no alternate value is provided).

The DependentPropertyExample class (lines #24 and #25) is derived from PointBaseClass (see previous post) and inherits the _x and _y attributes from it. The example class uses DependentProperty to define a single descriptor attribute xy and sets the default value to (-1, -1).

When run, this prints:

(-1, -1) 

obj: (21.000000, 42.000000)
obj.xy=(21,42)
obj._x=21 ._y=42

obj.xy=(86,99)

obj.xy=(-1,-1)

This is a step in the right direction, but we can do a lot more.

§

Another approach is to put the data in the descriptor, but this only works for data shared by all class instances. (Remember, descriptors are class attributes.) But sometimes classes do share data with all their instances. Here’s an example:

The idea is that the (class) data can be anything desired but is configured as to how that data appears when accessed (modes include hex string, binary string, and float object). Setting the data value sets the data mode — which requires a valid mode name. Invalid mode names raise an error. Deleting the data value resets the data mode to the default (string).

As with the previous example, the descriptor class defines __init__ (lines #5-#10) to initialize the descriptor object. The arguments are the data the descriptor is to own and an optional mode name (the default mode is string).

The __get__ method (lines #12-#30) returns the current mode when called on the class. When called on the instance, it returns its data in the form specified by _mode.

The __set__ method (lines #32-#37) allows class clients to change the mode. Mode names supplied here (or for the constructor) must be valid. They raise an exception if not recognized. Note that the empty string and the string “raw” are recognized as valid but the __get__ function doesn’t use them. These modes just drop through to line #30, which returns the raw data.

The __delete__ method (lines #39-#41) resets the mode to the default (string).

Using this descriptor, the ConfiguredPropertyExample class (lines #43-#49) defines four data attributes, a, b, c, and d.

The code in lines #52-#76 exercises an instance of the example class. When run, it prints:

a:hex = "15"
b:str = "local"
c:float = "3.141590"
d:cmplx = "[+1.000, +1.000i]"

a:raw = 21
a:bin = "10101"
a:hex = "15"
a:float = "21.000000"

a:str = "21"
a:hex = "15"

This is fine for class data, but we’d also like to manage instance data. That requires the descriptor to know about the instance data. So far, to accomplish that, we’ve put the descriptor functions inside the class that uses them (in the previous post) and here by making assumptions or by completely ignoring instance attributes. But there is another piece to this puzzle.

§

There is one more method to know about when it comes to descriptor definitions: __set_name__. Python calls this when the class attribute is created (after it calls the __init__ method). Note that this is when Python compiles the class that uses a descriptor. As part of creating the class dictionary, Python calls both the __init__ and __set_name__ methods.

The name Python passes to the __set_name__ method is the name of the class attribute being created. We can use this to tell us what variable to access in class instances:

In the __init__ method (lines #4-#6), the descriptor takes a single parameter, a default value. It also sets a name attribute to “<new>” (just to give it an obvious default value).

The __set_name__ method (lines #11-#13) receives the name the owner class is using for the new descriptor object. The owner parameter is the class that owns this new managed attribute. The code adds an underbar to the name parameter to build the name of the expected instance attribute. If the class attribute created using this descriptor is named foo, then the matching instance attribute must be named _foo.

The __get__ method (lines #15-#20), if called on the class returns the default value as if this was a class attribute. If called on an instance, it uses the computed name (with the leading underbar) to access the attribute in object’s dictionary.

The __set__ method (lines #19-#21) also uses the computed name to access the attribute but sets its value with the passed value. (We’re not doing any constraining in this example, just allowing set/get access (but not delete!) to a “private” instance variable.

The __delete__ method (lines #23-#25) resets the instance attribute’s value to the provided default (again using the computed name).

The SimplePropertyExample (lines #28-#45) uses the SimpleProperty class to define four managed data attributes: p1, p2, p3, and p4. The __str__ and __repr__ methods (lines #41-##45) just return appropriate strings.

The SimplePropertyExample.__init__ method (lines #34-#39) takes a required name and four optional parameters. The method defines four instance attributes to match the four class attributes: _p1, _p2, _p3, and _p4. If an input parameter is provided (not set to None) the instance attribute uses that value, otherwise it uses the default value from the class attribute.

The code in lines #48-#99 exercises the SimplePropertyExample class and two instances, b1 and b2. Lines #68-#77 demonstrate setting values on the instance attributes. Lines #79-#88 demonstrate manually copying the default values from the class attributes to the instance attributes, and lines #90-#99 demonstrate accomplishing the same thing by deleting the attributes.

When run, the code prints:

=== class:SimplePropertyExample (default) values ===
p1= 42
p2= 6.28318
p3= user
p4= /info

=== Object pooh:SimplePropertyExample values ===
p1= 68
p2= 2.71828
p3= user
p4= /info

=== Object bear:SimplePropertyExample values ===
p1= 86
p2= 42.21
p3= root
p4= /debug

Set b1 properties...
=== pooh:SimplePropertyExample values ===
p1= 3.14159
p2= 99
p3= piglet
p4= 1j

Copy default properties to b2...
=== bear:SimplePropertyExample values ===
p1= 42
p2= 6.28318
p3= user
p4= /info

Delete b1 properties...
=== pooh:SimplePropertyExample values ===
p1= 42
p2= 6.28318
p3= user
p4= /info

§

And that’s about it for descriptors. (As always, I’m happy to answer questions about the content if anything isn’t clear or you’d like something explained in more detail.) I’ll end with a heavily instrumented version of a descriptor you can use for experimentation:

This descriptor works much the one from last time that took a configuration that limited the range the instance attribute could have. This __init__ method expects a tuple with two range parameters, a minimum and a maximum. As usual, calls on the class return this configuration. Attempts to set the attribute to values outside the range raise an exception. Deleting the attribute resets it to zero.

Note that, since the __init__ method has a print statement (and so does the __set_name__ method), using this descriptor generates print output when the class that creates its attributes. That is, when the class is compiled. That may cause unexpected output.

§ §

Descriptors are a powerful mechanism for creating rich data attributes for your objects. Hopefully these two posts have illustrated their value and provided some examples showing how to use them. For a more detailed (and official) tutorial, see the Python Descriptor HowTo Guide.

Ø