twisted.protocols.amp.BoxDispatcher

class documentation

class BoxDispatcher: (source)

Known subclasses: twisted.protocols.amp.AMP

Implements interfaces: twisted.protocols.amp.IBoxReceiver

A BoxDispatcher dispatches '_ask', '_answer', and '_error' AmpBoxes, both incoming and outgoing, to their appropriate destinations.

Outgoing commands are converted into Deferreds and outgoing boxes, and associated tracking state to fire those Deferred when '_answer' boxes come back. Incoming '_answer' and '_error' boxes are converted into callbacks and errbacks on those Deferreds, respectively.

Incoming '_ask' boxes are converted into method calls on a supplied method locator.

Method	`__init__`	Undocumented
Method	`ampBoxReceived`	An AmpBox was received, representing a command, or an answer to a previously issued command (either successful or erroneous). Respond to it according to its contents.
Method	`callRemote`	This is the primary high-level API for sending messages via AMP. Invoke it with a command and appropriate arguments to send a message to this connection's peer.
Method	`callRemoteString`	This is a low-level API, designed only for optimizing simple messages for which the overhead of parsing is too great.
Method	`dispatchCommand`	A box with a _command key was received.
Method	`failAllOutgoing`	Call the errback on all outstanding requests awaiting responses.
Method	`startReceivingBoxes`	The given boxSender is going to start calling boxReceived on this `BoxDispatcher`.
Method	`stopReceivingBoxes`	No further boxes will be received here. Terminate all currently outstanding command deferreds with the given reason.
Method	`unhandledError`	This is a terminal callback called after application code has had a chance to quash any errors.
Instance Variable	`boxSender`	an object which can send boxes, via the `_sendBoxCommand` method, such as an `AMP` instance.
Instance Variable	`locator`	an object with a `CommandLocator.locateResponder` method that locates a responder function that takes a Box and returns a result (either a Box or a Deferred which fires one).
Method	`_answerReceived`	An AMP box was received that answered a command previously sent with `callRemote`.
Method	`_commandReceived`
Method	`_errorReceived`	An AMP box was received that answered a command previously sent with `callRemote`, with an error.
Method	`_nextTag`	Generate protocol-local serial numbers for _ask keys.
Method	`_safeEmit`	Emit a box, ignoring `ProtocolSwitched` and `ConnectionLost` errors which cannot be usefully handled.
Method	`_sendBoxCommand`	Send a command across the wire with the given `amp.Box`.
Class Variable	`_counter`	Undocumented
Instance Variable	`_failAllReason`	Undocumented
Instance Variable	`_outstandingRequests`	a dictionary mapping request IDs to `Deferred`s which were returned for those requests.

def __init__(self, locator): (source)

overridden in twisted.protocols.amp.AMP

Undocumented

def ampBoxReceived(self, box): (source)

from twisted.protocols.amp.IBoxReceiver

An AmpBox was received, representing a command, or an answer to a previously issued command (either successful or erroneous). Respond to it according to its contents.

Parameters
box	an AmpBox
Raises
`NoEmptyBoxes`	when a box is received that does not contain an '_answer', '_command' / '_ask', or '_error' key; i.e. one which does not fit into the command / response protocol defined by AMP.

def callRemote(self, commandType, *a, **kw): (source)

This is the primary high-level API for sending messages via AMP. Invoke it with a command and appropriate arguments to send a message to this connection's peer.

Parameters
commandType:`type`	a subclass of Command.
a	Positional (special) parameters taken by the command. Positional parameters will typically not be sent over the wire. The only command included with AMP which uses positional parameters is `ProtocolSwitchCommand`, which takes the protocol that will be switched to as its first argument.
kw	Keyword arguments taken by the command. These are the arguments declared in the command's 'arguments' attribute. They will be encoded and sent to the peer as arguments for the `commandType`.
Returns
If `commandType` has a `requiresAnswer` attribute set to `False`, then return `None`. Otherwise, return a `Deferred` which fires with a dictionary of objects representing the result of this call. Additionally, this `Deferred` may fail with an exception representing a connection failure, with `UnknownRemoteError` if the other end of the connection fails for an unknown reason, or with any error specified as a key in `commandType`'s `errors` dictionary.

def callRemoteString(self, command, requiresAnswer=True, **kw): (source)

This is a low-level API, designed only for optimizing simple messages for which the overhead of parsing is too great.

Parameters
command	a `bytes` naming the command.
requiresAnswer	a boolean. Defaults to True. If True, return a Deferred which will fire when the other side responds to this command. If False, return None and do not ask the other side for acknowledgement.
kw	arguments to the amp box.
Returns
a Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer.

def dispatchCommand(self, box): (source)

A box with a _command key was received.

Dispatch it to a local handler call it.

Parameters
box	an AmpBox to be dispatched.

def failAllOutgoing(self, reason): (source)

Call the errback on all outstanding requests awaiting responses.

Parameters
reason	the Failure instance to pass to those errbacks.

def startReceivingBoxes(self, boxSender): (source)

from twisted.protocols.amp.IBoxReceiver

The given boxSender is going to start calling boxReceived on this BoxDispatcher.

Parameters
boxSender	The `IBoxSender` to send command responses to.

def stopReceivingBoxes(self, reason): (source)

from twisted.protocols.amp.IBoxReceiver

No further boxes will be received here. Terminate all currently outstanding command deferreds with the given reason.

def unhandledError(self, failure): (source)

This is a terminal callback called after application code has had a chance to quash any errors.

boxSender: IBoxSender = (source)

an object which can send boxes, via the _sendBoxCommand method, such as an AMP instance.

locator = (source)

an object with a CommandLocator.locateResponder method that locates a responder function that takes a Box and returns a result (either a Box or a Deferred which fires one).

def _answerReceived(self, box): (source)

An AMP box was received that answered a command previously sent with callRemote.

Parameters
box	an AmpBox with a value for its `ANSWER` key.

def _commandReceived(self, box): (source)

Parameters
box	an `AmpBox` with a value for its `COMMAND` and `ASK` keys.

def _errorReceived(self, box): (source)

An AMP box was received that answered a command previously sent with callRemote, with an error.

Parameters
box	an `AmpBox` with a value for its `ERROR`, `ERROR_CODE`, and `ERROR_DESCRIPTION` keys.

def _nextTag(self): (source)

Generate protocol-local serial numbers for _ask keys.

Returns
a string that has not yet been used on this connection.

def _safeEmit(self, aBox): (source)

Emit a box, ignoring ProtocolSwitched and ConnectionLost errors which cannot be usefully handled.

def _sendBoxCommand(self, command, box, requiresAnswer=True): (source)

Send a command across the wire with the given amp.Box.

Mutate the given box to give it any additional keys (_command, _ask) required for the command and request/response machinery, then send it.

If requiresAnswer is True, returns a Deferred which fires when a response is received. The Deferred is fired with an amp.Box on success, or with an amp.RemoteAmpError if an error is received.

If the Deferred fails and the error is not handled by the caller of this method, the failure will be logged and the connection dropped.

Parameters
command	a `bytes`, the name of the command to issue.
box	an AmpBox with the arguments for the command.
requiresAnswer	a boolean. Defaults to True. If True, return a Deferred which will fire when the other side responds to this command. If False, return None and do not ask the other side for acknowledgement.
Returns
a Deferred which fires the AmpBox that holds the response to this command, or None, as specified by requiresAnswer.
Raises
`ProtocolSwitched`	if the protocol has been switched.

_counter: int = (source)

Undocumented

_failAllReason = (source)

Undocumented

_outstandingRequests = (source)

a dictionary mapping request IDs to Deferreds which were returned for those requests.