module documentation

Implementations of IStreamServerEndpoint and IStreamClientEndpoint that wrap the IReactorTCP, IReactorSSL, and IReactorUNIX interfaces.

This also implements an extensible mini-language for describing endpoints, parsed by the clientFromString and serverFromString functions.

Present Since
10.1
Class AdoptedStreamServerEndpoint An endpoint for listening on a file descriptor initialized outside of Twisted.
Class HostnameEndpoint A name-based endpoint that connects to the fastest amongst the resolved host addresses.
Class ProcessEndpoint An endpoint for child processes
Class SSL4ClientEndpoint SSL secured TCP client endpoint with an IPv4 configuration
Class SSL4ServerEndpoint SSL secured TCP server endpoint with an IPv4 configuration.
Class StandardErrorBehavior Constants used in ProcessEndpoint to decide what to do with stderr.
Class StandardIOEndpoint A Standard Input/Output endpoint
Class TCP4ClientEndpoint TCP client endpoint with an IPv4 configuration.
Class TCP4ServerEndpoint Implements TCP server endpoint with an IPv4 configuration
Class TCP6ClientEndpoint TCP client endpoint with an IPv6 configuration.
Class TCP6ServerEndpoint Implements TCP server endpoint with an IPv6 configuration
Class UNIXClientEndpoint UnixSocket client endpoint.
Class UNIXServerEndpoint UnixSocket server endpoint.
Function clientFromString Construct a client endpoint from a description string.
Function connectProtocol Connect a protocol instance to an endpoint.
Function quoteStringArgument Quote an argument to serverFromString and clientFromString. Since arguments are separated with colons and colons are escaped with backslashes, some care is necessary if, for example, you have a pathname, you may be tempted to interpolate into a string like this:...
Function serverFromString Construct a stream server endpoint from an endpoint description string.
Function wrapClientTLS Wrap an endpoint which upgrades to TLS as soon as the connection is established.
Interface _IProcessTransportWithConsumerAndProducer An _IProcessTransportWithConsumerAndProducer combines various interfaces to work around the issue that interfaces.IProcessTransport is incompletely defined and doesn't specify flow-control interfaces, and that ...
Class _ProcessEndpointTransport An ITransport, IProcessTransport, IConsumer, and IPushProducer provider for the IProtocol instance passed to the process endpoint.
Class _SimpleHostnameResolver An IHostnameResolver provider that invokes a provided callable to resolve hostnames.
Class _StandardIOParser Stream server endpoint string parser for the Standard I/O type.
Class _SystemdParser Stream server endpoint string parser for the systemd endpoint type.
Class _TCP6ServerParser Stream server endpoint string parser for the TCP6ServerEndpoint type.
Class _TCPServerEndpoint A TCP server endpoint interface
Class _TLSClientEndpointParser Stream client endpoint string parser for wrapClientTLS with HostnameEndpoint.
Class _WrapIProtocol An IProcessProtocol provider that wraps an IProtocol.
Class _WrapperEndpoint An endpoint that wraps another endpoint.
Class _WrapperServerEndpoint A server endpoint that wraps another server endpoint.
Class _WrappingFactory Wrap a factory in order to wrap the protocols it builds.
Class _WrappingProtocol Wrap another protocol in order to notify my user when a connection has been made.
Function _loadCAsFromDir Load certificate-authority certificate objects in a given directory.
Function _matchPluginToPrefix Match plugin to prefix.
Function _parse Convert a description string into a list of positional and keyword parameters, using logic vaguely like what Python does.
Function _parseClientSSL Perform any argument value coercion necessary for SSL client parameters.
Function _parseClientSSLOptions Parse common arguments for SSL endpoints, creating an CertificateOptions instance.
Function _parseClientTCP Perform any argument value coercion necessary for TCP client parameters.
Function _parseClientTLS Internal method to construct an endpoint from string parameters.
Function _parseClientUNIX Perform any argument value coercion necessary for UNIX client parameters.
Function _parseServer Parse a strports description into a 2-tuple of arguments and keyword values.
Function _parseSSL Internal parser function for _parseServer to convert the string arguments for an SSL (over TCP/IPv4) stream endpoint into the structured arguments.
Function _parseTCP Internal parser function for _parseServer to convert the string arguments for a TCP(IPv4) stream endpoint into the structured arguments.
Function _parseTrustRootPath Parse a string referring to a directory full of certificate authorities into a trust root.
Function _parseUNIX Internal parser function for _parseServer to convert the string arguments for a UNIX (AF_UNIX/SOCK_STREAM) stream endpoint into the structured arguments.
Function _privateCertFromPaths Parse a certificate path and key path, either or both of which might be None, into a certificate object.
Function _tokenize Tokenize a strports string and yield each token.
Variable _clientParsers Undocumented
Variable _endpointClientFactories Undocumented
Variable _endpointServerFactories Undocumented
Variable _OP Undocumented
Variable _serverParsers Undocumented
Variable _STRING Undocumented
def clientFromString(reactor, description): (source)

Construct a client endpoint from a description string.

Client description strings are much like server description strings, although they take all of their arguments as keywords, aside from host and port.

You can create a TCP client endpoint with the 'host' and 'port' arguments, like so:

    clientFromString(reactor, "tcp:host=www.example.com:port=80")

or, without specifying host and port keywords:

    clientFromString(reactor, "tcp:www.example.com:80")

Or you can specify only one or the other, as in the following 2 examples:

    clientFromString(reactor, "tcp:host=www.example.com:80")
    clientFromString(reactor, "tcp:www.example.com:port=80")

or an SSL client endpoint with those arguments, plus the arguments used by the server SSL, for a client certificate:

    clientFromString(reactor, "ssl:web.example.com:443:"
                              "privateKey=foo.pem:certKey=foo.pem")

to specify your certificate trust roots, you can identify a directory with PEM files in it with the caCertsDir argument:

    clientFromString(reactor, "ssl:host=web.example.com:port=443:"
                              "caCertsDir=/etc/ssl/certs")

Both TCP and SSL client endpoint description strings can include a 'bindAddress' keyword argument, whose value should be a local IPv4 address. This fixes the client socket to that IP address:

    clientFromString(reactor, "tcp:www.example.com:80:"
                              "bindAddress=192.0.2.100")

NB: Fixed client ports are not currently supported in TCP or SSL client endpoints. The client socket will always use an ephemeral port assigned by the operating system

You can create a UNIX client endpoint with the 'path' argument and optional 'lockfile' and 'timeout' arguments:

    clientFromString(
        reactor, b"unix:path=/var/foo/bar:lockfile=1:timeout=9")

or, with the path as a positional argument with or without optional arguments as in the following 2 examples:

    clientFromString(reactor, "unix:/var/foo/bar")
    clientFromString(reactor, "unix:/var/foo/bar:lockfile=1:timeout=9")

This function is also extensible; new endpoint types may be registered as IStreamClientEndpointStringParserWithReactor plugins. See that interface for more information.

Parameters
reactorThe client endpoint will be constructed with this reactor.
description:strThe strports description to parse.
Returns
IStreamClientEndpointA new endpoint which can be used to connect with the parameters given by description.
Present Since
10.2
def connectProtocol(endpoint, protocol): (source)

Connect a protocol instance to an endpoint.

This allows using a client endpoint without having to create a factory.

Parameters
endpointA client endpoint to connect to.
protocolA protocol instance.
Returns
The result of calling connect on the endpoint, i.e. a Deferred that will fire with the protocol when connected, or an appropriate error.
Present Since
13.1
def quoteStringArgument(argument): (source)

Quote an argument to serverFromString and clientFromString. Since arguments are separated with colons and colons are escaped with backslashes, some care is necessary if, for example, you have a pathname, you may be tempted to interpolate into a string like this:

    serverFromString(reactor, "ssl:443:privateKey=%s" % (myPathName,))

This may appear to work, but will have portability issues (Windows pathnames, for example). Usually you should just construct the appropriate endpoint type rather than interpolating strings, which in this case would be SSL4ServerEndpoint. There are some use-cases where you may need to generate such a string, though; for example, a tool to manipulate a configuration file which has strports descriptions in it. To be correct in those cases, do this instead:

    serverFromString(reactor, "ssl:443:privateKey=%s" %
                     (quoteStringArgument(myPathName),))
Parameters
argument:strThe part of the endpoint description string you want to pass through.
Returns
strThe quoted argument.
def serverFromString(reactor, description): (source)

Construct a stream server endpoint from an endpoint description string.

The format for server endpoint descriptions is a simple byte string. It is a prefix naming the type of endpoint, then a colon, then the arguments for that endpoint.

For example, you can call it like this to create an endpoint that will listen on TCP port 80:

    serverFromString(reactor, "tcp:80")

Additional arguments may be specified as keywords, separated with colons. For example, you can specify the interface for a TCP server endpoint to bind to like this:

    serverFromString(reactor, "tcp:80:interface=127.0.0.1")

SSL server endpoints may be specified with the 'ssl' prefix, and the private key and certificate files may be specified by the privateKey and certKey arguments:

    serverFromString(
        reactor, "ssl:443:privateKey=key.pem:certKey=crt.pem")

If a private key file name (privateKey) isn't provided, a "server.pem" file is assumed to exist which contains the private key. If the certificate file name (certKey) isn't provided, the private key file is assumed to contain the certificate as well.

You may escape colons in arguments with a backslash, which you will need to use if you want to specify a full pathname argument on Windows:

    serverFromString(reactor,
        "ssl:443:privateKey=C\:/key.pem:certKey=C\:/cert.pem")

finally, the 'unix' prefix may be used to specify a filesystem UNIX socket, optionally with a 'mode' argument to specify the mode of the socket file created by listen:

    serverFromString(reactor, "unix:/var/run/finger")
    serverFromString(reactor, "unix:/var/run/finger:mode=660")

This function is also extensible; new endpoint types may be registered as IStreamServerEndpointStringParser plugins. See that interface for more information.

Parameters
reactorThe server endpoint will be constructed with this reactor.
description:strThe strports description to parse.
Returns
IStreamServerEndpointA new endpoint which can be used to listen with the parameters given by description.
Raises
ValueErrorwhen the 'description' string cannot be parsed.
Present Since
10.2
def wrapClientTLS(connectionCreator, wrappedEndpoint): (source)

Wrap an endpoint which upgrades to TLS as soon as the connection is established.

Parameters
connectionCreator:twisted.internet.interfaces.IOpenSSLClientConnectionCreatorThe TLS options to use when connecting; see twisted.internet.ssl.optionsForClientTLS for how to construct this.
wrappedEndpoint:An IStreamClientEndpoint provider.The endpoint to wrap.
Returns
twisted.internet.interfaces.IStreamClientEndpointan endpoint that provides transport level encryption layered on top of wrappedEndpoint
Present Since
16.0
def _loadCAsFromDir(directoryPath): (source)

Load certificate-authority certificate objects in a given directory.

Parameters
directoryPatha unicode or bytes pointing at a directory to load .pem files from, or None.
Returns
an IOpenSSLTrustRoot provider.
def _matchPluginToPrefix(plugins, endpointType): (source)

Match plugin to prefix.

def _parse(description): (source)

Convert a description string into a list of positional and keyword parameters, using logic vaguely like what Python does.

Parameters
descriptiona string as described by serverFromString or clientFromString.
Returns
a 2-tuple of (args, kwargs), where 'args' is a list of all ':'-separated strs not containing an '=' and 'kwargs' is a map of all strs which do contain an '='. For example, the result of _parse('a:b:d=1:c') would be (['a', 'b', 'c'], {'d': '1'}).
def _parseClientSSL(*args, **kwargs): (source)

Perform any argument value coercion necessary for SSL client parameters.

Valid keyword arguments to this function are all IReactorSSL.connectSSL arguments except for contextFactory. Instead, certKey (the path name of the certificate file) privateKey (the path name of the private key associated with the certificate) are accepted and used to construct a context factory.

Valid positional arguments to this function are host and port.

Parameters
*argsUndocumented
caCertsDir:strThe one parameter which is not part of IReactorSSL.connectSSL's signature, this is a path name used to construct a list of certificate authority certificates. The directory will be scanned for files ending in .pem, all of which will be considered valid certificate authorities for this connection.
hostname:unicodeThe hostname to use for validating the server's certificate.
Returns
The coerced values as a dict.
def _parseClientSSLOptions(kwargs): (source)

Parse common arguments for SSL endpoints, creating an CertificateOptions instance.

Parameters
kwargs:dictA dict of keyword arguments to be parsed, potentially containing keys certKey, privateKey, caCertsDir, and hostname. See _parseClientSSL.
Returns
The remaining arguments, including a new key sslContextFactory.
def _parseClientTCP(*args, **kwargs): (source)

Perform any argument value coercion necessary for TCP client parameters.

Valid positional arguments to this function are host and port.

Valid keyword arguments to this function are all IReactorTCP.connectTCP arguments.

Returns
The coerced values as a dict.
def _parseClientTLS(reactor, host, port, timeout=b'30', bindAddress=None, certificate=None, privateKey=None, trustRoots=None, endpoint=None, **kwargs): (source)

Internal method to construct an endpoint from string parameters.

Parameters
reactorThe reactor passed to clientFromString.
host:bytes or unicodeThe hostname to connect to.
port:bytes or unicodeThe port to connect to.
timeout:bytes or unicodeFor each individual connection attempt, the number of seconds to wait before assuming the connection has failed.
bindAddress:bytes or unicodeThe address to which to bind outgoing connections.
certificate:bytes or unicodea string representing a filesystem path to a PEM-encoded certificate.
privateKey:bytes or unicodea string representing a filesystem path to a PEM-encoded certificate.
trustRootsUndocumented
endpoint:bytes or unicodean optional string endpoint description of an endpoint to wrap; if this is passed then host is used only for certificate verification.
**kwargsUndocumented
Returns
IStreamClientEndpointa client TLS endpoint
def _parseClientUNIX(*args, **kwargs): (source)

Perform any argument value coercion necessary for UNIX client parameters.

Valid keyword arguments to this function are all IReactorUNIX.connectUNIX keyword arguments except for checkPID. Instead, lockfile is accepted and has the same meaning. Also path is used instead of address.

Valid positional arguments to this function are path.

Returns
The coerced values as a dict.
def _parseServer(description, factory): (source)

Parse a strports description into a 2-tuple of arguments and keyword values.

Parameters
description:strA description in the format explained by serverFromString.
factory:IProtocolFactory or NoneA 'factory' argument; this is left-over from twisted.application.strports, it's not really used.
Returns
a 3-tuple of (plugin or name, arguments, keyword arguments)
def _parseSSL(factory, port, privateKey='server.pem', certKey=None, sslmethod=None, interface='', backlog=50, extraCertChain=None, dhParameters=None): (source)

Internal parser function for _parseServer to convert the string arguments for an SSL (over TCP/IPv4) stream endpoint into the structured arguments.

Parameters
factory:IProtocolFactory or Nonethe protocol factory being parsed, or None. (This was a leftover argument from when this code was in strports, and is now mostly None and unused.)
port:strthe integer port number to bind
privateKey:strThe file name of a PEM format private key file.
certKey:strThe file name of a PEM format certificate file.
sslmethod:strThe string name of an SSL method, based on the name of a constant in OpenSSL.SSL.
interfacethe interface IP to listen on
backlog:strthe length of the listen queue
extraCertChain:strThe path of a file containing one or more certificates in PEM format that establish the chain from a root CA to the CA that signed your certKey.
dhParameters:strThe file name of a file containing parameters that are required for Diffie-Hellman key exchange. If this is not specified, the forward secret DHE ciphers aren't available for servers.
Returns
a 2-tuple of (args, kwargs), describing the parameters to IReactorSSL.listenSSL (or, modulo argument 2, the factory, arguments to SSL4ServerEndpoint.
def _parseTCP(factory, port, interface='', backlog=50): (source)

Internal parser function for _parseServer to convert the string arguments for a TCP(IPv4) stream endpoint into the structured arguments.

Parameters
factory:IProtocolFactory or Nonethe protocol factory being parsed, or None. (This was a leftover argument from when this code was in strports, and is now mostly None and unused.)
port:strthe integer port number to bind
interfacethe interface IP to listen on
backlog:strthe length of the listen queue
Returns
a 2-tuple of (args, kwargs), describing the parameters to IReactorTCP.listenTCP (or, modulo argument 2, the factory, arguments to TCP4ServerEndpoint.
def _parseTrustRootPath(pathName): (source)

Parse a string referring to a directory full of certificate authorities into a trust root.

Parameters
pathName:unicode or bytes or Nonepath name
Returns
None or IOpenSSLTrustRoot
def _parseUNIX(factory, address, mode='666', backlog=50, lockfile=True): (source)

Internal parser function for _parseServer to convert the string arguments for a UNIX (AF_UNIX/SOCK_STREAM) stream endpoint into the structured arguments.

Parameters
factory:IProtocolFactory or Nonethe protocol factory being parsed, or None. (This was a leftover argument from when this code was in strports, and is now mostly None and unused.)
address:strthe pathname of the unix socket
modeUndocumented
backlog:strthe length of the listen queue
lockfileA string '0' or '1', mapping to True and False respectively. See the wantPID argument to listenUNIX
Returns
a 2-tuple of (args, kwargs), describing the parameters to twisted.internet.interfaces.IReactorUNIX.listenUNIX (or, modulo argument 2, the factory, arguments to UNIXServerEndpoint.
def _privateCertFromPaths(certificatePath, keyPath): (source)

Parse a certificate path and key path, either or both of which might be None, into a certificate object.

Parameters
certificatePath:bytes or unicode or Nonethe certificate path
keyPath:bytes or unicode or Nonethe private key path
Returns
a PrivateCertificate or None
def _tokenize(description): (source)

Tokenize a strports string and yield each token.

Parameters
description:str or bytesa string as described by serverFromString or clientFromString.
Returns

an iterable of 2-tuples of (_OP or _STRING, string). Tuples starting with _OP will contain a second element of either ':' (i.e. 'next parameter') or '=' (i.e. 'assign parameter value'). For example, the string 'hello:greeting=world' would result in a generator yielding these values:

    _STRING, 'hello'
    _OP, ':'
    _STRING, 'greet=ing'
    _OP, '='
    _STRING, 'world'
_clientParsers = (source)

Undocumented

_endpointClientFactories = (source)

Undocumented

_endpointServerFactories = (source)

Undocumented

Undocumented

_serverParsers = (source)

Undocumented

Undocumented