Part of twisted.internet View Source
Implementations of IStreamServerEndpoint
and IStreamClientEndpoint
that wrap the IReactorTCP
,
IReactorSSL
,
and IReactorUNIX
interfaces.
clientFromString
and serverFromString
functions.
Present Since | 10.1 |
Class | TCP4ServerEndpoint | TCP server endpoint with an IPv4 configuration |
Class | TCP4ClientEndpoint | TCP client endpoint with an IPv4 configuration. |
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. |
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. |
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. |
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.
|
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 stports description into a 2-tuple of arguments and keyword values. |
Function | _serverFromStringLegacy | Underlying implementation of serverFromString
which avoids exposing the deprecated 'default' argument to anything but strports.service .
|
Function | _parseClientTCP | Perform any argument value coercion necessary for TCP client parameters. |
Function | _loadCAsFromDir | Load certificate-authority certificate objects in a given directory. |
Function | _parseClientSSL | Perform any argument value coercion necessary for SSL client parameters. |
Function | _parseClientUNIX | Perform any argument value coercion necessary for UNIX client parameters. |
_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 .
|
_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 .
|
_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 .
|
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' |
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'}) .
|
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) |
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.
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 |
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 keyword arguments to this function are allIReactorTCP.connectTCP
arguments.
Returns | The coerced values as a dict .
|
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 allIReactorSSL.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.
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 allIReactorUNIX.connectUNIX
arguments except for checkPID
. Instead, lockfile
is accepted and has the same meaning.
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, since even the simplest client endpoint (plain TCP) requires at least 2 arguments (host and port) to construct.
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 an SSL client endpoint with those arguments, plus the arguments used by the server SSL, for a client certificate:
clientFromString(reactor, "ssl:host=web.example.com:port=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")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 |