Package twisted :: Package spread :: Module pb

[frames | no frames]

## Module twisted.spread.pb

Perspective Broker

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

Stability: semi-stable

Future Plans: The connection APIs will be extended with support for URLs, that will be able to extend resource location and discovery conversations and specify different authentication mechanisms besides username/password. This should only add to, and not change, the existing protocol.

# Important Changes

New APIs have been added for serving and connecting. On the client side, use PBClientFactory.getPerspective() instead of connect(), and PBClientFactory.getRootObject() instead of getObjectAt(). Server side should switch to updated cred APIs by using PBServerFactory, at which point clients would switch to PBClientFactory.login().

The new cred support means a different method is sent for login, although the protocol is compatible on the binary level. When we switch to pluggable credentials this will introduce another change, although the current change will still be supported.

The Perspective class is now deprecated, and has been replaced with Avatar, which does not rely on the old cred APIs.

# 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 similiarly, to local objects. Method calls are invoked asynchronously, and specific rules are applied when serializing arguments.

Author: Glyph Lefkowitz

Classes
`_Detacher` | DEPRECATED.
`_ObjectRetrieval` | DEPRECATED.
`_PortalAuthChallenger` | Called with response to password challenge.
`_PortalRoot` | Root object, used to login to portal.
`_PortalWrapper` | Root Referenceable object, used to login to portal.
`_RemoteCacheDummy` | Ignore.
`AsReferenceable` | AsReferenceable: a reference directed towards another object.
`AuthChallenger` | DEPRECATED.
`AuthRoot` | DEPRECATED.
`AuthServ` | DEPRECATED.
`Avatar` | A default IPerspective implementor.
`Broker` | I am a broker for objects.
`BrokerClientFactory` |
`BrokerFactory` | DEPRECATED, use PBServerFactory instead.
`CopiedFailure` |
`CopyableFailure` | A `flavors.RemoteCopy` and `flavors.Copyable` version of `twisted.python.failure.Failure` for serialization.
`IdentityConnector` | DEPRECATED.
`IdentityWrapper` | DEPRECATED.
`IPerspective` | per*spec*tive, n.
`IUsernameMD5Password` | I encapsulate a username and a hashed password.
`Local` | (internal) A reference to a local object.
`PBClientFactory` | Client factory for PB brokers.
`PBServerFactory` | Server factory for perspective broker.
`Perspective` | This class is DEPRECATED, because it relies on old cred APIs.
`RemoteMethod` | This is a translucent reference to a remote message.
`RemoteReference` | This is a translucent reference to a remote object.
`Service` | A service for Perspective Broker.

Exceptions
`DeadReferenceError` | This error is raised when a method is called on a dead reference (one whose broker has been disconnected).
`Error` | This error can be raised to generate known error conditions.
`PBConnectionLost` |
`ProtocolError` | This error is raised when an invalid protocol statement is received.

Function Summary
| `_cbLogInRespond((challenge, challenger), d, client, service, password, perspectiveName)`
| `_cbLogInResponded(identity, d, client, serviceName, perspectiveName)`
| `_cbRespondToChallenge((challenge, challenger), password, d)`
| `_connGotRoot(root, d, client, serviceName, username, password, perspectiveName)`
| ``authIdentity`(authServRef, username, password)` DEPRECATED.
| ``challenge`()` I return some random data.
| ``connect`(host, port, username, password, serviceName, perspectiveName, client, timeout)` DEPRECATED.
| `failure2Copyable(fail, unsafeTracebacks)`
| ``getObjectAt`(host, port, timeout)` DEPRECATED.
| ``getObjectAtSSL`(host, port, timeout, contextFactory)` DEPRECATED.
| ``getObjectRetriever`()` DEPRECATED.
| ``logIn`(authServRef, client, service, username, password, perspectiveName)` DEPRECATED.
| ``noOperation`(*args, **kw)` Do nothing.
| ``printTraceback`(tb)` Print a traceback (string) to the standard log.
| ``respond`(challenge, password)` Respond to a challenge.

Variable Summary
`str` | `__version__` = `'1.157'`
`int` | `MAX_BROKER_REFS` = 1024
`int` | `portno` = 8787

Function Details

### authIdentity(authServRef, username, password)

DEPRECATED. Return a Deferred which will do the challenge-response dance and return a remote Identity reference.

### challenge()

I return some random data.

### connect(host, port, username, password, serviceName, perspectiveName=None, client=None, timeout=None)

DEPRECATED. Connects and authenticates, then retrieves a PB service.

Required arguments:

- host -- the host the service is running on
- port -- the port on the host to connect to
- username -- the name you will be identified as to the authorizer
- password -- the password for this username
- serviceName -- name of the service to request

Optional (keyword) arguments:

- perspectiveName -- the name of the perspective to request, if different than the username
- client -- XXX the "reference" argument to perspective.Perspective.attached
- timeout -- see twisted.internet.tcp.Client

  Returns:
    A Deferred instance that gets a callback when the final Perspective is connected, and an errback when an error occurs at any stage of connecting.

### getObjectAt(host, port, timeout=None)

DEPRECATED. Establishes a PB connection and returns with a `RemoteReference`.

  Parameters:
    `host` - the host to connect to
    `port` - the port number to connect to
    `timeout` - a value in milliseconds to wait before failing by default. (OPTIONAL)
  Returns:
    A Deferred which will be passed a remote reference to the root object of a PB server.x

### getObjectAtSSL(host, port, timeout=None, contextFactory=None)

DEPRECATED. Establishes a PB connection over SSL and returns with a RemoteReference.

  Parameters:
    `host` - the host to connect to
    `port` - the port number to connect to
    `timeout` - a value in milliseconds to wait before failing by default. (OPTIONAL)
    `contextFactory` - A factory object for producing SSL.Context objects. (OPTIONAL)
  Returns:
    A Deferred which will be passed a remote reference to the root object of a PB server.

### getObjectRetriever()

DEPRECATED.

Get a factory which retreives a root object from its client

  Returns:
    A pair: A ClientFactory and a Deferred which will be passed a remote reference to the root object of a PB server.x

### logIn(authServRef, client, service, username, password, perspectiveName=None)

DEPRECATED. I return a Deferred which will be called back with a Perspective.

### noOperation(*args, **kw)

Do nothing.

Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit...

### printTraceback(tb)

Print a traceback (string) to the standard log.

### respond(challenge, password)

Respond to a challenge.

This is useful for challenge/response authentication.

Variable Details

### __version__

  Type:
    `str`
  Value:

        '1.157'

### MAX_BROKER_REFS

  Type:
    `int`
  Value:

        1024

### portno

  Type:
    `int`
  Value:

        8787

Generated by Epydoc 2.0 on Sat May 15 20:08:16 2004 | http://epydoc.sf.net