Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`protocols`.`amp`.`Command``

class documentation

`class Command: (source)`

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.stream.StreamOpen`, `twisted.trial._dist.stream.StreamWrite`, `twisted.trial._dist.workercommands.Run`, `twisted.trial._dist.workercommands.Start`

Constructor: `Command(**kw)`

View In Hierarchy

Subclass me to specify an AMP Command.

Class Method | `makeArguments` | Serialize a mapping of arguments using this `Command`'s argument schema.
Class Method | `makeResponse` | Serialize a mapping of arguments using this `Command`'s response schema.
Class Method | `parseArguments` | Parse a mapping of serialized arguments using this `Command`'s argument schema.
Class Method | `parseResponse` | Parse a mapping of serialized arguments using this `Command`'s response schema.
Class Method | `responder` | Declare a method to be a responder for a particular command.
Method | `__init__` | Create an instance of this command with specified values for its parameters.
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 | `commandName` | Undocumented
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 | `errors` | A mapping of subclasses of `Exception` to wire-protocol tags for errors represented as `str`s. Responders which raise keys from this dictionary will have the error translated to the corresponding tag on the wire...
Class Variable | `extra` | Undocumented
Class Variable | `fatalErrors` | like 'errors', but errors in this list will always terminate the connection, despite being of a recognizable error type.
Class Variable | `response` | A list like `arguments`, but instead used for the return value.
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 ...
Instance Variable | `structured` | Undocumented
Method | `_doCommand` | Encode and send this Command to the given protocol.

@classmethod
def makeArguments(cls, objects, proto): (source)

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

Parameters
objects | a 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.
proto | an `AMP`.
Returns
An instance of this `Command`'s `commandType`.

@classmethod
def makeResponse(cls, objects, proto): (source)
overridden in `twisted.protocols.amp.ProtocolSwitchCommand`

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

Parameters
objects | a dict with keys matching the names specified in self.response, having values of the types that the Argument objects in self.response can format.
proto | an `AMP`.
Returns
an `AmpBox`.

@classmethod
def parseArguments(cls, box, protocol): (source)

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

Parameters
box | A mapping of argument names to the seralized forms of those arguments.
protocol | The `AMP` protocol.
Returns
A mapping of argument names to the parsed forms.

@classmethod
def parseResponse(cls, box, protocol): (source)

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

Parameters
box | A mapping of response-argument names to the serialized forms of those arguments.
protocol | The `AMP` protocol.
Returns
A mapping of response-argument names to the parsed forms.

@classmethod
def responder(cls, methodfunc: `_T_Callable`) -> `_T_Callable`: (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.

Parameters
methodfunc:`_T_Callable` | A function which will later become a method, which has a keyword signature compatible with this command's `arguments` list and returns a dictionary with a set of keys compatible with this command's `response` list.
Returns
`_T_Callable` | the methodfunc parameter.

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.

Parameters
**kw | a dict containing an appropriate value for each name specified in the `arguments` attribute of my class.
Raises
`InvalidSignature` | if you forgot any required arguments.

arguments: `ClassVar[List[Tuple[bytes, Argument]]]` = (source)
overridden in `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.stream.StreamWrite`, `twisted.trial._dist.workercommands.Run`, `twisted.trial._dist.workercommands.Start`

A list of 2-tuples of (name, Argument-subclass-instance), specifying the names and values of the parameters which are required for this command.

commandName: `ClassVar[bytes]` = (source)

Undocumented

commandType: `ClassVar[Union[Type[Command], Type[Box]]]` = (source)

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`.

errors: `ClassVar[Dict[Type[Exception], bytes]]` = (source)

A mapping of subclasses of `Exception` to wire-protocol tags for errors represented as `str`s. 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.

extra: `ClassVar[List[Any]]` = (source)

Undocumented

fatalErrors: `ClassVar[Dict[Type[Exception], bytes]]` = (source)

like 'errors', but errors in this list will always terminate the connection, despite being of a recognizable error type.

response: `ClassVar[List[Tuple[bytes, Argument]]]` = (source)
overridden in `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.stream.StreamOpen`, `twisted.trial._dist.workercommands.Run`, `twisted.trial._dist.workercommands.Start`

A list like `arguments`, but instead used for the return value.

responseType: `ClassVar[Type[AmpBox]]` = (source)

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: `bool` = (source)

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.

structured = (source)

Undocumented

def _doCommand(self, proto): (source)
overridden in `twisted.protocols.amp.ProtocolSwitchCommand`, `twisted.protocols.amp.StartTLS`

Encode and send this Command to the given protocol.

Parameters
proto | an AMP, representing the connection to send to.
Returns
a 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).