High-level Cloud functions

Module for handling Cozify Cloud highlevel operations.

cozify.cloud.token_expiry

timedelta object for duration how often cloud_token will be considered valid for refresh.

Type:datetime.timedelta
cozify.cloud.authenticate(trustCloud=True, trustHub=True, remote=False, autoremote=True, autorefresh=True, expiry=None)[source]

Authenticate with the Cozify Cloud and any Hubs found.

Interactive only when absolutely needed, mostly on the first run. By default authentication is run selectively only for the portions needed. Hub authentication lives in the Cloud module since the authentication is obtained from the cloud.

Authentication is a multistep process:
  • trigger sending OTP to email address
  • perform email login with OTP to acquire cloud token
  • acquire hub information and authenticate with hub with cloud token
  • store hub token for further use
Parameters:
  • trustCloud (bool) – Trust current stored state of cloud auth. Default True.
  • trustHub (bool) – Trust current stored state of hub auth. Default True.
  • remote (bool) – Treat a hub as being outside the LAN, i.e. calls will be routed via the Cozify Cloud remote call system. Defaults to False.
  • autoremote (bool) – Autodetect hub LAN presence and flip to remote mode if needed. Defaults to True.
  • autorefresh (bool) – Autorefresh cloud and hub tokens if they’re no longer valid but can still be rescued. Defaults to True.
  • expiry (datetime.timedelta) – timedelta object for duration how often cloud_token will be auto-refreshed. Defaults to cloud.token_expiry
Returns:

True on authentication success. Failure will result in an exception.
Return type:

bool
cozify.cloud.email(new_email=None)[source]

Get currently used cloud account email or set a new one.

Returns:Cloud user account email address.
Return type:str
cozify.cloud.ping(autorefresh=True, expiry=None)[source]

Test cloud token validity. On success will also trigger a refresh if it’s needed by the current key expiry.

Parameters:
  • refresh (bool) – Wether to perform a autorefresh check after a successful ping. Defaults to True.
  • expiry (datetime.timedelta) – timedelta object for duration how often cloud_token will be auto-refreshed when cloud.ping() is called. Defaults to cloud.token_expiry()
Returns:

validity of stored token.
Return type:

bool
cozify.cloud.refresh(force=False, expiry=None)[source]

Renew current cloud token and store new token in state.

This call will only succeed if the current cloud token is still valid. A new refreshed token is requested from the API only if sufficient time has passed since the previous refresh.

Parameters:
  • force (bool) – Set to True to always perform a refresh regardless of time passed since previous refresh.
  • expiry (datetime.timedelta) – timedelta object for duration of refresh expiry. Defaults to cloud.token_expiry
Returns:

Success of refresh attempt, True also when expiry wasn’t over yet even though no refresh was performed.
Return type:

bool
cozify.cloud.resetState()[source]

Reset stored cloud state.

Any further authentication flow will start from a clean slate. Hub state is left intact.

cozify.cloud.token(new_token=None, commit=True)[source]

Get currently used cloud_token or set a new one.

Parameters:
  • new_token (str) – New cloud_token to store. Use cautiously since an invalid token means interactive recovery.
  • commit (bool) – Wether to commit the new value to persistent storage immediately or not.
Returns:

Cloud remote authentication token.
Return type:

str