smartbox 2.7.0__tar.gz → 3.0.0__tar.gz

{smartbox-2.7.0 → smartbox-3.0.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 3.0.0
+
+First stable release of the standalone protocol/core library used by the 3.x
+Home Assistant integration.
+
+### Breaking
+
+* The 2.7 session/update-manager API is replaced by `smartbox.protocol`
+  (`SmartboxClient`, auth, `ws_user` transport, named writes) and
+  `smartbox.core` (`SmartboxEngine`, state, deadlines, feed).
+* The library is Home Assistant-free by construction; the integration depends
+  on it instead of vendoring the layers.
+* The CLI now uses the new client and `ws_user` transport. The old per-device
+  `socket` command is replaced by `listen`; `set-setup` exposes the granular
+  setup writes; boost and node power-limit commands are added.
+
+### New
+
+* The CLI remains available as the optional `cli` extra:
+  `pip install "smartbox[cli] ..."`.
+* `SmartboxClient.get_home_guests()` and the CLI `guests` command.
+* `WriteApi.set_setup_value()` as the CLI/debug escape hatch for setup keys
+  without a named setter.
+
+See GitHub release notes: https://github.com/jandado/smartbox/releases
+
 ## 2.7.0
 
 ### New

smartbox-3.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: smartbox
+Version: 3.0.0
+Summary: Python API to control heating 'smart boxes'
+Project-URL: Homepage, https://github.com/jandado/smartbox
+Project-URL: Issues, https://github.com/jandado/smartbox/issues
+Project-URL: Upstream, https://github.com/ajtudela/smartbox
+Author-email: Alberto Tudela <ajtudela@gmail.com>, Delmael <delmael@outlook.com>, graham33 <graham@grahambennett.org>
+Maintainer: Jan Dado
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.14.2
+Requires-Dist: aiohttp<4,>=3
+Provides-Extra: cli
+Requires-Dist: asyncclick; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# smartbox 3.0
+
+Python library for Smartbox heating systems (Helki and its resellers: Elnur,
+Haverland, Climastar, Technotherm, HJM, …).
+
+This is the 3.0 rewrite. It exposes the protocol and domain layers that the
+Home Assistant integration uses, without importing Home Assistant. The 2.7
+API remains available on the `main` branch and the `v2.7.0` tag.
+
+## Install
+
+From the tagged source:
+
+```sh
+pip install "smartbox @ https://github.com/jandado/smartbox/archive/refs/tags/v3.0.0.tar.gz"
+```
+
+With the optional command line tool:
+
+```sh
+pip install "smartbox[cli] @ https://github.com/jandado/smartbox/archive/refs/tags/v3.0.0.tar.gz"
+```
+
+For development:
+
+```sh
+uv sync --all-extras --dev
+```
+
+## Library
+
+`SmartboxClient` owns the REST API and the token lifecycle. `smartbox.core`
+contains the Home Assistant-free state engine, write confirmation and feed
+supervision.
+
+```python
+import asyncio
+
+from smartbox.core import SmartboxEngine
+from smartbox.protocol import API_HOST, AuthConfig, ManagedTokenSource, SmartboxClient
+
+CONFIG = AuthConfig(
+    api_host=API_HOST,
+    basic_auth_creds="<reseller Basic auth>",
+    serial_id="1",
+    username="you@example.com",
+    password="secret",
+    referer="https://app.helki.com/",
+)
+
+async def main() -> None:
+    client = SmartboxClient(CONFIG)
+    try:
+        print(await client.get_devices())
+    finally:
+        await client.close()
+```
+
+The lower layers are Home Assistant-free and are tested without the HA test
+harness.
+
+## CLI
+
+The CLI is an optional extra; the base package only depends on `aiohttp`.
+
+Authentication options are `-a/--api-name`, `-b/--basic-auth-creds`,
+`-u/--username`, `-p/--password`, `-r/--x-referer`, `-i/--x-serial-id`.
+They also resolve from `SMARTBOX_*` environment variables, and the script
+loads the nearest `.env` file. Command line values win over the environment,
+which wins over `.env`.
+
+```sh
+smartbox -a api -u you@example.com -p secret devices
+smartbox -a api -u you@example.com -p secret nodes
+smartbox -a api -u you@example.com -p secret status
+smartbox -a api -u you@example.com -p secret set-status -d DEV -n 0 --mode auto
+smartbox -a api -u you@example.com -p secret set-boost-mode -d DEV -n 0 \
+  --active --mode runback --temperature 21 --time-minutes 60
+smartbox -a api -u you@example.com -p secret listen
+```
+
+`smartbox --help` lists every command. Reads print the raw wire payloads;
+writes print the posted path and body. `listen` follows the shared `ws_user`
+feed and can filter updates with `--device-id`.
+
+## Layout
+
+- `smartbox.protocol` — auth, REST client, `ws_user` transport, wire values
+  and named writes.
+- `smartbox.core` — versioned state store, merges, write confirmation,
+  deadlines and feed supervision.
+- `smartbox.cli` — the optional debugging CLI.
+
+The canonical wire record lives in the sibling `hass-smartbox` repository
+under `docs/` (`api-contract.md`, `api-ws-user.md`, `webapi-spec.md`);
+`webapi-spec.md` in this repo is a pointer.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+uv run tox
+```
+
+## Credits
+
+The original library and the 2.7.x line are by Alberto Tudela, Delmael,
+graham33 and the upstream contributors. This fork carries the 3.0 rewrite;
+upstream collaboration is welcome.

smartbox-3.0.0/README.md

@@ -0,0 +1,111 @@
+# smartbox 3.0
+
+Python library for Smartbox heating systems (Helki and its resellers: Elnur,
+Haverland, Climastar, Technotherm, HJM, …).
+
+This is the 3.0 rewrite. It exposes the protocol and domain layers that the
+Home Assistant integration uses, without importing Home Assistant. The 2.7
+API remains available on the `main` branch and the `v2.7.0` tag.
+
+## Install
+
+From the tagged source:
+
+```sh
+pip install "smartbox @ https://github.com/jandado/smartbox/archive/refs/tags/v3.0.0.tar.gz"
+```
+
+With the optional command line tool:
+
+```sh
+pip install "smartbox[cli] @ https://github.com/jandado/smartbox/archive/refs/tags/v3.0.0.tar.gz"
+```
+
+For development:
+
+```sh
+uv sync --all-extras --dev
+```
+
+## Library
+
+`SmartboxClient` owns the REST API and the token lifecycle. `smartbox.core`
+contains the Home Assistant-free state engine, write confirmation and feed
+supervision.
+
+```python
+import asyncio
+
+from smartbox.core import SmartboxEngine
+from smartbox.protocol import API_HOST, AuthConfig, ManagedTokenSource, SmartboxClient
+
+CONFIG = AuthConfig(
+    api_host=API_HOST,
+    basic_auth_creds="<reseller Basic auth>",
+    serial_id="1",
+    username="you@example.com",
+    password="secret",
+    referer="https://app.helki.com/",
+)
+
+async def main() -> None:
+    client = SmartboxClient(CONFIG)
+    try:
+        print(await client.get_devices())
+    finally:
+        await client.close()
+```
+
+The lower layers are Home Assistant-free and are tested without the HA test
+harness.
+
+## CLI
+
+The CLI is an optional extra; the base package only depends on `aiohttp`.
+
+Authentication options are `-a/--api-name`, `-b/--basic-auth-creds`,
+`-u/--username`, `-p/--password`, `-r/--x-referer`, `-i/--x-serial-id`.
+They also resolve from `SMARTBOX_*` environment variables, and the script
+loads the nearest `.env` file. Command line values win over the environment,
+which wins over `.env`.
+
+```sh
+smartbox -a api -u you@example.com -p secret devices
+smartbox -a api -u you@example.com -p secret nodes
+smartbox -a api -u you@example.com -p secret status
+smartbox -a api -u you@example.com -p secret set-status -d DEV -n 0 --mode auto
+smartbox -a api -u you@example.com -p secret set-boost-mode -d DEV -n 0 \
+  --active --mode runback --temperature 21 --time-minutes 60
+smartbox -a api -u you@example.com -p secret listen
+```
+
+`smartbox --help` lists every command. Reads print the raw wire payloads;
+writes print the posted path and body. `listen` follows the shared `ws_user`
+feed and can filter updates with `--device-id`.
+
+## Layout
+
+- `smartbox.protocol` — auth, REST client, `ws_user` transport, wire values
+  and named writes.
+- `smartbox.core` — versioned state store, merges, write confirmation,
+  deadlines and feed supervision.
+- `smartbox.cli` — the optional debugging CLI.
+
+The canonical wire record lives in the sibling `hass-smartbox` repository
+under `docs/` (`api-contract.md`, `api-ws-user.md`, `webapi-spec.md`);
+`webapi-spec.md` in this repo is a pointer.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+uv run tox
+```
+
+## Credits
+
+The original library and the 2.7.x line are by Alberto Tudela, Delmael,
+graham33 and the upstream contributors. This fork carries the 3.0 rewrite;
+upstream collaboration is welcome.

{smartbox-2.7.0 → smartbox-3.0.0}/pyproject.toml

@@ -1,12 +1,15 @@
 [project]
 name = "smartbox"
-version = "2.7.0"
+version = "3.0.0"
 requires-python = ">=3.14.2"
 authors = [
   { name="Alberto Tudela", email="ajtudela@gmail.com" },
   { name="Delmael", email="delmael@outlook.com" },
   { name="graham33", email="graham@grahambennett.org" },
 ]
+maintainers = [
+  { name="Jan Dado" },
+]
 description = "Python API to control heating 'smart boxes'"
 readme = "README.md"
 
@@ -19,38 +22,44 @@ license = "MIT"
 license-files = ["LICEN[CS]E*"]
 dependencies = [
     "aiohttp>=3,<4",
-    "asyncclick",
-    "jq",
-    "pydantic>=2,<3",
-    "python-socketio>=5,<6",
 ]
 
-[project.urls]
-Homepage = "https://github.com/ajtudela/smartbox"
-Issues = "https://github.com/ajtudela/smartbox/issues"
+[project.optional-dependencies]
+cli = ["asyncclick"]
 
 [project.scripts]
-smartbox = "smartbox.cmd:cli"
+smartbox = "smartbox.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/jandado/smartbox"
+Issues = "https://github.com/jandado/smartbox/issues"
+Upstream = "https://github.com/ajtudela/smartbox"
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/smartbox",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+  "/CHANGELOG.md",
+]
+
 
 [dependency-groups]
 dev = [
-    "pre-commit",
-    "freezegun",
+    "asyncclick",
+    "multidict",
     "pytest",
     "pytest-asyncio",
     "pytest-cov",
-    "pytest-mock",
-    "pytest-randomly",
-    "requests-mock",
-    "tox",
     "ruff",
     "mypy",
-    "time-machine",
+    "tox",
+    "yarl",
 ]
 
 [tool.pytest.ini_options]
@@ -61,6 +70,11 @@ markers = [
     "network: tests that make real HTTP calls to reseller servers (deselected by default; run with -m network)",
 ]
 
+[tool.coverage.run]
+# The CLI is an optional extra; it is exercised manually against the live API
+# and by the `--help`/reseller smoke tests, not by the core coverage gate.
+omit = ["src/smartbox/cli.py"]
+
 [tool.coverage.report]
 fail_under = 95
 exclude_also = ["if __name__ == .__main__.:"]
@@ -69,18 +83,14 @@ exclude_also = ["if __name__ == .__main__.:"]
 warn_unused_configs = true
 
 [[tool.mypy.overrides]]
-module = [
-    "jq",
-    "socketio",
-    "asyncio",
-]
+module = ["asyncio"]
 ignore_missing_imports = true
 disable_error_code = ["arg-type"]
 
 [tool.ruff]
 target-version = "py314"
 fix = true
-line-length = 80
+line-length = 88
 extend-exclude = ["tools"]
 
 [tool.ruff.lint]
@@ -140,8 +150,17 @@ max-complexity = 25
     "S106",
     "PLR2004",
     "B018",
+    "PT011",
+]
+"src/smartbox/cli.py" = [
+    "ANN401",
+    "D10",
+    "EM101",
+    "EM102",
+    "PLR2004",
+    "TRY003",
 ]
-"src/smartbox/cmd.py" = ["T201", "ANN001"]
+"src/smartbox/core/**" = ["TID252"]
 "tools/*" = ["T201", "ANN401", "INP001", "PLR0911", "PLR0915", "S108", "ASYNC240"]
 
 

smartbox-3.0.0/src/smartbox/__init__.py

@@ -0,0 +1,17 @@
+"""Smartbox protocol and domain layers.
+
+The package is Home Assistant-agnostic: ``smartbox.protocol`` owns the
+wire and the ``smartbox.core`` package owns the domain state. Both are
+usable without the HA test harness.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from . import core, protocol
+
+try:
+    __version__ = version("smartbox")
+except PackageNotFoundError:  # pragma: no cover - vendored/undist import
+    __version__ = "0.0.0"
+
+__all__ = ["__version__", "core", "protocol"]