Package: descriptor-tools
[![Python](https://img.shields.io/badge/Python-3.3+-brightgreen.svg)](https://www.python.org/)
[![Edition](https://img.shields.io/badge/Edition-2-AA3333.svg)](http://amzn.to/2sd2Ubt)
![Version](https://img.shields.io/badge/Version-1.1beta-992222.svg)
# 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 onUnboundAttributefor 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 anAttributeError.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=Truein order for it to not raise anAttributeError.Secret-set descriptors use a “secret” method to set the attribute, which is
usually theset()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 theInstancePropertywrapper/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 thestoragemodule, 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 anAttributeError, 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 thewithConstants()function; andLazyProperty, which allows lazy instantiation of properties,
given an evalutation method.