python_awair

Awair

Python asyncio client for the Awair REST API.

This module is an object-oriented wrapper around the Awair REST API. It requires an access token (which can be obtained from the developer console) and implements read-only access to the “user” portions of the API.

class python_awair.Awair(session: aiohttp.client.ClientSession, access_token: Optional[str] = None, authenticator: Optional[python_awair.auth.AwairAuth] = None)

Entry class for the Awair API.

Parameters:

• session – An aiohttp session that will be used to query the Awair API.
• access_token – An optional access token, obtained from the Awair developer console, used to authenticate to the Awair API.
• authenticator – An optional instance of an AwairAuth class, which can provide an HTTP Bearer token for authentication. Most users will simply provide an access_token, instead.

client = None

The instantiated AwairClient that will be used to fetch API responses and check for HTTP errors.

Type:AwairClient

user() → python_awair.user.AwairUser

Return the current AwairUser.

The Awair “user” API does not provide a way to query for a specific user, so this method always returns the user that is associated with the authentication that is in-use. This is typically the user that owns the access_token that was provided at class instantiaton, unless you have provided an authenticator class implementing some other stategy (perhaps OAuth).

class python_awair.AwairLocal(session: aiohttp.client.ClientSession, device_addrs: List[str])

Entry class for the local sensors Awair API.

client = None

The instantiated AwairClient that will be used to fetch API responses and check for HTTP errors.

Type:AwairClient

devices() → List[python_awair.devices.AwairLocalDevice]

Return a list of local awair devices.

AwairUser

An Awair user.

class python_awair.user.AwairUser(client: python_awair.client.AwairClient, attributes: Dict[str, Any])

Bases: object

An Awair user.

This class is primarily informational - it describes the user to which the provided authentication belongs (be that an access_token, or perhaps an OAuth token). Available fields include user information, API quotas, and usage. Additionally, the class provides a method to access the list of devices that are “owned” by this user.

Note

While you can instantiate this class by hand (perhaps in a test case), you should typically load a user by calling Awair.user() instead.

Parameters:

• client – An AwairClient that is used if this AwairUser object needs to query the API.
• attributes – A mapping which describes the user. This class expects that the attributes provided are essentially the result of calling the /v1/users/self API endpoint.

client = None

A reference to the configured AwairClient.

This AwairClient will be used to query the API and validate HTTP responses. It’s normally not something one would need to access.

Type:AwairClient

devices() → List[python_awair.devices.AwairDevice]

Return a list of awair devices this user owns.

Note

For organization users, the underlying API endpoint that this method uses should show you devices that you have access to view. However, the organization API is not directly supported at this time.

dob = None

The user’s date of birth, if known.

Type:Optional[date]

email = None

The email addres on file for the user.

Type:Optional[str]

first_name = None

The first name of the user.

Type:Optional[str]

last_name = None

The last name of the user.

Type:Optional[str]

permissions = None

A mapping describing API quotas.

The keys represent the type of API call being described, and if the API call has been used in this usage window, then it will be represented in this user’s usages attribute.

The values represent the maximum number of times that the API call may be used in this usage window. Usage windwos reset at midnight.

Todo

Document the timezone of the usage window reset.

Type:Dict[str, int]

sex = None

The ‘sex’ of the user.

Typical values seem to be ‘MALE’, ‘FEMALE’, or ‘UNKNOWN’.

Type:Optional[str]

tier = None

The account “tier”.

This broadly maps to a set of permissions and API quotas, but they are not currently well-defined.

Type:Optional[str]

usages = None

A mapping describing API usage.

The keys represent the type of API call being described, and should be reflected in the user’s permissions attribute.

The values represent the number of times that the API call has been used in this usage window. Usage windows reset at midnight.

Todo

Document the timezone of the usage window reset.

Type:Dict[str, int]

user_id = None

The user ID uniquely references an Awair user account. It is returned as a string, because API docs indicate it is a string.

Type:str

AwairDevice

Class to describe an Awair device.

class python_awair.devices.AwairBaseDevice(client: python_awair.client.AwairClient, attributes: Dict[str, Any])

Bases: abc.ABC

An Awair device.

This class serves two purposes - it provides metadata about a given Awair device, but it also provides methods that retrieve sensor measurements from that device. Available information includes things like the model, name, and location of a device; and the query interface allows the user to query for sensor data in several different samplings, over various timeframes.

Note

While you can instantiate this class by hand (perhaps in a test case), you should typically load user devices by calling AwairUser.devices().

Parameters:

• client – An AwairClient that is used if this AwairDevice object needs to query the API.
• attributes – A mapping which describes the device. This class expects that the attributes provided are essentially the result of calling the /v1/users/self/devices API endpoint.

air_data_fifteen_minute(**kwargs) → List[python_awair.air_data.AirData]

Return fifteen-minute summary air data readings for this device.

Each data point returned represents a fifteen-minute average of sensor readings. Up to a maximum of 672 data points will be returned - which represents 7 days of data.

Parameters:kwargs –

A mapping of query parameters, which influence the data returned. None are required:

Parameter	Value
fahrenheit	False (default): temperature data is returned in celsius. True: temperature data is returned in fahrenheit.
desc	True (default): datapoints are ordered descending from the to parameter. False: datapoints are ordered ascending from the to parameter.
limit	int: represents the maximum number of datapoints to return. The default and maximum for this parameter is 672.
from	datetime: lower bound for the earliest datapoint to return. May not be chronologically after the to parameter, and the difference between the to and from parameters may not exceed 7 days. Defaults to 7 days before the current date/time.
to	datetime: upper bound for the most recent datapoint to return. May not be chronologically before the from parameter, and the difference between the to and from parameters may not exceed 7 days. Defaults to the current date/time.

air_data_five_minute(**kwargs) → List[python_awair.air_data.AirData]

Return five-minute summary air data readings for this device.

Each data point returned represents a five-minute average of sensor readings. Up to a maximum of 288 data points will be returned - which represents 24 hours of data.

Parameters:kwargs –

A mapping of query parameters, which influence the data returned. None are required:

Parameter	Value
fahrenheit	False (default): temperature data is returned in celsius. True: temperature data is returned in fahrenheit.
desc	True (default): datapoints are ordered descending from the to parameter. False: datapoints are ordered ascending from the to parameter.
limit	int: represents the maximum number of datapoints to return. The default and maximum for this parameter is 288.
from	datetime: lower bound for the earliest datapoint to return. May not be chronologically after the to parameter, and the difference between the to and from parameters may not exceed 24 hours. Defaults to 24 hours before the current date/time.
to	datetime: upper bound for the most recent datapoint to return. May not be chronologically before the from parameter, and the difference between the to and from parameters may not exceed 24 hours. Defaults to the current date/time.

air_data_latest(fahrenheit: bool = False) → Optional[python_awair.air_data.AirData]

Get the latest air data for this device.

Returns one AirData class describing the most up-to-date measurements for this device’s sensors. If the device has been offline for more than 10 minutes, None will be returned.

Parameters:fahrenheit – Return temperatures in fahrenheit (the default is to return temperatures in celsius). The conversion is done in the Awair API itself, not in this library.

air_data_raw(**kwargs) → List[python_awair.air_data.AirData]

Return the raw, per-second air data readings for this device.

Each data point returned represents the sensor readings at a given second. Up to a maximum of 360 data points will be returned - which represents 1 hour of data.

Parameters:kwargs –

A mapping of query parameters, which influence the data returned. None are required:

Parameter	Value
fahrenheit	False (default): temperature data is returned in celsius. True: temperature data is returned in fahrenheit.
desc	True (default): datapoints are ordered descending from the to parameter. False: datapoints are ordered ascending from the to parameter.
limit	int: represents the maximum number of datapoints to return. The default and maximum for this parameter is 360.
from	datetime: lower bound for the earliest datapoint to return. May not be chronologically after the to parameter, and the difference between the to and from parameters may not exceed 1 hour. Defaults to 1 hour before the current date/time.
to	datetime: upper bound for the most recent datapoint to return. May not be chronologically before the from parameter, and the difference between the to and from parameters may not exceed 1 hour. Defaults to the current date/time.

client = None

A reference to the configured AwairClient.

This is the class that actually queries the API. It’s here if you need it, but you probably don’t need to use it.

Type:AwairClient

device_id = None

The ID that identifies the Awair device.

Type:int

device_type = None

The API name for the model of this Awair device.

This differs from the human-friendly name, which is given by the model attribute.

Device type	Model
awair	Awair (1st Edition)
awair-element	Awair Element
awair-glow	Awair Glow
awair-glow-c	Awair Glow C
awair-mint	Awair Baby
awair-omni	Awair Omni
awair-r2	Awair (2nd Edition)

Type:str

latitude = None

The latitude of the device’s location, if known.

Type:float

location_name = None

Description of the device’s location.

Type:float

longitude = None

The longitude of the device’s location, if known.

Type:float

mac_address = None

The network MAC address.

Type:Optional[str]

model

Return the human-friendly model, if known.

Device type	Model
awair	Awair (1st Edition)
awair-element	Awair Element
awair-glow	Awair Glow
awair-glow-c	Awair Glow C
awair-mint	Awair Baby
awair-omni	Awair Omni
awair-r2	Awair (2nd Edition)

name = None

The user-assigned name for this device.

Type:Optional[str]

preference = None

The device “preference”.

This represents an instruction to the Awair application, which represents the area of concern for this device. Put differently, it represents why the user is using this device to monitor air quality - for example, concern about allergies.

Example: “GENERAL”

Type:Optional[str]

room_type = None

The type of room this device is in.

For example, a “LIVING_ROOM” or an “OFFICE”.

Type:Optional[str]

space_type = None

The type of space this device is in.

For example, this might be an “OFFICE” or a “HOME”.

Type:Optional[str]

timezone = None

The timezone of the device.

Type:Optional[str]

uuid = None

Another ID that identifies the Awair device.

This ID typically takes the form of model_id. For example, given a first-gen Awair device with ID 123, The uuid would be “awair_123”.

Type:str

class python_awair.devices.AwairDevice(client: python_awair.client.AwairClient, attributes: Dict[str, Any])

Bases: python_awair.devices.AwairBaseDevice

A cloud-based Awair device.

class python_awair.devices.AwairLocalDevice(client: python_awair.client.AwairClient, device_addr: str, attributes: Dict[str, Any])

Bases: python_awair.devices.AwairBaseDevice

A local Awair device.

device_addr = None

The DNS or IP address of the device.

fw_version = None

The firmware version currently running on the device.

AirData

Wrapper class for awair airdata responses.

class python_awair.air_data.AirData(attributes: Dict[str, Any])

Bases: object

Wrapper class for awair airdata responses.

Sensors

Sensors dict with attribute-like access.

class python_awair.sensors.Sensors(attrs: Dict[str, Any])

Bases: python_awair.attrdict.AttrDict

Sensors of an AwairDevice.

A Sensors object represents a set of sensors and corresponding values for a given Awair device, at a given point in time. The object itself essentially inherits from dict, and thus one can access sensor values by their string keys, and it is iterable - just like a dict.

However, the class also supports getting, setting, and deleting sensor values via dot-notation; like an attribute or property.

For example, given a foo Sensors object with a “bar” sensor, you could access that value either by calling foo[“bar”] or foo.bar.

The sensor names from the Awair API are not entirely user-friendly, so we’ve aliased known sensors to more descriptive values:

API name	python_awair name
temp	temperature
humid	humidity
co2	carbon_dioxide
voc	volatile_organic_compounds
pm25	particulate_matter_2_5
lux	illuminance
spl_a	sound_pressure_level

A more thorough description of available sensors and their units is available on Awair’s API documentation.

Any new sensors added by an Awair device before this library is updated will be accessible via their API name, rather than a friendly name.

Note

The 1st generation Awair device contains an “aggregate dust” sensor, which measures a range of particle sizes. It cannot distinguish between pm2.5 and pm10 particles.

Indices

Indices dict with attribute access.

class python_awair.indices.Indices(attrs: Dict[str, Any])

Bases: python_awair.attrdict.AttrDict

Indices of an AwairDevice.

An Indices object represents a set of “index” values for a set of sensors of a given AwairDevice. Essentially, the “index” is a bit like a quality score - and Awair has devised a set of quality levels for a variety of their sensors. The “index” is given as a float between -4 and 4, but the absolute value is what really matters - just ignore the sign. As a value approaches 4.0, it is considered “worse”. As it approaches 0, it is considered “better”.

A mapping of index ranges and values per-sensor can be found at Awair’s API documentation - that list is authoritative.

The Indices object is a subclass of AttrDict, and thus its values are accessible via string keys - like foo[“bar”] - or via dot-notation: foo.bar.

The index names from the Awair API are not entirely user-friendly, so we’ve aliased known indices to more descriptive values:

API name	python_awair name
temp	temperature
humid	humidity
co2	carbon_dioxide
voc	volatile_organic_compounds
pm25	particulate_matter_2_5

Any new indices added by an Awair device before this library is updated will be accessible via their API name, rather than a friendly name.

Note

The 1st generation Awair device will have a “dust” index, since it has an aggregate pm2.5/pm10 dust sensor (and cannot distinguish between those two sizes).

Note

Do not assume that every sensor present on a device will also have a corresponding “index”; this is not the case.

Auth

Authentication constructs for the Awair API.

class python_awair.auth.AwairAuth

Bases: abc.ABC

Abstract authentication that provides a Bearer token.

get_bearer_token() → str

Return a valid bearer token for authentication.

class python_awair.auth.AccessTokenAuth(access_token: str)

Bases: python_awair.auth.AwairAuth

Authentication that uses an Awair access token.

get_bearer_token() → str

Return the access token for authentication.

AwairClient

Wrapper class to query the Awair API.

class python_awair.client.AwairClient(authenticator: python_awair.auth.AwairAuth, session: aiohttp.client.ClientSession)

Bases: object

Python asyncio client for the Awair GraphQL API.

query(url: str) → Any

Query the Awair api, and handle errors.

Exceptions

Various exceptions for the Awair API.

exception python_awair.exceptions.AwairError(extra_message: Optional[str] = None)

Bases: Exception

Base awair exception class.

message = 'Error querying the Awair API.'

exception python_awair.exceptions.AuthError(extra_message: Optional[str] = None)

Bases: python_awair.exceptions.AwairError

Some kind of authorization or authentication failure.

message = 'The supplied access token is invalid or does not have access to the requested data'

exception python_awair.exceptions.QueryError(extra_message: Optional[str] = None)

Bases: python_awair.exceptions.AwairError

The query was somehow malformed.

message = 'The supplied parameters were invalid.'

exception python_awair.exceptions.NotFoundError(extra_message: Optional[str] = None)

Bases: python_awair.exceptions.AwairError

The requested endpoint is gone.

message = 'The Awair API returned an unexpected HTTP 404.'

exception python_awair.exceptions.RatelimitError(extra_message: Optional[str] = None)

Bases: python_awair.exceptions.AwairError

The API quota was exceeded.

message = 'The ratelimit for the Awair API has been exceeded. Please try again later'

AttrDict

Dict with attribute-like access.

class python_awair.attrdict.AttrDict(attrs: Dict[str, Any])

Bases: dict, typing.Generic

Dict with attribute-like access.

For example, given an AttrDict foo, we could access its values via foo[“bar”] or foo.bar.

This is the parent class for the Sensors and Indices classes, and as such it renames some properties to friendlier names on initialization (but not anytime after).