module documentation

Perspective Broker

"This isn't a professional opinion, but it's probably got enough internet to kill you." --glyph

Introduction

This is a broker for proxies for and copies of objects. It provides a translucent interface layer to those proxies.

The protocol is not opaque, because it provides objects which represent the remote proxies and require no context (server references, IDs) to operate on.

It is not transparent because it does not attempt to make remote objects behave identically, or even similarly, to local objects. Method calls are invoked asynchronously, and specific rules are applied when serializing arguments.

To get started, begin with PBClientFactory and PBServerFactory.

Author
Glyph Lefkowitz
Interface IPBRoot Factory for root Referenceable objects for PB servers.
Interface IPerspective per*spec*tive, n. : The relationship of aspects of a subject to each other and to a whole: 'a perspective of history'; 'a need to view the problem in the proper perspective'.
Interface IUsernameMD5Password I encapsulate a username and a hashed password.
Class AsReferenceable A reference directed towards another object.
Class Avatar A default IPerspective implementor.
Class Broker I am a broker for objects.
Class Cacheable A cached instance.
Class Copyable Subclass me to get copied each time you are returned from or passed to a remote method.
Class Jellyable Inherit from me to Jelly yourself directly with the `getStateFor' convenience method.
Class Local (internal) A reference to a local object.
Class PBClientFactory Client factory for PB brokers.
Class PBServerFactory Server factory for perspective broker.
Class Referenceable No class docstring; 1/1 class variable, 2/2 methods documented
Class RemoteCache A cache is a local representation of a remote Cacheable object.
Class RemoteCacheObserver I am a reverse-reference to the peer's RemoteCache.
Class RemoteCopy I am a remote copy of a Copyable object.
Class RemoteMethod This is a translucent reference to a remote message.
Class RemoteReference A translucent reference to a remote object.
Class Root I provide a root object to pb.Brokers for a pb.PBClientFactory or pb.PBServerFactory.
Class Serializable An object that can be passed remotely.
Class Viewable I will be converted to a ViewPoint when passed to or returned from a remote method.
Class ViewPoint I act as an indirect reference to an object accessed through a pb.IPerspective.
Exception CopiedFailure A CopiedFailure is a pb.RemoteCopy of a failure.Failure transferred via PB.
Exception CopyableFailure A flavors.RemoteCopy and flavors.Copyable version of twisted.python.failure.Failure for serialization.
Exception DeadReferenceError This error is raised when a method is called on a dead reference (one whose broker has been disconnected).
Exception Error This error can be raised to generate known error conditions.
Exception NoSuchMethod Raised if there is no such remote method
Exception PBConnectionLost Undocumented
Exception ProtocolError This error is raised when an invalid protocol statement is received.
Exception RemoteError This class is used to wrap a string-ified exception from the remote side to be able to reraise it. (Raising string exceptions is no longer possible in Python 2.6+)
Function challenge No summary
Function failure2Copyable Undocumented
Function respond Respond to a challenge.
Function setCopierForClass Set which local class will represent a remote type.
Function setCopierForClassTree Set all classes in a module derived from baseClass as copiers for a corresponding remote class.
Function setFactoryForClass Set the factory to construct a remote instance of a type:
Constant MAX_BROKER_REFS Undocumented
Variable copyTags Undocumented
Variable portno Undocumented
Class _JellyableAvatarMixin Helper class for code which deals with avatars which PB must be capable of sending to a peer.
Class _PortalAuthChallenger Called with response to password challenge.
Class _PortalRoot Root object, used to login to portal.
Class _PortalWrapper Root Referenceable object, used to login to portal.
def challenge(): (source)
Returns
Some random data.
def failure2Copyable(fail, unsafeTracebacks=0): (source)

Undocumented

def respond(challenge, password): (source)

Respond to a challenge.

This is useful for challenge/response authentication.

Parameters
challengeA challenge.
passwordA password.
Returns
The password hashed twice.
def setCopierForClass(classname, unjellyable): (source)

Set which local class will represent a remote type.

If you have written a Copyable class that you expect your client to be receiving, write a local "copy" class to represent it, then call:

    jellier.setUnjellyableForClass('module.package.Class', MyCopier).

Call this at the module level immediately after its class definition. MyCopier should be a subclass of RemoteCopy.

The classname may be a special tag returned by 'Copyable.getTypeToCopyFor' rather than an actual classname.

This call is also for cached classes, since there will be no overlap. The rules are the same.

def setCopierForClassTree(module, baseClass, prefix=None): (source)

Set all classes in a module derived from baseClass as copiers for a corresponding remote class.

When you have a hierarchy of Copyable (or Cacheable) classes on one side, and a mirror structure of Copied (or RemoteCache) classes on the other, use this to setUnjellyableForClass all your Copieds for the Copyables.

Each copyTag (the "classname" argument to getTypeToCopyFor, and what the Copyable's getTypeToCopyFor returns) is formed from adding a prefix to the Copied's class name. The prefix defaults to module.__name__. If you wish the copy tag to consist of solely the classname, pass the empty string ''.

Parameters
modulea module object from which to pull the Copied classes. (passing sys.modules[__name__] might be useful)
baseClassthe base class from which all your Copied classes derive.
prefixthe string prefixed to classnames to form the unjellyableRegistry.
def setFactoryForClass(classname, copyFactory): (source)

Set the factory to construct a remote instance of a type:

  jellier.setUnjellyableFactoryForClass('module.package.Class', MyFactory)

Call this at the module level immediately after its class definition. copyFactory should return an instance or subclass of RemoteCopy.

Similar to setUnjellyableForClass except it uses a factory instead of creating an instance.

MAX_BROKER_REFS: int = (source)

Undocumented

Value
1024
copyTags: dict = (source)

Undocumented

Undocumented