vaillant-netatmo-api-ng 0.1.0__tar.gz

vaillant_netatmo_api_ng-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 Mislav Mandarić
+Copyright (c) 2026 LEOSCHUMY (NG fork modifications)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vaillant_netatmo_api_ng-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: vaillant-netatmo-api-ng
+Version: 0.1.0
+Summary: Community fork for managing Vaillant thermostats using Netatmo-backed APIs.
+Author: Mislav Mandaric
+Maintainer: LEOSCHUMY
+Project-URL: Homepage, https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG
+Project-URL: Source, https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG
+Project-URL: Issues, https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG/issues
+Project-URL: Changelog, https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG/blob/master/CHANGELOG.md
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.18.2
+Requires-Dist: tenacity>=8.0.1
+Dynamic: license-file
+
+# vaillant-netatmo-api-ng
+
+[![Tests](https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG/actions/workflows/tests.yml/badge.svg)](https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG/actions/workflows/tests.yml)
+
+## About this fork
+
+**vaillant-netatmo-api-ng** is a community-maintained fork of [Mislav Mandarić's vaillant-netatmo-api](https://github.com/MislavMandaric/vaillant-netatmo-api), a Python library for accessing Vaillant vSMART/eRELAX thermostats through Netatmo-backed APIs.
+
+This fork starts its **own version series at 0.1.0**. Version numbers do **not** track the original project's releases. The initial NG work adds read-only room temperatures from Vaillant's `homestatus` endpoint, without replacing existing thermostat data or control APIs.
+
+> [!IMPORTANT]
+> **Independent, unofficial project — NOT affiliated with, authorized, sponsored, or endorsed by Vaillant or Netatmo.**
+> This community fork is not an official Vaillant or Netatmo product, and neither company provides support for it. Their APIs may change or become unavailable without notice.
+
+This fork is also independent of the original project's maintainer. See [LICENSE](LICENSE) for the MIT license and original copyright notice.
+
+## Features
+
+- Existing authenticated thermostat data access and heating controls from the upstream library.
+- `ThermostatClient.async_get_homes_data()` for homes, rooms and `Room.module_ids`.
+- **NEW:** `ThermostatClient.async_get_home_status(home_id)` for room status (including measured temperature, target temperature and reachability) keyed by room ID.
+- Defensive validation for malformed responses and duplicate or conflicting room records.
+- No fabricated measurement timestamp: the `homestatus` response does not provide a verified temperature acquisition time.
+
+## Installation
+
+Once published on PyPI, the NG package can be installed with:
+
+```bash
+pip install vaillant-netatmo-api-ng==0.1.0
+```
+
+**Publication status:** Version 0.1.0 is prepared in this repository but is **not yet confirmed as published on PyPI**. Until release, use the [source repository](https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG) and a branch/commit-specific installation for development.
+
+The **distribution name** is `vaillant-netatmo-api-ng`, but the Python **import name** intentionally remains `vaillant_netatmo_api` for compatibility:
+
+```python
+from vaillant_netatmo_api.thermostat import ThermostatClient
+```
+
+Do not install `vaillant-netatmo-api` and `vaillant-netatmo-api-ng` in the same environment; they provide the same import package and may overwrite each other's files.
+
+Requires Python 3.8+ and the `httpx` and `tenacity` dependencies.
+
+## API usage
+
+### Reading room temperatures
+
+With an existing authenticated `ThermostatClient` instance:
+
+```python
+homes = await client.async_get_homes_data()
+for home in homes:
+    statuses = await client.async_get_home_status(home.id)
+    for room in home.rooms:
+        room_status = statuses.get(room.id)
+        if room_status is not None:
+            print(room_status.measured_temperature)
+```
+
+Use `homesdata` `rooms[].module_ids` to map room readings to the right thermostat module; do not assume the first room represents every thermostat. If `homestatus` cannot provide a valid room reading, applications should retain their previous measured-temperature fallback. This library does not change polling intervals for consumers.
+
+### Existing authentication and thermostat operations
+
+### Getting the token from the OAuth API
+
+All Netatmo APIs are protected and require a bearer token to authenticate. To get this token, Netatmo offers an OAuth API.
+
+Since Vaillant uses Resource Owner Password Credentials Grant, there is only one method in the `AuthClient` API:
+
+* `async_token`: getting a bearer token and storing it in the token store
+
+```python
+from vaillant_netatmo_api import auth_client
+
+CLIENT_ID = ""
+CLIENT_SECRET = ""
+
+def handle_token_update(token):
+    token_string = token.serialize()
+    write_to_storage(token_string)
+
+async with auth_client(CLIENT_ID, CLIENT_SECRET, handle_token_update) as client:
+    await client.async_token(
+        username,
+        password,
+        user_prefix,
+        app_version,
+    )
+```
+
+### Accessing the Thermostat API
+
+The existing `ThermostatClient` methods include:
+
+* `async_get_thermostats_data`: getting all the devices associated with the user account
+* `async_set_system_mode`: changing system mode for a device and module (ie. summer, winter or frostguard)
+* `async_set_minor_mode`: changing minor mode for a device and module (ie. manual mode, away mode or hot water boost mode)
+* `async_sync_schedule`: updating schedule data for a device and module
+* `async_switch_schedule`: changing active schedule for a device and module
+
+```python
+from vaillant_netatmo_api import thermostat_client, SystemMode, Token
+
+CLIENT_ID = ""
+CLIENT_SECRET = ""
+
+token_string = read_from_storage()
+token = Token.deserialize(token_string)
+
+def handle_token_update(token):
+    token_string = token.serialize()
+    write_to_storage(token_string)
+
+async with thermostat_client(CLIENT_ID, CLIENT_SECRET, token, handle_token_update) as client:
+    devices = await client.async_get_thermostats_data()
+
+    d_id = devices[0].id
+    m_id = devices[0].modules[0].id
+
+    await client.async_set_system_mode(d_id, m_id, SystemMode.WINTER)
+```
+
+### Using clients as singletons
+
+Even though library offers context manager for using `AuthClient` and `ThermostatClient`, this should only be done during development or in very infrequent usage scenarios.
+
+Both of the clients use `httpx.AsyncClient` as the underlying HTTP communication library, which implements connection pooling and connection reuse. This means doing multiple concurent requests should be done by using the same instance of the `AuthClient` or `ThermostatClient`, which is not possible by using the context manager API since this API will return new instance of the client every time `auth_client` or `thermostat_client` method is called.
+
+To achieve optimal usage, which will utilize connection pooling and connection reuse, both `AuthClient` and `ThermostatClient` should be used by instantiating the clients and providing `httpx.AsyncClient` instance in a constructor. This provided client should be used as singleton, or with some other context management mechanism, with the context wider than one block of code or one inbound request.
+
+Here is an example for usage in Home Assistant.
+
+```python
+# When setting up integration with all the devices of one account, instantiate and store the client in a configuration memory store
+async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    client = get_async_client(hass)
+    token_store = TokenStore(
+        entry.data[CONF_CLIENT_ID],
+        entry.data[CONF_CLIENT_SECRET],
+        token,
+        handle_token_update,
+    )
+
+    hass.data[DOMAIN][entry.entry_id] = ThermostatClient(client, token_store)
+    hass.config_entries.async_setup_platforms(entry, PLATFORMS)
+
+    return True
+
+# When unloading the integration of this same account, read the client and close it manually
+async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
+    if unload_ok:
+        hass.data[DOMAIN].pop(entry.entry_id)
+
+    return unload_ok
+```
+
+Similar hooks which represent some kind of application context should be used when integrating this library into a different application (Flask, Django or similar).
+
+## Acknowledgements
+
+The original library was created by **Mislav Mandarić**, who retains the original copyright and attribution. This NG fork builds on that work and preserves its MIT license.
+
+
+This library would not exist if it weren't for previous implementations by the following projects:
+
+* https://github.com/philippelt/netatmo-api-python
+* https://github.com/jabesq/netatmo-api-python
+* https://github.com/samueldumont/netatmo-api-python
+* https://github.com/jabesq/pyatmo
+* https://github.com/pjmaenh/pyvaillant
+
+They laid out the foundation by exploring and documenting the APIs.
+
+## Disclaimers
+
+**This is an unofficial, independent community project. It is not affiliated with, authorized, sponsored, or endorsed by Vaillant or Netatmo.** The project is provided without warranties or official support. Changes to either company's APIs, including restrictions on third-party access, may cause some or all features to stop working.

vaillant_netatmo_api_ng-0.1.0/README.md

@@ -0,0 +1,178 @@
+# vaillant-netatmo-api-ng
+
+[![Tests](https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG/actions/workflows/tests.yml/badge.svg)](https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG/actions/workflows/tests.yml)
+
+## About this fork
+
+**vaillant-netatmo-api-ng** is a community-maintained fork of [Mislav Mandarić's vaillant-netatmo-api](https://github.com/MislavMandaric/vaillant-netatmo-api), a Python library for accessing Vaillant vSMART/eRELAX thermostats through Netatmo-backed APIs.
+
+This fork starts its **own version series at 0.1.0**. Version numbers do **not** track the original project's releases. The initial NG work adds read-only room temperatures from Vaillant's `homestatus` endpoint, without replacing existing thermostat data or control APIs.
+
+> [!IMPORTANT]
+> **Independent, unofficial project — NOT affiliated with, authorized, sponsored, or endorsed by Vaillant or Netatmo.**
+> This community fork is not an official Vaillant or Netatmo product, and neither company provides support for it. Their APIs may change or become unavailable without notice.
+
+This fork is also independent of the original project's maintainer. See [LICENSE](LICENSE) for the MIT license and original copyright notice.
+
+## Features
+
+- Existing authenticated thermostat data access and heating controls from the upstream library.
+- `ThermostatClient.async_get_homes_data()` for homes, rooms and `Room.module_ids`.
+- **NEW:** `ThermostatClient.async_get_home_status(home_id)` for room status (including measured temperature, target temperature and reachability) keyed by room ID.
+- Defensive validation for malformed responses and duplicate or conflicting room records.
+- No fabricated measurement timestamp: the `homestatus` response does not provide a verified temperature acquisition time.
+
+## Installation
+
+Once published on PyPI, the NG package can be installed with:
+
+```bash
+pip install vaillant-netatmo-api-ng==0.1.0
+```
+
+**Publication status:** Version 0.1.0 is prepared in this repository but is **not yet confirmed as published on PyPI**. Until release, use the [source repository](https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG) and a branch/commit-specific installation for development.
+
+The **distribution name** is `vaillant-netatmo-api-ng`, but the Python **import name** intentionally remains `vaillant_netatmo_api` for compatibility:
+
+```python
+from vaillant_netatmo_api.thermostat import ThermostatClient
+```
+
+Do not install `vaillant-netatmo-api` and `vaillant-netatmo-api-ng` in the same environment; they provide the same import package and may overwrite each other's files.
+
+Requires Python 3.8+ and the `httpx` and `tenacity` dependencies.
+
+## API usage
+
+### Reading room temperatures
+
+With an existing authenticated `ThermostatClient` instance:
+
+```python
+homes = await client.async_get_homes_data()
+for home in homes:
+    statuses = await client.async_get_home_status(home.id)
+    for room in home.rooms:
+        room_status = statuses.get(room.id)
+        if room_status is not None:
+            print(room_status.measured_temperature)
+```
+
+Use `homesdata` `rooms[].module_ids` to map room readings to the right thermostat module; do not assume the first room represents every thermostat. If `homestatus` cannot provide a valid room reading, applications should retain their previous measured-temperature fallback. This library does not change polling intervals for consumers.
+
+### Existing authentication and thermostat operations
+
+### Getting the token from the OAuth API
+
+All Netatmo APIs are protected and require a bearer token to authenticate. To get this token, Netatmo offers an OAuth API.
+
+Since Vaillant uses Resource Owner Password Credentials Grant, there is only one method in the `AuthClient` API:
+
+* `async_token`: getting a bearer token and storing it in the token store
+
+```python
+from vaillant_netatmo_api import auth_client
+
+CLIENT_ID = ""
+CLIENT_SECRET = ""
+
+def handle_token_update(token):
+    token_string = token.serialize()
+    write_to_storage(token_string)
+
+async with auth_client(CLIENT_ID, CLIENT_SECRET, handle_token_update) as client:
+    await client.async_token(
+        username,
+        password,
+        user_prefix,
+        app_version,
+    )
+```
+
+### Accessing the Thermostat API
+
+The existing `ThermostatClient` methods include:
+
+* `async_get_thermostats_data`: getting all the devices associated with the user account
+* `async_set_system_mode`: changing system mode for a device and module (ie. summer, winter or frostguard)
+* `async_set_minor_mode`: changing minor mode for a device and module (ie. manual mode, away mode or hot water boost mode)
+* `async_sync_schedule`: updating schedule data for a device and module
+* `async_switch_schedule`: changing active schedule for a device and module
+
+```python
+from vaillant_netatmo_api import thermostat_client, SystemMode, Token
+
+CLIENT_ID = ""
+CLIENT_SECRET = ""
+
+token_string = read_from_storage()
+token = Token.deserialize(token_string)
+
+def handle_token_update(token):
+    token_string = token.serialize()
+    write_to_storage(token_string)
+
+async with thermostat_client(CLIENT_ID, CLIENT_SECRET, token, handle_token_update) as client:
+    devices = await client.async_get_thermostats_data()
+
+    d_id = devices[0].id
+    m_id = devices[0].modules[0].id
+
+    await client.async_set_system_mode(d_id, m_id, SystemMode.WINTER)
+```
+
+### Using clients as singletons
+
+Even though library offers context manager for using `AuthClient` and `ThermostatClient`, this should only be done during development or in very infrequent usage scenarios.
+
+Both of the clients use `httpx.AsyncClient` as the underlying HTTP communication library, which implements connection pooling and connection reuse. This means doing multiple concurent requests should be done by using the same instance of the `AuthClient` or `ThermostatClient`, which is not possible by using the context manager API since this API will return new instance of the client every time `auth_client` or `thermostat_client` method is called.
+
+To achieve optimal usage, which will utilize connection pooling and connection reuse, both `AuthClient` and `ThermostatClient` should be used by instantiating the clients and providing `httpx.AsyncClient` instance in a constructor. This provided client should be used as singleton, or with some other context management mechanism, with the context wider than one block of code or one inbound request.
+
+Here is an example for usage in Home Assistant.
+
+```python
+# When setting up integration with all the devices of one account, instantiate and store the client in a configuration memory store
+async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    client = get_async_client(hass)
+    token_store = TokenStore(
+        entry.data[CONF_CLIENT_ID],
+        entry.data[CONF_CLIENT_SECRET],
+        token,
+        handle_token_update,
+    )
+
+    hass.data[DOMAIN][entry.entry_id] = ThermostatClient(client, token_store)
+    hass.config_entries.async_setup_platforms(entry, PLATFORMS)
+
+    return True
+
+# When unloading the integration of this same account, read the client and close it manually
+async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
+    if unload_ok:
+        hass.data[DOMAIN].pop(entry.entry_id)
+
+    return unload_ok
+```
+
+Similar hooks which represent some kind of application context should be used when integrating this library into a different application (Flask, Django or similar).
+
+## Acknowledgements
+
+The original library was created by **Mislav Mandarić**, who retains the original copyright and attribution. This NG fork builds on that work and preserves its MIT license.
+
+
+This library would not exist if it weren't for previous implementations by the following projects:
+
+* https://github.com/philippelt/netatmo-api-python
+* https://github.com/jabesq/netatmo-api-python
+* https://github.com/samueldumont/netatmo-api-python
+* https://github.com/jabesq/pyatmo
+* https://github.com/pjmaenh/pyvaillant
+
+They laid out the foundation by exploring and documenting the APIs.
+
+## Disclaimers
+
+**This is an unofficial, independent community project. It is not affiliated with, authorized, sponsored, or endorsed by Vaillant or Netatmo.** The project is provided without warranties or official support. Changes to either company's APIs, including restrictions on third-party access, may cause some or all features to stop working.

vaillant_netatmo_api_ng-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = [
+    "setuptools",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vaillant-netatmo-api-ng"
+version = "0.1.0"
+authors = [
+    { name="Mislav Mandaric" },
+]
+description = "Community fork for managing Vaillant thermostats using Netatmo-backed APIs."
+readme = "README.md"
+maintainers = [
+    { name="LEOSCHUMY" },
+]
+requires-python = ">=3.8"
+dependencies = [
+    "httpx>=0.18.2",
+    "tenacity>=8.0.1",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG"
+Source = "https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG"
+Issues = "https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG/issues"
+Changelog = "https://github.com/LEOSCHUMY/vaillant-netatmo-api-NG/blob/master/CHANGELOG.md"
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+build_command = "pip install build && python -m build"
+commit_message = "chore(release): {version} [skip ci]"
+major_on_zero = false

vaillant_netatmo_api_ng-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vaillant_netatmo_api_ng-0.1.0/src/vaillant_netatmo_api/__init__.py

@@ -0,0 +1,79 @@
+"""Module HTTP communication with the Netatmo API."""
+
+from .auth import AuthClient, auth_client
+from .errors import (
+    ApiException,
+    NonOkResponseException,
+    NetworkException,
+    NetworkTimeoutException,
+    NonRetryableException,
+    RequestBackoffException,
+    RequestClientException,
+    RequestException,
+    RequestServerException,
+    RequestUnauthorizedException,
+    RetryableException,
+    UnsuportedArgumentsException,
+)
+from .home import (
+    Home,
+    Room,
+    TemperatureControlMode,
+    ThermMode,
+    ThermSetpointMode,
+)
+from .thermostat import (
+    Device,
+    Measured,
+    MeasurementItem,
+    MeasurementScale,
+    MeasurementType,
+    Module,
+    Program,
+    Setpoint,
+    SetpointMode,
+    SystemMode,
+    ThermostatClient,
+    TimeSlot,
+    Zone,
+    thermostat_client,
+)
+from .token import Token, TokenStore
+
+__all__ = [
+    "AuthClient",
+    "ThermostatClient",
+    "ApiException",
+    "NonOkResponseException",
+    "NetworkException",
+    "NetworkTimeoutException",
+    "NonRetryableException",
+    "RequestBackoffException",
+    "RequestClientException",
+    "RequestException",
+    "RequestServerException",
+    "RequestUnauthorizedException",
+    "RetryableException",
+    "UnsuportedArgumentsException",
+    "Home",
+    "Room",
+    "TemperatureControlMode",
+    "ThermMode",
+    "ThermSetpointMode",
+    "Device",
+    "Module",
+    "Program",
+    "Zone",
+    "TimeSlot",
+    "Setpoint",
+    "Measured",
+    "MeasurementItem",
+    "MeasurementType",
+    "MeasurementScale",
+    "SystemMode",
+    "SetpointMode",
+    "Token",
+    "TokenStore",
+    "auth_client",
+    "thermostat_client",
+]

vaillant_netatmo_api_ng-0.1.0/src/vaillant_netatmo_api/auth.py

@@ -0,0 +1,79 @@
+"""Module containing an AuthClient for the Netatmo API."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator, Callable
+
+from httpx import AsyncClient
+
+from .base import BaseClient
+from .token import Token, TokenStore
+
+_TOKEN_PATH = "oauth2/token"
+
+
+@asynccontextmanager
+async def auth_client(
+    client_id: str,
+    client_secret: str,
+    on_token_update: Callable[[Token], None],
+) -> AsyncGenerator[AuthClient, None]:
+    client = AsyncClient()
+    token_store = TokenStore(client_id, client_secret, None, on_token_update)
+    
+    c = AuthClient(client, token_store)
+
+    try:
+        yield c
+    finally:
+        await client.aclose()
+
+class AuthClient(BaseClient):
+    """
+    Client for making HTTP requests to the Netatmo API. Used for the subset of the API related to the authentication: getting the access and refresh tokens.
+
+    Uses BaseClient as a basis for making HTTP requests.
+    """
+
+    def __init__(
+        self,
+        client: AsyncClient,
+        token_store: TokenStore,
+    ) -> None:
+        """
+        Create new auth client instance.
+
+        Uses the provided parameters to instantiate the BaseClient class.
+        """
+
+        self._token_store = token_store
+        super().__init__(client, None)
+
+    async def async_token(
+        self,
+        username: str,
+        password: str,
+        user_prefix: str,
+        app_version: str,
+    ) -> None:
+        """
+        Get the access and refresh tokens from the Netatmo API which can be used for making requests towards all other protected APIs. Uses the resource owner password credentials grant, with custom Vaillant parameters - user prefix and app version.
+
+        On success, returns nothing. On error, throws an exception.
+        """
+
+        data = {
+            "username": username,
+            "password": password,
+            "user_prefix": user_prefix,
+            "app_version": app_version,
+        }
+        data.update(self._token_store.access_token_request)
+
+        body = await self._post(
+            _TOKEN_PATH,
+            data=data,
+        )
+
+        self._token_store.token = Token(body)

vaillant_netatmo_api_ng-0.1.0/src/vaillant_netatmo_api/auth_test.py

@@ -0,0 +1,65 @@
+import httpx
+import pytest
+
+from pytest_mock import MockerFixture
+from respx import MockRouter
+
+from vaillant_netatmo_api.auth import auth_client
+from vaillant_netatmo_api.errors import RequestClientException
+from vaillant_netatmo_api.token import Token
+
+get_token_request = {
+    "username": "user",
+    "password": "pass",
+    "user_prefix": "prefix",
+    "app_version": "version",
+    "grant_type": "password",
+    "client_id": "client",
+    "client_secret": "secret",
+    "scope": "all_scopes",
+}
+
+get_token_response = {
+    "access_token": "12345",
+    "refresh_token": "abcde",
+    "expires_at": "",
+}
+
+
+@pytest.mark.asyncio
+class TestAuth:
+    async def test_async_get_token__invalid_request_params__raises_error(self, respx_mock: MockRouter):
+        respx_mock.post("https://app.netatmo.net/oauth2/token",
+                        data=get_token_request).respond(400)
+
+        async with auth_client(get_token_request["client_id"], get_token_request["client_secret"], None) as client:
+            with pytest.raises(RequestClientException):
+                await client.async_token(get_token_request["username"], get_token_request["password"], get_token_request["user_prefix"], get_token_request["app_version"])
+
+    async def test_async_get_token__server_errors__retry_until_success(self, respx_mock: MockRouter, mocker: MockerFixture):
+        respx_mock.post("https://app.netatmo.net/oauth2/token", data=get_token_request).mock(side_effect=[
+            httpx.Response(500),
+            httpx.Response(200, json=get_token_response),
+        ])
+
+        on_token_update_stub = mocker.stub()
+
+        async with auth_client(get_token_request["client_id"], get_token_request["client_secret"], on_token_update_stub) as client:
+            await client.async_token(get_token_request["username"], get_token_request["password"], get_token_request["user_prefix"], get_token_request["app_version"])
+
+            assert respx_mock.calls.call_count == 2
+            on_token_update_stub.assert_called_once_with(
+                Token(get_token_response))
+
+    async def test_async_get_token__valid_request_params__returns_valid_oauth_token(self, respx_mock: MockRouter, mocker: MockerFixture):
+        respx_mock.post("https://app.netatmo.net/oauth2/token",
+                        data=get_token_request).respond(200, json=get_token_response)
+
+        on_token_update_stub = mocker.stub()
+
+        async with auth_client(get_token_request["client_id"], get_token_request["client_secret"], on_token_update_stub) as client:
+            await client.async_token(get_token_request["username"], get_token_request["password"], get_token_request["user_prefix"], get_token_request["app_version"])
+
+            assert respx_mock.calls.call_count == 1
+            on_token_update_stub.assert_called_once_with(
+                Token(get_token_response))