`pants.server`¶

Streaming (TCP) server implementation.

Servers are one of the two main types of channels in Pants - the other being streams. Servers listen for connections to your application, accept those connections and allow you to handle them easily. Pants servers support SSL and IPv6.

Servers¶

Writing Servers¶

You have two choices when writing a server application: either use Pants’ default Server class without modification or subclass Server in order to implement custom behaviour.

Pants’ default Server class will wrap every new connection in an instance of a connection class which you provide (see below). In most cases, this provides you with sufficient freedom to implement your application logic and has the added benefit of simplicity. To use the default server, simply instantiate Server and pass your connection class to the constructor.

If you need to implement custom server behaviour, you can subclass Server and define your connection class as a class attribute:

class MyServer(pants.Server):
    ConnectionClass = MyConnectionClass

It is recommended that you use the default Server class where possible and try to implement your application logic in your connection class.

Connection Classes¶

A connection class is a subclass of Stream which a server will use to wrap each incoming connection. Every time a new connection is made to the server, a new instance of your connection class will be created to handle it. You can override the various event handler methods of Stream to implement your application’s logic.

Running Servers¶

Having defined your connection class and instantiated your server, you can start it listening for new connections with the listen() method. This will bind the server to your chosen address and once the engine is started, the server will begin accepting new connections. Once the server has started listening for connections it can be stopped using the close() method. When close() is called, the default server implementation will close any connections that were made to it which are still open.

SSL¶

Pants servers have SSL support. If you want to start an SSL-enabled server, call the startSSL() method before calling the listen() method. When you call startSSL() you must provide a dictionary of SSL options as detailed in the method documentation. It is also possible to pass the SSL options dictionary directly to the Server constructor in order to enable SSL. Here is an example of how you might start an SSL-enabled server:

server = pants.Server(MyConnectionClass)
server.startSSL({
    'certfile': '/home/user/certfile.pem',
    'keyfile': '/home/user/keyfile.pem'
    })
server.listen(('', 8080))

If you are writing an SSL-enabled application you should read the entirety of Python’s ssl documentation. Pants does not override any of Python’s SSL defaults unless clearly stated in this documentation.

`Server`¶

class pants.server.Server(ConnectionClass=None, **kwargs)[source]¶

A stream-oriented server channel.

A Server instance represents a local server capable of listening for connections from remote hosts over a connection-oriented protocol such as TCP/IP.

Keyword Argument	Description
engine	Optional. The engine to which the channel should be added. Defaults to the global engine.
socket	Optional. A pre-existing socket to wrap. This can be a regular `socket` or an `SSLSocket`. If a socket is not provided, a new socket will be created for the channel when required.
ssl_options	Optional. If provided, `startSSL()` will be called with these options once the server is ready. By default, SSL will not be enabled.

close()[source]¶

Close the channel.

The channel will be closed immediately and will cease to accept new connections. Any connections accepted by this channel will remain open and will need to be closed separately. If this channel has an IPv4 slave (see listen()) it will be closed.

Once closed, a channel cannot be re-opened.

listen(address, backlog=1024, slave=True)[source]¶

Begin listening for connections made to the channel.

The given address is resolved, the channel is bound to the address and then begins listening for connections. Once the channel has begun listening, on_listen() will be called.

Addresses can be represented in a number of different ways. A single string is treated as a UNIX address. A single integer is treated as a port and converted to a 2-tuple of the form ('', port). A 2-tuple is treated as an IPv4 address and a 4-tuple is treated as an IPv6 address. See the socket documentation for further information on socket addresses.

If no socket exists on the channel, one will be created with a socket family appropriate for the given address.

An error will occur if the given address is not of a valid format or of an inappropriate format for the socket (e.g. if an IP address is given to a UNIX socket).

Calling listen() on a closed channel or a channel that is already listening will raise a RuntimeError.

Returns the channel.

Arguments	Description
address	The local address to listen for connections on.
backlog	Optional. The maximum size of the connection queue.
slave	Optional. If True, this will cause a Server listening on IPv6 INADDR_ANY to create a slave Server that listens on the IPv4 INADDR_ANY.

on_accept(socket, addr)[source]¶

Called after the channel has accepted a new connection.

Create a new instance of ConnectionClass to wrap the socket and add it to the server.

Argument	Description
sock	The newly connected socket object.
addr	The new socket’s address.

on_close()[source]¶

Called after the channel has finished closing.

Close all active connections to the server.

on_error(exception)¶

Placeholder. Generic error handler for exceptions raised on the channel. Called when an error occurs and no specific error-handling callback exists.

By default, logs the exception and closes the channel.

Argument	Description
exception	The exception that was raised.

on_listen()¶: Placeholder. Called when the channel begins listening for new connections or packets.

on_ssl_wrap_error(sock, addr, exception)[source]¶

Placeholder. Called when an error occurs while wrapping a new connection with an SSL context.

By default, logs the exception and closes the new connection.

Argument	Description
sock	The newly connected socket object.
addr	The new socket’s address.
exception	The exception that was raised.

startSSL(ssl_options={})[source]¶

Enable SSL on the channel.

Enabling SSL on a server channel will cause any new connections accepted by the server to be automatically wrapped in an SSL context before being passed to on_accept(). If an error occurs while a new connection is being wrapped, on_ssl_wrap_error() is called.

SSL is enabled immediately. Typically, this method is called before listen(). If it is called afterwards, any connections made in the meantime will not have been wrapped in SSL contexts.

The SSL options argument will be passed through to each invocation of ssl.wrap_socket() as keyword arguments - see the ssl documentation for further information. You will typically want to provide the keyfile, certfile and ca_certs options. The do_handshake_on_connect option must be False and the server_side option must be true, or a ValueError will be raised.

Attempting to enable SSL on a closed channel or a channel that already has SSL enabled on it will raise a RuntimeError.