cozify.hub
¶
Module for handling highlevel Cozify Hub operations.
Module Contents¶
Functions¶
|
Get up to date full devices data set as a dict. Optionally can be filtered to only include certain devices. |
|
Get up to date device data set as a dict. |
|
Wait for a device to reach a desired state |
|
Check if device state matches the provided state keys. Keys not provided are ignored. |
|
Check if device is reachable. |
|
Check if device exists. |
|
Check if device matches a AND devices filter. |
|
Toggle power state of any device capable of it such as lamps. Eligibility is determined by the capability ON_OFF. |
|
Replace the entire state of a device with the provided state. Useful for example for returning to a stored state. |
|
Turn on a device that is capable of turning on. Eligibility is determined by the capability ON_OFF. |
|
Turn off a device that is capable of turning off. Eligibility is determined by the capability ON_OFF. |
|
Set temperature of a light. |
|
Set color (hue & saturation) of a light. |
|
Set brightness of a light. |
|
Get full scene data set as a dict. Optionally filters scenes by on/off status. |
|
Get scene data set as a dict. |
|
Toggle on/off state of given scene. |
|
Turn on a scene. |
|
Turn off a scene. |
|
Get remote status of matching hub_id or set a new value for it. Always returns current state at the end. |
|
Get autoremote status of matching hub_id or set a new value for it. Always returns current state at the end. |
|
Get timezone of given hub or default hub if no id is specified. For more optional kwargs see cozify.hub_api.get() |
|
Perform a cheap API call to trigger any potential APIError and return boolean for success/failure. For optional kwargs see cozify.hub_api.get() |
|
Get hub name by it's id. |
|
Get hostname of matching hub_id |
|
Get hub_token of matching hub_id or set a new value for it. |
|
Get hub id by it's name. |
|
Check for existance of hub in local state. |
|
Return id of default Hub. |
|
Get hub state attributes by attr name. Optionally set a default value if attribute not found. |
|
Set hub state attributes by hub_id and attr name |
|
Get a hub_id from various sources, meant so that you can just throw kwargs at it and get a valid id. |
|
Check that common items are present in kwargs and fill them if not. |
|
Return purged state of values so only wanted values can be modified. |
|
Check that the value is in the given range, raise an error if not. |
|
Deprecated, will be removed in v0.3. Get up to date full devices data set as a dict. |
Deprecated, use default(). Return id of default Hub. |
|
|
Deprecated, use hub_id(). Return id of hub by it's name. |
Attributes¶
- cozify.hub.capability¶
- cozify.hub.devices(capabilities=None, and_filter=False, **kwargs)¶
Get up to date full devices data set as a dict. Optionally can be filtered to only include certain devices.
- Parameters
capabilities (cozify.hub.capability) – Single or list of cozify.hub.capability types to filter by, for example: [ cozify.hub.capability.TEMPERATURE, cozify.hub.capability.HUMIDITY ]. Defaults to no filtering.
and_filter (bool) – Multi-filter by AND instead of default OR. Defaults to False.
**hub_name (str) – optional name of hub to query. Will get converted to hubId for use.
**hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.
**remote (bool) – Remote or local query.
**hubId (str) – Deprecated. Compatibility keyword for hub_id, to be removed in v0.3
**hubName (str) – Deprecated. Compatibility keyword for hub_name, to be removed in v0.3
- Returns
full live device state as returned by the API
- Return type
dict
- cozify.hub.device(device_id, **kwargs)¶
Get up to date device data set as a dict.
- Parameters
device_id (str) – ID of the device to retrieve.
**hub_name (str) – optional name of hub to query. Will get converted to hub_id for use.
**hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.
**remote (bool) – Remote or local query.
- Returns
full live device data as returned by the API
- Return type
dict
- cozify.hub.await_state(device_id, state, timeout=10, **kwargs)¶
Wait for a device to reach a desired state
- Parameters
device_id (str) – ID of the device to check.
state (dict) – Full state dictionary to expect. Timestamp fields are ignored.
timeout (int) – Timeout of wait time.
- Returns
True when state matches or False on timeout.
- Return type
bool
- cozify.hub.has_state(device_id, state, **kwargs)¶
Check if device state matches the provided state keys. Keys not provided are ignored.
- Parameters
device_id (str) – ID of the device to check.
state (dict) – State dictionary to expect. Only provide keys you care about.
- Returns
If given state values match.
- Return type
bool
- cozify.hub.device_reachable(device_id, **kwargs)¶
Check if device is reachable.
- Parameters
device_id (str) – ID of the device to check.
- Returns
Reachability as defined by the API.
- Return type
bool
- cozify.hub.device_exists(device_id, devs=None, state=None, **kwargs)¶
Check if device exists.
- Parameters
device_id (str) – ID of the device to check.
devs (dict) – Optional devices dictionary to use. If not defined, will be retrieved live.
state (dict) – Optional state dictionary, will be updated with state of checked device if device is eligible. Previous data in the dict is preserved unless it’s overwritten by new values.
- Returns
True if filter matches.
- Return type
bool
- cozify.hub.device_eligible(device_id, capability_filter, devs=None, state=None, **kwargs)¶
Check if device matches a AND devices filter.
- Parameters
device_id (str) – ID of the device to check.
capability_filter (hub.capability) – Single hub.capability or a list of them to match against.
devs (dict) – Optional devices dictionary to use. If not defined, will be retrieved live.
state (dict) – Optional state dictionary, will be updated with state of checked device if device is eligible. Previous data in the dict is preserved unless it’s overwritten by new values.
- Returns
True if filter matches.
- Return type
bool
- cozify.hub.device_toggle(device_id, **kwargs)¶
Toggle power state of any device capable of it such as lamps. Eligibility is determined by the capability ON_OFF.
- Parameters
device_id (str) – ID of the device to toggle.
**hub_id (str) – optional id of hub to operate on. A specified hub_id takes presedence over a hub_name or default Hub.
**hub_name (str) – optional name of hub to operate on.
**remote (bool) – Remote or local query.
- cozify.hub.device_state_replace(device_id, state, **kwargs)¶
Replace the entire state of a device with the provided state. Useful for example for returning to a stored state.
- Parameters
device_id (str) – ID of the device to toggle.
state (dict) – State dictionary to push out.
**hub_id (str) – optional id of hub to operate on. A specified hub_id takes presedence over a hub_name or default Hub.
**hub_name (str) – optional name of hub to operate on.
**remote (bool) – Remote or local query.
- cozify.hub.device_on(device_id, **kwargs)¶
Turn on a device that is capable of turning on. Eligibility is determined by the capability ON_OFF.
- Parameters
device_id (str) – ID of the device to operate on.
- cozify.hub.device_off(device_id, **kwargs)¶
Turn off a device that is capable of turning off. Eligibility is determined by the capability ON_OFF.
- Parameters
device_id (str) – ID of the device to operate on.
- cozify.hub.light_temperature(device_id, temperature=2700, transition=0, **kwargs)¶
Set temperature of a light.
- Parameters
device_id (str) – ID of the device to operate on.
temperature (float) – Temperature in Kelvins. If outside the operating range of the device the extreme value is used. Defaults to 2700K.
transition (int) – Transition length in milliseconds. Defaults to instant.
- cozify.hub.light_color(device_id, hue, saturation=1.0, transition=0, **kwargs)¶
Set color (hue & saturation) of a light.
- Parameters
device_id (str) – ID of the device to operate on.
hue (float) – Hue in the range of [0, Pi*2]. If outside the range a ValueError is raised.
saturation (float) – Saturation in the range of [0, 1]. If outside the range a ValueError is raised. Defaults to 1.0 (full saturation.)
transition (int) – Transition length in milliseconds. Defaults to instant.
- cozify.hub.light_brightness(device_id, brightness, transition=0, **kwargs)¶
Set brightness of a light.
- Parameters
device_id (str) – ID of the device to operate on.
brightness (float) – Brightness in the range of [0, 1]. If outside the range a ValueError is raised.
transition (int) – Transition length in milliseconds. Defaults to instant.
- cozify.hub.scenes(filters=None, **kwargs)¶
Get full scene data set as a dict. Optionally filters scenes by on/off status.
- Parameters
filters (dict) – Filter scenes by their values by defining key value pairs as a dict. Defaults to all scenes.
**hub_name (str) – optional name of hub to query. Will get converted to hubId for use.
**hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.
**remote (bool) – Remote or local query.
**hubId (str) – Deprecated. Compatibility keyword for hub_id, to be removed in v0.3
**hubName (str) – Deprecated. Compatibility keyword for hub_name, to be removed in v0.3
- Returns
scene data as returned by the API
- Return type
dict
- cozify.hub.scene(scene_id, **kwargs)¶
Get scene data set as a dict.
- Parameters
scene_id (str) – ID of the scene to retrieve.
**hub_name (str) – optional name of hub to query. Will get converted to hub_id for use.
**hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.
**remote (bool) – Remote or local query.
- Returns
scene data as returned by the API
- Return type
dict
- cozify.hub.scene_toggle(scene_id, **kwargs)¶
Toggle on/off state of given scene.
- Parameters
scene_id (str) – ID of the scene to toggle.
**hub_id (str) – optional id of hub to operate on. A specified hub_id takes presedence over a hub_name or default Hub.
**hub_name (str) – optional name of hub to operate on.
**remote (bool) – Remote or local query.
- cozify.hub.scene_on(scene_id, **kwargs)¶
Turn on a scene.
- Parameters
scene_id (str) – ID of the scene to operate on.
- cozify.hub.scene_off(scene_id, **kwargs)¶
Turn off a scene.
- Parameters
scene_id (str) – ID of the scene to operate on.
- cozify.hub.remote(hub_id, new_state=None)¶
Get remote status of matching hub_id or set a new value for it. Always returns current state at the end.
- Parameters
hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.
new_state (bool) – New remoteness state to set for hub. True means remote. Defaults to None when only the current value will be returned.
- Returns
True for a hub considered remote.
- Return type
bool
- cozify.hub.autoremote(hub_id, new_state=None)¶
Get autoremote status of matching hub_id or set a new value for it. Always returns current state at the end.
- Parameters
hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.
new_state (bool) – New autoremoteness state to set for hub. True means remote will be automanaged. Defaults to None when only the current value will be returned.
- Returns
True for a hub with autoremote enabled.
- Return type
bool
- cozify.hub.tz(**kwargs)¶
Get timezone of given hub or default hub if no id is specified. For more optional kwargs see cozify.hub_api.get()
- Parameters
**hub_id (str) – Hub to query, by default the default hub is used.
- Returns
Timezone of the hub, for example: ‘Europe/Helsinki’
- Return type
str
- cozify.hub.ping(autorefresh=True, **kwargs)¶
Perform a cheap API call to trigger any potential APIError and return boolean for success/failure. For optional kwargs see cozify.hub_api.get()
- Parameters
autorefresh (bool) – Wether to perform a autorefresh after an initially failed ping. If successful, will still return True. Defaults to True.
**hub_id (str) – Hub to ping or default if neither id or name set.
**hub_name (str) – Hub to ping by name.
- Returns
True for a valid and working hub authentication state.
- Return type
bool
- cozify.hub.name(hub_id)¶
Get hub name by it’s id.
- Parameters
hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.
- Returns
Hub name or None if the hub wasn’t found.
- Return type
str
- cozify.hub.host(hub_id)¶
Get hostname of matching hub_id
- Parameters
hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.
- Returns
ip address of matching hub. Be aware that this may be empty if the hub is only known remotely and will still give you an ip address even if the hub is currently remote and an ip address was previously locally known.
- Return type
str
- cozify.hub.token(hub_id, new_token=None)¶
Get hub_token of matching hub_id or set a new value for it.
- Parameters
hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.
- Returns
Hub authentication token.
- Return type
str
- cozify.hub.hub_id(hub_name)¶
Get hub id by it’s name.
- Parameters
hub_name (str) – Name of hub to query. The name is given when registering a hub to an account.
- Returns
hub_id on success, raises an attributeerror on failure.
- Return type
str
- cozify.hub.exists(hub_id)¶
Check for existance of hub in local state.
- Parameters
hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.
- cozify.hub.default()¶
Return id of default Hub.
If default hub isn’t known an AttributeError will be raised.
- cozify.hub._getAttr(hub_id, attr, default=None, boolean=False)¶
Get hub state attributes by attr name. Optionally set a default value if attribute not found.
- Parameters
hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.
attr (str) – Name of hub attribute to retrieve
default – Optional default value to set for unset attributes. If no default is provided these raise an AttributeError.
boolean – Retrieve and return value as a boolean instead of string. Defaults to False.
- Returns
Value of attribute or exception on failure.
- Return type
str
- cozify.hub._setAttr(hub_id, attr, value, commit=True)¶
Set hub state attributes by hub_id and attr name
- Parameters
hub_id (str) – Id of hub to store for. The id is a string of hexadecimal sections used internally to represent a hub.
attr (str) – Name of cloud state attribute to overwrite. Attribute will be created if it doesn’t exist.
value (str) – Value to store
commit (bool) – True to commit state after set. Defaults to True.
- cozify.hub._get_id(**kwargs)¶
Get a hub_id from various sources, meant so that you can just throw kwargs at it and get a valid id. If no data is available to determine which hub was meant, will default to the default hub. If even that fails, will raise an AttributeError.
- Parameters
**hub_id (str) – Will be returned as-is if defined.
**hub_name (str) – Name of hub.
hubName (str) – Deprecated. Compatibility keyword for hub_name, to be removed in v0.3
hubId (str) – Deprecated. Compatibility keyword for hub_id, to be removed in v0.3
- cozify.hub._fill_kwargs(kwargs)¶
Check that common items are present in kwargs and fill them if not.
Args: kwargs(dict): kwargs dictionary to fill. Operated on directly.
- cozify.hub._clean_state(state)¶
Return purged state of values so only wanted values can be modified.
Args: state(dict): device state dictionary. Original won’t be modified.
- cozify.hub._in_range(value, low, high, description='undefined')¶
Check that the value is in the given range, raise an error if not. None is always considered a valid value.
- Returns
True if value in range. Otherwise a ValueError is raised.
- Return type
bool
- cozify.hub.getDevices(**kwargs)¶
Deprecated, will be removed in v0.3. Get up to date full devices data set as a dict.
- Parameters
**hub_name (str) – optional name of hub to query. Will get converted to hubId for use.
**hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.
**remote (bool) – Remote or local query.
**hubId (str) – Deprecated. Compatibility keyword for hub_id, to be removed in v0.3
**hubName (str) – Deprecated. Compatibility keyword for hub_name, to be removed in v0.3
- Returns
full live device state as returned by the API
- Return type
dict
- cozify.hub.getDefaultHub()¶
Deprecated, use default(). Return id of default Hub.
- cozify.hub.getHubId(hub_name)¶
Deprecated, use hub_id(). Return id of hub by it’s name.
- Parameters
hub_name (str) – Name of hub to query. The name is given when registering a hub to an account.
str – hub_id on success, raises an attributeerror on failure.
- Returns
Hub id or raises
- Return type
str