pyfenixcontrol 0.1.0__tar.gz

pyfenixcontrol-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

pyfenixcontrol-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-15
+
+First release, extracted from the `api.py` module of the
+[`fenix_tft`](https://github.com/baracudaz/fenix_tft) Home Assistant integration
+(v1.3.8).
+
+### Added
+- `FenixControlClient` with typed models (`Installation`, `Room`, `Device`,
+  `EnergyMetric`) and enums (`PresetMode`, `HvacState`, `HolidayMode`,
+  `EnergyPeriod`).
+- Pluggable authentication via `AbstractAuth`; `PasswordAuth` implements the
+  existing e-mail/password OAuth2 PKCE login.
+- Exception hierarchy separating auth, connection and response errors.
+
+### Changed compared to the integration's `api.py`
+- No dependency on Home Assistant or BeautifulSoup (login form parsed with the
+  standard library).
+- Network errors and timeouts during login raise `FenixControlConnectionError`
+  instead of an auth error, so a network outage no longer looks like invalid
+  credentials.
+- Invalid credentials are reported explicitly instead of a generic login failure.
+- Concurrent requests share one login/refresh (asyncio lock) instead of a
+  re-entrancy flag that let parallel callers proceed without a token.
+- Identity-server cookies are cleared before a full login, so a cached identity
+  session cannot authenticate a different account sharing the HTTP session.
+- PUT requests now use the request timeout (previously unbounded).
+- API requests no longer follow HTTP redirects.
+- Energy queries take explicit `start`/`end` instead of "today in HA's time zone";
+  the daily total and the "user connected" update trigger are left to the caller.

pyfenixcontrol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Stanislav Likavčan
+
+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.

pyfenixcontrol-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: pyfenixcontrol
+Version: 0.1.0
+Summary: Asynchronous Python client for the FENIX Control cloud API (FENIX TFT WiFi thermostats).
+Project-URL: Homepage, https://github.com/baracudaz/pyfenixcontrol
+Project-URL: Source, https://github.com/baracudaz/pyfenixcontrol
+Project-URL: Issues, https://github.com/baracudaz/pyfenixcontrol/issues
+Project-URL: Changelog, https://github.com/baracudaz/pyfenixcontrol/blob/main/CHANGELOG.md
+Author-email: Stanislav Likavčan <likavcan@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,fenix,fenix control,home assistant,tft,thermostat
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9.0
+Description-Content-Type: text/markdown
+
+# pyfenixcontrol
+
+Asynchronous Python client for the **FENIX Control** cloud, used by FENIX TFT WiFi
+thermostats. It powers the FENIX integration for [Home Assistant](https://www.home-assistant.io/),
+but has no Home Assistant dependency and can be used from any asyncio code.
+
+- Fully typed (`py.typed`), `asyncio` + `aiohttp`, Python 3.12+
+- Read thermostats, rooms and installations; set target temperature and operating mode
+- Installation-wide holiday schedules
+- Room energy consumption at hourly … yearly aggregation
+- Pluggable authentication: bundled e-mail/password login, or bring your own OAuth2 tokens
+- Automatic token refresh, single retry on HTTP 401, backoff on HTTP 5xx
+
+## Installation
+
+```bash
+pip install pyfenixcontrol
+```
+
+## Quick start
+
+```python
+import asyncio
+
+import aiohttp
+
+from pyfenixcontrol import FenixControlClient, PasswordAuth, PresetMode
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        auth = PasswordAuth(session, "you@example.com", "password")
+        client = FenixControlClient(auth)
+
+        for device in await client.get_devices():
+            print(device.name, device.room_temperature, device.target_temperature)
+
+        await client.set_target_temperature(device.id, 21.5)
+        await client.set_preset_mode(device.id, PresetMode.PROGRAM)
+
+
+asyncio.run(main())
+```
+
+## Authentication
+
+The client never sees credentials. It asks an `AbstractAuth` for a bearer token:
+
+```python
+from pyfenixcontrol import AbstractAuth
+
+
+class MyAuth(AbstractAuth):
+    async def async_get_access_token(self) -> str:
+        return await my_token_store.get_valid_token()
+
+    async def async_invalidate_access_token(self) -> None:
+        # Called after an HTTP 401; optional.
+        await my_token_store.mark_expired()
+```
+
+`PasswordAuth` performs the OAuth2 authorization-code + PKCE login used by the
+FENIX Control app and keeps tokens in memory. `await auth.async_login()` validates
+credentials up front (e.g. in a setup wizard).
+
+`PasswordAuth` needs an `aiohttp` session with a working cookie jar, because the
+identity server tracks its login form with cookies. Cookies of the identity host
+are cleared before each full login.
+
+## API overview
+
+| Method | Description |
+|---|---|
+| `get_user_id()` | Account subject id (cached on the client) |
+| `get_installations()` | Installations (homes) with their rooms and device ids |
+| `get_devices(installations=None)` | `Device` state of every thermostat |
+| `get_device_properties(device_id)` | Raw device twin properties |
+| `trigger_installation_update(installation_id)` | Ask thermostats to report fresh values |
+| `set_target_temperature(device_id, celsius)` | Set target °C (switches to manual) |
+| `set_preset_mode(device_id, mode)` | `PresetMode.OFF / PROGRAM / MANUAL / DEFROST / BOOST / HOLIDAYS` |
+| `set_holiday_schedule(installation_id, start, end, mode)` | Holiday for the whole installation |
+| `cancel_holiday_schedule(installation_id)` | Remove the holiday schedule |
+| `get_room_energy(installation_id, room_id, start, end, period)` | `EnergyMetric` buckets in Wh |
+
+### Errors
+
+| Exception | Meaning |
+|---|---|
+| `FenixControlAuthError` | Credentials or tokens rejected – user action needed |
+| `FenixControlConnectionError` | Network error or timeout – retry later |
+| `FenixControlResponseError` | Unexpected status or body (`.status` holds the HTTP code) |
+
+All inherit from `FenixControlError`.
+
+### Units and conventions
+
+- Temperatures are °C. The API transports °F × `divFactor`;
+  `decode_temperature()` / `encode_temperature()` convert.
+- Holiday `start`/`end` are wall-clock times of the installation (no time zone
+  conversion). Energy queries convert to UTC; naive datetimes are taken as UTC.
+- Every model keeps the original payload in `.raw` for fields not yet modelled.
+
+## Development
+
+```bash
+uv sync
+uv run pytest --cov
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+Tests run against a local fake of the cloud and identity server; no account is needed.
+
+Releases: bump `__version__`, update `CHANGELOG.md`, publish a GitHub release
+tagged `vX.Y.Z`. The release workflow publishes to PyPI via trusted publishing.
+
+## License
+
+MIT – see [LICENSE](LICENSE). Not an official product of FENIX Trading s.r.o.
+unless stated otherwise in the project metadata.

pyfenixcontrol-0.1.0/README.md

@@ -0,0 +1,119 @@
+# pyfenixcontrol
+
+Asynchronous Python client for the **FENIX Control** cloud, used by FENIX TFT WiFi
+thermostats. It powers the FENIX integration for [Home Assistant](https://www.home-assistant.io/),
+but has no Home Assistant dependency and can be used from any asyncio code.
+
+- Fully typed (`py.typed`), `asyncio` + `aiohttp`, Python 3.12+
+- Read thermostats, rooms and installations; set target temperature and operating mode
+- Installation-wide holiday schedules
+- Room energy consumption at hourly … yearly aggregation
+- Pluggable authentication: bundled e-mail/password login, or bring your own OAuth2 tokens
+- Automatic token refresh, single retry on HTTP 401, backoff on HTTP 5xx
+
+## Installation
+
+```bash
+pip install pyfenixcontrol
+```
+
+## Quick start
+
+```python
+import asyncio
+
+import aiohttp
+
+from pyfenixcontrol import FenixControlClient, PasswordAuth, PresetMode
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        auth = PasswordAuth(session, "you@example.com", "password")
+        client = FenixControlClient(auth)
+
+        for device in await client.get_devices():
+            print(device.name, device.room_temperature, device.target_temperature)
+
+        await client.set_target_temperature(device.id, 21.5)
+        await client.set_preset_mode(device.id, PresetMode.PROGRAM)
+
+
+asyncio.run(main())
+```
+
+## Authentication
+
+The client never sees credentials. It asks an `AbstractAuth` for a bearer token:
+
+```python
+from pyfenixcontrol import AbstractAuth
+
+
+class MyAuth(AbstractAuth):
+    async def async_get_access_token(self) -> str:
+        return await my_token_store.get_valid_token()
+
+    async def async_invalidate_access_token(self) -> None:
+        # Called after an HTTP 401; optional.
+        await my_token_store.mark_expired()
+```
+
+`PasswordAuth` performs the OAuth2 authorization-code + PKCE login used by the
+FENIX Control app and keeps tokens in memory. `await auth.async_login()` validates
+credentials up front (e.g. in a setup wizard).
+
+`PasswordAuth` needs an `aiohttp` session with a working cookie jar, because the
+identity server tracks its login form with cookies. Cookies of the identity host
+are cleared before each full login.
+
+## API overview
+
+| Method | Description |
+|---|---|
+| `get_user_id()` | Account subject id (cached on the client) |
+| `get_installations()` | Installations (homes) with their rooms and device ids |
+| `get_devices(installations=None)` | `Device` state of every thermostat |
+| `get_device_properties(device_id)` | Raw device twin properties |
+| `trigger_installation_update(installation_id)` | Ask thermostats to report fresh values |
+| `set_target_temperature(device_id, celsius)` | Set target °C (switches to manual) |
+| `set_preset_mode(device_id, mode)` | `PresetMode.OFF / PROGRAM / MANUAL / DEFROST / BOOST / HOLIDAYS` |
+| `set_holiday_schedule(installation_id, start, end, mode)` | Holiday for the whole installation |
+| `cancel_holiday_schedule(installation_id)` | Remove the holiday schedule |
+| `get_room_energy(installation_id, room_id, start, end, period)` | `EnergyMetric` buckets in Wh |
+
+### Errors
+
+| Exception | Meaning |
+|---|---|
+| `FenixControlAuthError` | Credentials or tokens rejected – user action needed |
+| `FenixControlConnectionError` | Network error or timeout – retry later |
+| `FenixControlResponseError` | Unexpected status or body (`.status` holds the HTTP code) |
+
+All inherit from `FenixControlError`.
+
+### Units and conventions
+
+- Temperatures are °C. The API transports °F × `divFactor`;
+  `decode_temperature()` / `encode_temperature()` convert.
+- Holiday `start`/`end` are wall-clock times of the installation (no time zone
+  conversion). Energy queries convert to UTC; naive datetimes are taken as UTC.
+- Every model keeps the original payload in `.raw` for fields not yet modelled.
+
+## Development
+
+```bash
+uv sync
+uv run pytest --cov
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+Tests run against a local fake of the cloud and identity server; no account is needed.
+
+Releases: bump `__version__`, update `CHANGELOG.md`, publish a GitHub release
+tagged `vX.Y.Z`. The release workflow publishes to PyPI via trusted publishing.
+
+## License
+
+MIT – see [LICENSE](LICENSE). Not an official product of FENIX Trading s.r.o.
+unless stated otherwise in the project metadata.

pyfenixcontrol-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyfenixcontrol"
+dynamic = ["version"]
+description = "Asynchronous Python client for the FENIX Control cloud API (FENIX TFT WiFi thermostats)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Stanislav Likavčan", email = "likavcan@gmail.com" }]
+keywords = ["fenix", "fenix control", "tft", "thermostat", "home assistant", "asyncio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.9.0"]
+
+[project.urls]
+Homepage = "https://github.com/baracudaz/pyfenixcontrol"
+Source = "https://github.com/baracudaz/pyfenixcontrol"
+Issues = "https://github.com/baracudaz/pyfenixcontrol/issues"
+Changelog = "https://github.com/baracudaz/pyfenixcontrol/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.11",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+]
+
+[tool.hatch.version]
+path = "src/pyfenixcontrol/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pyfenixcontrol", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "--strict-markers"
+
+[tool.coverage.run]
+source = ["pyfenixcontrol"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = ["if TYPE_CHECKING:", "@abstractmethod", "raise NotImplementedError"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unreachable = true
+files = ["src", "tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",  # conflicts with formatter
+    "D203",    # incompatible with D211
+    "D213",    # incompatible with D212
+    "PLR0913", # API methods legitimately take many arguments
+    "CPY001",  # license is declared once in LICENSE
+    "ANN401",  # JSON payloads are genuinely untyped at the API boundary
+    "B027",    # AbstractAuth.async_invalidate_access_token is an optional hook
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "PLR2004", "SLF001", "D", "FBT001", "DTZ001", "TC001", "TC003"]

pyfenixcontrol-0.1.0/src/pyfenixcontrol/__init__.py

@@ -0,0 +1,46 @@
+"""Asynchronous Python client for the FENIX Control cloud API."""
+
+from __future__ import annotations
+
+from .auth import AbstractAuth, PasswordAuth
+from .client import FenixControlClient
+from .const import EnergyPeriod, HolidayMode, HvacState, PresetMode
+from .exceptions import (
+    FenixControlAuthError,
+    FenixControlConnectionError,
+    FenixControlError,
+    FenixControlResponseError,
+)
+from .models import (
+    Device,
+    EnergyMetric,
+    Installation,
+    Room,
+    decode_temperature,
+    encode_temperature,
+    parse_holiday_date,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AbstractAuth",
+    "Device",
+    "EnergyMetric",
+    "EnergyPeriod",
+    "FenixControlAuthError",
+    "FenixControlClient",
+    "FenixControlConnectionError",
+    "FenixControlError",
+    "FenixControlResponseError",
+    "HolidayMode",
+    "HvacState",
+    "Installation",
+    "PasswordAuth",
+    "PresetMode",
+    "Room",
+    "__version__",
+    "decode_temperature",
+    "encode_temperature",
+    "parse_holiday_date",
+]