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 aClient
.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 theClient
to help identify it on the network.host (
str
, optional) – The hostname (or IP address) of the NetworkManager
that theClient
should connect to.port (
int
, optional) – The port number of the NetworkManager
that theClient
should connect to.timeout (
float
, optional) – The maximum number of seconds to wait to connect to the NetworkManager
.username (
str
, optional) – The username to use to connect to the NetworkManager
. You need to specify a username to connect to aManager
only if theManager
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. Seecli_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 NetworkManager
. You need to specify the password only if the NetworkManager
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. IfNone
then there is no (practical) limit.disable_tls (
bool
, optional) – Whether to connect to the NetworkManager
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 NetworkManager
. Not used if disable_tls isTrue
.assert_hostname (
bool
, optional) – Whether to check that the hostname of the NetworkManager
matches the value of host. Not used if disable_tls isTrue
.auto_save (
bool
, optional) – Whether to automatically save the certificate of the NetworkManager
if the certificate is not already saved. Not used if disable_tls isTrue
.
- Returns:
- 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.
- class msl.network.client.Client(name)[source]
Bases:
Device
Base class for all Clients.
- 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
. Seecli_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 theManager
. 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 afloat
orint
as the maximum number of seconds to wait for the reply from the NetworkManager
. The default timeout isNone
.
- 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.
- is_connected()[source]
Whether the
Client
is currently connected to the NetworkManager
.New in version 1.0.
- Returns:
bool
– Whether the connection is active.
- link(service, *, timeout=None)[source]
Link with a
Service
on the NetworkManager
.Changed in version 0.3: Added the timeout keyword argument.
- 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 NetworkManager
as a human-readable string.indent (
int
, optional) – The amount of indentation added for each recursive level. Only used if as_string isTrue
.timeout (
int
orfloat
, optional) – The maximum number of seconds to wait for the reply from the NetworkManager
.
- Returns:
- class msl.network.client.Link(client, service, identity)[source]
Bases:
object
A network link between a
Client
and aService
.Attention
Not to be instantiated directly. A
Client
creates aLink
via theClient.link()
method.- acquire_lock(shared=False, timeout=None)[source]
Acquire a lock with the linked
Service
.When a lock is acquired, no more
Client
s are allowed to link with theService
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 singleClient
can link with theService
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 singleClient
is linked with theService
. A shared lock allows for multiple simultaneous links, however, once any of the linkedClient
s requests a lock the lock is shared amongst the currently-linkedClient
s and no newClient
s can link with theService
until all locks have been released.timeout (
int
orfloat
, optional) – The maximum number of seconds to wait for the reply from the NetworkManager
.
- Returns:
list
ofstr
– The names of theClient
s that are linked with theService
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 theClient
that requested the lock.- Raises:
RuntimeError – If a lock cannot be acquired.
- property service_max_clients
The maximum number of
Client
s that can be linked with theService
. A value \(\leq\) 0 means that there is no limit.New in version 1.0.
- Type:
- 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()
- shutdown_service(*args, **kwargs)[source]
Send a request for the
Service
to shut down.A
Service
must also implement a method calledshutdown_service
otherwise calling thisshutdown_service()
method will raise an exception.See Starting a Service from another computer for an example use case.
New in version 0.5.
- Parameters:
args – The positional arguments that are passed to the
shutdown_service
method of theService
that this object is linked with.kwargs – The keyword arguments that are passed to the
shutdown_service
method of theService
that this object is linked with. Also accepts a timeout keyword argument as afloat
orint
as the maximum number of seconds to wait for the reply from the NetworkManager
. The default timeout isNone
.
- Returns:
Whatever the
shutdown_service
method of theService
returns.
- class msl.network.client.LinkedClient(service_name, **kwargs)[source]
Bases:
object
Create a new
Client
that has aLink
with the specifiedService
.New in version 0.4.
- Parameters:
- acquire_lock(shared=False, timeout=None)[source]
See
Link.acquire_lock
for more details.
- admin_request(attrib, *args, **kwargs)[source]
See
Client.admin_request
for more details.
- disconnect(timeout=None)[source]
See
Client.disconnect
for more details.
- identities(*, as_string=False, indent=2, timeout=None)[source]
See
Client.identities
for more details.
- is_connected()[source]
See
Client.is_connected
for more details.
- notification_handler(*args, **kwargs)[source]
See
Link.notification_handler
for more details.
- service_error_handler()[source]
This method is called immediately before an exception is raised if there was an error processing a request on the
Service
that this object is linked with.You can override this method to perform any necessary cleanup (e.g., closing file handles, shutting down threads, disconnecting from devices, etc.) before a
RuntimeError
is raised.The
Service
remains running. This is to clean up theClient
instance.
- shutdown_service(*args, **kwargs)[source]
See
Link.shutdown_service
for more details.
- spawn(name='LinkedClient')[source]
Returns a new connection to the Network
Manager
that has aLink
with the sameService
.
- unlink(timeout=None)[source]
See
Link.unlink
for more details.
- property address_manager
See
address_manager
for more details.
- release_lock(timeout=None)[source]
See
Link.release_lock
for more details.
- property service_address
See
Link.service_address
for more details.
- property service_attributes
See
Link.service_attributes
for more details.
- property service_language
See
Link.service_language
for more details.
- property service_max_clients
See
Link.service_max_clients
for more details.
- property service_name
See
Link.service_name
for more details.
- property service_os
See
Link.service_os
for more details.