Interface

Proxy Constructors

These constructors are available in the package:

Proxy(object,interface=None,passobj=None)

Returns a new Proxy instance that wraps object.

interface can be given as sequence of strings and/or objects with __name__ attribute or as dictionary with string keys (only the keys are currently used) and tells the Proxy to only allow access to these names. If not given or None, no filtering is done by the Proxy (see above on how access is managed).

passobj can be provided to retrieve the wrapped object from the Proxy at a later point using the .proxy_object() method.

InstanceProxy(object,interface=None,passobj=None)

Same as above, except that a Python instance wraps the Proxy object.

This makes the Proxy transparent for access to wrapped Python instances, meaning that the Proxy will act as if it were the wrapped object itself (with the added features mentioned above).

CachingInstanceProxy(object,interface=None,passobj=None)

Same as InstanceProxy(), except that a read cache is used by the Proxy which caches all queried attributes in the Proxy instance's dictionary.

Note that this may introduce circular references if not used properly. Cached attributes are not looked up in the wrapped instance after the first lookup -- if their value changes, this won't be noticed by objects that access the object through this wrapper.

SelectiveCachingInstanceProxy(object,interface=None,passobj=None)

Same as InstanceProxy(), except that a read cache is used by the Proxy which caches certain queried attributes in the Proxy instance's dictionary depending on their type.

The cached types are defined by the .proxy_cacheable_types attribute. It defaults to only cache Python methods.

MethodCachingProxy(object,interface=None,passobj=None)

Alias for SelectiveCachingInstanceProxy().

ReadonlyInstanceProxy(object,interface=None,passobj=None)

Same as InstanceProxy, except that write access will result in an AccessError being raised

ProxyFactory(Class,interface=None)

Returns a factory object for producing Class instances that are automatically wrapped using Proxy-instances.

interface is passed to the Proxy constructor, pass-objects are not supported.

InstanceProxyFactory(Class,interface=None)

Returns a factory object for producing Class instances that are automatically wrapped using InstanceProxy-instances.

WeakProxy(object,interface=None,passobj=None)

Returns a new weak referencing Proxy instance that points to object.

interface can be given as sequence of strings and/or objects with __name__ attribute or as dictionary with string keys (only the keys are currently used) and tells the Proxy to only allow access to these names. If not given or None, no filtering is done by the Proxy (see above on how access is managed).

passobj can be provided to retrieve the wrapped object from the Proxy at a later point using the .proxy_object() method.

For details on weak references and how they work, see the above discussion.

Proxy Instance Methods

A Proxy instance proxy defines these methods in addition to the ones available through restricted access to the wrapped object:

proxy_object(passobj)

Returns the wrapped object provided the given passobj is identical to the one used for creating the Proxy.

Simple equality is not enough -- it has to be the same object.

proxy_getattr(name)

Same as getattr(proxy,name).

proxy_setattr(name,value)

Same as setattr(proxy,name,value).

proxy_defunct()

Return 1 iff the referenced object has already been garbage collected.

Note that all attribute names starting with 'proxy_' are interpreted as being Proxy attributes and are not passed to the wrapped object. Access to these attributes is not subject to the restrictions explained above.

Proxy Instance Variables

Proxy instances do not provide any instance variables themselves. They do provide restricted access to the variables of the wrapped object though.

Note that all attribute names starting with 'proxy_' are interpreted as being Proxy attributes and are not passed to the wrapped object. Also, access to these attributes is not subject to the restrictions explained above.

Functions

These functions are available:

checkweakrefs()

Calling this function causes the global dictionary used for managing weak references to be checked for phantom objects. If such objects are found, they are garbage collected during the call and weak referencing Proxies pointing to them are defunct.

Weak references cause the objects to stay alive until either a proxy is used on them (causing an exception), a proxy referencing them is deleted or this function is called. To ensure the timely garbage collection of the objects, call this function at regular intervals.

Constants

These constants are available:

AccessError

Exception object used for access specific errors that the module raises. It is a subclass of exceptions.StandardError.

__weakrefs

Global dictionary for managing weak references. DO NOT MANIPULATE IN ANY WAY. Any changes would probably cause core dumps. Also, keeping references to objects in this dictionary is not allowed. It is merely exposed for the sake of debugging the weak reference mechanism.

Examples of Use

Here is a very simple one:

import Proxy

class DataRecord:
    a = 2
    b = 3
    # Make read-only:
    def __public_setattr__(self,what,to):
	  raise Proxy.AccessError,'read-only'
    # Cleanup protocol
    def __cleanup__(self):
	  print 'cleaning up',self

o = DataRecord()

# Wrap the instance:
p = Proxy.InstanceProxy(o,('a',))
# Remove o from the accessible system:
del o

print 'Read p.a through Proxy:',p.a

# This will cause an exception, because the object is read-only
p.a = 3

# This will cause an exception, because no access is given to .b
print p.b

# Clear all traces of the provious exceptions (they might contain
# references to p) by issuing another one. Note that not doing
# so will cause the following 'del p' to not destroy the final
# reference to p... (don't ask me why).
1/0

# Deleting the Proxy will also delete the wrapped object, if there
# is no other reference to it in the system. It will invoke
# the __cleanup__ method in that case.
del p

# If you want to have the wrapping done automatically, you can use
# the InstanceProxyFactory:
DataRecord = Proxy.InstanceProxyFactory(DataRecord,('a',))

# This gives the same behaviour...
p = DataRecord()
print p.a
p.a = 3
print p.b

More examples will eventually appear in the Examples subdirectory of the package.

Package Structure

[Proxy]
       Doc/
       Examples/
       [mxProxy]
       Proxy.py
	

Entries enclosed in brackets are packages (i.e. they are directories that include a __init__.py file). Ones without brackets are just simple subdirectories that are not accessible via import.

The package imports all symbols from the Proxy sub module which in turn imports the extension module, so you only need to 'import Proxy' to start working.

Installation

Copyright & Disclaimer

History & Future