tlspyo API (tlspyo.api module)

class tlspyo.api.Endpoint(ip_server: str, port: int, password: str, groups=None, local_com_port: int = 2097, header_size: int = 10, max_buf_len: int = 4096, security: str = DEFAULT_SECURITY, keys_dir: str | None = None, hostname: str = 'default', serializer=None, deserializer=None, recon_max_delay=60.0, recon_initial_delay=10.0, recon_factor=1.5, recon_jitter=0.1, deserializer_mode='asynchronous')

Bases: object

tlspyo Endpoint.

Endpoints in tlspyo are python objects that can securely send and receive Python object over the network. They communicate via the Relay, and should use TLS security (default) on public networks. See the Command Line Interface section of the documentation to generate your TLS credentials.

Parameters:

• ip_server (str) – the IP address of the Relay (set to ‘127.0.0.1’ for local testing)

• port (int) – the port of the Relay (use the same number for the Relay, it must be > 1024)

• password (str) – password of the Relay (use the same for the Relay, the stronger, the better)

• groups (tuple of str, or str) – groups in which this Endpoint is

• local_com_port (int) – local port used for internal communication with Twisted

• header_size (int) – number of bytes used for the header (the default should be OK for most cases)

• max_buf_len (int) – max bytes to read at once from socket buffers (the default should be OK for most cases)

• security (str) – one of (None, “TLS”); None disables TLS, do not use None on a public network unless you know what you are doing!

• serializer (callable) – custom serializer that outputs a bytestring from a python object

• deserializer (callable) – custom deserializer that outputs a python object from a bytestring

• recon_max_delay (float) – in case of network failure, maximum delay between reconnection attempts

• recon_initial_delay (float) – in case of network failure, initial delay between reconnection attempts

• recon_factor (float) – in case of network failure, delay will increase by this factor between attempts

• recon_jitter (float) – in case of network failure, jitter factor of the delay between attempts

• deserializer_mode (str) – one of (“synchronous”, “asynchronous”); (“sync”, “async”) are also accepted; in asynchronous mode, objects are deserialized by the receiver thread as soon as they arrive, such that they become available to the calling thread as soon as it needs to retrieve them; in synchronous mode, objects are deserialized by the calling thread upon object retrieval; synchronous mode removes the need for potentially useless, randomly timed deserialization in the background, at the cost of performing deserialization upon object retrieval instead

broadcast(obj, group)

Alias for send_object(obj=obj, destination={group: -1})

Note that broadcasting an object overrides the previous brodcast object

Parameters:

• obj (object) – object to send to be broadcast to entire group

• group (str) – destination group to which the object should be broadcast.

get_last(max_items=1, blocking=False)

Returns at most the max_items most recently received objects, and clears receiving buffer.

Items are returned from older to more recent. Calling this method clears the receiving buffer. In other words, only the most recent objects are retrieved, older objects in the buffer are deleted. In case this behavior is not desirable in your application, use receive_all or pop instead.

Parameters:

• max_items (int) – maximum number of items to return

• blocking (bool) – If True, the call blocks until at least one item is retrieved. Otherwise, the returned list may be empty.

Returns:

The returned items.

Return type:

list

notify(groups)

Notifies the Relay that the Endpoint is ready to retrieve consumables from destination groups.

groups can either be:

• a string (single group)

• a tuple of strings (set of groups)

• a dictionary where keys are strings (group) and values are integers (number of consumables from the group)

When groups is a string or a tuple of strings, 1 consumable will be retrieved per corresponding group(s). When groups is a dictionary, each key is a destination group.

For each corresponding value:

• if the value is N < 0, all available consumables are retrieved from the group

• if the value is N > 0, at most N available consumables are retrieved from the group

In any case, the group strings must be a subset of the Endpoint’s groups.

Parameters:

groups (object) – destination groups of the consumables.

pop(max_items=1, blocking=False)

Returns at most max_items oldest received objects (FIFO).

Items are returned from older to more recent.

Parameters:

• max_items (int) – max number of retrieved items.

• blocking (bool) – If True, the call blocks until at least 1 item is retrieved. Otherwise, the returned list may be empty.

Returns:

returned items.

Return type:

list

produce(obj, group)

Alias for send_object(obj=obj, destination={group: 1}).

Parameters:

• obj (object) – object to send as consumable

• group (str) – target group

receive_all(blocking=False)

Returns all received objects in a list, from oldest to newest.

Parameters:

blocking (bool) – If True, the call blocks until objects are available. Otherwise, the list may be empty.

Returns:

received objects

Return type:

list

send_object(obj, destination)

Either broadcast object to destination group(s) or send it as a consumable.

obj can be any picklable python object.

destination can either be:

• a string (single group)

• a tuple of strings (set of groups)

• a dictionary where keys are strings (group) and values are integers (number of copies for the group)

When destination is a string or a tuple of strings, the object will be broadcast to corresponding group(s).

When destination is a dictionary, each key is a destination group.

For each corresponding value:

• if the value is N < 0, the object is broadcast to the group

• if the value is N > 0, N objects are sent to the group to be consumed. To consume an object, the Endpoint first needs to signal itself as idle for the corresponding group with Endpoint.notify().

Parameters:

• obj (object) – object to broadcast to destination

• destination (object) – destination group(s)

stop()

Stop the Endpoint.

class tlspyo.api.Relay(port: int, password: str, accepted_groups=None, local_com_port: int = 2096, header_size: int = 10, security: str = DEFAULT_SECURITY, keys_dir: str | None = None, serializer=None, deserializer=None)

Bases: object

tlspyo Relay.

Endpoints connect to a central Relay, which allows them to communicate in tlspyo. When used on the Internet, the machine running the Relay must be directly visible from the Internet. (Usually, if the machine is behind an Internet box/router, this involves port forwarding.) WHEN USING tlspyo ON THE INTERNET, IT IS IMPORTANT TO USE TLS SECURITY (default). In particular, you will want to choose a strong password, and use your own TLS credentials. See the Command Line Interface section of the documentation to generate your TLS credentials.

Parameters:

• port (int) – port of the Relay

• password (str) – password of the Relay

• accepted_groups (object) –

  groups accepted by the Relay. If None, the Relay accepts any group; Else, must be a dictionary where keys are groups and values are dictionaries with the following entries:

  • ’max_count’: max number of connected clients in the group (None for unlimited)

  • ’max_consumables’: max number of pending consumables in the group (None for unlimited)

• local_com_port (int) – local port used for internal communication with Twisted.

• header_size (int) – bytes to read at once from socket buffers (the default should work for most cases)

• security (str) – one of (None, “TLS”); None disables TLS, do not use None on a public network unless you know what you are doing!

• serializer (callable) – custom serializer that outputs a bytestring from a python object

• deserializer (callable) – custom deserializer that outputs a python object from a bytestring

stop()

Stop the Relay.