vi-api-client 6.1.1__tar.gz

vi_api_client-6.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael
+
+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.

vi_api_client-6.1.1/MANIFEST.in

@@ -0,0 +1,17 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+
+recursive-include src/vi_api_client *.py
+include src/vi_api_client/py.typed
+recursive-include src/vi_api_client/fixtures *.json
+
+# Exclude documentation and local config
+exclude tokens.json
+exclude HA_INTEGRATION_HANDOVER.md
+prune tests
+prune docs
+global-exclude .DS_Store
+global-exclude *.pyc
+global-exclude __pycache__

vi_api_client-6.1.1/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: vi_api_client
+Version: 6.1.1
+Summary: Async Python client for Viessmann Climate Solutions API
+Author: Michael
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ignazhabibi/vi_api_client
+Project-URL: Documentation, https://github.com/ignazhabibi/vi_api_client/tree/main/docs
+Project-URL: Issues, https://github.com/ignazhabibi/vi_api_client/issues
+Project-URL: Changelog, https://github.com/ignazhabibi/vi_api_client/releases
+Keywords: api-client,asyncio,heat-pump,heating,home-assistant,viessmann
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.13.3
+Provides-Extra: dev
+Requires-Dist: aiointercept>=0.1.12; extra == "dev"
+Requires-Dist: build>=1.4; extra == "dev"
+Requires-Dist: pytest>=9; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.1; extra == "dev"
+Requires-Dist: pyright==1.1.414; extra == "dev"
+Requires-Dist: pre-commit==4.7.0; extra == "dev"
+Requires-Dist: ruff==0.17.4; extra == "dev"
+Dynamic: license-file
+
+# Viessmann API Python Client
+
+A Python library for accessing the [Viessmann Climate Solutions API](https://developer.viessmann-climatesolutions.com/start.html).
+Designed for integration with Home Assistant and other async Python applications.
+
+## Features
+
+- **Asynchronous**: Built on `aiohttp` and `asyncio`.
+- **OAuth2 Authentication**: Handles token retrieval and automatic renewal.
+- **Auto-Discovery**: Automatically finds installations, gateways, and devices.
+- **Recursive Feature Flattening**: Converts complex nested API responses into a simple, flat list of features (e.g., `heating.circuits.0.heating.curve.shift`).
+- **Gateway-Scoped Refresh**: Refreshes multiple known devices with one normal-case request while preserving partial successes.
+- **Command Execution**: Supports safe single-feature writes with automatic
+  parameter resolution and explicit multi-parameter commands.
+- **Fixture-backed Client**: Runs the same client workflows against bundled real-device
+  responses without authentication, sessions, or network requests.
+- **Strictly Typed**: Ships as a PEP 561 complete package with `py.typed`; the
+  shipped code passes strict Pyright and dynamic values follow a typed JSON
+  value contract.
+
+## Public API
+
+Import consumer-facing symbols from `vi_api_client`:
+
+```python
+from vi_api_client import (
+    AbstractAuth,
+    CommandResponse,
+    DEFAULT_SCOPES,
+    Device,
+    ENDPOINT_AUTHORIZE,
+    ENDPOINT_TOKEN,
+    EventHistoryPage,
+    Feature,
+    FeatureControl,
+    FeatureValue,
+    Gateway,
+    GatewayDeviceRefreshResult,
+    Installation,
+    InstallationEvent,
+    JsonValue,
+    FixtureViClient,
+    OAuth,
+    ScheduleConstraints,
+    ValidationDetail,
+    ViAuthError,
+    ViClient,
+    ViConnectionError,
+    ViError,
+    ViNotFoundError,
+    ViRateLimitError,
+    ViResponseError,
+    ViServerInternalError,
+    ViValidationError,
+    format_feature,
+    redact_device,
+    redact_feature,
+    redact_sensitive,
+    validate_json_value,
+)
+```
+
+`DEFAULT_SCOPES`, `ENDPOINT_AUTHORIZE`, and `ENDPOINT_TOKEN` support external
+OAuth integrations. `JsonValue`, `FeatureValue`, `ValidationDetail`, and
+`validate_json_value` form the public recursive JSON value contract that
+dynamic feature values and API validation details follow. `redact_sensitive`,
+`redact_feature`, and `redact_device` redact secrets, address data,
+identifiers, and coordinates in log text, API documents, and model objects.
+CLI helpers, transport details, persistence, and parsing remain available from
+their dedicated modules.
+
+## Installation
+
+**Requires Python 3.14+.** Install the released package from PyPI:
+
+```bash
+python3.14 -m venv .venv
+source .venv/bin/activate
+pip install vi_api_client
+```
+
+To work on the library itself, install it from a clone in editable mode:
+
+```bash
+git clone https://github.com/ignazhabibi/vi_api_client.git
+cd vi_api_client
+pip install -e .
+```
+
+## Development and Tests
+
+Install the development dependencies with the CI constraints to reproduce the
+tested HTTP client and mock combination locally:
+
+```bash
+python -m pip install -c constraints-ci.txt '.[dev]'
+pre-commit install
+ruff check .
+ruff format --check .
+pyright --pythonpath python
+pyright --project pyrightconfig.strict.json
+python -m pytest -q
+python scripts/check_coverage.py
+python -m build
+python scripts/verify_distributions.py
+```
+
+The shipped package is strictly typed and PEP 561 complete: the strict
+Pyright pass covers `src/vi_api_client`, the built wheel and source
+distribution ship `py.typed`, and the installed wheel passes
+`pyright --verifytypes vi_api_client --ignoreexternal`. Tests remain under
+standard type checking. The suite must keep at least 95% line
+and branch coverage over `src/vi_api_client`; `scripts/check_coverage.py`
+enforces both thresholds in the quality gate.
+
+## Quick Start
+
+### CLI
+
+The `vi-client` tool is the easiest way to explore the API.
+
+```bash
+# 1. Login
+vi-client login --client-id <YOUR_CLIENT_ID>
+
+# 2. List Devices
+vi-client list-devices
+
+# 3. List only enabled Features with values (auto-detects first device)
+vi-client list-features --enabled --values
+
+# 4. List Writable Features (Settings)
+vi-client list-writable
+
+# 5. List the complete installation event history (last 7 days)
+vi-client list-events --days 7
+```
+
+See [CLI Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/06_cli_reference.md) for more details.
+
+### Python Code
+
+The example reads tokens from `tokens.json`. Create that file once with
+`vi-client login`, or log in from Python as shown in the
+[Authentication reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/03_auth_reference.md#first-login).
+
+```python
+import asyncio
+import aiohttp
+from vi_api_client import OAuth, ViClient
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        # Initialize Auth (tokens saved to tokens.json)
+        auth = OAuth(
+            client_id="YOUR_CLIENT_ID",
+            redirect_uri="http://localhost:4200/",
+            token_file="tokens.json",
+            websession=session,
+        )
+
+        client = ViClient(auth)
+
+        # 1. Get Installations & Gateways
+        installations = await client.get_installations()
+        if not installations:
+            return
+        installation = installations[0]
+
+        gateways = await client.get_gateways()
+        gateway = next(
+            (
+                gateway
+                for gateway in gateways
+                if gateway.installation_id == installation.id
+            ),
+            None,
+        )
+        if gateway is None:
+            return
+
+        # 2. Discover and refresh devices behind one gateway
+        devices = await client.get_devices(installation.id, gateway.serial)
+        refresh = await client.refresh_gateway_devices(devices)
+        for device_id, error in refresh.errors_by_device_id.items():
+            print(f"Device {device_id} could not be refreshed: {error}")
+        if not refresh.updated_devices:
+            return
+        device = refresh.updated_devices[0]
+        print(f"Device: {device.model_id} ({device.status})")
+
+        # 3. Iterate Features (Flat List)
+        for feature in device.features:
+            print(f"{feature.name}: {feature.value}")
+
+        # 4. Write one Feature with automatic dependency resolution
+        # Find a writable feature (e.g. heating curve slope)
+        slope = next(
+            (f for f in device.features if "curve.slope" in f.name and f.is_writable),
+            None,
+        )
+        if slope:
+            print(f"Setting slope to 1.4...")
+            response, device = await client.set_feature(device, slope, 1.4)
+            if response.success:
+                print("✅ Success! Device updated.")
+                # Use updated device for subsequent calls
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Documentation
+
+The detailed documentation is available in the `docs/` directory:
+
+1.  **[Getting Started](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/01_getting_started.md)**: Installation and First Steps.
+2.  **[API Structure & Concepts](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/02_api_structure.md)**: Understanding the Flat Architecture.
+3.  **[Authentication & Connection](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/03_auth_reference.md)**: Tokens, Sessions, and Thread-Safety.
+4.  **[Models Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/04_models_reference.md)**: Devices, Features, and Controls.
+5.  **[Client Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/05_client_reference.md)**: The `ViClient` class methods.
+6.  **[CLI Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/06_cli_reference.md)**: Using the command line interface.
+7.  **[Exceptions Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/07_exceptions_reference.md)**: Handling errors.
+8.  **[Architecture Guide](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/08_architecture.md)**: System structure,
+    responsibilities, data flows, and diagrams explained for developers and
+    non-specialists.

vi_api_client-6.1.1/README.md

@@ -0,0 +1,228 @@
+# Viessmann API Python Client
+
+A Python library for accessing the [Viessmann Climate Solutions API](https://developer.viessmann-climatesolutions.com/start.html).
+Designed for integration with Home Assistant and other async Python applications.
+
+## Features
+
+- **Asynchronous**: Built on `aiohttp` and `asyncio`.
+- **OAuth2 Authentication**: Handles token retrieval and automatic renewal.
+- **Auto-Discovery**: Automatically finds installations, gateways, and devices.
+- **Recursive Feature Flattening**: Converts complex nested API responses into a simple, flat list of features (e.g., `heating.circuits.0.heating.curve.shift`).
+- **Gateway-Scoped Refresh**: Refreshes multiple known devices with one normal-case request while preserving partial successes.
+- **Command Execution**: Supports safe single-feature writes with automatic
+  parameter resolution and explicit multi-parameter commands.
+- **Fixture-backed Client**: Runs the same client workflows against bundled real-device
+  responses without authentication, sessions, or network requests.
+- **Strictly Typed**: Ships as a PEP 561 complete package with `py.typed`; the
+  shipped code passes strict Pyright and dynamic values follow a typed JSON
+  value contract.
+
+## Public API
+
+Import consumer-facing symbols from `vi_api_client`:
+
+```python
+from vi_api_client import (
+    AbstractAuth,
+    CommandResponse,
+    DEFAULT_SCOPES,
+    Device,
+    ENDPOINT_AUTHORIZE,
+    ENDPOINT_TOKEN,
+    EventHistoryPage,
+    Feature,
+    FeatureControl,
+    FeatureValue,
+    Gateway,
+    GatewayDeviceRefreshResult,
+    Installation,
+    InstallationEvent,
+    JsonValue,
+    FixtureViClient,
+    OAuth,
+    ScheduleConstraints,
+    ValidationDetail,
+    ViAuthError,
+    ViClient,
+    ViConnectionError,
+    ViError,
+    ViNotFoundError,
+    ViRateLimitError,
+    ViResponseError,
+    ViServerInternalError,
+    ViValidationError,
+    format_feature,
+    redact_device,
+    redact_feature,
+    redact_sensitive,
+    validate_json_value,
+)
+```
+
+`DEFAULT_SCOPES`, `ENDPOINT_AUTHORIZE`, and `ENDPOINT_TOKEN` support external
+OAuth integrations. `JsonValue`, `FeatureValue`, `ValidationDetail`, and
+`validate_json_value` form the public recursive JSON value contract that
+dynamic feature values and API validation details follow. `redact_sensitive`,
+`redact_feature`, and `redact_device` redact secrets, address data,
+identifiers, and coordinates in log text, API documents, and model objects.
+CLI helpers, transport details, persistence, and parsing remain available from
+their dedicated modules.
+
+## Installation
+
+**Requires Python 3.14+.** Install the released package from PyPI:
+
+```bash
+python3.14 -m venv .venv
+source .venv/bin/activate
+pip install vi_api_client
+```
+
+To work on the library itself, install it from a clone in editable mode:
+
+```bash
+git clone https://github.com/ignazhabibi/vi_api_client.git
+cd vi_api_client
+pip install -e .
+```
+
+## Development and Tests
+
+Install the development dependencies with the CI constraints to reproduce the
+tested HTTP client and mock combination locally:
+
+```bash
+python -m pip install -c constraints-ci.txt '.[dev]'
+pre-commit install
+ruff check .
+ruff format --check .
+pyright --pythonpath python
+pyright --project pyrightconfig.strict.json
+python -m pytest -q
+python scripts/check_coverage.py
+python -m build
+python scripts/verify_distributions.py
+```
+
+The shipped package is strictly typed and PEP 561 complete: the strict
+Pyright pass covers `src/vi_api_client`, the built wheel and source
+distribution ship `py.typed`, and the installed wheel passes
+`pyright --verifytypes vi_api_client --ignoreexternal`. Tests remain under
+standard type checking. The suite must keep at least 95% line
+and branch coverage over `src/vi_api_client`; `scripts/check_coverage.py`
+enforces both thresholds in the quality gate.
+
+## Quick Start
+
+### CLI
+
+The `vi-client` tool is the easiest way to explore the API.
+
+```bash
+# 1. Login
+vi-client login --client-id <YOUR_CLIENT_ID>
+
+# 2. List Devices
+vi-client list-devices
+
+# 3. List only enabled Features with values (auto-detects first device)
+vi-client list-features --enabled --values
+
+# 4. List Writable Features (Settings)
+vi-client list-writable
+
+# 5. List the complete installation event history (last 7 days)
+vi-client list-events --days 7
+```
+
+See [CLI Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/06_cli_reference.md) for more details.
+
+### Python Code
+
+The example reads tokens from `tokens.json`. Create that file once with
+`vi-client login`, or log in from Python as shown in the
+[Authentication reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/03_auth_reference.md#first-login).
+
+```python
+import asyncio
+import aiohttp
+from vi_api_client import OAuth, ViClient
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        # Initialize Auth (tokens saved to tokens.json)
+        auth = OAuth(
+            client_id="YOUR_CLIENT_ID",
+            redirect_uri="http://localhost:4200/",
+            token_file="tokens.json",
+            websession=session,
+        )
+
+        client = ViClient(auth)
+
+        # 1. Get Installations & Gateways
+        installations = await client.get_installations()
+        if not installations:
+            return
+        installation = installations[0]
+
+        gateways = await client.get_gateways()
+        gateway = next(
+            (
+                gateway
+                for gateway in gateways
+                if gateway.installation_id == installation.id
+            ),
+            None,
+        )
+        if gateway is None:
+            return
+
+        # 2. Discover and refresh devices behind one gateway
+        devices = await client.get_devices(installation.id, gateway.serial)
+        refresh = await client.refresh_gateway_devices(devices)
+        for device_id, error in refresh.errors_by_device_id.items():
+            print(f"Device {device_id} could not be refreshed: {error}")
+        if not refresh.updated_devices:
+            return
+        device = refresh.updated_devices[0]
+        print(f"Device: {device.model_id} ({device.status})")
+
+        # 3. Iterate Features (Flat List)
+        for feature in device.features:
+            print(f"{feature.name}: {feature.value}")
+
+        # 4. Write one Feature with automatic dependency resolution
+        # Find a writable feature (e.g. heating curve slope)
+        slope = next(
+            (f for f in device.features if "curve.slope" in f.name and f.is_writable),
+            None,
+        )
+        if slope:
+            print(f"Setting slope to 1.4...")
+            response, device = await client.set_feature(device, slope, 1.4)
+            if response.success:
+                print("✅ Success! Device updated.")
+                # Use updated device for subsequent calls
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Documentation
+
+The detailed documentation is available in the `docs/` directory:
+
+1.  **[Getting Started](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/01_getting_started.md)**: Installation and First Steps.
+2.  **[API Structure & Concepts](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/02_api_structure.md)**: Understanding the Flat Architecture.
+3.  **[Authentication & Connection](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/03_auth_reference.md)**: Tokens, Sessions, and Thread-Safety.
+4.  **[Models Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/04_models_reference.md)**: Devices, Features, and Controls.
+5.  **[Client Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/05_client_reference.md)**: The `ViClient` class methods.
+6.  **[CLI Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/06_cli_reference.md)**: Using the command line interface.
+7.  **[Exceptions Reference](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/07_exceptions_reference.md)**: Handling errors.
+8.  **[Architecture Guide](https://github.com/ignazhabibi/vi_api_client/blob/main/docs/08_architecture.md)**: System structure,
+    responsibilities, data flows, and diagrams explained for developers and
+    non-specialists.

vi_api_client-6.1.1/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vi_api_client"
+version = "6.1.1"
+description = "Async Python client for Viessmann Climate Solutions API"
+readme = "README.md"
+authors = [
+  { name = "Michael" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "api-client",
+    "asyncio",
+    "heat-pump",
+    "heating",
+    "home-assistant",
+    "viessmann",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "aiohttp>=3.13.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/ignazhabibi/vi_api_client"
+Documentation = "https://github.com/ignazhabibi/vi_api_client/tree/main/docs"
+Issues = "https://github.com/ignazhabibi/vi_api_client/issues"
+Changelog = "https://github.com/ignazhabibi/vi_api_client/releases"
+
+[project.optional-dependencies]
+dev = [
+    "aiointercept>=0.1.12",
+    "build>=1.4",
+    "pytest>=9",
+    "pytest-asyncio>=1.3",
+    "pytest-cov>=7.1",
+    "pyright==1.1.414",
+    "pre-commit==4.7.0",
+    "ruff==0.17.4",
+]
+
+[project.scripts]
+vi-client = "vi_api_client.cli:main"
+
+[tool.setuptools.package-data]
+vi_api_client = ["py.typed"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "D",   # pydocstyle
+    "E",   # pycodestyle error
+    "W",   # pycodestyle warning
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "PL",  # pylint
+    "RUF", # ruff specific
+    "S"    # flake8-bandit (security)
+]
+
+ignore = [
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package
+    "D105", # Missing docstring in magic method
+    "D203", # 1 blank line required before class docstring
+    "D213", # Multi-line docstring summary should start at the second line
+    "PLR2004", # Magic value used
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "D", "PLR0913", "PLR0917", "PLR2004", "E501",
+    # Tests assert, use placeholder tokens, and run the CLI as a subprocess.
+    "S101", "S105", "S106", "S603",
+]
+# Repository scripts run fixed tool commands and parse the local coverage.xml.
+"scripts/*" = ["S314", "S603"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.pyright]
+include = ["src", "tests"]
+exclude = [".venv", "build", "dist"]
+pythonVersion = "3.14"
+typeCheckingMode = "standard"

vi_api_client-6.1.1/setup.cfg

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