:mod:`typetools` --- Utilities for working with Python types
============================================================

.. module:: typetools
   :synopsis: Utilities for working with Python types and classes
.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
.. sectionauthor:: Nick Coghlan <ncoghlan@gmail.com>


.. versionadded:: 2.6

This module provides utilities for working with and
defining Python type objects (instances of the builtin metaclass
:class:`type`). The utilities provided by this module may be
useful regardless of whether the type instances are defined in
Python code using a normal :statement:`class` statement or as part
of an extension module.

The :mod:`typetools` module currently defines a single utility class:

.. class:: ProxyMixin(target)

   A proxy class that ensures all special method invocations which may
   otherwise bypass the normal :method:`__getattribute__` lookup
   process are correctly delegated to the specified target object.
   Normal attribute manipulation operations are also delegated to the
   specified target object.

   All operations on a :class:`ProxyMixin` instance return an unproxied
   result. Operations involving multiple :class:`ProxyMixin` instances
   (e.g. addition) are permitted, and endeavour to return the same
   result as would be calculated if the proxy objects were not involved.

   Custom proxy class implementations may inherit from this class
   in order to automatically delegate all such special methods
   that the custom proxy class does not need to provide special
   handling for.  To support more complex target resolution methods
   (e.g. holding only a weak reference to the target, which then
   needs to be checked for validity before each operation in fashion
   similar to that used by :code:`weakref.proxy`) it is possible to
   replace the simple :attribute:`_target` attribute on the base class
   with a :class:`property` descriptor in the subclass.

   This may still not be sufficient for more complex delegation
   scenarios which need to deal more carefully with the arguments
   and return values of method calls (e.g. a local interface
   to arbitrary remote objects), but :class:`ProxyMixin` and its test
   cases may still be used as a reference when developing such
   classes to identify which methods must be defined explicitly on
   the proxy type in order for them to be delegated correctly by
   the Python interpreter.