lce_service.device_class_api package

Device Class Module.

This module provides the functionality needed to list, create, update and delete device classes, which the platform has no other API to author.

A device class is keyed by its GUID, so a device class authored on one system (e.g. as part of a PowerPack) keeps its identity on another. Dynamic Applications are aligned with a device class through its class type, which is allocated when the device class is created, and devices belong to a device class the same way. A device class that devices or Dynamic Applications still reference cannot be deleted. An icon is assigned to a device class the way the setDeviceClassIcon GraphQL mutation assigns it.

exception lce_service.device_class_api.DeviceClassInUseError(message: str, references: Dict[str, Any])

Bases: InvalidResourceError

Exception raised when a device class cannot be deleted because it is still referenced.

Parameters:

  • message – A descriptive error message naming the device class.

  • references – What still references the device class, with the number of devices and the Dynamic Applications aligned to it.

exception lce_service.device_class_api.InvalidIconError(message: str)

Bases: InvalidResourceError

Exception raised when the icon a request names does not resolve to a single icon.

Parameters:

message – A descriptive error message naming the icon.

exception lce_service.device_class_api.InvalidIconRequestError

Bases: ValueError

Exception raised when the body of a request assigning an icon is not valid.

Parameters:

message – A descriptive error message.

lce_service.device_class_api.delete_device_class(dbc: silo_cursor, device_class_id: int, user: User) → Dict[str, Any]

Delete a device class that nothing references.

A device class cannot be deleted while devices belong to it or Dynamic Applications are aligned to it. Its assigned and fallback icons are unassigned, the platform’s cache of device classes is invalidated, and the revision of its PowerPack is incremented when it is installed.

Parameters:

  • dbc – A silo_cursor instance, within the transaction of the request.

  • device_class_id – The id of the device class.

  • user – The user making the request.

Returns:

The identifier (id, guid and name) of the deleted device class.

Raises:
lce_service.device_class_api.get_code_for_device_class(dbc: silo_cursor, device_class_id: int, pretty: bool, include: str | None = None, exclude: str | None = None) → Dict[str, Any]

Retrieve and serialize a single device class.

Parameters:

  • dbc – A silo_cursor instance used to execute the database query.

  • device_class_id – The id of the device class.

  • pretty – Whether enums are serialized by name rather than by value.

  • include – An optional comma-separated list of the fields to include.

  • exclude – An optional comma-separated list of the fields to exclude.

Returns:

The serialized device class.

Raises:
lce_service.device_class_api.get_codes_for_device_classes(dbc: silo_cursor, device_class_ids: List[int], pretty: bool, include: str | None = None, exclude: str | None = None) → List[Dict[str, Any]]

Retrieve and serialize device classes, with one query.

Parameters:

  • dbc – A silo_cursor instance used to execute the database query.

  • device_class_ids – The ids of the device classes.

  • pretty – Whether enums are serialized by name rather than by value.

  • include – An optional comma-separated list of the fields to include.

  • exclude – An optional comma-separated list of the fields to exclude.

Returns:

The serialized device classes, in the order of their ids.

Raises:
lce_service.device_class_api.get_device_class_icon(dbc: silo_cursor, device_class_id: int) → Dict[str, Any]

Get the icons of a device class.

Parameters:

  • dbc – A silo_cursor instance used to execute the database queries.

  • device_class_id – The id of the device class.

Returns:

The icons of the device class, see build_icon_result.

Raises:
lce_service.device_class_api.get_device_class_identifier(dbc: silo_cursor, identifier: int | str, fuzzy: bool = True) → int

Resolve a device class identifier (an id, a GUID or a name) to the id of a device class.

Parameters:

  • dbc – A silo_cursor instance used to look up the device class.

  • identifier – The id, GUID (in either case) or name of the device class.

  • fuzzy – Whether a name without an exact match is matched approximately. Requests that change a device class pass False, so they only act on the device class named.

Returns:

The id of the device class.

Raises:
lce_service.device_class_api.get_device_classes_from_filters(dbc: silo_cursor, args: Dict[str, str], pretty: bool, include: str | None, exclude: str | None, require_all: bool) → Dict[str, List[Dict[str, Any]]]

Retrieve and serialize the device classes matching filter criteria.

Filters use the same syntax as the other entities of the API, e.g. filter[class_name][contains]=Microsoft&filter[device_type][is]=COMPONENT. Unlike other entities, filters are optional: every device class is listed when none are provided. The limit and offset query parameters page through the device classes, ordered by id.

Parameters:

  • dbc – A silo_cursor instance used to execute the database queries.

  • args – The query parameters of the request, holding the filters and paging.

  • pretty – Whether enums are serialized by name rather than by value.

  • include – An optional comma-separated list of the fields to include.

  • exclude – An optional comma-separated list of the fields to exclude.

  • require_all – Whether every filter must match (AND), rather than any filter (OR).

Returns:

A dictionary holding the “device_classes” that match, ordered by id.

Raises:

  • ValueError – Raised when a filter is malformed, references an unknown field or uses an unsupported operator, or a paging parameter is not an integer from 0 to MAX_PAGING_VALUE.

  • MissingResourceError – Raised when filters are provided and no device class matches, unless the page is empty for paging (an offset, or a limit of 0).

  • InvalidResourceError – Raised when a stored device class fails a rule of its model that is not about a single field.

  • DatabaseExecutionError – Raised when a database query fails.

lce_service.device_class_api.get_device_classes_from_payload(dbc: silo_cursor, payload: List[Dict[str, Any]] | Dict[str, Any]) → List[DeviceClass]

Convert a request payload into device class models to create or update.

A device class is keyed by its GUID: a GUID that exists updates that device class with the provided fields, a new GUID creates a device class with it, and no GUID creates a device class with a generated one. The read-only fields of a device class (see DEVICE_CLASS_READ_ONLY_FIELDS) are discarded, so a retrieved device class is a valid payload.

Parameters:

  • dbc – A silo_cursor instance used to retrieve the stored device classes and resolve categories.

  • payload – A single device class dictionary, a list of them, or a dictionary with a “device_classes” list.

Returns:

The device class models, in payload order.

Raises:

  • ValueError – Raised when the payload format is invalid or provides a GUID twice.

  • InvalidResourceError – Raised when a device class fails validation.

  • DatabaseExecutionError – Raised when a database query fails.

lce_service.device_class_api.get_icons(dbc: silo_cursor, search: str | None = None) → Dict[str, List[Dict[str, Any]]]

List the icons that can be assigned to device classes.

Parameters:

  • dbc – A silo_cursor instance used to execute the database query.

  • search – An optional text the names of the icons must contain, ignoring case. It is matched as text: % and _ are not wildcards. Surrounding whitespace is ignored, so a blank search lists every icon, like other optional parameters.

Returns:

A dictionary holding the “icons” (id, name, and size in bytes), ordered by name.

Raises:

DatabaseExecutionError – Raised when the database query fails.

lce_service.device_class_api.set_device_class_icon(dbc: silo_cursor, device_class_id: int, icon: str | None, user: User) → Dict[str, Any]

Assign an icon to a device class, or unassign its icon.

This does what the setDeviceClassIcon GraphQL mutation does: the assignment of the device class is replaced, and the change is recorded in the audit log. The legacy fallback icon of the device class is left as is. Unlike the mutation, assigning the icon a device class already has changes nothing, and is not audited.

Parameters:

  • dbc – A silo_cursor instance, within the transaction of the request.

  • device_class_id – The id of the device class.

  • icon – The id or exact name of the icon to assign, or None to unassign the icon.

  • user – The user making the request.

Returns:

The icons of the device class after the change, see build_icon_result.

Raises:
lce_service.device_class_api.update_device_classes(dbc: silo_cursor, device_classes: List[DeviceClass], user: User) → List[Dict[str, Any]]

Create or update device classes.

Every device class is validated before any is written, with the categories, tiers and PowerPacks they reference looked up once for all of them. Each change is recorded in the audit log, and the revision of each PowerPack whose device classes change is incremented.

Parameters:

  • dbc – A silo_cursor instance, within the transaction of the request.

  • device_classes – The device class models, see get_device_classes_from_payload.

  • user – The user making the request.

Returns:

The identifier (id, guid, name and new) of each device class, in payload order.

Raises:
lce_service.device_class_api.validate_icon_payload(payload: Any) → str | None

Get the icon a request body assigns to a device class.

Parameters:

payload – The decoded JSON body of the request.

Returns:

The id or name of the icon to assign, or None to unassign the icon.

Raises:

InvalidIconRequestError – Raised when the body is not an object with an icon that is a non-empty string or null.

Submodules