leads.comm.prototype

Module Contents

Classes

Service
ConnectionBase
Connection
Callback
Entity

Functions

my_ip_addresses

API

leads.comm.prototype.my_ip_addresses() → list[str]

class leads.comm.prototype.Service(port: int)

Initialization

Parameters:

port – the port on which the service listens

port() → int

Returns:

the port that the service listens on or connects to

abstractmethod run(*args, **kwargs) → None

Override this method to define the specific workflow. :param args: args :param kwargs: kwargs

_run(*args, **kwargs) → None

This method is equivalent to run(). It leaves a middle layer for possible features in subclasses. :param args: args passed to run() :param kwargs: kwargs passed to run()

_register_process(*args, **kwargs) → None

Register the multithread worker. :param args: args passed to run() :param kwargs: kwargs passed to run() :exception RuntimeError: duplicated registration

_parallel_run(*args, **kwargs) → None

This method is similar to Service._run() except that it runs the workflow in a child thread. :param args: args passed to run() :param kwargs: kwargs passed to run()

start(parallel: bool = False, *args, **kwargs) → Self

This is the publicly exposed interface to start the service. :param parallel: True: run in a separate thread; False: run in the caller thread :param args: args passed to run() :param kwargs: kwargs passed to run() :return: self

abstractmethod close() → None

Release the occupied resources.

class leads.comm.prototype.ConnectionBase(remainder: bytes, separator: bytes)

Initialization

Parameters:

• remainder – the message remained from the last connection

• separator – the symbol that splits the stream into messages

drop_remainder() → None

Clear the current remainder.

use_remainder() → bytes

Parse the remainder queue. :return: the first message from the remainder queue

with_remainder(msg: bytes) → bytes

Parse the raw message and store the remaining part in the remainder queue. :param msg: the raw message :return: the first message

abstractmethod closed() → bool

Returns:

True: the socket is closed; False: the socket is active

abstractmethod receive() → bytes | None

Returns:

the message or None

abstractmethod send(msg: bytes) → None

Parameters:

msg – the message

disconnect() → None

Request disconnection.

abstractmethod close() → None

Directly close the socket.

class leads.comm.prototype.Connection(socket: socket.socket, address: tuple[str, int], remainder: bytes = b'', separator: bytes = b';', on_close: Callable[[Self], None] = lambda _: ...)

Bases: leads.comm.prototype.ConnectionBase

Initialization

Parameters:

• socket – the socket used for this connection (must be open)

• address – [address, port]

• remainder – the message remained from the last connection

• separator – the symbol that splits the stream into messages

• on_close – callback method when the connection is closed

__str__() → str

Returns:

“{address}:{port}”

closed() → bool

Return the status of the connection. :return: True: closed; False: active

_require_open_socket(mandatory: bool = True) → socket.socket

Check if the socket is active and return it. :param mandatory: True: an open socket is required; False: a closed socket is acceptable :return: the socket object :exception IOError: the socket is closed

receive(chunk_size: int = 512) → bytes | None

Receive a full sentence from the socket. :param chunk_size: chunk buffer size :return: bytes: the message; None: failed to read (will lead to disconnection)

send(msg: bytes) → None

Send the message to the peer. :param msg: the message to send

close() → None

Close the connection.

class leads.comm.prototype.Callback(chain: Self | None = None)

Bases: leads.callback.CallbackChain

Initialization

on_initialize(service: leads.comm.prototype.Service) → None

on_fail(service: leads.comm.prototype.Service, error: Exception) → None

on_connect(service: leads.comm.prototype.Service, connection: leads.comm.prototype.ConnectionBase) → None

on_receive(service: leads.comm.prototype.Service, msg: bytes) → None

on_disconnect(service: leads.comm.prototype.Service, connection: leads.comm.prototype.ConnectionBase) → None

class leads.comm.prototype.Entity(port: int, callback: leads.comm.prototype.Callback)

Bases: leads.comm.prototype.Service

Initialization

Parameters:

• port – the port that the service listens on or connects to

• callback – the callback interface

set_callback(callback: leads.comm.prototype.Callback) → None

Parameters:

callback – the callback interface

_stage(connection: leads.comm.prototype.ConnectionBase) → None

Stage the connection. It loops and blocks to listen for income messages. :param connection: the connection to stage

_run(*args, **kwargs) → None

This handles any exception raised by super()._run() and call the callback method on_fail(). :param args: args passed to run() :param kwargs: kwargs passed to run()