cicada.communicator.socket.connect module

Functionality for communicating using the builtin socket module.

class cicada.communicator.socket.connect.CommunicatorEvents(name, rank)[source]

Bases: object

Warning

class ‘cicada.communicator.socket.connect.CommunicatorEvents’ undocumented

filter(record)[source]: Warning

method ‘cicada.communicator.socket.connect.CommunicatorEvents.filter’ undocumented

exception cicada.communicator.socket.connect.EncryptionFailed[source]

Bases: Exception

Raised if an encrypted connection can’t be established with another player.

class cicada.communicator.socket.connect.LoggerAdapter(logger, name, rank)[source]

Bases: LoggerAdapter

Wraps a Python logger for consistent formatting of communicator log entries.

logger: logging.Logger, required: Python logger to wrap.
name: str, required: Communicator name.
rank: int, required: Communicator rank

process(msg, kwargs)[source]

Process the logging message and keyword arguments passed in to a logging call to insert contextual information. You can either manipulate the message itself, the keyword args or both. Return the message and kwargs modified (or not) to suit your needs.

Normally, you’ll only need to override this one method in a LoggerAdapter subclass for your specific needs.

class cicada.communicator.socket.connect.NetstringSocket(sock)[source]

Bases: object

Message-oriented socket that uses the Netstrings protocol.

close()[source]: Close the underlying socket.

property family

Return the underlying socket’s address family.

See socket.socket.family.

feed()[source]: Read data from the underlying socket, decoding whatever is available.

fileno()[source]

Return the file descriptor for the underlying socket.

This allows NetstringSocket to be used with select.select().

getsockname()[source]

Return the underlying socket’s address.

See socket.socket.getsockname().

messages()[source]: Return every message that has been received, if any.

next_message(*, timeout)[source]: Return the next available message, if any.

send(msg)[source]: Send a message.

property stats

Return a dict containing statistics.

Returns the number of bytes and messages that have been sent and received.

exception cicada.communicator.socket.connect.Timeout[source]

Bases: Exception

Raised when an operation has timed-out.

class cicada.communicator.socket.connect.Timer(threshold)[source]

Bases: object

Tracks elapsed time.

Parameters:: threshold (numbers.Number, required) – The maximum of number of elapsed seconds before this timer will be expired.

property elapsed: Return the number of seconds since the Timer was created.

property expired: Returns True if the elapsed time has exceeded a threshold.

exception cicada.communicator.socket.connect.TokenMismatch[source]

Bases: Exception

Raised when players can’t agree on a token for communicator creation.

cicada.communicator.socket.connect.certformat(cert, indent='')[source]

Format an X509 certificate for easy reading.

Parameters:

cert (dict, required) – X509 certificate returned from ssl.SSLSocket.getpeercert() or similar.
indent (str, optional) – Optional indenting to be added to the output.

Returns:

prettycert – The contents of the certificate, formatted for easy reading by humans.

Return type:

str

cicada.communicator.socket.connect.connect(*, address, rank, other_rank, name='world', tls=None)[source]

Given an address, create a socket and make a connection.

Parameters:

address (urllib.parse.ParseResult, required) – The address URL.
rank (int, required) – Rank of the calling player.
other_rank (int, required) – Rank of the other player (the one we’re connecting to).
name (str, optional) – Human readable label used for logging and error messages. Typically, this should be the same name that will be eventually used by a communicator instance. Defaults to “world”.
tls (pair of ssl.SSLContext, optional) – If provided, the returned sockets will implement transport layer security. Callers must provide a sequence containing one context configured for server connections, and one for configured for client connections, in that order.

Returns:

socket – The newly-connected socket, ready for use.

Return type:

NetstringSocket

cicada.communicator.socket.connect.direct(*, listen_socket, addresses, rank, name='world', timer=None, tls=None)[source]

Create socket connections given a list of player addresses.

Parameters:

listen_socket (socket.socket, required) – A nonblocking Python socket or compatible object, already bound and listening for connections. Typically created with listen().
addresses (list of str, required) – List of address URLs for every player in rank order.
rank (int, required) – Rank of the calling player.
name (str, optional) – Human readable label used for logging and error messages. Typically, this should be the same name assigned to the communicator that will use the direct() outputs. Defaults to “world”.
timer (Timer, optional) – Determines the maximum time to wait for player connections. Defaults to five seconds.
tls (pair of ssl.SSLContext, optional) – If provided, the returned sockets will implement transport layer security. Callers must provide a sequence containing one context configured for server connections, and one for configured for client connections, in that order.

Raises:

EncryptionFailed – If there are problems establishing an encrypted connection with another player.
Timeout – If timer expires before all connections are established.
ValueError – If there are problems with input parameters.

Returns:

sockets – Dictionary mapping player ranks to connected sockets.

Return type:

dict of NetstringSocket

cicada.communicator.socket.connect.getLogger(name, comm, rank)[source]: Warning

function ‘cicada.communicator.socket.connect.getLogger’ undocumented

cicada.communicator.socket.connect.getpeerurl(sock)[source]

Return a socket’s peer address as a URL.

Parameters:: sock (socket.socket, required) –
Returns:: url – The socket’s local address as a URL. For example: “tcp://127.0.0.1:59678” for TCP sockets, or “file:///path/to/foo” for Unix domain sockets.
Return type:: str

cicada.communicator.socket.connect.gettls(*, identity=None, trusted=None)[source]

Construct a pair of ssl.SSLContext instances.

Parameters:

identity (str, optional) – Path to a private key and certificate in PEM format that will identify the local player.
trusted (sequence of str, optional) – Path to certificates in PEM format that will identify the other players.

Returns:

tls

Return type:

(server, client) tuple or None

cicada.communicator.socket.connect.geturl(sock)[source]

Return a socket’s local address as a URL.

Parameters:: sock (socket.socket, required) –
Returns:: url – The socket’s local address as a URL. For example: “tcp://127.0.0.1:59678” for TCP sockets, or “file:///path/to/foo” for Unix domain sockets.
Return type:: str

cicada.communicator.socket.connect.listen(*, address, rank, name='world', timer=None)[source]

Create a listening socket from a URL.

Typically, callers should use this function to create a listening socket for use with either direct() or rendezvous().

Parameters:

address (str, required) – Address to use for listening, in the form of a URL. For example: “tcp://127.0.0.1:59478” to create a TCP socket, or “file:///path/to/foo” to create a Unix domain socket.
rank (int, required) – Integer rank of the caller. Used for logging and error messages.
name (str, optional) – Human readable label. Used for logging and error messages. Typically, this should match the name used elsewhere to create a communicator.
timer (Timer, optional) – Determines the maximum time to wait for socket creation. Defaults to five seconds.

Raises:

ValueError – If there are problems with input parameters.
Timeout – If timer expires before all connections are established.

Returns:

socket – A non-blocking socket, bound to address, listening for connections.

Return type:

socket.socket

cicada.communicator.socket.connect.message(name, rank, msg)[source]: Format a message for logging and error handling.

cicada.communicator.socket.connect.rendezvous(*, listen_socket, root_address, world_size, rank, name='world', token=0, timer=None, tls=None)[source]

Create socket connections given just the address of the root player.

Parameters:

listen_socket (socket.socket, required) – A nonblocking Python socket or compatible object, already bound and listening for connections. Typically created with listen().
root_address (str, required) – URL address of the root (rank 0) player. The address must be reachable by all of the other players.
world_size (int, required) – The number of players that will be members of this communicator.
rank (int, required) – The rank of the caller, in the range [0, world_size).
name (str, optional) – Human readable label used for logging and debugging. Typically, this should be the same name assigned to the communicator that will use the rendezvous() outputs. Defaults to “world”.
token (object, optional) – All players provide an arbitrary token at startup; every player token must match, or a TokenMismatch exception will be raised.
timer (Timer, optional) – Determines the maximum time to wait for socket creation. Defaults to five seconds.
tls (pair of ssl.SSLContext, optional) – If provided, the returned sockets will implement transport layer security. Callers must provide a sequence containing one context configured for server connections, and one for configured for client connections, in that order.

Raises:

EncryptionFailed – If there are problems establishing an encrypted connection with another player.
Timeout – If timer expires before all connections are established.
TokenMismatch – If every player doesn’t call this function with the same token.
ValueError – If there are problems with input parameters.

Returns:

sockets – Dictionary mapping player ranks to connected sockets.

Return type:

dict of NetstringSocket