twisted.application.strports : API documentation

Port description language

This module implements a description mini-language for ports, and provides functions to parse it and to use it to directly construct appropriate network server services or to directly listen on them.

Here are some examples. They assume the following toy resource and factory definitions:

   class Simple(resource.Resource):
       isLeaf = True
       def render_GET(self, request):
           return "<html>Hello, world!</html>"

    class FingerProtocol(protocol.Protocol):
        def connectionMade(self):
            self.transport.loseConnection()

    class FingerFactory(protocol.ServerFactory):
        protocol = FingerProtocol

Examples using SSL require a private key and a certificate. 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:

   >>> s=service("80", server.Site(Simple()))
   >>> s=service("tcp:80", server.Site(Simple()))
   >>> s=service("tcp:80:interface=127.0.0.1", server.Site(Simple()))
   >>> s=service("ssl:443", server.Site(Simple()))
   >>> s=service("ssl:443:privateKey=mykey.pem", server.Site(Simple()))
   >>> s=service("ssl:443:privateKey=mykey.pem:certKey=cert.pem", server.Site(Simple()))
   >>> s=service("unix:/var/run/finger", FingerFactory())
   >>> s=service("unix:/var/run/finger:mode=660", FingerFactory())
   >>> p=listen("80", server.Site(Simple()))
   >>> p=listen("tcp:80", server.Site(Simple()))
   >>> p=listen("tcp:80:interface=127.0.0.1", server.Site(Simple()))
   >>> p=listen("ssl:443", server.Site(Simple()))
   >>> p=listen("ssl:443:privateKey=mykey.pem", server.Site(Simple()))
   >>> p=listen("ssl:443:privateKey=mykey.pem:certKey=cert.pem", server.Site(Simple()))
   >>> p=listen("unix:/var/run/finger", FingerFactory())
   >>> p=listen("unix:/var/run/finger:mode=660", FingerFactory())
   >>> p=listen("unix:/var/run/finger:lockfile=0", FingerFactory())

See specific function documentation for more information.

Maintainer: Moshe Zadka

def _parseTCP(factory, port, interface='', backlog=50): (source)

Undocumented

def _parseUNIX(factory, address, mode='666', backlog=50, lockfile=True): (source)

Undocumented

def _parseSSL(factory, port, privateKey='server.pem', certKey=None, sslmethod=None, interface='', backlog=50): (source)

Undocumented

def _tokenize(description): (source)

Undocumented

def _parse(description): (source)

Undocumented

def parse(description, factory, default=None): (source)

Parse the description of a reliable virtual circuit server (that is, a TCP port, a UNIX domain socket or an SSL port) and return the data necessary to call the reactor methods to listen on the given socket with the given factory.

An argument with no colons means a default port. Usually the default type is tcp, but passing a non-None value as default will set that as the default. Otherwise, it is a colon-separated string. The first part means the type -- currently, it can only be ssl, unix or tcp. After that, comes a list of arguments. Arguments can be positional or keyword, and can be mixed. Keyword arguments are indicated by 'name=value'. If a value is supposed to contain a ':', a '=' or a '\', escape it with a '\'.

For TCP, the arguments are the port (port number) and, optionally the interface (interface on which to listen) and backlog (how many clients to keep in the backlog).

For UNIX domain sockets, the arguments are address (the file name of the socket) and optionally the mode (the mode bits of the file, as an octal number) and the backlog (how many clients to keep in the backlog).

For SSL sockets, the arguments are the port (port number) and, optionally, the privateKey (file in which the private key is in), certKey (file in which the certification is in), sslmethod (the name of the SSL method to allow), the interface (interface on which to listen) and the backlog (how many clients to keep in the backlog).

Parameters	description	(type: `str` )
	factory	(type: `twisted.internet.interfaces.IProtocolFactory` )
	default	(type: `str` or `None` )
Returns	a tuple of string, tuple and dictionary. The string is the name of the method (sans `'listen'`) to call, and the tuple and dictionary are the arguments and keyword arguments to the method. (type: `tuple` )
Raises	ValueError	if the string is formatted incorrectly.
	KeyError	if the type is other than unix, ssl or tcp.

def service(description, factory, default=None): (source)

Return the service corresponding to a description

Parameters	description	(type: `str` )
	factory	(type: `twisted.internet.interfaces.IProtocolFactory` )
	default	(type: `str` or `None` )
Returns	the service corresponding to a description of a reliable virtual circuit server. See the documentation of the `parse` function for description of the semantics of the arguments. (type: `twisted.application.service.IService` )

def listen(description, factory, default=None): (source)

Listen on a port corresponding to a description

Parameters	description	(type: `str` )
	factory	(type: `twisted.internet.interfaces.IProtocolFactory` )
	default	(type: `str` or `None` )
Returns	the port corresponding to a description of a reliable virtual circuit server. See the documentation of the `parse` function for description of the semantics of the arguments. (type: `twisted.internet.interfaces.IListeningPort` )

Function	parse	No summary
Function	service	Return the service corresponding to a description
Function	listen	Listen on a port corresponding to a description
Function	_parseTCP	Undocumented
Function	_parseUNIX	Undocumented
Function	_parseSSL	Undocumented
Function	_tokenize	Undocumented
Function	_parse	Undocumented

t.a.strports : module documentation