t.i.endpoints : module documentation

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 NoneType)
	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.

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 NoneType)
	address	the pathname of the unix socket (type: str)
	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 IReactorTCP.listenUNIX (or, modulo argument 2, the factory, arguments to UNIXServerEndpoint.

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 NoneType)
	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)
	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)
Returns	a 2-tuple of (args, kwargs), describing the parameters to IReactorSSL.listenSSL (or, modulo argument 2, the factory, arguments to SSL4ServerEndpoint.

Tokenize a strports string and yield each token.

Parameters	description	a 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:greet\=ing=world' would result in a generator yielding these values: _STRING, 'hello' _OP, ':' _STRING, 'greet=ing' _OP, '=' _STRING, 'world'

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 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'}).

Parse a stports 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)
	default	Deprecated argument, specifying the default parser mode to use for unqualified description strings (those which do not have a ':' and prefix). (type: str or NoneType)
Returns	a 3-tuple of (plugin or name, arguments, keyword arguments)

Underlying implementation of serverFromString which avoids exposing the deprecated 'default' argument to anything but strports.service.

Construct a stream server endpoint from an endpoint description string.

The format for server endpoint descriptions is a simple 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.
Returns	A new endpoint which can be used to listen with the parameters given by by description. (type: IStreamServerEndpoint)
Raises	ValueError	when the 'description' string cannot be parsed.
Present Since	10.2

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("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("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)

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.

Load certificate-authority certificate objects in a given directory.

Parameters	directoryPath	a FilePath pointing at a directory to load .pem files from.
Returns	a list of OpenSSL.crypto.X509 objects.

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	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)
Returns	The coerced values as a dict.

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.

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")

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

   clientFromString(reactor, "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 IStreamClientEndpointStringParser plugins. See that interface for more information.

Parameters	reactor	The client endpoint will be constructed with this reactor.
	description	The strports description to parse.
Returns	A new endpoint which can be used to connect with the parameters given by by description. (type: IStreamClientEndpoint)
Present Since	10.2