Introduce device type

.github/workflows/ci.yml

@@ -8,7 +8,7 @@ jobs:
     name: Lint Python API SDK
     defaults:
         run:
-          working-directory: api/python
+          working-directory: api/python/airthings-sdk
     steps:
       - name: Checkout
         uses: actions/checkout@v6

api/python/openapi.yaml → api/openapi.yaml

@@ -9,13 +9,18 @@ externalDocs:
   description: Find out more about consumerAPI
   url: https://consumer-api-doc.airthings.com/
 servers:
-  - url: https://consumer-api.airthings.com/v1
+  - url: https://consumer-api.airthings.com
     description: Airthings for Consumer API (prod)
 
 paths:
   /v1/accounts/{accountId}/sensors:
     get:
       summary: Get sensors for a set of devices
+      description: |
+        Get sensors for a set of devices. The response will contain the latest sensor values for the devices.
+        The sensor values are updated depending on the device types sampling rate.
+        It is recommended to poll the API at a regular interval to get the latest sensor values.
+        The response will be paginated with a maximum of 50 records per page.
       operationId: getMultipleSensors
       parameters:
         - $ref: '#/components/parameters/deviceSerialNumbers'
@@ -78,6 +83,7 @@ paths:
   /v1/accounts/{accountId}/devices:
     get:
       summary: Get all devices connected to a user
+      description: List all devices (and their sensor abilities) connected to a user’s account. The data returned by this endpoint changes when a device is registered, unregistered or renamed.
       operationId: getDevices
       parameters:
         - $ref: '#/components/parameters/accountId'
@@ -101,6 +107,7 @@ paths:
   /v1/accounts:
     get:
       summary: List all accounts the current user is member of
+      description: Lists all accounts the current user is member of. The data returned by this endpoint changes when a user is added or removed from business accounts. It is safe to assume that the accountId remains constant for Consumer users. The accountId returned by this endpoint is used to fetch the devices and sensors from the other endpoints.
       operationId: getAccountsIds
       tags:
         - Accounts

api/python/airthings-sdk/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# JetBrains
+.idea/
+
+/coverage.xml
+/.coverage

api/python/airthings-sdk/README.md

@@ -0,0 +1,124 @@
+# airthings-sdk
+A client library for accessing Airthings for Consumer API
+
+## Usage
+First, create a client:
+
+```python
+from airthings_api_client import Client
+
+client = Client(base_url="https://api.example.com")
+```
+
+If the endpoints you're going to hit require authentication, use `AuthenticatedClient` instead:
+
+```python
+from airthings_api_client import AuthenticatedClient
+
+client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
+```
+
+Now call your endpoint and use your models:
+
+```python
+from airthings_api_client.models import MyDataModel
+from airthings_api_client.api.my_tag import get_my_data_model
+from airthings_api_client.types import Response
+
+with client as client:
+    my_data: MyDataModel = get_my_data_model.sync(client=client)
+    # or if you need more info (e.g. status_code)
+    response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
+```
+
+Or do the same thing with an async version:
+
+```python
+from airthings_api_client.models import MyDataModel
+from airthings_api_client.api.my_tag import get_my_data_model
+from airthings_api_client.types import Response
+
+async with client as client:
+    my_data: MyDataModel = await get_my_data_model.asyncio(client=client)
+    response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
+```
+
+By default, when you're calling an HTTPS API it will attempt to verify that SSL is working correctly. Using certificate verification is highly recommended most of the time, but sometimes you may need to authenticate to a server (especially an internal server) using a custom certificate bundle.
+
+```python
+client = AuthenticatedClient(
+    base_url="https://internal_api.example.com", 
+    token="SuperSecretToken",
+    verify_ssl="/path/to/certificate_bundle.pem",
+)
+```
+
+You can also disable certificate validation altogether, but beware that **this is a security risk**.
+
+```python
+client = AuthenticatedClient(
+    base_url="https://internal_api.example.com", 
+    token="SuperSecretToken", 
+    verify_ssl=False
+)
+```
+
+Things to know:
+1. Every path/method combo becomes a Python module with four functions:
+    1. `sync`: Blocking request that returns parsed data (if successful) or `None`
+    1. `sync_detailed`: Blocking request that always returns a `Request`, optionally with `parsed` set if the request was successful.
+    1. `asyncio`: Like `sync` but async instead of blocking
+    1. `asyncio_detailed`: Like `sync_detailed` but async instead of blocking
+
+1. All path/query params, and bodies become method arguments.
+1. If your endpoint had any tags on it, the first tag will be used as a module name for the function (my_tag above)
+1. Any endpoint which did not have a tag will be in `airthings_api_client.api.default`
+
+## Advanced customizations
+
+There are more settings on the generated `Client` class which let you control more runtime behavior, check out the docstring on that class for more info. You can also customize the underlying `httpx.Client` or `httpx.AsyncClient` (depending on your use-case):
+
+```python
+from airthings_api_client import Client
+
+def log_request(request):
+    print(f"Request event hook: {request.method} {request.url} - Waiting for response")
+
+def log_response(response):
+    request = response.request
+    print(f"Response event hook: {request.method} {request.url} - Status {response.status_code}")
+
+client = Client(
+    base_url="https://api.example.com",
+    httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
+)
+
+# Or get the underlying httpx client to modify directly with client.get_httpx_client() or client.get_async_httpx_client()
+```
+
+You can even set the httpx client directly, but beware that this will override any existing settings (e.g., base_url):
+
+```python
+import httpx
+from airthings_api_client import Client
+
+client = Client(
+    base_url="https://api.example.com",
+)
+# Note that base_url needs to be re-set, as would any shared cookies, headers, etc.
+client.set_httpx_client(httpx.Client(base_url="https://api.example.com", proxies="http://localhost:8030"))
+```
+
+## Building / publishing this package
+This project uses [Poetry](https://python-poetry.org/) to manage dependencies  and packaging.  Here are the basics:
+1. Update the metadata in pyproject.toml (e.g. authors, version)
+1. If you're using a private repository, configure it with Poetry
+    1. `poetry config repositories.<your-repository-name> <url-to-your-repository>`
+    1. `poetry config http-basic.<your-repository-name> <username> <password>`
+1. Publish the client with `poetry publish --build -r <your-repository-name>` or, if for public PyPI, just `poetry publish --build`
+
+If you want to install this client into another project without publishing it (e.g. for development) then:
+1. If that project **is using Poetry**, you can simply do `poetry add <path-to-this-client>` from that project
+1. If that project is not using Poetry:
+    1. Build a wheel with `poetry build -f wheel`
+    1. Install that wheel from the other project `pip install <path-to-wheel>`

api/python/airthings_api_client/__init__.py → api/python/airthings-sdk/airthings_api_client/__init__.py

@@ -1,4 +1,5 @@
-""" A client library for accessing Airthings for Consumer API """
+"""A client library for accessing Airthings for Consumer API"""
+
 from .client import AuthenticatedClient, Client
 
 __all__ = (

api/python/airthings-sdk/airthings_api_client/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

api/python/airthings-sdk/airthings_api_client/api/accounts/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

api/python/airthings_api_client/api/accounts/get_accounts_ids.py → api/python/airthings-sdk/airthings_api_client/api/accounts/get_accounts_ids.py

@@ -1,5 +1,5 @@
 from http import HTTPStatus
-from typing import Any, Dict, Optional, Union
+from typing import Any, Optional, Union
 
 import httpx
 
@@ -9,8 +9,8 @@
 from ...types import Response
 
 
-def _get_kwargs() -> Dict[str, Any]:
-    _kwargs: Dict[str, Any] = {
+def _get_kwargs() -> dict[str, Any]:
+    _kwargs: dict[str, Any] = {
         "method": "get",
         "url": "/v1/accounts",
     }
@@ -21,7 +21,7 @@ def _get_kwargs() -> Dict[str, Any]:
 def _parse_response(
     *, client: Union[AuthenticatedClient, Client], response: httpx.Response
 ) -> Optional[AccountsResponse]:
-    if response.status_code == HTTPStatus.OK:
+    if response.status_code == 200:
         response_200 = AccountsResponse.from_dict(response.json())
 
         return response_200
@@ -48,6 +48,11 @@ def sync_detailed(
 ) -> Response[AccountsResponse]:
     """List all accounts the current user is member of
 
+     Lists all accounts the current user is member of. The data returned by this endpoint changes when a
+    user is added or removed from business accounts. It is safe to assume that the accountId remains
+    constant for Consumer users. The accountId returned by this endpoint is used to fetch the devices
+    and sensors from the other endpoints.
+
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException: If the request takes longer than Client.timeout.
@@ -71,6 +76,11 @@ def sync(
 ) -> Optional[AccountsResponse]:
     """List all accounts the current user is member of
 
+     Lists all accounts the current user is member of. The data returned by this endpoint changes when a
+    user is added or removed from business accounts. It is safe to assume that the accountId remains
+    constant for Consumer users. The accountId returned by this endpoint is used to fetch the devices
+    and sensors from the other endpoints.
+
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException: If the request takes longer than Client.timeout.
@@ -90,6 +100,11 @@ async def asyncio_detailed(
 ) -> Response[AccountsResponse]:
     """List all accounts the current user is member of
 
+     Lists all accounts the current user is member of. The data returned by this endpoint changes when a
+    user is added or removed from business accounts. It is safe to assume that the accountId remains
+    constant for Consumer users. The accountId returned by this endpoint is used to fetch the devices
+    and sensors from the other endpoints.
+
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException: If the request takes longer than Client.timeout.
@@ -111,6 +126,11 @@ async def asyncio(
 ) -> Optional[AccountsResponse]:
     """List all accounts the current user is member of
 
+     Lists all accounts the current user is member of. The data returned by this endpoint changes when a
+    user is added or removed from business accounts. It is safe to assume that the accountId remains
+    constant for Consumer users. The accountId returned by this endpoint is used to fetch the devices
+    and sensors from the other endpoints.
+
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException: If the request takes longer than Client.timeout.

api/python/airthings-sdk/airthings_api_client/api/device/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

api/python/airthings_api_client/api/device/get_devices.py → api/python/airthings-sdk/airthings_api_client/api/device/get_devices.py

@@ -1,5 +1,5 @@
 from http import HTTPStatus
-from typing import Any, Dict, Optional, Union
+from typing import Any, Optional, Union
 
 import httpx
 
@@ -11,8 +11,8 @@
 
 def _get_kwargs(
     account_id: str,
-) -> Dict[str, Any]:
-    _kwargs: Dict[str, Any] = {
+) -> dict[str, Any]:
+    _kwargs: dict[str, Any] = {
         "method": "get",
         "url": f"/v1/accounts/{account_id}/devices",
     }
@@ -23,7 +23,7 @@ def _get_kwargs(
 def _parse_response(
     *, client: Union[AuthenticatedClient, Client], response: httpx.Response
 ) -> Optional[DevicesResponse]:
-    if response.status_code == HTTPStatus.OK:
+    if response.status_code == 200:
         response_200 = DevicesResponse.from_dict(response.json())
 
         return response_200
@@ -51,6 +51,9 @@ def sync_detailed(
 ) -> Response[DevicesResponse]:
     """Get all devices connected to a user
 
+     List all devices (and their sensor abilities) connected to a user’s account. The data returned by
+    this endpoint changes when a device is registered, unregistered or renamed.
+
     Args:
         account_id (str):
 
@@ -80,6 +83,9 @@ def sync(
 ) -> Optional[DevicesResponse]:
     """Get all devices connected to a user
 
+     List all devices (and their sensor abilities) connected to a user’s account. The data returned by
+    this endpoint changes when a device is registered, unregistered or renamed.
+
     Args:
         account_id (str):
 
@@ -104,6 +110,9 @@ async def asyncio_detailed(
 ) -> Response[DevicesResponse]:
     """Get all devices connected to a user
 
+     List all devices (and their sensor abilities) connected to a user’s account. The data returned by
+    this endpoint changes when a device is registered, unregistered or renamed.
+
     Args:
         account_id (str):
 
@@ -131,6 +140,9 @@ async def asyncio(
 ) -> Optional[DevicesResponse]:
     """Get all devices connected to a user
 
+     List all devices (and their sensor abilities) connected to a user’s account. The data returned by
+    this endpoint changes when a device is registered, unregistered or renamed.
+
     Args:
         account_id (str):
 

api/python/airthings-sdk/airthings_api_client/api/health/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

api/python/airthings_api_client/api/health/get_health.py → api/python/airthings-sdk/airthings_api_client/api/health/get_health.py

@@ -1,5 +1,5 @@
 from http import HTTPStatus
-from typing import Any, Dict, Optional, Union
+from typing import Any, Optional, Union
 
 import httpx
 
@@ -8,8 +8,8 @@
 from ...types import Response
 
 
-def _get_kwargs() -> Dict[str, Any]:
-    _kwargs: Dict[str, Any] = {
+def _get_kwargs() -> dict[str, Any]:
+    _kwargs: dict[str, Any] = {
         "method": "get",
         "url": "/v1/health",
     }
@@ -18,7 +18,7 @@ def _get_kwargs() -> Dict[str, Any]:
 
 
 def _parse_response(*, client: Union[AuthenticatedClient, Client], response: httpx.Response) -> Optional[Any]:
-    if response.status_code == HTTPStatus.OK:
+    if response.status_code == 200:
         return None
     if client.raise_on_unexpected_status:
         raise errors.UnexpectedStatus(response.status_code, response.content)

api/python/airthings-sdk/airthings_api_client/api/sensor/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""