Code

Internal Implementation Documentation.

maaspower package

maaspower

automodule below.

maaspower.__version__: str

Version number as calculated by https://github.com/dls-controls/versiongit

massconfig.py

This module uses APISchema to serialize and deserialize the config file, plus provides a schema for easy editing of the config.

The MaasConfig class plus SwitchDevice derived classes in the devices folder provide an in memory representation of the contents of the maaspower YAML configuration file that specifies the set of power manager devices for which to serve web hooks.

maaspower.maasconfig

class maaspower.maasconfig.SwitchDevice(*, name: str)

A base class for the switching devices that the webhook server will control.

Concrete subclasses MUST provide a type field akin to this:

type: Literal[“ConreteDevice”] = “ConcreteDevice”

Concrete subclasses are found in the devices subfolder

copy(new_name: str, match) → SwitchDevice

Create a copy of this device with a new name. All the fields of the object are reformatted with substitutions in regex matches using {name} for the whole match and {m1} {m2} etc for matching subgroups.

This is used for creating a specific instance of a device from a regex defined device.

class maaspower.maasconfig.RegexSwitchDevice(*, name: str, query_on_regex: str = 'on', query_off_regex: str = 'off')

An abstract SwitchDevice which has the ability to interpret reponses and convert them to the requisit MaasReponse values using regex.

abstract run_query() → str

Ths method should be overridden by concrete classes. This method is called by query_state and it’s response is run through query_regex_on and query_regex_off.

returns: A value to be parsed by query_regex_on and query_regex_off.

query_state() → str

Uses the regex patterns defined in query_on_regex and query_off_regex to ascertain the correct response.

class maaspower.maasconfig.MaasConfig(name: str, ip_address: str, port: int, username: str, password: str, devices: Sequence[SwitchDevice])

Provides global information regarding webhook address, passwords etc.

Plus a list of switch devices. The devices are generic in this module, config definitions and function for specific device types are in the devices folder.

find_device(name: str)

use the indexed list to find the device or walk through the and check for regex matches. A regex match creates a new device which goes in the _devices cache so will not need matching a second time

TODO https://github.com/gilesknap/maaspower/issues/10#issue-1222292918

webhook.py

Use Flask to implement a web server that provides web hooks based on the provided configuration

maaspower.webhook

maaspower.webhook.command(devicename: str, command: str)

Accept webhooks at /maaspower/<devicename>/<command>

maaspower.webhook.load_web_hook(c: MaasConfig)

Setup config for the webserver

maaspower.webhook.run_web_hook(c: MaasConfig)

Launch the webserver

devices package

Each SwitchDevice derived class in this package adds support for a type of switching device.

maaspower.devices

smart_thing.py

Classes to represent the configuration and functionality for devices that can be controlled via the SmartThings API.

See https://www.smartthings.com/

maaspower.devices.smart_thing

class maaspower.devices.smart_thing.SmartThing(*, name: str, query_on_regex: str = 'on', query_off_regex: str = 'off', on: str, off: str, query: str, type: Literal['SmartThingDevice'] = 'SmartThingDevice', api_token: str = 'none', device_id: str = 'none')

A device controlled via SmartThings

shell_cmd.py

Classes to represent the configuration and functionality for devices that can be controlled via a command line utility.

e.g. smart power switching usb hubs https://github.com/mvp/uhubctl

maaspower.devices.shell_cmd

class maaspower.devices.shell_cmd.CommandLine(*, name: str, query_on_regex: str = 'on', query_off_regex: str = 'off', on: str, off: str, query: str, type: Literal['CommandLine'] = 'CommandLine')

A device controlled via a command line utility