The connection sub-package allows the sending of picklable objects between processes using sockets or (on Windows) named pipes. It also has support for digest authetication (using the hmac module from the standard library).
The sub-package contains C extensions socket_connection and pipe_connection. Without these extensions connection will still work, but will be slower and will not support the use of named pipes.
The module exports the following classes:
- class Listener(address=None, family=None, backlog=1, authkey=None)
- A wrapper for a bound socket or Windows named pipe which is 'listening' for connections.
- exception AuthenticationError
- Exception raised when there is an authentication error.
The module exports one function:
- Client(address, family=None, authkey=None)
Attempts to set up a connection to the listener which is using address address.
The type of the connection is determined by family argument, but this can generally be omitted since it can usually be inferred from the format of address.
If authkey is not None then a handshake is preformed with the other end of the connection using authkey as an authentication key. If this fails then AuthenticationError is raised.
A Connection object is returned. (See Connection objects.)
Instances of Listener have the following methods:
- __init__(address=None, family=None, backlog=1, authkey=None)
- address
- The address to be used by the bound socket or named pipe of the listener object.
- family
The type of the socket (or named pipe) to use.
This can be one of the strings 'AF_INET' (for a TCP socket), 'AF_UNIX' (for a Unix domain socket) or 'AF_PIPE' (for a Windows named pipe). Of these only the first is guaranteed to be available.
If family is None than the family is inferred from the format of address. If address is also None then a default is chosen. This default is the family which is assumed to be the fastest available. See Address formats.
- backlog
- If the listener object uses a socket then backlog is passed to the listen() method of the socket once it has been bound.
- authkey
- If not None then when accept() is called the other end of the resulting connection is required to prove that it knows the value of authkey. See Authentication keys.
- accept()
Accept a connection on the bound socket or named pipe of the listener object.
Returns a Connection object. See Connection objects.
If authkey is not None then a handshake is preformed with the other end of the connection using authkey as an authentication key. If this fails then AuthenticationError is raised.
- close()
Close the bound socket or named pipe of the listener object.
This is called automatically when the listener is garbage collected.
Listener objects have the following read-only properties:
- property address
- The address which is being used by the listener object.
- property last_accepted
The address from which the last accepted connection came.
If this is unavailable then None is returned.
Connections objects have the following methods:
- recv()
- Return an object sent from the other end of the connection using send().
- send(obj)
Send an object to the other end of the connection which should be read using recv().
The object must be picklable.
- recv_string()
- Return a string sent from the other end of the connection using send_string().
- send_string(obj)
- Send a string to the other end of the connection which should be read using recv_string().
- close()
Close the connection.
This is called automatically when the connection is garbage collected.
Warning
The recv() method automatically unpickles the data it receives which can be a security risk. Therefore if you are using the recv() and send() methods you should be using some form of authentication. See Authentication keys.
An 'AF_INET' address is a tuple of the form (hostname, port) where hostname is a string and port is an integer
An 'AF_UNIX' address is a string representing a filename on the filesystem.
An 'AF_PIPE' address is a string of the form r'\\.\pipe\PipeName'.
To use Client to connect to a named pipe on a remote computer called ServerName one should use an address of the form r'\\ServerName\pipe\PipeName' instead.
Note that any string beginning with two backslashes is assumed by default to be an 'AF_PIPE' address rather than an 'AF_UNIX' address.
When one uses the recv() method of a connection object, the data received is automatically unpickled. Unfortunately unpickling data from an untrusted source is a security risk. Therefore Listener and Client use the hmac module to provide digest authentication.
An authentication key is a string which can be thought of as a password: once a connection is established both ends will demand proof that the other knows the authentication key. (Demonstrating that both ends are using the same key does not involve sending the key over the connection.)
As an authentication key one can use the return value of currentProcess().getAuthKey() (see Process objects). This value will automatically inherited by any Process object that the current process creates. This means that (by default) all processes of a multi-process program will share a single authentication key which can be used when setting up connections between the themselves.
Suitable authentication keys can be generated by os.urandom().
The following server code creates a listener which uses 'secret password' as an authentication key. It then waits for a connection, receives an object and then sends it back boxed inside a list:
from processing.connection import Listener
address = ('localhost', 6000) # family is deduced to be 'AF_INET'
listener = Listener(address, authkey='secret password')
conn = listener.accept()
print 'connection accepted from', listener.last_accepted
obj = conn.recv()
boxed_obj = [obj]
conn.send(boxed_obj)
The following code connects to the server, sends it the number 42, and then prints the reply from the server:
from processing.connection import Client
address = ('localhost', 6000)
conn = Client(address, authkey='secret password')
obj = 42
print 'sending:', obj
conn.send(obj)
print 'recieved:', conn.recv() # prints 'received: [42]'