devcfg - Devices network configuration data access tools¶

Devices network configuration data access tools.

The configuration data are stored as a single JSON file, which default path is /etc/cstbox/devices.cfg.

class pycstbox.devcfg.DeviceNetworkConfiguration(path='/etc/cstbox/devices.cfg', autoload=False, logger=None)¶

Abstraction class providing the access to the devices network configuration data.

It is an extended dictionary, containing the collection of the coordinators and attached devices, with safe manipulation methods

Parameters:	path (str) – the path of the root dir under which are stored the configuration data. Default value : as specified by DEFAULT_PATH module variable
Raises ValueError:
	if invalid value passed (None, empty, existing path but not pointing to a valid file,...)

path¶

The path of the configuration file.

load(path=None)¶

Loads the configuration data from a file.

Parameters:	path (str) – the path of the configuration file (default: as defined at instantiation time)
Raises ValueError:
	if data are not valid

load_str(s)¶

Loads the configuration date from a string containing the JSON serialization of the configuration.

load_dict(cfg)¶

Load the configuration data from a dictionary.

The passed dictionary must conform to the following structure, where each level is a dictionary and optional parts are indicated by square brackets:

• coordinators/

  • <coord_uid>/

    • type

    • [custom props if required]

    • devices/

      • <device_uid>/

        • type
        • address
        • location
        • [custom props if required]

• [configuration level custom props if required]

If the device is not a single endpoint, relevant sub-dictionaries must exist, keyed by ‘outputs’ or ‘controls’ depending on the endpoint nature. Endpoint definition is device type dependent.

Parameters:	cfg (dict) – the configuration data as a dictionary

get_coordinator(c_id)¶

Returns a coordinator by its id.

This is just an alias of the inherited dictionary item retrieval operator, but it can be more explicit like this in user’s code, since similar to get_device call.

add_coordinator(c)¶

Adds a coordinator to the configuration

Parameters:	c (Coordinator) – the coordinator to be added
Raises DuplicatedCoordinator:
	if instance is not a valid coordinator, of if it exists already

del_coordinator(c_id)¶

Deletes the coordinator and its devices.

Parameters:	c_id (str) – the id of coordinator to be deleted
Raises KeyError:
	if coordinator does not exist

add_device(c, d)¶

Adds a device to a coordinator.

Parameters:	c (Coordinator/str) – the coordinator instance, or its id d (Device) – the device instance
Raises ValueError:
	if the device is not valid

get_device(c, d_id)¶

Returns a device, knowing its parent and its local id.

Parameters:	c (Coordinator/str) – the coordinator instance, or its id d_id (str) – the id of the device within this coordinator
Raises KeyError:
	if not found

get_device_by_uid(uid)¶

Returns a device, knowing its parent and its unique id.

The unique id is something like the absolute path of a file. It is composed of the id of the parent coordinator, concatenated with the id of the device itself.

Parameters:	uid (str) – the unique id of the device (<coord_id> ‘/’ <dev_id>)
Raises:	ValueError – if the id is not valid KeyError – if not found

del_device(c, d)¶

Deletes a device.

It is removed from the parent coordinator, and its storage is deleted too.

Parameters:	c (Coordinator/str) – the coordinator instance, or its id d (Device) – the device instance

del_device_by_uid(uid)¶

Deletes a device.

Parameters:	uid (str) – the unique id of the device (<coord_id> ‘/’ <dev_id>)

rename_device(uid, newid)¶

Changes the id of a device.

:params str uid :

the unique id of the device (<coord_id> ‘/’ <dev_id>)

Params str newid:
	the new device local id (ie without the coord_id part)
Raises DuplicatedDevice:
	if the new id already exists

class pycstbox.devcfg.Metadata¶

This class bundles static methods working at the global level. They could have just been top-level functions, but it seemed cleaner to packaged them in a well identified structure.

static coordinator_types()¶

Returns the list of known coordinator types.

static coordinator(c_type)¶

Returns the metadata for a given coordinator type.

Raises ValueError:
	if not available

static device_types(c_type)¶

Returns the device types supported by a given coordinator type.

Parameters:	c_type (str) – the coordinator type
Returns:	the (maybe empty) list of supported device types
Raises ValueError:
	if unknown coordinator type

static device(fqdt)¶

Returns the metadata for a given device.

Parameters:	fqdt (str) – fully qualified device type (see _device_path documentation for details)
Returns:	the device metadata as a dictionary
Raises:	ValueError – if unknown device type InvalidCfgFile – if device metadata file has errors

class pycstbox.devcfg.DevCfgObject(uid)¶

Base class for all device configuration objects

It manages integrity checking by providing a method ensuring that all required attributes are defined. The list is defined by the class attribute _required_attrs, which can be overridden in descendants.

It also provides a generic JSON serialization mechanism, managing not persisted attributes.

Parameters:	uid (str) – the id of the object (cannot be None or empty)
Raises ValueError:
	if arguments not valid

classmethod required_attrs()¶

Returns the list of the required attributes, which must thus be present in the configuration data as keys in the dictionary describing the object.

check()¶

Check that all required attributes are defined.

Their list is defined by the class attribute _requited_attrs

Raises ValueError:
	if at least one attribute is missing

js_dict()¶

JSON serializer for DevCfgObject’s and descendant. (see json package documentation for details about custom serializers)

Returns:	a dictionary containing the attributes to be persisted. Transient (ie not persisted) ones are defined by the class attribute _transient

class pycstbox.devcfg.Coordinator(uid, **kwargs)¶

Network coordinator model

The coordinator has devices attached to it. It is implemented as a typed dictionary, augmented with convenience methods.

Required attributes :

• type

Parameters:	uid (str) – (see DevCfgObject) kwargs – optional complementary named parameters

add_device(d)¶

Adds a device to the coordinator.

Parameters:	d (Device) – the device instance
Raises ValueError:
	if the passed object is not a device, is invalid, or already exists

del_device(d)¶

Deletes a device

Parameters:	d (Device) – the device to be deleted, or its id
Raises:	ValueError – if the passed parameter is neither a Device nor a string. KeyError – if the device does not exist

class pycstbox.devcfg.Device(uid, **kwargs)¶

Device model

By default all the attributes of the instances are persisted.

Required attributes :

• address
• type
• location

Constructor

If a device type is provided in the extra parameters, the end points defined in the corresponding device metadata are automatically added to the new instance. Passed extra parameters are added afterwards, so that they can override those defined in the metadata.

Parameters:	uid (str) – (see DevCfgObject) kwargs – optional complementary named parameters