# Usage

`padme` – a mostly transparent proxy class for Python.

Padme, named after the Star Wars (tm) character, is a library for creating proxy objects out of any other python object.

The resulting object is as close to mimicking the original as possible. Some things are impossible to fake in CPython so those are highlighted below. All other operations are silently forwarded to the original.

## Terminology

proxy:

  An intermediate object that is used in place of some original object.

proxiee:

  The original object hidden behind one or more proxies.

## Basic features

Let’s consider a simple example:

    >>> pets = [str('cat'), str('dog'), str('fish')]
    >>> pets_proxy = proxy(pets)
    >>> pets_proxy
    ['cat', 'dog', 'fish']
    >>> isinstance(pets_proxy, list)
    True
    >>> pets_proxy.append(str('rooster'))
    >>> pets
    ['cat', 'dog', 'fish', 'rooster']

By default, a proxy object is not that interesting. What is more interesting is the ability to create subclasses that change a subset of the behavior. For implementation simplicity such methods need to be decorated with `@proxy.direct`.

Let’s consider a crazy proxy that overrides the `__repr__()` method to censor the word ‘cat’. This is how it can be implemented:

    >>> class censor_cat(proxy):
    ...     @proxy.direct
    ...     def __repr__(self):
    ...         return repr(proxy.original(self)).replace(
    ...             str('cat'), str('***'))

Now let’s create a proxy for our pets collection and see how it looks like:

    >>> pets_proxy = censor_cat(pets)
    >>> pets_proxy
    ['***', 'dog', 'fish', 'rooster']

As before, all other aspects of the proxy behave the same way. All of the methods work and are forwarded to the original object. The type of the proxy object is correct, event the meta-class of the object is correct (this matters for `issubclass()`, for instance).

## Accessing the original object

At any time one can access the original object hidden behind any proxy by using the `proxy.original()` function. For example:

    >>> obj = 'hello world'
    >>> proxy.original(proxy(obj)) is obj
    True

## Accessing proxy state

At any time the state of any proxy object can be accessed using the `proxy.state()` function. The state object behaves as a regular object with attributes. It can be used to add custom state to an object that cannot hold it, for example:

    >>> obj = 42
    >>> obj.foo = 42
    Traceback (most recent call last):
        ...
    AttributeError: 'int' object has no attribute 'foo'
    >>> obj = proxy(obj)
    >>> obj.foo = 42
    Traceback (most recent call last):
        ...
    AttributeError: 'int' object has no attribute 'foo'
    >>> proxy.state(obj).foo = 42
    >>> proxy.state(obj).foo
    42

## Using the @proxy.direct decorator

The `@proxy.direct` decorator can be used to disable the automatic pass-through behavior that is exhibited by any proxy object. In practice we can use it to either intercept and substitute an existing functionality or to add a new functionality that doesn’t exist in the original object.

First, let’s write a custom proxy class for the `bool` class (which cannot be used as a base class anymore) and change the core functionality.

    >>> class nay(proxy):
    ...
    ...     @proxy.direct
    ...     def __nonzero__(self):
    ...         return not bool(proxiee(self))
    ...
    ...     @proxy.direct
    ...     def __bool__(self):
    ...         return not bool(proxiee(self))

    >>> bool(nay(True))
    False
    >>> bool(nay(False))
    True
    >>> if nay([]):
    ...     print("It works!")
    It works!

Now, let’s write a different proxy class that will add some new functionality

Here, the self_aware_proxy class gives any object a new property, `is_proxy` which always returns `True`.

    >>> class self_aware_proxy(proxy):
    ...     @proxy.direct
    ...     def is_proxy(self):
    ...         return True
    >>> self_aware_proxy('hello').is_proxy()
    True

## Limitations

There are only two things that that give our proxy away.

The `type()` function:

    >>> type(pets_proxy)
    <class '...censor_cat[list]'>

And the `id` function (and anything that checks object identity):

    >>> pets_proxy is pets
    False
    >>> id(pets) == id(pets_proxy)
    False

That’s it, enjoy. You can read the unit tests for additional interesting details of how the proxy class works. Those are not covered in this short introduction.

Note

There are a number of classes and meta-classes but the only public interface is the `proxy` class and the `proxy.direct()` decorator. See below for examples.

## Deprecated 1.0 APIs

If you’ve used Padme before you may have seen `@unproxied()` and `proxiee()`. They are still here but `@unproxied` is now spelled `@proxy.direct` and `proxiee()` is now `proxy.original()`. This was done to allow all of Padme to be used from the one `proxy` class.

## Reference

class padme.proxy(proxiee, *args, **kwargs)

  A mostly transparent proxy type.

  The proxy class can be used in two different ways. First, as a callable `proxy(obj)`. This simply returns a proxy for a single object.

      >>> truth = [str('trust no one')]
      >>> lie = proxy(truth)

  This will return an instance of a new `proxy` sub-class which for all intents and purposes, to the extent possible in CPython, forwards all requests to the original object.

  One can still examine the proxy with some ways:

      >>> lie is truth
      False
      >>> type(lie) is type(truth)
      False

  Having said that, the vast majority of stuff will make the proxy behave identically to the original object.

      >>> lie[0]
      'trust no one'
      >>> lie[0] = str('trust the government')
      >>> truth[0]
      'trust the government'

  The second way of using the `proxy` class is as a base class. In this way, one can actually override certain methods. To ensure that all the dunder methods work correctly please use the `@proxy.direct` decorator on them.

      >>> import codecs
      >>> class crypto(proxy):
      ...
      ...     @proxy.direct
      ...     def __repr__(self):
      ...         return codecs.encode(
      ...             super(crypto, self).__repr__(), "rot_13")

  With this weird class, we can change the repr() of any object we want to be ROT-13 encoded. Let’s see:

      >>> orig = [str('ala ma kota'), str('a kot ma ale')]
      >>> prox = crypto(orig)

  We can sill access all of the data through the proxy:

      >>> prox[0]
      'ala ma kota'

  But the whole repr() is now a bit different than usual:

      >>> prox
      ['nyn zn xbgn', 'n xbg zn nyr']

  static direct(fn)

    Mark a method as not-to-be-proxied.

    This decorator can be used inside `proxy` sub-classes. Please consult the documentation of `proxy` for details.

    In practical terms there are two reasons one can use `proxy.direct`.

    - First, as a way to change the behaviour of a proxy. In this mode a method that already exists on the proxied object is intercepted and custom code is executed. The custom code can still call the original, if desired, by using the `proxy.original()` function to access the original object

    - Second, as a way to introduce new functionality to an object. In that sense the resulting proxy will be less transparent as all `proxy.direct` methods are explicitly visible and available to access but this may be exactly what is desired in some situations.

    For additional details on how to use this decorator, see the documentation of the `padme` module.

  static original(proxy_obj)

    Return the proxiee hidden behind the given proxy.

    Parameters:

      proxy – An instance of `proxy` or its subclass.

    Returns:

      The original object that the proxy is hiding.

    This function can be used to access the object hidden behind a proxy. This is useful when access to original object is necessary, for example, to implement an method decorated with `@proxy.direct`.

    In the following example, we cannot use `super()` to get access to the append method because the proxy does not really subclass the list object. To override the `append` method in a way that allows us to still call the original we must use the `proxy.original()` function:

        >>> class verbose_list(proxy):
        ...     @proxy.direct
        ...     def append(self, item):
        ...         print("Appending:", item)
        ...         proxy.original(self).append(item)

    Now that we have a `verbose_list` class, we can use it to see that it works as expected:

        >>> l = verbose_list([])
        >>> l.append(42)
        Appending: 42
        >>> l
        [42]

  static state(proxy_obj)

    Support function for accessing the state of a proxy object.

    The main reason for this function to exist is to facilitate creating stateful proxy objects. This allows you to put state on objects that cannot otherwise hold it (typically built-in classes or classes using `__slots__`) and to keep the state invisible to the original object so that it cannot interfere with any future APIs.

    To use it, just call it on any proxy object and use the return value as a normal object you can get/set attributes on. For example:

        >>> life = proxy(42)

    We cannot set attributes on integer instances:

        >>> life.foo = True
        Traceback (most recent call last):
            ...
        AttributeError: 'int' object has no attribute 'foo'

    But we can do that with a proxy around the integer object.

        >>> proxy.state(life).foo = True
        >>> proxy.state(life).foo
        True

## Internals

class padme.proxy_meta(name, bases, ns, *args, **kwargs)

  Meta-class for all proxy types.

  This meta-class is responsible for gathering the __unproxied__ attributes on each created class. The attribute is a frozenset of names that will not be forwarded to the `proxiee` but instead will be looked up on the proxy itself.

padme.make_typed_proxy_meta(proxiee_cls)

  Make a new proxy meta-class for the specified class of proxiee objects.

  Note

  Had python had an easier way of doing this, it would have been spelled as `proxy_meta[cls]` but I didn’t want to drag pretty things into something nobody would ever see.

  Parameters:

    proxiee_cls – The type of the that will be proxied

  Returns:

    A new meta-class that lexically wraps `proxiee` and `proxiee_cls` and subclasses `proxy_meta`.

class padme.proxy_base

  Base class for all proxies.

  This class implements the bulk of the proxy work by having a lot of dunder methods that delegate their work to a `proxiee` object. The `proxiee` object must be available as the `__proxiee__` attribute on a class deriving from `base_proxy`. Apart from `__proxiee__`, the ``__unproxied__` attribute, which should be a frozenset, must also be present in all derived classes.

  In practice, the two special attributes are injected via `boundproxy_meta` created by `make_boundproxy_meta()`. This class is also used as a base class for the tricky `proxy` below.

  NOTE: Look at `pydoc3 SPECIALMETHODS` section titled `Special method lookup` for a rationale of why we have all those dunder methods while still having __getattribute__()

  __abs__()
  __add__(other)
  __and__(other)
  __annotations__ = {}
  __bool__()
  __bytes__()
  __call__(*args, **kwargs)

    Call self as a function.

  __complex__()
  __contains__(item)
  __del__()

    No-op object delete method.

    Note

    This method is handled specially since it must be called after an object becomes unreachable. As long as the proxy object itself exits, it holds a strong reference to the original object.

  __delattr__(name)

    Implement delattr(self, name).

  __delete__(instance)
  __delitem__(item)
  __dict__ = mappingproxy({'__module__': 'padme', '__doc__': '\n Base class for all proxies.\n\n This class implements the bulk of the proxy work by having a lot of dunder\n methods that delegate their work to a ``proxiee`` object. The ``proxiee``\n object must be available as the ``__proxiee__`` attribute on a class\n deriving from ``base_proxy``. Apart from ``__proxiee__`, the\n ``__unproxied__`` attribute, which should be a frozenset, must also be\n present in all derived classes.\n\n In practice, the two special attributes are injected via\n ``boundproxy_meta`` created by :func:`make_boundproxy_meta()`. This class\n is also used as a base class for the tricky :class:`proxy` below.\n\n NOTE: Look at ``pydoc3 SPECIALMETHODS`` section titled ``Special method\n lookup`` for a rationale of why we have all those dunder methods while\n still having __getattribute__()\n ', '__del__': <function proxy_base.__del__>, '__repr__': <function proxy_base.__repr__>, '__str__': <function proxy_base.__str__>, '__bytes__': <function proxy_base.__bytes__>, '__format__': <function proxy_base.__format__>, '__lt__': <function proxy_base.__lt__>, '__le__': <function proxy_base.__le__>, '__eq__': <function proxy_base.__eq__>, '__ne__': <function proxy_base.__ne__>, '__gt__': <function proxy_base.__gt__>, '__ge__': <function proxy_base.__ge__>, '__hash__': <function proxy_base.__hash__>, '__bool__': <function proxy_base.__bool__>, '__getattr__': <function proxy_base.__getattr__>, '__getattribute__': <function proxy_base.__getattribute__>, '__setattr__': <function proxy_base.__setattr__>, '__delattr__': <function proxy_base.__delattr__>, '__dir__': <function proxy_base.__dir__>, '__get__': <function proxy_base.__get__>, '__set__': <function proxy_base.__set__>, '__delete__': <function proxy_base.__delete__>, '__call__': <function proxy_base.__call__>, '__len__': <function proxy_base.__len__>, '__length_hint__': <function proxy_base.__length_hint__>, '__getitem__': <function proxy_base.__getitem__>, '__setitem__': <function proxy_base.__setitem__>, '__delitem__': <function proxy_base.__delitem__>, '__iter__': <function proxy_base.__iter__>, '__reversed__': <function proxy_base.__reversed__>, '__contains__': <function proxy_base.__contains__>, '__add__': <function proxy_base.__add__>, '__sub__': <function proxy_base.__sub__>, '__mul__': <function proxy_base.__mul__>, '__matmul__': <function proxy_base.__matmul__>, '__truediv__': <function proxy_base.__truediv__>, '__floordiv__': <function proxy_base.__floordiv__>, '__mod__': <function proxy_base.__mod__>, '__divmod__': <function proxy_base.__divmod__>, '__pow__': <function proxy_base.__pow__>, '__lshift__': <function proxy_base.__lshift__>, '__rshift__': <function proxy_base.__rshift__>, '__and__': <function proxy_base.__and__>, '__xor__': <function proxy_base.__xor__>, '__or__': <function proxy_base.__or__>, '__radd__': <function proxy_base.__radd__>, '__rsub__': <function proxy_base.__rsub__>, '__rmul__': <function proxy_base.__rmul__>, '__rmatmul__': <function proxy_base.__rmatmul__>, '__rtruediv__': <function proxy_base.__rtruediv__>, '__rfloordiv__': <function proxy_base.__rfloordiv__>, '__rmod__': <function proxy_base.__rmod__>, '__rdivmod__': <function proxy_base.__rdivmod__>, '__rpow__': <function proxy_base.__rpow__>, '__rlshift__': <function proxy_base.__rlshift__>, '__rrshift__': <function proxy_base.__rrshift__>, '__rand__': <function proxy_base.__rand__>, '__rxor__': <function proxy_base.__rxor__>, '__ror__': <function proxy_base.__ror__>, '__iadd__': <function proxy_base.__iadd__>, '__isub__': <function proxy_base.__isub__>, '__imul__': <function proxy_base.__imul__>, '__imatmul__': <function proxy_base.__imatmul__>, '__itruediv__': <function proxy_base.__itruediv__>, '__ifloordiv__': <function proxy_base.__ifloordiv__>, '__imod__': <function proxy_base.__imod__>, '__ipow__': <function proxy_base.__ipow__>, '__ilshift__': <function proxy_base.__ilshift__>, '__irshift__': <function proxy_base.__irshift__>, '__iand__': <function proxy_base.__iand__>, '__ixor__': <function proxy_base.__ixor__>, '__ior__': <function proxy_base.__ior__>, '__neg__': <function proxy_base.__neg__>, '__pos__': <function proxy_base.__pos__>, '__abs__': <function proxy_base.__abs__>, '__invert__': <function proxy_base.__invert__>, '__complex__': <function proxy_base.__complex__>, '__int__': <function proxy_base.__int__>, '__float__': <function proxy_base.__float__>, '__round__': <function proxy_base.__round__>, '__index__': <function proxy_base.__index__>, '__enter__': <function proxy_base.__enter__>, '__exit__': <function proxy_base.__exit__>, '__dict__': <attribute '__dict__' of 'proxy_base' objects>, '__weakref__': <attribute '__weakref__' of 'proxy_base' objects>, '__annotations__': {}})
  __dir__()

    Default dir() implementation.

  __divmod__(other)
  __enter__()
  __eq__(other)

    Return self==value.

  __exit__(exc_type, exc_value, traceback)
  __float__()
  __floordiv__(other)
  __format__(format_spec)

    Default object formatter.

  __ge__(other)

    Return self>=value.

  __get__(instance, owner)
  __getattr__(name)
  __getattribute__(name)

    Return getattr(self, name).

  __getitem__(item)
  __gt__(other)

    Return self>value.

  __hash__()

    Return hash(self).

  __iadd__(other)
  __iand__(other)
  __ifloordiv__(other)
  __ilshift__(other)
  __imatmul__(other)
  __imod__(other)
  __imul__(other)
  __index__()
  __int__()
  __invert__()
  __ior__(other)
  __ipow__(other, modulo=None)
  __irshift__(other)
  __isub__(other)
  __iter__()
  __itruediv__(other)
  __ixor__(other)
  __le__(other)

    Return self<=value.

  __len__()
  __length_hint__()
  __lshift__(other)
  __lt__(other)

    Return self<value.

  __matmul__(other)
  __mod__(other)
  __module__ = 'padme'
  __mul__(other)
  __ne__(other)

    Return self!=value.

  __neg__()
  __or__(other)

    Return self|value.

  __pos__()
  __pow__(other, modulo=None)
  __radd__(other)
  __rand__(other)
  __rdivmod__(other)
  __repr__()

    Return repr(self).

  __reversed__()
  __rfloordiv__(other)
  __rlshift__(other)
  __rmatmul__(other)
  __rmod__(other)
  __rmul__(other)
  __ror__(other)

    Return value|self.

  __round__(n)
  __rpow__(other)
  __rrshift__(other)
  __rshift__(other)
  __rsub__(other)
  __rtruediv__(other)
  __rxor__(other)
  __set__(instance, value)
  __setattr__(name, value)

    Implement setattr(self, name, value).

  __setitem__(item, value)
  __str__()

    Return str(self).

  __sub__(other)
  __truediv__(other)
  __weakref__

    list of weak references to the object

  __xor__(other)

class padme.proxy_state(proxy_obj)

  Support class for working with proxy state.

  This class implements simple attribute-based access methods. It is normally instantiated internally for each proxy object. You don’t want to fuss with it manually, instead just use `proxy.state()` function to access it.

  __dict__ = mappingproxy({'__module__': 'padme', '__doc__': "\n Support class for working with proxy state.\n\n This class implements simple attribute-based access methods. It is normally\n instantiated internally for each proxy object. You don't want to fuss with\n it manually, instead just use :meth:`proxy.state()` function to access it.\n ", '__init__': <function proxy_state.__init__>, '__repr__': <function proxy_state.__repr__>, '__dict__': <attribute '__dict__' of 'proxy_state' objects>, '__weakref__': <attribute '__weakref__' of 'proxy_state' objects>, '__annotations__': {}})
  __init__(proxy_obj)
  __module__ = 'padme'
  __repr__()

    Return repr(self).

  __weakref__

    list of weak references to the object