msl.network.manager module

The Network Manager.

class msl.network.manager.Manager(port, password, login, hostnames, connections_table, users_table, hostnames_table, loop)

Bases: Network

The Network Manager.

Attention

Not to be instantiated directly. Start the Network Manager from the command line. Run msl-network start --help from a terminal for more information.

async acquire_lock(writer, uid, service, shared)

A request from a Client to lock a Service.

New in version 1.0.

Parameters:

• writer (asyncio.StreamWriter) – The stream writer of the Client.

• uid (str) – The unique identifier of the request.

• service (str) – The name of the Service that the Client wants to acquire a lock with.

• shared (bool) – Whether the lock is exclusive or shared.

async new_connection(reader, writer)

Receive a new connection request.

To accept the new connection request, the following checks must be successful:

1. The correct authentication reply is received.

2. A correct identity is received, i.e., is the connection from a Client or Service?

Parameters:

• reader (asyncio.StreamReader) – The stream reader.

• writer (asyncio.StreamWriter) – The stream writer.

async check_user(reader, writer)

Check the login credentials of a user.

Parameters:

• reader (asyncio.StreamReader) – The stream reader.

• writer (asyncio.StreamWriter) – The stream writer.

Returns:

bool – Whether the login credentials are valid.

async check_manager_password(reader, writer)

Check the Manager's password from the connected device.

Parameters:

• reader (asyncio.StreamReader) – The stream reader.

• writer (asyncio.StreamWriter) – The stream writer.

Returns:

bool – Whether the correct password was received.

async check_identity(reader, writer)

Check the identity of the connected device.

Parameters:

• reader (asyncio.StreamReader) – The stream reader.

• writer (asyncio.StreamWriter) – The stream writer.

Returns:

str or None – If the identity check was successful then returns the connection type, either 'client' or 'service', otherwise returns None.

async get_handshake_data(reader)

Used by check_manager_password(), check_identity() and check_user().

Parameters:

reader (asyncio.StreamReader) – The stream reader.

Returns:

None, str or dict – The data.

async handler(reader, writer)

Handles requests from the connected Clients and replies or notifications from the connected Services.

Parameters:

• reader (asyncio.StreamReader) – The stream reader.

• writer (asyncio.StreamWriter) – The stream writer.

async release_lock(writer, uid, service)

A request from a Client to unlock a Service.

New in version 1.0.

Parameters:

• writer (asyncio.StreamWriter) – The stream writer of the Client.

• uid (str) – The unique identifier of the request.

• service (str) – The name of the Service that the Client wants to release a lock with.

async remove_peer(id_type, writer)

Remove this peer from the registry of connected peers.

Parameters:

• id_type (str) – The type of the connection, either 'client' or 'service'.

• writer (asyncio.StreamWriter) – The stream writer of the peer.

async close_writer(writer)

Close the connection to the asyncio.StreamWriter.

Log that the connection is closing, drains the writer and then closes the connection.

Parameters:

writer (asyncio.StreamWriter) – The stream writer to close.

async shutdown_manager()

Disconnect all Services and Clients from the Manager and then shut down the Manager.

identity()

dict: The identity of the Network Manager.

async link(writer, uid, service)

A request from a Client to link it with a Service.

Parameters:

• writer (asyncio.StreamWriter) – The stream writer of the Client.

• uid (str) – The unique identifier of the request.

• service (str) – The name of the Service that the Client wants to link with.

async unlink(writer, uid, service)

A request from a Client to unlink it from a Service.

New in version 0.5.

Parameters:

• writer (asyncio.StreamWriter) – The stream writer of the Client.

• uid (str) – The unique identifier of the request.

• service (str) – The name of the Service that the Client wants to unlink from.

async write_request(writer, attribute, *args, **kwargs)

Write a request to a Client or to a Service.

Parameters:

• writer (asyncio.StreamWriter) – The stream writer of the Client or Service.

• attribute (str) – The name of the attribute to request.

• args – The arguments that attribute requires.

• kwargs – The key-value pairs that attribute requires.

class msl.network.manager.Peer(writer)

Bases: object

Metadata about a peer that is connected to the Network Manager.

Attention

Not to be called directly. To be called when the Network Manager receives a new_connection() request.

Parameters:

writer (asyncio.StreamWriter) – The stream writer for the peer.

msl.network.manager.run_forever(*, host=None, port=1875, auth_hostname=False, auth_login=False, auth_password=None, database=None, disable_tls=False, cert_file=None, key_file=None, key_file_password=None, log_level='INFO', log_file=None)

Start the event loop for the Network Manager.

This is a blocking function. It will not return until the event loop of the Manager has stopped.

New in version 0.4.

Changed in version 1.0: Renamed certfile to cert_file. Renamed keyfile to key_file. Renamed keyfile_password to key_file_password. Renamed logfile to log_file. Removed the debug keyword argument. Added the log_level keyword argument. Added the host keyword argument.

Parameters:

• host (str, optional) – The hostname or IP address to run the Network Manager on. If unspecified then all network interfaces are used.

• port (int, optional) – The port number to run the Network Manager on.

• auth_hostname (bool, optional) – If True then only connections from trusted hosts are allowed. If enabling auth_hostname then do not specify an auth_password and do not enable auth_login. Run msl-network hostname --help for more details.

• auth_login (bool, optional) – If True then checks a users login credentials (the username and password) before a Client or Service successfully connects. If enabling auth_login then do not specify an auth_password and do not enable auth_hostname. Run msl-network user --help for more details.

• auth_password (str, optional) – The password of the Network Manager. Essentially, this can be a thought of as a single password that all Clients and Services need to specify before the connection to the Network Manager is successful. Can be a path to a file that contains the password on the first line in the file (WARNING!! if the path does not exist then the value of the path becomes the password). If using an auth_password then do not enable auth_login nor auth_hostname.

• database (str, optional) – The path to the sqlite3 database that contains the records for the following tables – ConnectionsTable, HostnamesTable, UsersTable. If None then loads the default database.

• disable_tls (bool, optional) – Whether to use TLS for the communication protocol.

• cert_file (str, optional) – The path to the TLS certificate file. See load_cert_chain() for more details. Only required if using TLS.

• key_file (str, optional) – The path to the TLS key file. See load_cert_chain() for more details.

• key_file_password (str, optional) – The password to decrypt the key_file. See load_cert_chain() for more details. Can be a path to a file that contains the password on the first line in the file (WARNING!! if the path does not exist then the value of the path becomes the password).

• log_level (str or int, optional) – The logging level to initially use. Can also be changed via an admin_request().

• log_file (str, optional) – The file path to write logging messages to. If None then uses the default file path.

msl.network.manager.run_services(*services, **kwargs)

This function starts the Network Manager and then starts the specified Services.

This is a convenience function for running the Network Manager only when the specified Services are all connected to the Manager. Once all Services disconnect from the Manager then the Manager shuts down.

This is a blocking call. It will not return until the event loop of the Manager has stopped.

New in version 0.4.

Parameters:

• services – The Services to run on the Manager. Each Service must be instantiated but not started. This run_services() function will start each Service.

• kwargs – Keyword arguments are passed to run_forever() and to start(). The keyword arguments that are passed to run_forever() and start() that are not valid for that function are silently ignored.

Examples

If you want to allow a Client to be able to shut down a Service then implement a public shutdown_service() method on the Service. For example, the following shutdownable_example.py is a script that starts a Network Manager and two Services

# shutdownable_example.py

from msl.network import Service, run_services

class AddService(Service):

    def add(self, a, b):
        return a + b

    def shutdown_service(self, *args, **kwargs):
        # do whatever you need to do before the AddService shuts down
        # return whatever you want
        return True

class SubtractService(Service):

    def subtract(self, a, b):
        return a - b

    def shutdown_service(self, *args, **kwargs):
        # do whatever you need to do before the SubtractService shuts down
        # return whatever you want
        return 'Success!'

run_services(AddService(), SubtractService())

Then the Client script could be

from msl.network import connect

cxn = connect()
a = cxn.link('AddService')
s = cxn.link('SubtractService')
assert a.add(1, 2) == 3
assert s.subtract(1, 2) == -1
a.shutdown_service()
s.shutdown_service()

When both Services have shut down then the Network Manager will also shut down and the run_services() function will no longer be blocking the execution of shutdownable_example.py.

msl.network.manager.filter_run_forever_kwargs(**kwargs)

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

New in version 0.4.

Parameters:

kwargs – All keyword arguments that are not part of the function signature for run_forever() are silently ignored and are not included in the output.

Returns:

dict – Valid keyword arguments that can be passed to run_forever().