twisted.internet.endpoints
module documentationtwisted.internet
View 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 |
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 |
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. |
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. |
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. |
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 . |
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 . |
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 ) | |
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 . |
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 ) | |
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 ) | |
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 . |
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' |
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'}) . |
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) |
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 |
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 ) |
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 unicode or
bytes
pointing at a directory to load .pem files from, or None . |
Returns | an IOpenSSLTrustRoot
provider. |
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 |
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 . |
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 ) |
hostname | The hostname to use for validating the server's certificate. (type: unicode ) | |
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")
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 |
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 |
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 |
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 ) | |
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 ) | |
Returns | a client TLS endpoint (type: IStreamClientEndpoint ) |