msl.network.database module

Databases that are used by the Network Manager.

class msl.network.database.Database(database, **kwargs)

Bases: object

Base class for connecting to a SQLite database.

Automatically creates the database if it does not already exist.

Parameters:

• database (str) – The path to the database file, or ':memory:' to open a connection to a database that resides in RAM instead of on disk.

• kwargs – Optional keyword arguments to pass to sqlite3.connect().

property path

The path to the database file.

Type:

str

property connection

The connection object.

Type:

sqlite3.Connection

property cursor

The cursor object.

Type:

sqlite3.Cursor

close()

Closes the connection to the database.

execute(sql, parameters=None)

Wrapper around sqlite3.Cursor.execute().

Parameters:

• sql (str) – The SQL command to execute

• parameters (list, tuple or dict, optional) – Only required if the sql command is parameterized.

tables()

list of str: A list of the names of each table that is in the database.

table_info(name)

Returns the information about each column in the specified table.

Parameters:

name (str) – The name of the table to get the information of.

Returns:

list of tuple – The list of the fields in the table. The indices of each tuple correspond to:

• 0 - id number of the column

• 1 - the name of the column

• 2 - the datatype of the column

• 3 - whether a value in the column can be NULL (0 or 1)

• 4 - the default value for the column

• 5 - whether the column is used as a primary key (0 or 1)

column_names(table_name)

Returns the names of the columns in the specified table.

Parameters:

table_name (str) – The name of the table.

Returns:

list of str – A list of the names of each column in the table.

column_datatypes(table_name)

Returns the datatype of each column in the specified table.

Parameters:

table_name (str) – The name of the table.

Returns:

list of str – A list of the datatypes of each column in the table.

class msl.network.database.ConnectionsTable(*, database=None, as_datetime=False, **kwargs)

Bases: Database

The database table for devices that have connected to the Network Manager.

Parameters:

• database (str, optional) – The path to the database file, or ':memory:' to open a connection to a database that resides in RAM instead of on disk. If None then loads the default database.

• as_datetime (bool, optional) – Whether to fetch the timestamps from the database as datetime.datetime objects. If False then the timestamps will be of type str.

• kwargs – Optional keyword arguments to pass to sqlite3.connect().

NAME = 'connections'

The name of the table in the database.

Type:

str

insert(peer, message)

Insert a message about what happened when a device connected.

Parameters:

• peer (Peer) – The peer that connected to the Network Manager.

• message (str) – The message about what happened (e.g, the connection was successful, or it failed).

connections(*, start=None, end=None)

Return the information of the devices that have connected to the Network Manager.

Changed in version 1.0: Use T as the separator between the date and time. Renamed timestamp1 to start. Renamed timestamp2 to end.

Parameters:

• start (datetime.datetime or str, optional) – Include all records that have a timestamp \(\ge\) start. If a str then in the yyyy-mm-dd or yyyy-mm-ddTHH:MM:SS format.

• end (datetime.datetime or str, optional) – Include all records that have a timestamp \(\le\) end. If a str then in the yyyy-mm-dd or yyyy-mm-ddTHH:MM:SS format.

Returns:

list of tuple – The connection records.

class msl.network.database.HostnamesTable(*, database=None, **kwargs)

Bases: Database

The database table for trusted hostname’s that are allowed to connect to the Network Manager.

Parameters:

• database (str, optional) – The path to the database file, or ':memory:' to open a connection to a database that resides in RAM instead of on disk. If None then loads the default database.

• kwargs – Optional keyword arguments to pass to sqlite3.connect().

NAME = 'auth_hostnames'

The name of the table in the database.

Type:

str

insert(hostname)

Insert a hostname.

If the hostname is already in the table then it does not insert it again.

Parameters:

hostname (str) – The trusted hostname.

delete(hostname)

Delete a hostname.

Parameters:

hostname (str) – A hostname in the table.

Raises:

ValueError – If hostname is not in the table.

hostnames()

list of str: Returns all the trusted hostnames.

class msl.network.database.UsersTable(*, database=None, **kwargs)

Bases: Database

The database table for keeping information about a users login credentials for connecting to a Network Manager.

Parameters:

• database (str, optional) – The path to the database file, or ':memory:' to open a connection to a database that resides in RAM instead of on disk. If None then loads the default database.

• kwargs – Optional keyword arguments to pass to sqlite3.connect().

NAME = 'auth_users'

The name of the table in the database.

Type:

str

insert(username, password, is_admin)

Insert a new user.

The password is encrypted and stored in the database using PBKDF2

To update the values for a user use update().

Parameters:

• username (str) – The name of the user.

• password (str) – The password of the user in plain-text format.

• is_admin (bool) – Does this user have admin rights?

Raises:

ValueError – If the username is invalid or if password is empty.

update(username, *, password=None, is_admin=None)

Update either the salt used for the password and/or the admin rights.

Parameters:

• username (str) – The name of the user.

• password (str, optional) – The password of the user in plain-text format.

• is_admin (bool, optional) – Does this user have admin rights?

Raises:

ValueError – If username is not in the table. If both password and is_admin are not specified. If password is an empty string.

delete(username)

Delete a user.

Parameters:

username (str) – The name of the user.

Raises:

ValueError – If username is not in the table.

get_user(username)

Get the information about a user.

Parameters:

username (str) – The name of the user.

Returns:

tuple – Returns (pid, username, key, salt, is_admin) for the specified username.

records()

list of tuple: Returns [(pid, username, key, salt, is_admin), …] for all users.

usernames()

list of str: Returns the names of all registered users.

users()

list of tuple: Returns [(username, is_admin), … ] for all users.

is_user_registered(username)

bool: Whether username is a registered user.

is_password_valid(username, password)

Check whether the password matches the encrypted password in the database.

Parameters:

• username (str) – The name of the user.

• password (str) – The password to check (in plain-text format).

Returns:

bool – Whether password matches the password in the database for the user.

is_admin(username)

Check whether a user has admin rights.

Parameters:

username (str) – The name of the user.

Returns:

bool – Whether the user has admin rights.

msl.network.database.convert_datetime(value)

Convert a date and time to a datetime object.

Parameters:

value (bytes) – The datetime value from an SQLite database.

Returns:

datetime.datetime – The value as a datetime object.