msl.network.client module

Use the connect() function to connect to a Network Manager as a Client.

msl.network.client.connect(*, name='Client', host='localhost', port=1875, timeout=10, username=None, password=None, password_manager=None, read_limit=None, disable_tls=False, cert_file=None, assert_hostname=True, auto_save=False)[source]

Create a new connection to a Network Manager as a Client.

Changed in version 0.4: Renamed certificate to certfile.

Changed in version 1.0: Renamed certfile to cert_file. Added the auto_save and read_limit keyword arguments.

Parameters:

name (str, optional) – A name to assign to the Client to help identify it on the network.
host (str, optional) – The hostname (or IP address) of the Network Manager that the Client should connect to.
port (int, optional) – The port number of the Network Manager that the Client should connect to.
timeout (float, optional) – The maximum number of seconds to wait to connect to the Network Manager.
username (str, optional) – The username to use to connect to the Network Manager. You need to specify a username to connect to a Manager only if the Manager was started using the --auth-login flag. If a username is required, and you have not specified a value then you will be asked for a username. See cli_start for more details.
password (str, optional) – The password that is associated with username. If a password is required, and you have not specified a value then you will be asked for the password.
password_manager (str, optional) – The password that is associated with the Network Manager. You need to specify the password only if the Network Manager was started using the --auth-password flag. If a password is required, and you have not specified a value then you will be asked for the password.
read_limit (int, optional) – The buffer size limit when reading bytes from a network stream. If None then there is no (practical) limit.
disable_tls (bool, optional) – Whether to connect to the Network Manager with or without using the secure TLS protocol.
cert_file (str, optional) – The path to a certificate file to use for the secure TLS connection with the Network Manager. Not used if disable_tls is True.
assert_hostname (bool, optional) – Whether to check that the hostname of the Network Manager matches the value of host. Not used if disable_tls is True.
auto_save (bool, optional) – Whether to automatically save the certificate of the Network Manager if the certificate is not already saved. Not used if disable_tls is True.

Returns:

Client – A new connection to a Network Manager.

msl.network.client.filter_client_connect_kwargs(**kwargs)[source]

From the specified keyword arguments only return those that are valid for connect().

New in version 0.4.

Parameters:: kwargs – All keyword arguments that are not in the function signature of connect() are silently ignored and are not included in the output.
Returns:: dict – Valid keyword arguments that can be passed to connect().

class msl.network.client.Client(name)[source]

Bases: Device

Base class for all Clients.

Attention

Do not instantiate directly. Use connect() to connect to a Network Manager.

admin_request(attrib, *args, **kwargs)[source]

Send a request to the Network Manager as an administrator.

The user that calls this method must have administrative privileges for that Manager. See cli_user for details on how to create a user that is an administrator .

Changed in version 0.3: Added a timeout option as one of the keyword arguments.

Parameters:

attrib (str) – The attribute of the Manager. Can contain dots . to access sub-attributes.
*args – The arguments to send to attrib of the Manager.
**kwargs – The keyword arguments to send to attrib of the Manager. Also accepts a timeout keyword argument as a float or int as the maximum number of seconds to wait for the reply from the Network Manager. The default timeout is None.

Returns:

The reply from the Network Manager.

Examples

>>> from msl.network import connect
>>> cxn = connect(**kwargs)
>>> cxn.admin_request('users_table.usernames')
['Alice', 'Bob', 'Charlie', 'Eve', 'admin']
>>> cxn.admin_request('users_table.is_user_registered', 'N.Bohr')
False

An admin can also shut down the Manager

>>> from msl.network.constants import SHUTDOWN_MANAGER
>>> cxn.admin_request(SHUTDOWN_MANAGER)

disconnect(timeout=None)[source]

Disconnect from the Network Manager.

Changed in version 1.0: Added the timeout keyword argument.

Parameters:: timeout (int or float, optional) – The maximum number of seconds to wait for the reply from the Network Manager.

is_connected()[source]

Whether the Client is currently connected to the Network Manager.

New in version 1.0.

Returns:: bool – Whether the connection is active.

link(service, *, timeout=None)[source]

Link with a Service on the Network Manager.

Changed in version 0.3: Added the timeout keyword argument.

Parameters:

service (str) – The name of the Service to link with.
timeout (int or float, optional) – The maximum number of seconds to wait for the reply from the Network Manager.

Returns:

Link – A Link with the requested service.

identities(*, as_string=False, indent=2, timeout=None)[source]

Returns the identities of all devices that are connected to the Network Manager.

Changed in version 0.3: Added the timeout keyword argument.

Changed in version 0.4: Renamed as_yaml to as_string.

Changed in version 1.0: Renamed this method from manager to identities.

Parameters:

as_string (bool, optional) – Whether to return the information from the Network Manager as a human-readable string.
indent (int, optional) – The amount of indentation added for each recursive level. Only used if as_string is True.
timeout (int or float, optional) – The maximum number of seconds to wait for the reply from the Network Manager.

Returns:

dict or str – The identities of all connected devices.

spawn(name='Client')[source]

Returns a new connection to the Network Manager.

Parameters:: name (str, optional) – The name to assign to the new Client.
Returns:: Client – A new Client.

unlink(link, *, timeout=None)[source]

Unlink from a Service on the Network Manager.

New in version 0.5.

Parameters:

link (Link) – The object that is linked with the Service.
timeout (int or float, optional) – The maximum number of seconds to wait for the reply from the Network Manager.

class msl.network.client.Link(client, service, identity)[source]

Bases: object

A network link between a Client and a Service.

Attention

Not to be instantiated directly. A Client creates a Link via the Client.link() method.

acquire_lock(shared=False, timeout=None)[source]

Acquire a lock with the linked Service.

When a lock is acquired, no more Clients are allowed to link with the Service until all locks have been released.

If service_max_clients returns a value of 1, then there is no need to acquire a lock since only a single Client can link with the Service at a time.

New in version 1.0.

Parameters:

shared (bool, optional) – Whether the lock is exclusive or shared. An exclusive lock can only be acquired if a single Client is linked with the Service. A shared lock allows for multiple simultaneous links, however, once any of the linked Clients requests a lock the lock is shared amongst the currently-linked Clients and no new Clients can link with the Service until all locks have been released.
timeout (int or float, optional) – The maximum number of seconds to wait for the reply from the Network Manager.

Returns:

list of str – The names of the Clients that are linked with the Service while the lock is active. For an exclusive lock, only a single link is allowed so the list contains a single item that is the name of the Client that requested the lock.

Raises:

RuntimeError – If a lock cannot be acquired.

release_lock(timeout=None)[source]

Release a lock with the linked Service.

New in version 1.0.

Parameters:: timeout (int or float, optional) – The maximum number of seconds to wait for the reply from the Network Manager.
Returns:: list of str – The names of the Clients that still have a lock with the Service after this lock has been released. An emtpy list means that there are no active locks.

property service_address

The address of the Service that this object is linked with.

Type:: str

property service_attributes

The attributes of the Service that this object is linked with.

Type:: dict

property service_language

The programming language that the Service is running on.

Type:: str

property service_max_clients

The maximum number of Clients that can be linked with the Service. A value \(\leq\) 0 means that there is no limit.

New in version 1.0.

Type:: int

property service_name

The name of the Service that this object is linked with.

Type:: str

property service_os

The operating system that the Service is running on.

Type:: str

disconnect(timeout=None)[source]: An alias for unlink().

New in version 0.5.

notification_handler(*args, **kwargs)[source]

Handle a notification from the Service that emitted a notification.

Important

You must re-assign this method at the instance level in order to handle the notification.

New in version 0.5.

Parameters:

args – The arguments that were emitted.
kwargs – The keyword arguments that were emitted.

Examples

The following assumes that the Heartbeat Service is running on the same computer. Using types.MethodType allows for the print_notification function to access the self attribute of heartbeat.

>>> import types
>>> from msl.network import connect
>>> cxn = connect()
>>> heartbeat = cxn.link('Heartbeat')
>>> def print_notification(self, *args, **kwargs):
...     print(f'The {self.service_name} Service emitted', args, kwargs)
...
>>> heartbeat.notification_handler = types.MethodType(print_notification, heartbeat)
The Heartbeat Service emitted (72,) {}
The Heartbeat Service emitted (73,) {}
The Heartbeat Service emitted (74,) {}
The Heartbeat Service emitted (75,) {}
The Heartbeat Service emitted (76,) {}
The Heartbeat Service emitted (77,) {}
>>> heartbeat.reset()
The Heartbeat Service emitted (0,) {}
The Heartbeat Service emitted (1,) {}
The Heartbeat Service emitted (2,) {}
The Heartbeat Service emitted (3,) {}
The Heartbeat Service emitted (4,) {}
The Heartbeat Service emitted (5,) {}
The Heartbeat Service emitted (6,) {}
>>> heartbeat.kill()
>>> cxn.disconnect()