[python source code]

rest_api_control

Base REST Application Programming Interface (API) control class module.

RESTAPIControl 

RESTAPIControl(config_entry: DeviceConfigEntry, verbose: bool)

Bases: _AbstractDeviceControl, ABC

flowchart LR tm_devices.driver_mixins.device_control.rest_api_control.RESTAPIControl[RESTAPIControl] tm_devices.driver_mixins.device_control._abstract_device_control._AbstractDeviceControl[_AbstractDeviceControl] tm_devices.driver_mixins.device_control._abstract_device_control._AbstractDeviceControl --> tm_devices.driver_mixins.device_control.rest_api_control.RESTAPIControl click tm_devices.driver_mixins.device_control.rest_api_control.RESTAPIControl href "" "tm_devices.driver_mixins.device_control.rest_api_control.RESTAPIControl" click tm_devices.driver_mixins.device_control._abstract_device_control._AbstractDeviceControl href "" "tm_devices.driver_mixins.device_control._abstract_device_control._AbstractDeviceControl"

Base REST Application Programming Interface (API) control class.

Important

Any class that inherits this control mixin must also inherit a descendant of the Device class in order to have access to the attributes required by this class.

Parameters:
  • config_entry (DeviceConfigEntry) –

    A config entry object parsed by the DMConfigParser.

  • verbose (bool) –

    A boolean indicating if verbose output should be printed. If True, communication printouts will be logged with a level of INFO. If False, communication printouts will be logged with a level of DEBUG.

API_VERSIONS class-attribute instance-attribute 

API_VERSIONS: Mapping[int, str] = MappingProxyType({})

A mapping of supported API version numbers with the corresponding API URL.

api_url property 

api_url: str

Return the base API url of the device.

base_url property 

base_url: str

Return the base url of the device.

device_type abstractmethod cached property 

device_type: str

Return a string representing the device type.

ip_address abstractmethod cached property 

ip_address: str

The IP address of the device.

manufacturer abstractmethod cached property 

manufacturer: str

Return the manufacturer of the device.

model abstractmethod cached property 

model: str

Return the full model of the device.

name_and_alias abstractmethod cached property 

name_and_alias: str

A string containing the device name and alias.

serial abstractmethod cached property 

serial: str

Return the serial number of the device.

sw_version abstractmethod cached property 

sw_version: Version

Return the software version of the device.

delete 

delete(
    url: str,
    headers: Mapping[str, str] | None = None,
    auth: tuple[str, str] | None = None,
    timeout: float | None = None,
    return_bytes: bool = False,
    allow_errors: bool = False,
    verify_ssl: bool = True,
    allow_redirects: bool = False,
) -> tuple[bool, dict[str, Any] | bytes, int, RequestException | None]

Perform a DELETE request with the given url and headers.

Parameters:
  • url (str) –

    The url to DELETE.

  • headers (Mapping[str, str] | None, default: None ) –

    The headers to use during the request.

  • auth (tuple[str, str] | None, default: None ) –

    A tuple containing the username and password to use in the request.

  • timeout (float | None, default: None ) –

    How many seconds to wait for the server to send data before giving up.

  • return_bytes (bool, default: False ) –

    A boolean indicating if the response content should be returned instead of the response json.

  • verify_ssl (bool, default: True ) –

    A bool that indicates if the SSL certificate should be verified.

  • allow_redirects (bool, default: False ) –

    A bool that indicates if URL redirects should be allowed.

  • allow_errors (bool, default: False ) –

    A boolean indicating if errors are allowed.
Returns:

get 

get(
    url: str,
    headers: Mapping[str, str] | None = None,
    auth: tuple[str, str] | None = None,
    timeout: float | None = None,
    return_bytes: bool = False,
    allow_errors: bool = False,
    verify_ssl: bool = True,
    allow_redirects: bool = False,
) -> tuple[bool, dict[str, Any] | bytes, int, RequestException | None]

Perform a GET request with the given url and headers.

Parameters:
  • url (str) –

    The url to GET.

  • headers (Mapping[str, str] | None, default: None ) –

    The headers to use during the request.

  • auth (tuple[str, str] | None, default: None ) –

    A tuple containing the username and password to use in the request.

  • timeout (float | None, default: None ) –

    How many seconds to wait for the server to send data before giving up.

  • return_bytes (bool, default: False ) –

    A boolean indicating if the response content should be returned instead of the response json.

  • verify_ssl (bool, default: True ) –

    A bool that indicates if the SSL certificate should be verified.

  • allow_redirects (bool, default: False ) –

    A bool that indicates if URL redirects should be allowed.

  • allow_errors (bool, default: False ) –

    A boolean indicating if errors are allowed.
Returns:

patch 

patch(
    url: str,
    json_body: dict[str, Any] | None = None,
    data_body: str | None = None,
    headers: Mapping[str, str] | None = None,
    auth: tuple[str, str] | None = None,
    timeout: float | None = None,
    return_bytes: bool = False,
    allow_errors: bool = False,
    verify_ssl: bool = True,
    allow_redirects: bool = False,
) -> tuple[bool, dict[str, Any] | bytes, int, RequestException | None]

Perform a PATCH request with the given url and headers.

Parameters:
  • url (str) –

    The url to PATCH.

  • json_body (dict[str, Any] | None, default: None ) –

    Any data to serialize and send to the url. The “Content-Type” header is set to “application/json”.

  • data_body (str | None, default: None ) –

    Any raw data to send to the url. “Content-Type” must be set manually. The data is not serialized. WARNING: IF DATA IS PASSED USING THIS ARGUMENT THEN ANY DATA PASSED USING THE json_body ARGUMENT WILL BE IGNORED.

  • headers (Mapping[str, str] | None, default: None ) –

    The headers to use during the request.

  • auth (tuple[str, str] | None, default: None ) –

    A tuple containing the username and password to use in the request.

  • timeout (float | None, default: None ) –

    How many seconds to wait for the server to send data before giving up.

  • return_bytes (bool, default: False ) –

    A boolean indicating if the response content should be returned instead of the response json.

  • verify_ssl (bool, default: True ) –

    A bool that indicates if the SSL certificate should be verified.

  • allow_redirects (bool, default: False ) –

    A bool that indicates if URL redirects should be allowed.

  • allow_errors (bool, default: False ) –

    A boolean indicating if errors are allowed.
Returns:

post 

post(
    url: str,
    json_body: dict[str, Any] | None = None,
    data_body: str | None = None,
    headers: Mapping[str, str] | None = None,
    auth: tuple[str, str] | None = None,
    timeout: float | None = None,
    return_bytes: bool = False,
    allow_errors: bool = False,
    verify_ssl: bool = True,
    allow_redirects: bool = False,
) -> tuple[bool, dict[str, Any] | bytes, int, RequestException | None]

Perform a POST request with the given url and headers.

Parameters:
  • url (str) –

    The url to POST.

  • json_body (dict[str, Any] | None, default: None ) –

    Any data to serialize and send to the url. The “Content-Type” header is set to “application/json”.

  • data_body (str | None, default: None ) –

    Any raw data to send to the url. “Content-Type” must be set manually. The data is not serialized. WARNING: IF DATA IS PASSED USING THIS ARGUMENT THEN ANY DATA PASSED USING THE json_body ARGUMENT WILL BE IGNORED.

  • headers (Mapping[str, str] | None, default: None ) –

    The headers to use during the request.

  • auth (tuple[str, str] | None, default: None ) –

    A tuple containing the username and password to use in the request.

  • timeout (float | None, default: None ) –

    How many seconds to wait for the server to send data before giving up.

  • return_bytes (bool, default: False ) –

    A boolean indicating if the response content should be returned instead of the response json.

  • verify_ssl (bool, default: True ) –

    A bool that indicates if the SSL certificate should be verified.

  • allow_redirects (bool, default: False ) –

    A bool that indicates if URL redirects should be allowed.

  • allow_errors (bool, default: False ) –

    A boolean indicating if errors are allowed.
Returns:

put 

put(
    url: str,
    json_body: dict[str, Any] | None = None,
    data_body: str | None = None,
    headers: Mapping[str, str] | None = None,
    auth: tuple[str, str] | None = None,
    timeout: float | None = None,
    return_bytes: bool = False,
    allow_errors: bool = False,
    verify_ssl: bool = True,
    allow_redirects: bool = False,
) -> tuple[bool, dict[str, Any] | bytes, int, RequestException | None]

Perform a PUT request with the given url and headers.

Parameters:
  • url (str) –

    The url to PUT.

  • json_body (dict[str, Any] | None, default: None ) –

    Any data to serialize and send to the url. The “Content-Type” header is set to “application/json”.

  • data_body (str | None, default: None ) –

    Any raw data to send to the url. “Content-Type” must be set manually. The data is not serialized. WARNING: IF DATA IS PASSED USING THIS ARGUMENT THEN ANY DATA PASSED USING THE json_body ARGUMENT WILL BE IGNORED.

  • headers (Mapping[str, str] | None, default: None ) –

    The headers to use during the request.

  • auth (tuple[str, str] | None, default: None ) –

    A tuple containing the username and password to use in the request.

  • timeout (float | None, default: None ) –

    How many seconds to wait for the server to send data before giving up.

  • return_bytes (bool, default: False ) –

    A boolean indicating if the response content should be returned instead of the response json.

  • verify_ssl (bool, default: True ) –

    A bool that indicates if the SSL certificate should be verified.

  • allow_redirects (bool, default: False ) –

    A bool that indicates if URL redirects should be allowed.

  • allow_errors (bool, default: False ) –

    A boolean indicating if errors are allowed.
Returns:

set_api_version 

set_api_version(api_version: int) -> None

Set the API version used by the device.

Parameters:
  • api_version (int) –

    The API version to use for this device

wait_for_api_connection 

wait_for_api_connection(
    wait_time: float, sleep_seconds: int = 5, accept_immediate_connection: bool = False
) -> bool

Wait for an API call to go through to the device.

Using wait_for_network_connection does not ensure that the API network is also up.

Parameters:
  • wait_time (float) –

    The number of seconds to wait for the API connection.

  • sleep_seconds (int, default: 5 ) –

    The number of seconds to sleep in between connection attempts.

  • accept_immediate_connection (bool, default: False ) –

    A boolean indicating if a connection on the first attempt is a valid connection.
Returns:
  • bool –

    A boolean indicating if an API connection was made within the given time limit.
Raises:
  • AssertionError –

    Indicating that the device erroneously connected on the first try.