3.1. device_manager package

3.1.2. Submodules

device_manager.device module

Device types that are supported by the device manager and scanners.

Currently two types of devices are supported: USB and LAN devices. USB devices are identified by their vendor id, product id and serial number. The ethernet (LAN) devices use their mac address for a unique identification. Device’s are simple data classes that store the relevant information of the device. They are abstracted by their abstract base class Device. The device types are also encapsulated by the DeviceType enumeration. This enumeration makes it easier to find out the device’s type and to specify requested types when using scanners or the device manager.

class device_manager.device.DeviceType[source]

Bases: enum.Enum

An enumeration of available device types.

USB = 'usb'
LAN = 'lan'
property type

Returns the corresponding device type.

Returns

Corresponding Device-type of this enumeration value.

Return type

type

class device_manager.device.Device[source]

Bases: abc.ABC

Base class for all supported device types.

abstract property device_type

Corresponding DeviceType-object

abstract property unique_identifier

Returns an unique identifier for this device. This makes device objects of the same or similar type comparable.

property address

Main address of the device.

property address_aliases

Address aliases for this device.

If there are more than one address, which can be used to connect to the device, these addresses can be found here. If there is only one this property remains empty.

property all_addresses

All addresses contained in properties address and address_aliases

to_dict() → Dict[str, Any][source]

Converts the object into a dictionary.

Subclasses should call super.to_dict, when overriding this function.

Returns

Device object represented as dictionary.

Return type

dict

from_dict(dct: Dict[str, Any], old: bool = False) → None[source]

Fills the attributes from a dictionary.

Subclasses should call super.from_dict, when overriding this function.

Parameters

  • dct – A dictionary containing values, used to fill these object’s attributes.

  • old – True, if the addresses in d should be set as _old_addresses because they are not upt-to-date. False (default), if the addresses should be set to these values.

from_device(other: device_manager.device.Device) → None[source]

Updates self from another device.

Addresses that are currently in address or address_aliases, will be moved to _old_addresses.

Parameters

other – Device that is used to update self.

reset_addresses() → None[source]

Moves address and address_aliases to _old_addresses.

class device_manager.device.USBDevice[source]

Bases: device_manager.device.Device

Special device class for USB devices.

property device_type

Corresponding DeviceType-object.

property unique_identifier

Returns an unique identifier for this device. This makes device objects of the same or similar type comparable.

The unique identifiers of an usb device are vendor_id, product_id and serial.

property vendor_id

Manufacturer id of the USB device, defined by the USB committee.

property vendor_name

Name of the device’s manufacturer.

property product_id

Product id of the USB device, defined by the manufacturer.

property product_name

The model name of the device.

property revision_id

Revisision code of the USB device.

property serial

The USB device’s serial number.

to_dict() → Dict[str, Any][source]

Converts the object into a dictionary.

Returns

Device object represented as dictionary.

Return type

dict

from_dict(dct: Dict[str, Any], old: bool = False) → None[source]

Fills the attributes from a dictionary.

Parameters

  • d – A dictionary containing values, used to fill these object’s attributes

  • old – True, if the addresses in d should be set as _old_addresses because they are not upt-to-date. False (default), if the addresses should be set to these values.

from_device(other: device_manager.device.USBDevice) → None[source]

Updates self from another device.

Addresses that are currently in address or address_aliases, will be moved to _old_addresses.

Parameters

other – Device that is used to update self.

class device_manager.device.LANDevice[source]

Bases: device_manager.device.Device

Special device for ethernet devices.

property device_type

Corresponding DeviceType-object

property unique_identifier

Returns an unique identifier for this device. This makes device objects of the same or similar type comparable.

The unique identifier of an ethernet device is its mac address (physical address).

property mac_address

The mac address (physical address) of this ethernet device.

When setting the mac address, it is automatically converted into a standardized format.

to_dict() → Dict[str, Any][source]

Converts the object into a dictionary.

Returns

Device object represented as dictionary.

Return type

dict

from_dict(dct: Dict[str, Any], old: bool = False) → None[source]

Fills the attributes from a dictionary.

Parameters

  • d – A dictionary containing values, used to fill these object’s attributes

  • old – True, if the addresses in d should be set as _old_addresses because they are not upt-to-date. False (default), if the addresses should be set to these values.

from_device(other: device_manager.device.LANDevice) → None[source]

Updates self from another device.

Addresses that are currently in address or address_aliases, will be moved to _old_addresses.

Parameters

other – Device that is used to update self.

static format_mac(mac_address: Optional[str]) → Optional[str][source]

Checks if the mac address is formatted correctly. If so, the mac address is formatted in a standardized way (upper letters and colons as separators).

Parameters

mac_address – A mac address with colons, hyphens or dots as separators. None is also allowed.

Returns

The correctly formatted mac address or None, if mac_address was None, too.

Return type

str

Raises

TypeError – If mac_address has an invalid format and is not interpretable as a mac address.

device_manager.manager module

The device manager can store devices and makes them accessible by the user.

The DeviceManager-class works like a dictionary that stores Device-objects by user-defined names as dictionary-keys. But the device manager is slightly more intelligent than a ordinary dictionary. It automatically searches for device addresses, if these are not known, yet. For this purpose, it contains device scanners for each supported device type. These scanners can also be used by the user of the device manager. To add a device to the device manager, it is not required to create an device object with all the information. It is sufficient to set the device’s address as string (and optionally the device type, to only search with a specific scanner). Additionally, the device manager can be serialized into a JSON-file and it can also be loaded from this file. To make the file access easier, the function load_device_manager can be used.

Examples

Creating a DeviceManager-object:

>>> dm = DeviceManager()

Finding a device by its identifier:

>>> usb_device = dm.scanner["usb"].find_devices(serial="1234567890AB")

Adding a new device and accessing it

>>> dm["my-device"] = usb_device
>>> assert dm["my-device"] is usb_device

Adding a device by its address, is also possible

>>> dm["my-device"] = "192.168.1.23"  # Searches all supported device types
>>> dm["my-device", "lan"] = "192.168.1.23"  # Only searches ethernet (lan) devices

Last, but not least, you can serialize the DeviceManager into a JSON file:

>>> with open("filename.json", "w") as f:
>>>     dm.save(f)  # Save the device manager to "filename.json"
>>> with load_device_manager("filename.json") as dev_man:
>>>     device = dev_man["my-device", "usb"]  # returns `usb_device`
device_manager.manager.load_device_manager(filename: str, autosave: bool = False) → AbstractContextManager[device_manager.manager.DeviceManager][source]

Loads a device manager from a json formatted file.

Parameters

  • filename – Path to json file which contains the serialized device manager

  • autosave – True to save the device manager at the end of the with-statement, but only if no error occurred. If you want your device manager to be saved, use a try-except block inside the with-block.

Returns

A context manager which can be used in a with-statement. That context manager returns a DeviceManager if it is used in a with-statement.

class device_manager.manager.DeviceManager(**kwargs)[source]

Bases: device_manager.manager.DeviceDict

The DeviceManager stores devices by user-defined names. Also multiple devices can be stored for the same name as long as the device types are different.

Usage: - self[name] returns a DeviceTypeDict containing the devices of all available device types. - self[name, type] or self[name][type] can also be used to request a specific type of device.

Parameters

file – A handle to a json formatted file, to load the device manager data from.

property scanner

A DeviceScanner object that is used to search for devices

find_by_address(address: str, device_type: Union[device_manager.device.DeviceType, str, Type[device_manager.device.Device], device_manager.device.Device, None] = None) → Optional[device_manager.device.Device][source]

Finds a device by its address.

Parameters

  • address – The device’s address or port.

  • device_type – The device type or None, to search for all device types.

Returns

The device at the given address or None if no device was found.

Return type

Device

find_by_device(search_device: device_manager.device.Device, scan: bool = False) → Optional[device_manager.device.Device][source]

Finds a device that matches the unique identifiers of a given device.

Parameters

  • search_device – device whose identifiers are used to search for an up-to-date device.

  • scan – True, to scan for devices. False, to scan only, if there are currently no addresses for the device. If the device is already known and connected, it is taken from the cache.

Returns

A device that matches the identifiers of search_device. If search_device already has addresses stored and scan is False, the search_device is returned. Otherwise, this function will search for a device that matches the identifiers of search_device. The found device will be returned with addresses that are up-to-date. If this search does not lead to any results, None is returned.

set(key: Union[str, Tuple[str, Union[device_manager.device.DeviceType, str, Type[device_manager.device.Device], device_manager.device.Device]]], value: Union[device_manager.device.Device, str], scan: bool = False) → None[source]

Sets self[key] to value. The value is a Device-object or a string.

Parameters

  • key – The key (device name) used to store the value (device). If value is an address of type string, you can also provide a second key to specify the device type. This will speed up the search for the device’s address because only the corresponding protocol is used to search for the address.

  • value – Value to store at self[key]. The value can be a Device-object or a string. If a string is used, it is interpreted as the device’s address. The device at this address is determined automatically.

  • scan – True, to rescan for the device. If no addresses are known for the device to set, a scan is performed nevertheless. False, if you only want to scan in that case.

get(key: Union[str, Tuple[str, Union[device_manager.device.DeviceType, str, Type[device_manager.device.Device], device_manager.device.Device]]], scan: bool = False) → Union[Dict[device_manager.device.DeviceType, device_manager.device.Device], device_manager.device.Device][source]

Gets the value(s) behind self[key] (or self[key, type], if key is a tuple). If a device is found for the key, this function searches for updated addresses of this device, as soon as this was not done in this session before.

Parameters

  • key – The key whose value is requested. It can be a single string which specifies the device’s name. Or the key is a tuple. If this is the case, the first component specifies the device’s name, as well. The second component specifies a DeviceType that is used as key for the DeviceTypeDict: So, self[name, type] is equal to self[name][type].

  • scan – True, to rescan for the device. If no addresses are known for the requested device, a scan is performed nevertheless. False, if you only want to scan in that case.

Returns

If key is a single string, the return value is a DeviceTypeDict-object containing all available device types for this device. If key is a tuple, the second component specifies the requested device type to return, so if key is (name, type), the return value is the same as self[name][type].

reset_addresses() → None[source]

Resets the addresses of all stored devices.

This forces the scanners to rescan for devices, when these are requested again.

load(file: IO, clear: bool = True) → None[source]

Loads the device managers data from a json formatted file.

Parameters

  • file – A handle to a json formatted file, to load the device manager data from.

  • clear – True, if all previous data of this device manager should be cleared before loading the file. False, to keep the previous data. In this case, devices with equal keys may be replaced by the file’s data.

save(file: IO, pretty: bool = False) → None[source]

Serializes the device manager to json and saves it to a file.

Parameters

  • file – A handle to a file, to save the data at.

  • pretty – True, to indent the json file to make it easier to read. If False (default), the file is formatted without newlines or indentation, to reduce the amount of data.

device_manager.utils module

3.1.3. Module contents

The device manager module can be used to scan for connected devices and stores them persistently.

The devices are represented as Device-objects (especially USBDevice and LANDevice). To search for connected devices of these types the DeviceScanner-classes are used. The DeviceScanner is a general device scanner, that scans for all supported types. Additionally, there are the LANDeviceScanner and the USBDeviceScanner which are used to only scan the specific protocols. These are also contained by the general device scanner. The master class of this module is the DeviceManager which allows its users to scan for devices and also to store them persistently in a file. The device manager contains a general device scanner and a dictionary to store devices by a user-defined name. The whole class is serializable as a JSON formatted file from which it can be loaded, too.