Welcome to Padme’s documentation!

Contents:

Padme - a mostly transparent proxy class for Python

https://badge.fury.io/py/padme.png https://travis-ci.org/zyga/padme.png?branch=master https://pypip.in/d/padme/badge.png

Features

  • Free software: LGPLv3 license
  • Support for Python 2.7 and Python 3.2+
  • Documentation: https://padme.readthedocs.org.
  • Create proxy classes for any object with padme.proxy.
  • Redirect particular methods in subclasses using padme.unproxied.

Installation

At the command line:

$ easy_install padme

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv padme
$ pip install padme

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(proxy_obj, proxiee)[source]

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']
direct(fn)[source]

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.

original(proxy_obj)[source]

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]
state(proxy_obj)[source]

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[source]

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)[source]

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[source]

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__()[source]
__add__(other)[source]
__and__(other)[source]
__bool__()[source]
__bytes__()[source]
__call__(*args, **kwargs)[source]
__complex__()[source]
__contains__(item)[source]
__del__()[source]

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)[source]
__delete__(instance)[source]
__delitem__(item)[source]
__dict__ = mappingproxy({'__iter__': <function proxy_base.__iter__ at 0x7ff19ed289d8>, '__rand__': <function proxy_base.__rand__ at 0x7ff19ed32840>, '__dir__': <function proxy_base.__dir__ at 0x7ff19ed28488>, '__ipow__': <function proxy_base.__ipow__ at 0x7ff19ed32d08>, '__neg__': <function proxy_base.__neg__ at 0x7ff19ed370d0>, '__delattr__': <function proxy_base.__delattr__ at 0x7ff19ed28400>, '__weakref__': <attribute '__weakref__' of 'proxy_base' objects>, '__setitem__': <function proxy_base.__setitem__ at 0x7ff19ed288c8>, '__enter__': <function proxy_base.__enter__ at 0x7ff19ed37598>, '__eq__': <function proxy_base.__eq__ at 0x7ff19ed30ea0>, '__itruediv__': <function proxy_base.__itruediv__ at 0x7ff19ed32b70>, '__abs__': <function proxy_base.__abs__ at 0x7ff19ed371e0>, '__int__': <function proxy_base.__int__ at 0x7ff19ed37378>, '__getattr__': <function proxy_base.__getattr__ at 0x7ff19ed28268>, '__module__': 'padme', '__rfloordiv__': <function proxy_base.__rfloordiv__ at 0x7ff19ed32510>, '__index__': <function proxy_base.__index__ at 0x7ff19ed37510>, '__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 ', '__divmod__': <function proxy_base.__divmod__ at 0x7ff19ed28ea0>, '__mul__': <function proxy_base.__mul__ at 0x7ff19ed28c80>, '__del__': <function proxy_base.__del__ at 0x7ff19ed30ae8>, '__ge__': <function proxy_base.__ge__ at 0x7ff19ed280d0>, '__rshift__': <function proxy_base.__rshift__ at 0x7ff19ed320d0>, '__reversed__': <function proxy_base.__reversed__ at 0x7ff19ed28a60>, '__bool__': <function proxy_base.__bool__ at 0x7ff19ed281e0>, '__ixor__': <function proxy_base.__ixor__ at 0x7ff19ed32f28>, '__gt__': <function proxy_base.__gt__ at 0x7ff19ed28048>, '__setattr__': <function proxy_base.__setattr__ at 0x7ff19ed28378>, '__rmul__': <function proxy_base.__rmul__ at 0x7ff19ed32400>, '__ror__': <function proxy_base.__ror__ at 0x7ff19ed32950>, '__lt__': <function proxy_base.__lt__ at 0x7ff19ed30d90>, '__contains__': <function proxy_base.__contains__ at 0x7ff19ed28ae8>, '__hash__': <function proxy_base.__hash__ at 0x7ff19ed28158>, '__lshift__': <function proxy_base.__lshift__ at 0x7ff19ed32048>, '__bytes__': <function proxy_base.__bytes__ at 0x7ff19ed30c80>, '__rxor__': <function proxy_base.__rxor__ at 0x7ff19ed328c8>, '__float__': <function proxy_base.__float__ at 0x7ff19ed37400>, '__or__': <function proxy_base.__or__ at 0x7ff19ed32268>, '__call__': <function proxy_base.__call__ at 0x7ff19ed286a8>, '__repr__': <function proxy_base.__repr__ at 0x7ff19ed30b70>, '__exit__': <function proxy_base.__exit__ at 0x7ff19ed37620>, '__xor__': <function proxy_base.__xor__ at 0x7ff19ed321e0>, '__ilshift__': <function proxy_base.__ilshift__ at 0x7ff19ed32d90>, '__delitem__': <function proxy_base.__delitem__ at 0x7ff19ed28950>, '__ifloordiv__': <function proxy_base.__ifloordiv__ at 0x7ff19ed32bf8>, '__get__': <function proxy_base.__get__ at 0x7ff19ed28510>, '__floordiv__': <function proxy_base.__floordiv__ at 0x7ff19ed28d90>, '__dict__': <attribute '__dict__' of 'proxy_base' objects>, '__invert__': <function proxy_base.__invert__ at 0x7ff19ed37268>, '__round__': <function proxy_base.__round__ at 0x7ff19ed37488>, '__pos__': <function proxy_base.__pos__ at 0x7ff19ed37158>, '__irshift__': <function proxy_base.__irshift__ at 0x7ff19ed32e18>, '__rrshift__': <function proxy_base.__rrshift__ at 0x7ff19ed327b8>, '__le__': <function proxy_base.__le__ at 0x7ff19ed30e18>, '__ne__': <function proxy_base.__ne__ at 0x7ff19ed30f28>, '__sub__': <function proxy_base.__sub__ at 0x7ff19ed28bf8>, '__rpow__': <function proxy_base.__rpow__ at 0x7ff19ed326a8>, '__length_hint__': <function proxy_base.__length_hint__ at 0x7ff19ed287b8>, '__pow__': <function proxy_base.__pow__ at 0x7ff19ed28f28>, '__len__': <function proxy_base.__len__ at 0x7ff19ed28730>, '__imul__': <function proxy_base.__imul__ at 0x7ff19ed32ae8>, '__ior__': <function proxy_base.__ior__ at 0x7ff19ed37048>, '__getattribute__': <function proxy_base.__getattribute__ at 0x7ff19ed282f0>, '__add__': <function proxy_base.__add__ at 0x7ff19ed28b70>, '__rdivmod__': <function proxy_base.__rdivmod__ at 0x7ff19ed32620>, '__set__': <function proxy_base.__set__ at 0x7ff19ed28598>, '__imod__': <function proxy_base.__imod__ at 0x7ff19ed32c80>, '__mod__': <function proxy_base.__mod__ at 0x7ff19ed28e18>, '__and__': <function proxy_base.__and__ at 0x7ff19ed32158>, '__str__': <function proxy_base.__str__ at 0x7ff19ed30bf8>, '__rsub__': <function proxy_base.__rsub__ at 0x7ff19ed32378>, '__iand__': <function proxy_base.__iand__ at 0x7ff19ed32ea0>, '__rlshift__': <function proxy_base.__rlshift__ at 0x7ff19ed32730>, '__radd__': <function proxy_base.__radd__ at 0x7ff19ed322f0>, '__getitem__': <function proxy_base.__getitem__ at 0x7ff19ed28840>, '__delete__': <function proxy_base.__delete__ at 0x7ff19ed28620>, '__complex__': <function proxy_base.__complex__ at 0x7ff19ed372f0>, '__isub__': <function proxy_base.__isub__ at 0x7ff19ed32a60>, '__rmod__': <function proxy_base.__rmod__ at 0x7ff19ed32598>, '__truediv__': <function proxy_base.__truediv__ at 0x7ff19ed28d08>, '__rtruediv__': <function proxy_base.__rtruediv__ at 0x7ff19ed32488>, '__format__': <function proxy_base.__format__ at 0x7ff19ed30d08>, '__iadd__': <function proxy_base.__iadd__ at 0x7ff19ed329d8>})
__dir__()[source]
__divmod__(other)[source]
__enter__()[source]
__eq__(other)[source]
__exit__(exc_type, exc_value, traceback)[source]
__float__()[source]
__floordiv__(other)[source]
__format__(format_spec)[source]
__ge__(other)[source]
__get__(instance, owner)[source]
__getattr__(name)[source]
__getattribute__(name)[source]
__getitem__(item)[source]
__gt__(other)[source]
__hash__()[source]
__iadd__(other)[source]
__iand__(other)[source]
__ifloordiv__(other)[source]
__ilshift__(other)[source]
__imod__(other)[source]
__imul__(other)[source]
__index__()[source]
__int__()[source]
__invert__()[source]
__ior__(other)[source]
__ipow__(other, modulo=None)[source]
__irshift__(other)[source]
__isub__(other)[source]
__iter__()[source]
__itruediv__(other)[source]
__ixor__(other)[source]
__le__(other)[source]
__len__()[source]
__length_hint__()[source]
__lshift__(other)[source]
__lt__(other)[source]
__mod__(other)[source]
__module__ = 'padme'
__mul__(other)[source]
__ne__(other)[source]
__neg__()[source]
__or__(other)[source]
__pos__()[source]
__pow__(other, modulo=None)[source]
__radd__(other)[source]
__rand__(other)[source]
__rdivmod__(other)[source]
__repr__()[source]
__reversed__()[source]
__rfloordiv__(other)[source]
__rlshift__(other)[source]
__rmod__(other)[source]
__rmul__(other)[source]
__ror__(other)[source]
__round__(n)[source]
__rpow__(other)[source]
__rrshift__(other)[source]
__rshift__(other)[source]
__rsub__(other)[source]
__rtruediv__(other)[source]
__rxor__(other)[source]
__set__(instance, value)[source]
__setattr__(name, value)[source]
__setitem__(item, value)[source]
__str__()[source]
__sub__(other)[source]
__truediv__(other)[source]
__weakref__

list of weak references to the object (if defined)

__xor__(other)[source]
class padme.proxy_state(proxy_obj)[source]

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({'__dict__': <attribute '__dict__' of 'proxy_state' objects>, '__module__': 'padme', '__repr__': <function proxy_state.__repr__ at 0x7ff19ed37730>, '__init__': <function proxy_state.__init__ at 0x7ff19ed376a8>, '__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 ", '__weakref__': <attribute '__weakref__' of 'proxy_state' objects>})
__init__(proxy_obj)[source]
__module__ = 'padme'
__repr__()[source]
__weakref__

list of weak references to the object (if defined)

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/zyga/padme/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation

padme could always use more documentation, whether as part of the official padme docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/zyga/padme/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up padme for local development.

  1. Fork the padme repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/padme.git
    
  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv padme
    $ cd padme/
    $ python setup.py develop
    
  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature
    

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 padme
    $ python setup.py test
    $ tox
    

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
    $ git commit -m "Your detailed description of your changes."
    $ git push origin name-of-your-bugfix-or-feature
    
  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for Python 2.7, 3.2, 3.3, and 3.4, and for PyPy. Check https://travis-ci.org/zyga/padme/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ python -m unittest padme.tests

Credits

Development Lead

Contributors

None yet. Why not be the first?

History

1.1.1 (2015-03-04)

  • Add general support for Python 2.7.
  • All numeric methods are now supported with some methods exclusive to Python 2.x (__div__(), __coerce__(), __oct__(), __hex__()).
  • Add support for the new matrix multiplication operator @.
  • Make __nonzero__() and __unicode__() exlusive to Python 2.x.
  • Make __bool__() and __bytes__() exclusive to Python 3.x.
  • Make __length_hint() exclusive to Python 3.4.
  • Add support for the __cmp__() method, exclusive to Python 2.x.
  • Add support for accessing the proxied object with the new original() function.
  • Add support for accessing proxy state with the new state() function.
  • De-couple proxy classes from proxied objects, much more lightweight proxy design is possible this way (less objects, lower cost to create each new proxy).

1.0 (2014-02-11)

  • First release on PyPI.
  • Add a short introduction.
  • Enable travis-ci.org integration.
  • Remove numbering of generated meta-classes

2015

  • Released on PyPI as a part of plainbox as plainbox.impl.proxy

Indices and tables