Metadata-Version: 1.1
Name: descriptor-tools
Version: 1.1.0
Summary: A collection of classes and functions to make the creation of descriptors simpler and quicker
Home-page: https://github.com/sad2project/descriptor-tools
Author: Jacob Zimmerman
Author-email: sad2project@gmail.com
License: CC0 1.0 Universal
Download-URL: https://github.com/sad2project/descriptor-tools/tarball/1.1.0
Description: [![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 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.
        
Keywords: descriptors,properties
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
