twisted.protocols.amp.Command class documentation

Part of twisted.protocols.amp View Source (View In Hierarchy)

Known subclasses: twisted.protocols.amp.ProtocolSwitchCommand, twisted.protocols.amp.StartTLS, twisted.trial._dist.managercommands.AddError, twisted.trial._dist.managercommands.AddExpectedFailure, twisted.trial._dist.managercommands.AddFailure, twisted.trial._dist.managercommands.AddSkip, twisted.trial._dist.managercommands.AddSuccess, twisted.trial._dist.managercommands.AddUnexpectedSuccess, twisted.trial._dist.managercommands.TestWrite, twisted.trial._dist.workercommands.Run, twisted.trial._dist.workercommands.Start

Subclass me to specify an AMP Command.

Class Variable arguments A list of 2-tuples of (name, Argument-subclass-instance), specifying the names and values of the parameters which are required for this command.
Class Variable response A list like arguments, but instead used for the return value.
Class Variable errors A mapping of subclasses of Exception to wire-protocol tags for errors represented as strs. Responders which raise keys from this dictionary will have the error translated to the corresponding tag on the wire. Invokers which receive Deferreds from invoking this command with BoxDispatcher.callRemote will potentially receive Failures with keys from this mapping as their value. This mapping is inherited; if you declare a command which handles FooError as 'FOO_ERROR', then subclass it and specify BarError as 'BAR_ERROR', responders to the subclass may raise either FooError or BarError, and invokers must be able to deal with either of those exceptions.
Class Variable fatalErrors like 'errors', but errors in this list will always terminate the connection, despite being of a recognizable error type.
Class Variable commandType The type of Box used to issue commands; useful only for protocol-modifying behavior like startTLS or protocol switching. Defaults to a plain vanilla Box.
Class Variable responseType The type of Box used to respond to this command; only useful for protocol-modifying behavior like startTLS or protocol switching. Defaults to a plain vanilla Box.
Instance Variable requiresAnswer a boolean; defaults to True. Set it to False on your subclass if you want callRemote to return None. Note: this is a hint only to the client side of the protocol. The return-type of a command responder method must always be a dictionary adhering to the contract specified by response, because clients are always free to request a response if they want one.
Class __metaclass__ Metaclass hack to establish reverse-mappings for 'errors' and 'fatalErrors' as class vars.
Method __init__ Create an instance of this command with specified values for its parameters.
Class Method makeResponse Serialize a mapping of arguments using this Command's response schema.
Class Method makeArguments Serialize a mapping of arguments using this Command's argument schema.
Class Method parseResponse Parse a mapping of serialized arguments using this Command's response schema.
Class Method parseArguments Parse a mapping of serialized arguments using this Command's argument schema.
Class Method responder Declare a method to be a responder for a particular command.
Method _doCommand Encode and send this Command to the given protocol.
arguments =
A list of 2-tuples of (name, Argument-subclass-instance), specifying the names and values of the parameters which are required for this command.
response =
A list like arguments, but instead used for the return value.
errors =
A mapping of subclasses of Exception to wire-protocol tags for errors represented as strs. Responders which raise keys from this dictionary will have the error translated to the corresponding tag on the wire. Invokers which receive Deferreds from invoking this command with BoxDispatcher.callRemote will potentially receive Failures with keys from this mapping as their value. This mapping is inherited; if you declare a command which handles FooError as 'FOO_ERROR', then subclass it and specify BarError as 'BAR_ERROR', responders to the subclass may raise either FooError or BarError, and invokers must be able to deal with either of those exceptions.
fatalErrors =
like 'errors', but errors in this list will always terminate the connection, despite being of a recognizable error type.
commandType =
The type of Box used to issue commands; useful only for protocol-modifying behavior like startTLS or protocol switching. Defaults to a plain vanilla Box.
responseType =
The type of Box used to respond to this command; only useful for protocol-modifying behavior like startTLS or protocol switching. Defaults to a plain vanilla Box.
requiresAnswer =
a boolean; defaults to True. Set it to False on your subclass if you want callRemote to return None. Note: this is a hint only to the client side of the protocol. The return-type of a command responder method must always be a dictionary adhering to the contract specified by response, because clients are always free to request a response if they want one.
def __init__(self, **kw): (source)
overridden in twisted.protocols.amp.ProtocolSwitchCommand, twisted.protocols.amp.StartTLS

Create an instance of this command with specified values for its parameters.

In Python 3, keyword arguments MUST be Unicode/native strings whereas in Python 2 they could be either byte strings or Unicode strings.

A Command's arguments are defined in its schema using bytes names. The values for those arguments are plucked from the keyword arguments using the name returned from _wireNameToPythonIdentifier. In other words, keyword arguments should be named using the Python-side equivalent of the on-wire (bytes) name.

Parameterskwa dict containing an appropriate value for each name specified in the arguments attribute of my class.
RaisesInvalidSignatureif you forgot any required arguments.
@classmethod
def makeResponse(cls, objects, proto): (source)
overridden in twisted.protocols.amp.ProtocolSwitchCommand

Serialize a mapping of arguments using this Command's response schema.

Parametersobjectsa dict with keys matching the names specified in self.response, having values of the types that the Argument objects in self.response can format.
protoan AMP.
Returnsan AmpBox.
@classmethod
def makeArguments(cls, objects, proto): (source)

Serialize a mapping of arguments using this Command's argument schema.

Parametersobjectsa dict with keys similar to the names specified in self.arguments, having values of the types that the Argument objects in self.arguments can parse.
protoan AMP.
ReturnsAn instance of this Command's commandType.
@classmethod
def parseResponse(cls, box, protocol): (source)

Parse a mapping of serialized arguments using this Command's response schema.

ParametersboxA mapping of response-argument names to the serialized forms of those arguments.
protocolThe AMP protocol.
ReturnsA mapping of response-argument names to the parsed forms.
@classmethod
def parseArguments(cls, box, protocol): (source)

Parse a mapping of serialized arguments using this Command's argument schema.

ParametersboxA mapping of argument names to the seralized forms of those arguments.
protocolThe AMP protocol.
ReturnsA mapping of argument names to the parsed forms.
@classmethod
def responder(cls, methodfunc): (source)

Declare a method to be a responder for a particular command.

This is a decorator.

Use like so:

   class MyCommand(Command):
       arguments = [('a', ...), ('b', ...)]

   class MyProto(AMP):
       def myFunMethod(self, a, b):
           ...
       MyCommand.responder(myFunMethod)

Notes: Although decorator syntax is not used within Twisted, this function returns its argument and is therefore safe to use with decorator syntax.

This is not thread safe. Don't declare AMP subclasses in other threads. Don't declare responders outside the scope of AMP subclasses; the behavior is undefined.

ParametersmethodfuncA function which will later become a method, which has a keyword signature compatible with this command's argument list and returns a dictionary with a set of keys compatible with this command's response list.
Returnsthe methodfunc parameter.
def _doCommand(self, proto): (source)
overridden in twisted.protocols.amp.ProtocolSwitchCommand, twisted.protocols.amp.StartTLS

Encode and send this Command to the given protocol.

Parametersprotoan AMP, representing the connection to send to.
Returnsa Deferred which will fire or error appropriately when the other side responds to the command (or error if the connection is lost before it is responded to).
API Documentation for Twisted, generated by pydoctor at 2018-10-15 19:29:43.