descriptor-tools 1.1.0

A collection of classes and functions to make the creation of descriptors simpler and quicker

[](https://www.python.org/) [](http://amzn.to/2sd2Ubt)  # descriptor-tools A collection of classes and functions to make the creation of descriptors simpler and quicker. Most of the ideas present in this library were presented, but not fully fleshed out in my book, [Python Descriptors](https://amzn.to/2HAL6gE) (2nd Edition).

The first major contribution that this library provides is attribute binding see below), along with many helpers for building descriptors that use it.

The next major contribution is a set of decorators (GoF style AND method decorators) and mixins, both of which are the only modules that cannot have its members accessed directly from the descriptor_tools package. While everything else that’s public is available from there, the decorators have to be accessed from descriptor_tools.decorators, and the mixins have to be accessed from descriptor_tools.mixins.

See the documentation of the corresponding modules to read more about them.

### Attribute Binding Attribute binding is just like method binding in Python. When you refer to a method through its class name without calling it (e.g. ClassName.method_name), you get a version of the method that can accept an instance (and whatever other necessary arguments) when it is called, rather than being bound directly to the instance. These were once called “unbound methods” in Python 2, but now they’re just implemented as functions in Python 3.

Nevertheless, they are still unbound methods. And now it’s possible to have unbound attributes. If an attribute is defined using a descriptor that uses attribute binding, you can get an unbound attribute from a class (e.g. ClassName.attr_name), which can then be called like a function which takes an instance as a parameter and returns the attribute value for that instance. Check out the documentation on UnboundAttribute for benefits of this technique.

### Special Accessor Types In the book, there were four different special ways of accessing, and these ideas are spread throughout this code base.

The first one is a binding descriptor, which implements attribute binding, mentioned above.

The other three are different ways of implementing “read-only” attributes: set-once, forced-set, and secret-set.

The set-once type only allows for __set__() to be called once per instance. If it’s ever tried again, it raises an AttributeError.

The forced-set method is similar to the secret-set method in that they both allow the attribute to be set multiple times, but it must be done in a roundabout way through a back door. Forced-set allows you call the usual __set__() method on the descriptor, but it must be provided with the named argument, force=True in order for it to not raise an AttributeError.

Secret-set descriptors use a “secret” method to set the attribute, which is usually the set() method (as opposed to the __set__() method). This is generally preferred over the forced-set style because it doesn’t require someone to explicitly call a “magic” method, and it doesn’t alter the signature of a protocol method.

### New Addition: Instance Properties! These aren’t mentioned in the book because they’re new, but if the book ever gets a new edition, they will certainly be added. What are instance properties? They’re a micro framework where you delegate to what are called ‘delegated properties’, a term and idea I “stole” from the Kotlin language.

Delegated properties are similar to descriptors, but because of the InstanceProperty wrapper/delegator, one exists per instance of the class they’re assigned to. This allows you to write a class for dealing with typical property situations in a much simpler way, only needing to care about the one value for the one instance it’s associated with. Check them out! Currently the only documentation on them is in doc strings found in the instance_properties package. Later, more convenient documentation will be available, hopefully on ReadTheDocs as well on the Github wiki.

### New Addition: Universal Descriptor Storage In the storage module, there is a new interface, DescriptorStorage. This interface defines a set of methods that make it act mostly like a dictionary, but it also has a few things for saving and/or looking up the name of the attribute the descriptor is assigned to, allowing it to provide nicer error messages when raising an AttributeError, taking an extra little bit of the load off of the descriptor writer.

### Other Points of Note There are quite a few little helper functions and classes within the library, most notably those for grabbing descriptor objects from classes (preventing the lookup from triggering the descriptor’s __get__() method) and those for providing universal ways to assign values to attributes when they’re read-only (since a back door must usually be present for initializing the value).

Lastly, there are a few new “property” types: BindingProperty, which provides attribute binding to properties; constants, defined using the withConstants() function; and LazyProperty, which allows lazy instantiation of properties, given an evalutation method.