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.

Let’s consider a simple example:

>>> pets = ['cat', 'dog', 'fish']
>>> pets_proxy = proxy(pets)
>>> pets_proxy
['cat', 'dog', 'fish']
>>> isinstance(pets_proxy, list)
>>> pets_proxy.append('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 @unproxied.

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):
...     @unproxied
...     def __repr__(self):
...         return super(censor_cat, self).__repr__().replace('cat', '***')

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).

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

The type() function:

>>> type(pets_proxy)  
<class 'padme...boundproxy'>

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

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

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.


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


class padme.proxy[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 = ['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
>>> type(lie) is type(truth)

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] = '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 @unproxied decorator on them.

>>> import codecs
>>> class crypto(proxy):
...     @unproxied
...     def __repr__(self):
...         return codecs.encode(super().__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 = ['ala ma kota', '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']

alias of proxy_meta


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.


Initialize self. See help(type(self)) for accurate signature.

static __new__(proxy_cls, proxiee)[source]

Create a new instance of proxy() wrapping proxiee

Parameters:proxiee – The object to proxy
Returns:An instance of new subclass of proxy, called boundproxy that uses a new meta-class that lexically bounds the proxiee argument. The new sub-class has a different implementation of __new__ and can be instantiated without additional arguments.

helper for pickle


helper for pickle

__sizeof__() → int

size of object in memory, in bytes


Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).


list of weak references to the object (if defined)


Mark an object (attribute) as not-to-be-proxied.

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


class padme.proxy_meta[source]

Meta-class for all proxy types

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


Make a new bound proxy meta-class for the specified object

Parameters:proxiee – The object that will be proxied
Returns:A new meta-class that lexically wraps proxiee 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__()