twisted.internet.endpoints : API documentation

module documentation

(source)

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

Variable	TLSMemoryBIOFactory	Undocumented
Class	StandardIOEndpoint	A Standard Input/Output endpoint
Class	StandardErrorBehavior	Constants used in ProcessEndpoint to decide what to do with stderr.
Class	ProcessEndpoint	An endpoint for child processes
Class	TCP4ServerEndpoint	Implements TCP server endpoint with an IPv4 configuration
Class	TCP6ServerEndpoint	Implements TCP server endpoint with an IPv6 configuration
Class	TCP4ClientEndpoint	TCP client endpoint with an IPv4 configuration.
Class	TCP6ClientEndpoint	TCP client endpoint with an IPv6 configuration.
Class	HostnameEndpoint	A name-based endpoint that connects to the fastest amongst the resolved host addresses.
Class	SSL4ServerEndpoint	SSL secured TCP server endpoint with an IPv4 configuration.
Class	SSL4ClientEndpoint	SSL secured TCP client endpoint with an IPv4 configuration
Class	UNIXServerEndpoint	UnixSocket server endpoint.
Class	UNIXClientEndpoint	UnixSocket client endpoint.
Class	AdoptedStreamServerEndpoint	An endpoint for listening on a file descriptor initialized outside of Twisted.
Function	serverFromString	Construct a stream server endpoint from an endpoint description string.
Function	quoteStringArgument	No summary
Function	clientFromString	Construct a client endpoint from a description string.
Function	connectProtocol	Connect a protocol instance to an endpoint.
Function	wrapClientTLS	Wrap an endpoint which upgrades to TLS as soon as the connection is established.
Class	_WrappingProtocol	Wrap another protocol in order to notify my user when a connection has been made.
Class	_WrappingFactory	Wrap a factory in order to wrap the protocols it builds.
Interface	_IProcessTransportWithConsumerAndProducer	No summary
Class	_ProcessEndpointTransport	An `ITransport`, `IProcessTransport`, `IConsumer`, and `IPushProducer` provider for the `IProtocol` instance passed to the process endpoint.
Class	_WrapIProtocol	An `IProcessProtocol` provider that wraps an `IProtocol`.
Class	_TCPServerEndpoint	A TCP server endpoint interface
Class	_SimpleHostnameResolver	An `IHostnameResolver` provider that invokes a provided callable to resolve hostnames.
Function	_parseTCP	Internal parser function for `_parseServer` to convert the string arguments for a TCP(IPv4) stream endpoint into the structured arguments.
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	_parseSSL	Internal parser function for `_parseServer` to convert the string arguments for an SSL (over TCP/IPv4) stream endpoint into the structured arguments.
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.
Variable	_serverParsers	Undocumented
Variable	_OP	Undocumented
Variable	_STRING	Undocumented
Function	_tokenize	Tokenize a strports string and yield each token.
Function	_parse	Convert a description string into a list of positional and keyword parameters, using logic vaguely like what Python does.
Variable	_endpointServerFactories	Undocumented
Variable	_endpointClientFactories	Undocumented
Function	_parseServer	Parse a strports description into a 2-tuple of arguments and keyword values.
Function	_matchPluginToPrefix	Match plugin to prefix.
Function	_parseClientTCP	Perform any argument value coercion necessary for TCP client parameters.
Function	_loadCAsFromDir	Load certificate-authority certificate objects in a given directory.
Function	_parseTrustRootPath	Parse a string referring to a directory full of certificate authorities into a trust root.
Function	_privateCertFromPaths	Parse a certificate path and key path, either or both of which might be `None`, into a certificate object.
Function	_parseClientSSLOptions	Parse common arguments for SSL endpoints, creating an `CertificateOptions` instance.
Function	_parseClientSSL	Perform any argument value coercion necessary for SSL client parameters.
Function	_parseClientUNIX	Perform any argument value coercion necessary for UNIX client parameters.
Variable	_clientParsers	Undocumented
Class	_WrapperEndpoint	An endpoint that wraps another endpoint.
Class	_WrapperServerEndpoint	A server endpoint that wraps another server endpoint.
Function	_parseClientTLS	Internal method to construct an endpoint from string parameters.
Class	_TLSClientEndpointParser	Stream client endpoint string parser for `wrapClientTLS` with `HostnameEndpoint`.

TLSMemoryBIOFactory = (source)

Undocumented

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	the 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.) (type: `IProtocolFactory` or `None`)
	port	the integer port number to bind (type: `str`)
	interface	the interface IP to listen on
	backlog	the length of the listen queue (type: `str`)
Returns	a 2-tuple of (args, kwargs), describing the parameters to `IReactorTCP.listenTCP` (or, modulo argument 2, the factory, arguments to `TCP4ServerEndpoint`.

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	the 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.) (type: `IProtocolFactory` or `None`)
	address	the pathname of the unix socket (type: `str`)
	mode	Undocumented
	backlog	the length of the listen queue (type: `str`)
	lockfile	A 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 _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	the 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.) (type: `IProtocolFactory` or `None`)
	port	the integer port number to bind (type: `str`)
	privateKey	The file name of a PEM format private key file. (type: `str`)
	certKey	The file name of a PEM format certificate file. (type: `str`)
	sslmethod	The string name of an SSL method, based on the name of a constant in `OpenSSL.SSL`. Must be one of: "SSLv23_METHOD", "SSLv2_METHOD", "SSLv3_METHOD", "TLSv1_METHOD". (type: `str`)
	interface	the interface IP to listen on
	backlog	the length of the listen queue (type: `str`)
	extraCertChain	The 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`. (type: `str`)
	dhParameters	The 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. (type: `str`)
Returns	a 2-tuple of (args, kwargs), describing the parameters to `IReactorSSL.listenSSL` (or, modulo argument 2, the factory, arguments to `SSL4ServerEndpoint`.

_serverParsers = (source)

Undocumented

_OP = (source)

Undocumented

_STRING = (source)

Undocumented

def _tokenize(description): (source)

Tokenize a strports string and yield each token.

Parameters	description	a string as described by `serverFromString` or `clientFromString`. (type: `str` or `bytes`)
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'

def _parse(description): (source)

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

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

_endpointServerFactories = (source)

Undocumented

_endpointClientFactories = (source)

Undocumented

def _parseServer(description, factory): (source)

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

Parameters	description	A description in the format explained by `serverFromString`. (type: `str`)
	factory	A 'factory' argument; this is left-over from twisted.application.strports, it's not really used. (type: `IProtocolFactory` or `None`)
Returns	a 3-tuple of (plugin or name, arguments, keyword arguments)

def _matchPluginToPrefix(plugins, endpointType): (source)

Match plugin to prefix.

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	reactor	The server endpoint will be constructed with this reactor.
	description	The strports description to parse. (type: `str`)
Returns	A new endpoint which can be used to listen with the parameters given by `description`. (type: `IStreamServerEndpoint`)
Raises	ValueError	when the 'description' string cannot be parsed.
Present Since	10.2

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	The part of the endpoint description string you want to pass through. (type: `str`)
Returns	The quoted argument. (type: `str`)

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 _loadCAsFromDir(directoryPath): (source)

Load certificate-authority certificate objects in a given directory.

Parameters	directoryPath	a `unicode` or `bytes` pointing at a directory to load .pem files from, or `None`.
Returns	an `IOpenSSLTrustRoot` provider.

def _parseTrustRootPath(pathName): (source)

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

Parameters	pathName	path name (type: `unicode` or `bytes` or `None`)
Returns	`None` or `IOpenSSLTrustRoot`

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	the certificate path (type: `bytes` or `unicode` or `None`)
	keyPath	the private key path (type: `bytes` or `unicode` or `None`)
Returns	a `PrivateCertificate` or `None`

def _parseClientSSLOptions(kwargs): (source)

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

Parameters	kwargs	A dict of keyword arguments to be parsed, potentially containing keys `certKey`, `privateKey`, `caCertsDir`, and `hostname`. See `_parseClientSSL`. (type: `dict`)
Returns	The remaining arguments, including a new key `sslContextFactory`.

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	args	Undocumented
	kwargs	Undocumented
	caCertsDir	The 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. (type: `str`)
	hostname	The hostname to use for validating the server's certificate. (type: `unicode`)
Returns	The coerced values as a `dict`.

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.

_clientParsers = (source)

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	reactor	The client endpoint will be constructed with this reactor.
	description	The strports description to parse. (type: `str`)
Returns	A new endpoint which can be used to connect with the parameters given by `description`. (type: `IStreamClientEndpoint`)
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	endpoint	A client endpoint to connect to.
	protocol	A 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 wrapClientTLS(connectionCreator, wrappedEndpoint): (source)

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

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

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	reactor	The reactor passed to `clientFromString`.
	host	The hostname to connect to. (type: `bytes` or `unicode`)
	port	The port to connect to. (type: `bytes` or `unicode`)
	timeout	For each individual connection attempt, the number of seconds to wait before assuming the connection has failed. (type: `bytes` or `unicode`)
	bindAddress	The address to which to bind outgoing connections. (type: `bytes` or `unicode`)
	certificate	a string representing a filesystem path to a PEM-encoded certificate. (type: `bytes` or `unicode`)
	privateKey	a string representing a filesystem path to a PEM-encoded certificate. (type: `bytes` or `unicode`)
	trustRoots	Undocumented
	endpoint	an optional string endpoint description of an endpoint to wrap; if this is passed then `host` is used only for certificate verification. (type: `bytes` or `unicode`)
	kwargs	Undocumented
Returns	a client TLS endpoint (type: `IStreamClientEndpoint`)

API Documentation for Twisted, generated by pydoctor 20.12.1 at 2021-02-28 19:53:36.