Wrapt

--------------

**Bugs Fixed**

* When using ``FunctionWrapper`` around a method of an existing instance of
a class, rather than on the type, then a memory leak could occur in two
different scenarios.

The first issue was that wrapping a method on an instance of a class was
causing an unwanted reference to the class meaning that if the class type
was transient, such as it is being created inside of a function call, the
type object would leak.

The second issue was that wrapping a method on an instance of a class and
then calling the method was causing an unwanted reference to the instance
meaning that if the instance was transient, it would leak.

This was only occurring when the C extension component for the
``wrapt`` module was being used.

--------------

**New Features**

* When specifying an adapter for a decorator, it is now possible to pass
in, in addition to passing in a callable, a tuple of the form which
is returned by ``inspect.getargspec()``, or a string of the form which
is returned by ``inspect.formatargspec()``. In these two cases the
decorator will automatically compile a stub function to use as the
adapter. This eliminates the need for a caller to generate the stub
function if generating the signature on the fly.

::

def argspec_factory(wrapped):
argspec = inspect.getargspec(wrapped)

args = argspec.args[1:]
defaults = argspec.defaults and argspec.defaults[-len(argspec.args):]

return inspect.ArgSpec(args, argspec.varargs,
argspec.keywords, defaults)

def session(wrapped):
wrapt.decorator(adapter=argspec_factory(wrapped))
def _session(wrapped, instance, args, kwargs):
with transaction() as session:
return wrapped(session, *args, **kwargs)

return _session(wrapped)

This mechanism and the original mechanism to pass a function, meant
that the adapter function had to be created in advance. If the adapter
needed to be generated on demand for the specific function to be
wrapped, then it would have been necessary to use a closure around
the definition of the decorator as above, such that the generator could
be passed in.

As a convenience, instead of using such a closure, it is also now
possible to write:

::

def argspec_factory(wrapped):
argspec = inspect.getargspec(wrapped)

args = argspec.args[1:]
defaults = argspec.defaults and argspec.defaults[-len(argspec.args):]

return inspect.ArgSpec(args, argspec.varargs,
argspec.keywords, defaults)

wrapt.decorator(adapter=wrapt.adapter_factory(argspec_factory))
def _session(wrapped, instance, args, kwargs):
with transaction() as session:
return wrapped(session, *args, **kwargs)

The result of ``wrapt.adapter_factory()`` will be recognised as indicating
that the creation of the adapter is to be deferred until the decorator is
being applied to a function. The factory function for generating the
adapter function or specification on demand will be passed the function
being wrapped by the decorator.

If wishing to create a library of routines for generating adapter
functions or specifications dynamically, then you can do so by creating
classes which derive from ``wrapt.AdapterFactory`` as that is the type
which is recognised as indicating lazy evaluation of the adapter
function. For example, ``wrapt.adapter_factory()`` is itself implemented
as:

::

class DelegatedAdapterFactory(wrapt.AdapterFactory):
def __init__(self, factory):
super(DelegatedAdapterFactory, self).__init__()
self.factory = factory
def __call__(self, wrapped):
return self.factory(wrapped)

adapter_factory = DelegatedAdapterFactory

**Bugs Fixed**

* The ``inspect.signature()`` function was only added in Python 3.3.
Use fallback when doesn't exist and on Python 3.2 or earlier Python 3
versions.

Note that testing is only performed for Python 3.3+, so it isn't
actually known if the ``wrapt`` package works on Python 3.2.

-------------

**Features Changed**

* When using ``wrapt.wrap_object()``, it is now possible to pass an
arbitrary object in addition to a module object, or a string name
identifying a module. Similar for underlying ``wrapt.resolve_path()``
function.

**Bugs Fixed**

* It is necessary to proxy the special ``__weakref__`` attribute in the
pure Python object proxy else using ``inspect.getmembers()`` on a
decorator class will fail.

* The ``FunctionWrapper`` class was not passing through the instance
correctly to the wrapper function when it was applied to a method of an
existing instance of a class.

* The ``FunctionWrapper`` was not always working when applied around a
method of a class type by accessing the method to be wrapped using
``getattr()``. Instead it is necessary to access the original unbound
method from the class ``__dict__``. Updated the ``FunctionWrapper`` to
work better in such situations, but also modify ``resolve_path()`` to
always grab the class method from the class ``__dict__`` when wrapping
methods using ``wrapt.wrap_object()`` so wrapping is more predictable.
When doing monkey patching ``wrapt.wrap_object()`` should always be
used to ensure correct operation.

* The ``AttributeWrapper`` class used internally to the function
``wrap_object_attribute()`` had wrongly named the ``__delete__`` method
for the descriptor as ``__del__``.

-------------

**Features Changed**

* Previously using wrapt.decorator on a class type didn't really yield
anything which was practically useful. This is now changed and when
applied to a class an instance of the class will be automatically
created to be used as the decorator wrapper function. The requirement
for this is that the __call__() method be specified in the style as
would be done for the decorator wrapper function.

::

wrapt.decorator
class mydecoratorclass(object):
def __init__(self, arg=None):
self.arg = arg
def __call__(self, wrapped, instance, args, kwargs):
return wrapped(*args, **kwargs)

mydecoratorclass
def function():
pass

If the resulting decorator class is to be used with no arguments, the
__init__() method of the class must have all default arguments. These
arguments can be optionally supplied though, by using keyword arguments
to the resulting decorator when applied to the function to be decorated.

::

mydecoratorclass(arg=1)
def function():
pass

-------------

**New Features**

* Provide wrapt.getcallargs() for determining how arguments mapped to a
wrapped function. For Python 2.7 this is actually inspect.getcallargs()
with a local copy being used in the case of Python 2.6.

* Added wrapt.wrap_object_attribute() as a way of wrapping or otherwise
modifying the result of trying to access the attribute of an object
instance. It works by adding a data descriptor with the same name as
the attribute, to the class type, allowing reading of the attribute
to be intercepted. It does not affect updates to or deletion of the
attribute.

**Bugs Fixed**

* Need to explicitly proxy special methods __bytes__(), __reversed__()
and __round__() as they are only looked up on the class type and not
the instance, so can't rely on __getattr__() fallback.

* Raise more appropriate TypeError, with corresponding message, rather
than IndexError, when a decorated instance or class method is called via
the class but the required 1st argument of the instance or class is not
supplied.

-------------

**Bugs Fixed**

* The ObjectProxy class would return that the __call__() method existed
even though the wrapped object didn't have one. Similarly, callable()
would always return True even if the wrapped object was not callable.

This resulted due to the existence of the __call__() method on the
wrapper, required to support the possibility that the wrapped object
may be called via the proxy object even if it may not turn out that
the wrapped object was callable.

Because checking for the existence of a __call__() method or using
callable() can sometimes be used to indirectly infer the type of an
object, this could cause issues. To ensure that this now doesn't
occur, the ability to call a wrapped object via the proxy object has
been removed from ObjectProxy. Instead, a new class CallableObjectProxy
is now provided, with it being necessary to make a conscious choice as
to which should be used based on whether the object to be wrapped is
in fact callable.

Note that neither before this change, or with the introduction of the
class CallableObjectProxy, does the object proxy perform binding. If
binding behaviour is required it still needs to be implemented
explicitly to match the specific requirements of the use case.
Alternatively, the FunctionWrapper class should be used which does
implement binding, but also enforces a wrapper mechanism for
manipulating what happens at the time of the call.