Package twisted :: Package spread :: Module pb

[show private | hide private]
[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: 'connect' and 'IdentityConnector' will be gradually replaced with 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. There are no anticipated protocol-breaking changes before a complete finalization but we need more users before we can be totally sure of that.

# 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<mailto:glyph@twistedmatrix.com>

Classes
`AsReferenceable` | AsReferenceable: a reference directed towards another object.
`AuthChallenger` | XXX
`AuthRoot` | I provide AuthServs as root objects to Brokers for a BrokerFactory.
`AuthServ` | XXX
`Broker` | I am a broker for objects.
`BrokerClientFactory` |
`BrokerFactory` | I am a server for object brokerage.
`CopiedFailure` |
`CopyableFailure` | A `flavors.RemoteCopy` and `flavors.Copyable` version of `twisted.python.failure.Failure`for serialization.
`IdentityConnector` | I support connecting to multiple Perspective Broker services that are in a service tree.
`IdentityWrapper` | I delegate most functionality to a `twisted.cred.identity.Identity`.
`Local` | (internal) A reference to a local object.
`Perspective` | A perspective on a service.
`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
| ``authIdentity`(authServRef, username, password)` Return a Deferred which will do the challenge-response dance and return a remote Identity reference.
| ``connect`(host, port, username, password, serviceName, perspectiveName, client, timeout)` Connects and authenticates, then retrieves a PB service.
| `failure2Copyable(fail)`
| ``getObjectAt`(host, port, timeout)` Establishes a PB connection and returns with a `RemoteReference`.
| ``getObjectAtSSL`(host, port, timeout)` Establishes a PB connection over SSL and returns with a RemoteReference.
| ``getObjectRetriever`()` Get a factory which retreives a root object from its client
| ``logIn`(authServRef, client, service, username, password, perspectiveName)` I return a Deferred which will be called back with a Perspective.
| ``noOperation`(*args, **kw)` Do nothing.
| ``printTraceback`(tb)` Print a traceback (string) to the standard log.

Variable Summary
`str` | `__version__`
`dict` | `copyTags`
`SecurityOptions` | `globalSecurity`
`int` | `MAX_BROKER_REFS`
`_Feature` | `nested_scopes`
`int` | `portno`
`SelectReactor` | `reactor`

Function Details

### authIdentity(authServRef, username, password)

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

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

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)

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)

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)
  Returns:
    A Deferred which will be passed a remote reference to the root object of a PB server.x

### getObjectRetriever()

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)

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.

Variable Details

### __version__

  Type:
    `str`
  Value:

        '1.124'

### copyTags

  Type:
    `dict`
  Value:

        {'cached': <function unjellyCached at 0x848b854>,
         'lcache': <function unjellyLCache at 0x848b88c>,
         'local': <function unjellyLocal at 0x847616c>,
         'remote': <class twisted.spread.pb.RemoteReference at 0x844040c>,
         'twisted.spread.pb.CopyableFailure': <class twisted.spread.pb.CopiedF\
        ailure at 0x8344ec4>,
         'twisted.web.server.Request': <class twisted.web.distrib.Request at 0\
        x86cfaec>}

### globalSecurity

  Type:
    `SecurityOptions`
  Value:

        <twisted.spread.jelly.SecurityOptions instance at 0x838d2a4>

### MAX_BROKER_REFS

  Type:
    `int`
  Value:

        1024

### nested_scopes

  Type:
    `_Feature`
  Value:

        _Feature((2, 1, 0, 'beta', 1), (2, 2, 0, 'alpha', 0), 16)

### portno

  Type:
    `int`
  Value:

        8787

### reactor

  Type:
    `SelectReactor`
  Value:

        <twisted.internet.default.SelectReactor instance at 0x82e8c8c>

Generated by Epydoc 1.1 on Thu May 8 13:16:53 2003 | http://epydoc.sf.net