Skip to main content

General purpose proxy and wrapper types

Project description

The objproxies module provides some useful base classes for creating proxies and wrappers for ordinary Python objects. Proxy objects automatically delegate all attribute access and operations to the proxied object. Wrappers are similar, but can be subclassed to allow additional attributes and operations to be added to the wrapped object.

Note that these proxy types are not intended to be tamper-proof; the unproxied form of an object can be readily accessed using a proxy’s __subject__ attribute, and some proxy types even allow this attribute to be set. (This can be handy for algorithms that lazily create circular structures and thus need to be able to hand out “forward reference” proxies.)

Development status

At the moment this is a straightforward Python 3 port of ProxyTypes wrote by Phillip J. Eby for a part of PEAK.

The namespace was changed from peak.util.proxies to objproxies. Other than that it should be a compatible replacement.

So far the following was accomplished:

  • Streamlined files and setup
  • Ported unittests and doctests
  • Cleaned up syntax


  • Add test for the various Wrappers
  • Turn the module in a package, separate functionalities in different modules
  • Make sure that any new Python 3 magic method is supported
  • Simplify code wherever possible

Contributions and bug reports are welcome.

Proxy Basics

Here’s a quick demo of the ObjectProxy type:

>>> from objproxies import ObjectProxy
>>> p = ObjectProxy(42)

>>> p

>>> isinstance(p, int)

>>> p.__class__
<class 'int'>

>>> p*2

>>> 'X' * p

>>> hex(p)

>>> chr(p)

>>> p ^ 1

>>> p ** 2

As you can see, a proxy is virtually indistinguishable from the object it proxies, except via its __subject__ attribute, and its type():

>>> p.__subject__

>>> type(p)
<class 'objproxies.ObjectProxy'>

You can change the __subject__ of an ObjectProxy, and it will then refer to something else:

>>> p.__subject__ = 99
>>> p
>>> p-33

>>> p.__subject__ = "foo"
>>> p

All operations are delegated to the subject, including setattr and delattr:

>>> class Dummy: pass
>>> d = Dummy()
>>> p = ObjectProxy(d)

>>> = "bar"

>>> del
>>> hasattr(d,'foo')

Callback Proxies

Sometimes, you may want a proxy’s subject to be determined dynamically whenever the proxy is used. For this purpose, you can use the CallbackProxy type, which accepts a callback function and creates a proxy that will invoke the callback in order to get the target. Here’s a quick example of a counter that gets incremented each time it’s used, from zero to three:

>>> from objproxies import CallbackProxy

>>> callback = iter(range(4)).__next__
>>> counter = CallbackProxy(callback)

>>> counter
>>> counter
>>> str(counter)
>>> hex(counter)

>>> counter
Traceback (most recent call last):

As you can see, the callback is automatically invoked on any attempt to use the proxy. This is a somewhat silly example; a better one would be something like a thread_id proxy that is always equal to the ID # of the thread it’s running in.

A callback proxy’s callback can be obtained or changed via the get_callback and set_callback functions:

>>> from objproxies import get_callback, set_callback
>>> set_callback(counter, lambda: 42)

>>> counter

>>> type(get_callback(counter))
<class 'function'>

Lazy Proxies

A LazyProxy is similar to a DynamicProxy, but its callback is called at most once, and then cached:

>>> from objproxies import LazyProxy

>>> def callback():
...     print("called")
...     return 42

>>> lazy = LazyProxy(callback)
>>> lazy
>>> lazy

You can use the get_callback and set_callback functions on lazy proxies, but it has no effect if the callback was already called:

>>> set_callback(lazy, lambda: 99)
>>> lazy

But you can use the get_cache and set_cache functions to tamper with the cached value:

>>> from objproxies import get_cache, set_cache
>>> get_cache(lazy)
>>> set_cache(lazy, 99)
>>> lazy


The ObjectWrapper, CallbackWrapper and LazyWrapper classes are similar to their proxy counterparts, except that they are intended to be subclassed in order to add custom extra attributes or methods. Any attribute that exists in a subclass of these classes will be read or written from the wrapper instance, instead of the wrapped object. For example:

>>> from objproxies import ObjectWrapper
>>> class NameWrapper(ObjectWrapper):
...     name = None
...     def __init__(self, ob, name):
...         ObjectWrapper.__init__(self, ob)
... = name
...     def __str__(self):
...         return

>>> w = NameWrapper(42, "The Ultimate Answer")
>>> w

>>> print(w)
The Ultimate Answer

>>> w * 2

'The Ultimate Answer'

Notice that any attributes you add must be defined in the class. You can’t add arbitrary attributes at runtime, because they’ll be set on the wrapped object instead of the wrapper:

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

Note that this means that all instance attributes must be implemented as either slots, properties, or have a default value defined in the class body (like the name = None shown in the example above.

The CallbackWrapper and LazyWrapper base classes are basically the same as ObjectWrapper, except that they use a callback or cached lazy callback instead of expecting an object as their subject.

Creating Custom Subclasses and Mixins

In addition to all the concrete classes described above, there are also two abstract base classes: AbstractProxy and AbstractWrapper. If you want to create a mixin type that can be used with any of the concrete types, you should subclass the abstract version and set __slots__ to an empty list:

>>> from objproxies import AbstractWrapper

>>> class NamedMixin(AbstractWrapper):
...     __slots__ = []
...     name = None
...     def __init__(self, ob, name):
...         super(NamedMixin, self).__init__(ob)
... = name
...     def __str__(self):
...         return

Then, when you mix it in with the respective base class, you can add back in any necessary slots, or leave off __slots__ to give the subclass instances a dictionary of their own:

>>> from objproxies import CallbackWrapper, LazyWrapper

>>> class NamedObject(NamedMixin, ObjectWrapper): pass
>>> class NamedCallback(NamedMixin, CallbackWrapper): pass
>>> class NamedLazy(NamedMixin, LazyWrapper): pass

>>> print(NamedObject(42, "The Answer"))
The Answer

>>> n = NamedCallback(callback, "Test")
>>> n
>>> n

>>> n = NamedLazy(callback, "Once")
>>> n
>>> n

Both the AbstractProxy and AbstractWrapper base classes work by assuming that self.__subject__ will be the wrapped or proxed object. If you don’t want to use any of the standard three ways of defining __subject__ (i.e., as an object, callback, or lazy callback), you will need to subclass AbstractProxy or AbstractWrapper and provide your own way of defining __subject__.

Project details

Release history Release notifications

History Node


History Node


History Node


This version
History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
objproxies-0.9.1.linux-x86_64.tar.gz (8.0 kB) Copy SHA256 hash SHA256 Dumb Binary any Jun 14, 2014
objproxies-0.9.1.tar.gz (6.2 kB) Copy SHA256 hash SHA256 Source None Jun 14, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page