tado package

Submodules

tado.base module

exception tado.base.APIRequestUnsuccessful

Bases: Exception

Exception raised when an API returns a non-success HTTP code

class tado.base.TadoManager(username: Optional[str] = None, password: Optional[str] = None, client_secret: Optional[str] = None, client_id: str = 'tado-web-app', load_config: bool = True)

Bases: object

Base class used to orchestrate interaction with the Tado API.

Authentication with the Tado API uses credentials in the following order:

1. Via arguments supplied to this class during instantiation

   • username, password, client_id, client_secret

2. Via environment variables configured by the user

   • TADO_USERNAME, TADO_PASSWORD, CLIENT_ID, CLIENT_SECRET

Args:

username (str, optional):

Tado account username, defaults to None

password (str, optional):

Tado account password, defaults to None

client_secret (str, optional):

Tado OAuth client secret, defaults to None

client_id (str, optional):

Tado OAuth client identifier, defaults to “tad-web-app”

load_config (bool, optional):

Automatically authenticate and load initial config, defaults to True

_call_tado_api(method: str, url: str, data: dict = {}) → str

Convenience wrapper method to call API endpoints with automatic retry.

Args:

method (str):

HTTP method (e.g. GET, POST, PUT)

url (str):

URL as constructed and requested by the method caller

data (dict, optional):

Request body, defaults to {}

Returns:

str: Stringified JSON response from the called API

Raises:

TokenExpired: Raised when an API request uses an expired token

_load_config() → None

Bootstrap configuration method.

This runs the minimum set of calls to render the package functional (i.e. authentication with the Tado API, and retrieval of basic configuration information).

_prepare_headers() → dict

Prepares the set of web request headers for each API call.

If the access_token has already been retrieved, it will be included in the headers as a bearer authentication token.

Returns:

dict: Dict of headers

_show_banner() → None

Output ASCII art banner

build_authentication_params() → str

Prepares the set of query parameters required to retrieve an access token from the Tado API.

• Client ID - e.g. tado-web-app

• Client Secret - as retrieved from https://app.tado.com/env.js

• Grant Type - e.g. password

• Scope - e.g. home.user

• Tado username - sourced from class instantiation argument or environment

• Tado password - sourced from class instantiation argument or environment

Returns:

str: URL encoded string of query parameters

static celsius_to_fahrenheit(input_temperature: float) → float

Converts a given temperature from celsius to fahrenheit.

Args:

input_temperature (float):

Temperature in celsius

Returns:

float: Temperature in fahrenheit

static fahrenheit_to_celsius(input_temperature: float) → float

Converts a given temperature from fahrenheit to celsius.

Args:

input_temperature (float):

Temperature in fahrenheit

Returns:

float: Temperature in celsius

get_access_token() → None

Generates and uses a new authorization token for all subsequent requests.

get_home_id() → None

Retrieves the Tado home identifier.

get_leader_devices() → None

Retrieves the set of zone_name:device_serial_number for the leader device in each zone (i.e. the device designated to provide the temperature reading for its zone).

get_zones() → None

Retrieves the list of zones and full configuration for each.

exception tado.base.TokenExpired

Bases: Exception

Exception raised when an API request is made with an expired token

tado.enums module

class tado.enums.AuthenticationProperties(value)

Bases: Enum

Static properties used during authentication with Tado APIs

GRANT_TYPE = 'password'

SCOPE = 'home.user'

class tado.enums.BaseUrls(value)

Bases: Enum

Base URL prefixes for various Tado APIs

TADO_AUTH_API = 'https://auth.tado.com/oauth/token'

TADO_BASE_API = 'https://my.tado.com/api/v2/me'

TADO_DEVICE_API = 'https://my.tado.com/api/v2/devices'

TADO_HOME_API = 'https://my.tado.com/api/v2/homes'

class tado.enums.EnvVarNames(value)

Bases: Enum

Environment variable names used for configuration purposes

CLIENT_ID = 'CLIENT_ID'

CLIENT_SECRET = 'CLIENT_SECRET'

TADO_PASSWORD = 'TADO_PASSWORD'

TADO_USERNAME = 'TADO_USERNAME'

tado.offsets module

exception tado.offsets.NoTargetOffsetsConfigured

Bases: Exception

Exception raised when no target offsets can be found

class tado.offsets.TadoOffsetsManager(offsets_dict: dict = {}, offsets_file: str = 'config.yaml', **kwargs)

Bases: TadoManager

Manage temperature offsets for zones and devices.

Each zone in a Tado home has a designated leader device which is responsible for providing temperature readings for that zone. Depending on the proximity of the device to heat or cold sources (e.g. radiators, windows etc.) it may be necessary to “offset” the readings from that device by a certain temperature, to provide a more representative/accurate reading for that zone. This class can be used to inspect and set these offsets.

Offsets are defined as pairs of: zone_name:temperature_offset_in_celsius

Args:

offsets_dict (dict: dict, optional):

Inline dict of offsets to set, defaults to {}

offsets_file (str, optional):

YAML file with offsets to set, defaults to config.yaml

apply_offset_changes(dry_run=False) → None

Sets the target offset to any zone which has a different value already set.

This function compares the set of user-provided (target) offsets with the existing (current) offsets for each zone. For any zone where the target offset is different, a PUT request is issued to the Tado API to change the offset.

Args:

dry_run (bool, optional, optional):

Doesn’t modify offsets when set to True, defaults to False

get_current_device_offsets() → dict

Retrieves the currently configured temperature offset values from the leader device in each zone.

Returns:

dict: Set of zone_name:current_offset_temperature entries

get_target_device_offsets() → dict

Retrieves the target temperature offset values to be set in each zone, as defined by the user in the input configuration file.

Returns:

dict: Set of zone_name:target_offset_temperature entries

tado.utils module

tado.utils.get_environment_variable(key: str) → str

Retrieves an environment variable by name.

Args:

key (str):

Environment variable name

Returns:

str: Environment variable value

Raises:

KeyError: If the environment variable cannot be found

tado.utils.has_token_expired(response: Response) → bool

Evaluates an API response to determine if an expired token was the cause of an HTTP 401 Unauthorized error.

Args:

response (requests.Response):

Response: https://requests.readthedocs.io/en/latest/api/#requests.Response

Returns:

bool: True if an expired token was used, False if not

tado.utils.load_yaml_file(filename: str) → dict

Loads a given YAML file.

Args:

filename (str):

Full path and filename to load

Returns:

dict: Dictionary representation of the file

tado.utils.mask(value: str, length: int = 4) → str

Truncates a value, typically for display purposes (e.g. hiding a device’s serial number from being displayed in full).

Args:

value (str):

Input string to mask/truncate

length (int, optional):

String length to preserve, defaults to 4

Returns:

str: Truncated string suffixed by an ellipsis