earwax.networking module

Provides classes for networking.

exception earwax.networking.AlreadyConnected

Bases: earwax.networking.NetworkingConnectionError

Already connected.

Attempted to call connect() on an already connected NetworkConnection instance.

exception earwax.networking.AlreadyConnecting

Bases: earwax.networking.NetworkingConnectionError

Already connecting.

An attempt was made to call connect() on an NetworkConnection instance which is already attempting to connect.

class earwax.networking.ConnectionStates

Bases: enum.Enum

Various states that NetworkConnection classes can be in.

Variables:

• not_connected – The connection’s connect() method has not yet been called.
• connecting – The connection is still being established.
• connected – A connection has been established.
• disconnected – This connection is no longer connected (but was at some point).
• error – There was an error establishing a connection.

connected = 2

connecting = 1

disconnected = 3

error = 4

not_connected = 0

class earwax.networking.NetworkConnection

Bases: earwax.mixins.RegisterEventMixin

Represents a single outbound connection.

You can read data by providing an event handler for on_data(), and write data with the send() method.

Variables:

• socket – The raw socket this instance uses for communication.
• state – The state this connection is in.

close() → None

Close this connection.

Disconnect self.socket, and call shutdown() to clean up..

connect(hostname: str, port: int) → None

Open a new connection.

Connect self.socket to the provided hostname and port.

Parameters:

• hostname – The hostname to connect to.
• port – The port to connect on.

on_connect() → None

Deal with the connection being opened.

This event is dispatched when text is first received from self.socket, since I’ve not found a better way to know when the socket is properly open.

on_data(data: bytes) → None

Handle incoming data.

An event which is dispatched whenever data is received from self.socket.

on_disconnect() → None

Handle the connection closing.

Dispatched when self.socket has disconnected.

A socket disconnect is defined by the socket in question receiving an empty string.

on_error(e: Exception) → None

Handle a connection error.

This event is dispatched when there is an error establishing a connection.

Parameters:e – The exception that was raised.

poll(dt: float) → None

Check if any data has been received.

Poll self.socket for anything that has been received since the last time this function ran.

This function will be scheduled by connect(), and unscheduled by shutdown(), when no more data is received from the socket.

If this connection is not connected yet (I.E.: you called this function yourself), then earwax.NotConnectedYet will be raised.

send(data: bytes) → None

Send some data over this connection.

Sends some data to self.socket.

If this object is not connected yet, then NotConnectedYet will be raised.

Parameters:data –

The data to send to the socket.

Must end with '\r\n'.

shutdown() → None

Shutdown this server.

Unschedule self.poll, set self.socket to None, and reset self.state to earwax.ConnectionStates.not_connected.

exception earwax.networking.NetworkingConnectionError

Bases: Exception

Base class for connection errors.

exception earwax.networking.NotConnectedYet

Bases: earwax.networking.NetworkingConnectionError

Tried to send data on a connection which is not yet connected.