Ductworks Base Classes and Socket Ducts

This page documents the API for the ductworks.base_duct module.

Base Duct Objects

Parent Raw Socket Duct

class ductworks.base_duct.RawDuctParent(bind_address, server_listener_socket_constructor=<function unix_domain_socket_constructor>, server_listener_socket_destructor=<function unix_domain_socket_listener_destructor>, server_connection_socket_destructor=<function client_socket_destructor>, timeout=30)

The RawDuctParent is a thin wrapper over top of a “server” socket, that uses the socket in an “anonymous” way. Once the first connection is seen, the listener socket is closed, and the “parent” and “child” act like an anonymous socket pair (with a few extra niceties, like a poll method).

bind(listen_queue_depth=1)

Create and bind the listener socket, if this hasn’t been done already.

This will raise AlreadyConnectedException if the steady-state connection socket has already been created.

Parameters:listen_queue_depth – The queue depth for the listener socket. Default: 1 Returns:None Return type:NoneType

close(shutdown=False)

Close the connection or listener sockets, if they’re open. :param shutdown: Should shutdown be performed on the connection socket? (Usually no). Default: False :type shutdown: bool :return: None

fileno()

Get the file descriptor of the underlying connection socket. This is useful for integrating into other event loops.

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

Returns:The connection file descriptor. Return type:int

listen(timeout=60)

Listen for incoming connections from an incoming child duct. This will bind if it hasn’t been done already.

This will raise AlreadyConnectedException if the steady-state connection socket has already been created.

Parameters:

• timeout – Amount of time to wait for the other end to connect before giving up.
• timeout – float | int

Returns:

True if a connection was received and connected, False otherwise.

Return type:

bool

poll(timeout=60)

Poll to see if the socket has any data to read from the remote host.

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

A RemoteSocketClosed exception is raised if the local socket has faulted (we can’t talk to the remote any more).

Parameters:timeout (float | int) – Time to wait for data to show up. If 0, poll() does not block. Returns:True if this data to read, False otherwise.

recv(buff_size, flags=None)

Receive up to buff_size bytes from the remote host.

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

Parameters:

• buff_size (int) – The maximum number of bytes to read off the socket buffer from the remote host.
• flags – Optional flags to be set on the socket recv call.
• flags – bytearray | buffer | str | bytes | None

Returns:

A bytes-like object that contains data from the remote host.

Return type:

bytearray | buffer | str | bytes

recv_into(buffer, recv_num_bytes=None, flags=None)

Receive up to buff_size bytes from the remote host. A buffer is given to write directly into to reduce the memory overhead of recv (one less copy needed).

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

Parameters:

• buffer (buffer) – An object that implements the buffer interface and can have data written directly into it.
• recv_num_bytes (int | Nonre) – The maximum number of bytes to read off the socket buffer from the remote host. If this is not set, it is calculated from the length of the buffer passed in.
• flags – Optional flags to be set on the socket recv call.
• flags – bytearray | buffer | str | bytes | None

Returns:

The number of bytes read from the socket’s recv buffer from the remote host.

Return type:

int

send(byte_array, flags=None)

Send data to the other end of the duct. NOTE: This send call is a thin wrapper over the underlying socket send call, and is thus _stream oriented_. A single send call may _not_ send all the data given to the method. It is your responsibility to add additional semantics and metadata to get “message-based” send/recv, and to check from the return value how many bytes were _actually_ sent.

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

Parameters:

• byte_array (bytearray | buffer | str | bytes) – The bytes-like data to send to the other end.
• flags – Optional flags to be set on the socket send call.
• flags – bytearray | buffer | str | bytes | None

Returns:

The number of bytes sent.

Return type:

int

Child Raw Socket Duct

class ductworks.base_duct.RawDuctChild(connect_address, socket_constructor=<function unix_domain_socket_constructor>, socket_destructor=<function client_socket_destructor>, timeout=30)

The RawDuctChild is a thin wrapper over top of a “client” socket, and should be at the other end of a listening RawDuctParent. Once the first connection is seen, the listener socket is closed, and the “parent” and “child” act like an anonymous socket pair (with a few extra niceties, like a poll method).

close(shutdown=False)

Close the connection socket, if it’s open. :param shutdown: Should shutdown be performed on the connection socket? (Usually no). Default: False :type shutdown: bool :return: None

connect(connect_retry_count=3, connect_retry_delay=3)

Attempt to connect to another duct.

AlreadyConnectedException is raised if the connection has already been established.

Parameters:

• connect_retry_count (int) – The number of times to retry connecting if the connection is refused or if the file system entry for the Unix Domain socket does not yet exist on disk. Default: 3
• connect_retry_delay (int | float) – The amount of time to sleep between successive connect retries in the event of failure. Default: 3

Returns:

None

fileno()

Get the file descriptor of the underlying connection socket. This is useful for integrating into other event loops.

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

Returns:The connection file descriptor. Return type:int

poll(timeout=60)

Poll to see if the socket has any data to read from the remote host.

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

A RemoteSocketClosed exception is raised if the local socket has faulted (we can’t talk to the remote any more).

Parameters:timeout (float | int) – Time to wait for data to show up. If 0, poll() does not block. Returns:True if this data to read, False otherwise.

recv(buff_size, flags=None)

Receive up to buff_size bytes from the remote host.

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

Parameters:

• buff_size (int) – The maximum number of bytes to read off the socket buffer from the remote host.
• flags – Optional flags to be set on the socket recv call.
• flags – bytearray | buffer | str | bytes | None

Returns:

A bytes-like object that contains data from the remote host.

Return type:

bytearray | buffer | str | bytes

recv_into(buffer, recv_num_bytes=None, flags=None)

Receive up to buff_size bytes from the remote host. A buffer is given to write directly into to reduce the memory overhead of recv (one less copy needed).

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

Parameters:

• buffer (buffer) – An object that implements the buffer interface and can have data written directly into it.
• recv_num_bytes (int | Nonre) – The maximum number of bytes to read off the socket buffer from the remote host. If this is not set, it is calculated from the length of the buffer passed in.
• flags – Optional flags to be set on the socket recv call.
• flags – bytearray | buffer | str | bytes | None

Returns:

The number of bytes read from the socket’s recv buffer from the remote host.

Return type:

int

send(byte_array, flags=None)

Send data to the other end of the duct. NOTE: This send call is a thin wrapper over the underlying socket send call, and is thus _stream oriented_. A single send call may _not_ send all the data given to the method. It is your responsibility to add additional semantics and metadata to get “message-based” send/recv, and to check from the return value how many bytes were _actually_ sent.

A NotConnectedException is raised if the duct hasn’t been bound to the other end yet.

Parameters:

• byte_array (bytearray | buffer | str | bytes) – The bytes-like data to send to the other end.
• flags – Optional flags to be set on the socket send call.
• flags – bytearray | buffer | str | bytes | None

Returns:

The number of bytes sent.

Return type:

int

Supporting Functions and Datastructures

ductworks.base_duct.unix_domain_socket_constructor(linger_time=3)

Create a new UDS streaming socket with reasonable socket options set.

Parameters:linger_time (int) – The linger time after closing the socket to allow buffers to flush. Default: 3 Returns:A new Unix Domain socket. Return type:socket.socket

ductworks.base_duct.tcp_socket_constructor(linger_time=10, tcp_no_delay=1)

Create a new TCP socket with reasonable socket options set.

Parameters:

• linger_time (int) – The linger time after closing the socket to allow buffers to flush. Default: 10
• tcp_no_delay (int) – 1 -> disable Nagle’s algorithm on the created socket, 0 -> enable Nagle’s algorithm. Default: 1

Returns:

A new TCP socket.

:rtype socket.socket

ductworks.base_duct.unix_domain_socket_listener_destructor(listener_socket, shutdown=False, shutdown_mode=2)

Close and clean up a Unix Domain listener socket.

Parameters:

• listener_socket (socket.socket) – The socket to close down.
• shutdown (bool) – Should shutdown be performed on the socket? (Usually no). Default: False
• shutdown_mode (int) – The parameters to be passed to the socket’s shutdown function.

Returns:

None

ductworks.base_duct.tcp_socket_listener_destructor(listener_socket, shutdown=False, shutdown_mode=2)

Close and clean up a TCP listener socket.

Parameters:

• listener_socket (socket.socket) – The socket to close down.
• shutdown (bool) – Should shutdown be performed on the socket? (Usually no). Default: False
• shutdown_mode (int) – The parameters to be passed to the socket’s shutdown function.

Returns:

None

ductworks.base_duct.client_socket_destructor(client_socket, shutdown=False, shutdown_mode=2)

Close and clean up a client socket.

Parameters:

• client_socket (socket.socket) – The socket to close down.
• shutdown (bool) – Should shutdown be performed on the socket? (Usually no). Default: False
• shutdown_mode (int) – The parameters to be passed to the socket’s shutdown function.

Returns:

None

exception ductworks.message_duct.MessageProtocolException

exception ductworks.base_duct.DuctworksException

This is the generic base exception from which all custom exceptions thrown in Ductworks should inherit.

exception ductworks.base_duct.CommunicationFaultException

This exception is thrown when the underlying listener socket in the parent is returned in the error list on the select syscall while waiting for the child to connect.

exception ductworks.base_duct.AlreadyConnectedException

This exception is thrown when a child duct attempts to connect after a connection has already been established.

exception ductworks.base_duct.NotConnectedException

This exception is thrown when either duct attempts to send/recv/poll prior to a successful connection becoming established.

exception ductworks.base_duct.LocalSocketFault

This exception is thrown when the underlying communication socket is returned in the error list on the select syscall.