twisted.spread.pb

module documentation

(source)

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`	perspective, 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	`CopiedFailure`	A `CopiedFailure` is a `pb.RemoteCopy` of a `failure.Failure` transferred via PB.
Class	`Copyable`	Subclass me to get copied each time you are returned from or passed to a remote method.
Class	`CopyableFailure`	A `flavors.RemoteCopy` and `flavors.Copyable` version of `twisted.python.failure.Failure` for serialization.
Class	`DeadReferenceError`	This error is raised when a method is called on a dead reference (one whose broker has been disconnected).
Class	`Error`	This error can be raised to generate known error conditions.
Class	`Jellyable`	Inherit from me to Jelly yourself directly with the `getStateFor' convenience method.
Class	`Local`	(internal) A reference to a local object.
Class	`NoSuchMethod`	Raised if there is no such remote method
Class	`PBClientFactory`	Client factory for PB brokers.
Class	`PBConnectionLost`	Undocumented
Class	`PBServerFactory`	Server factory for perspective broker.
Class	`ProtocolError`	This error is raised when an invalid protocol statement is received.
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	`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+)
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.Broker`s 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`.
Function	`challenge`
Function	`failure2Copyable`	Undocumented
Function	`respond`	Respond to a challenge.
Function	`setUnjellyableFactoryForClass`	Set the factory to construct a remote instance of a type:
Function	`setUnjellyableForClass`	Set which local class will represent a remote type.
Function	`setUnjellyableForClassTree`	Set all classes in a module derived from `baseClass` as copiers for a corresponding remote class.
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
challenge	A challenge.
password	A password.
Returns
The password hashed twice.

def setUnjellyableFactoryForClass(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.

def setUnjellyableForClass(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 setUnjellyableForClassTree(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
module	a module object from which to pull the Copied classes. (passing sys.modules[__name__] might be useful)
baseClass	the base class from which all your Copied classes derive.
prefix	the string prefixed to classnames to form the unjellyableRegistry.

MAX_BROKER_REFS: int = (source)

Undocumented

Value

copyTags: dict = (source)

Undocumented

portno: int = (source)

Undocumented