weishaupt-webif-api 0.1.0__tar.gz

weishaupt_webif_api-0.1.0/LICENSE

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

weishaupt_webif_api-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: weishaupt-webif-api
+Version: 0.1.0
+Summary: Async Python library for the Weishaupt WebIF heat pump interface.
+Author-email: Mad_One <madone85@googlemail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MadOne/weishaupt_webif_api
+Project-URL: Repository, https://github.com/MadOne/weishaupt_webif_api
+Project-URL: Issues, https://github.com/MadOne/weishaupt_webif_api/issues
+Keywords: weishaupt,heatpump,heat-pump,home-assistant,hvac,webif
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24
+Requires-Dist: beautifulsoup4>=4.12
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: respx>=0.20.0; extra == "test"
+Dynamic: license-file
+
+# Weishaupt WebIF API
+
+A Python library for interacting asynchronously with the Weishaupt heating system web interface (WebIF). This library allows you to programmatically retrieve telemetry data and system statistics.
+
+## Features
+
+- **Asynchronous Design**: Built on `httpx` and `asyncio` for non-blocking I/O.
+- **Selective Updates**: Fetch only the categories you need (e.g., "Statistik", "Heizkreis") to minimize load on the device's MCU.
+- **Persistence**: Automatically manages session cookies and internal state (cooldowns, request timing) across restarts using local storage.
+- **Smart Batching**: Includes logic to batch requests safely, preventing resource exhaustion on the hardware interface.
+- **Robust Error Handling**: Detects session expiration, login redirections, and MCU resource errors.
+- **Mock Mode**: Access real-world sample data without polling the device—perfect for developing Home Assistant integrations.
+- **CLI Monitor**: A built-in command-line tool to monitor your heat pump telemetry in real-time.
+
+## Installation
+
+Currently, this library can be installed locally:
+
+```bash
+pip install .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from weishaupt_webif_api import WebifConnection
+
+async def main():
+    # Initialize the connection
+    async with WebifConnection(
+        ip="10.10.1.225", 
+        username="user", 
+        password="pass",
+        storage_path="./data"
+    ) as api:
+        # Fetch specific categories
+        data = await api.update_all(["Statistik", "Heizkreis"])
+
+        # Fetch mockup data for developement puposes. This is no real data and wont change!
+        mcok_data = await api.update_all_mock(["Statistik", "Heizkreis"])
+        
+        for category, values in data.items():
+            print(f"--- {category} ---")
+            for key, value in values.items():
+                print(f"{key}: {value}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+
+
+## Configuration & State
+
+The library creates several files in the `storage_path` to maintain state:
+
+- `lwp_cookies.txt`: Stores session cookies to avoid redundant logins.
+- `lwp_state.json`: Stores internal metadata, such as request cooldown timers.
+- `weishaupt_webif_api.log`: Contains diagnostic logs for troubleshooting.
+
+These files are excluded from version control by default via `.gitignore`.
+
+## Development
+
+### Running Tests
+
+The project uses `pytest` with `pytest-asyncio` and `respx` for mocking API responses.
+
+```bash
+pytest
+```
+
+Tests utilize HTML fixtures located in `tests/fixtures/` to simulate real device responses without requiring access to physical hardware.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Disclaimer
+
+*This project is not affiliated with or endorsed by Weishaupt. Use it at your own risk. Frequent polling can put significant stress on the device's web interface.*

weishaupt_webif_api-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Weishaupt WebIF API
+
+A Python library for interacting asynchronously with the Weishaupt heating system web interface (WebIF). This library allows you to programmatically retrieve telemetry data and system statistics.
+
+## Features
+
+- **Asynchronous Design**: Built on `httpx` and `asyncio` for non-blocking I/O.
+- **Selective Updates**: Fetch only the categories you need (e.g., "Statistik", "Heizkreis") to minimize load on the device's MCU.
+- **Persistence**: Automatically manages session cookies and internal state (cooldowns, request timing) across restarts using local storage.
+- **Smart Batching**: Includes logic to batch requests safely, preventing resource exhaustion on the hardware interface.
+- **Robust Error Handling**: Detects session expiration, login redirections, and MCU resource errors.
+- **Mock Mode**: Access real-world sample data without polling the device—perfect for developing Home Assistant integrations.
+- **CLI Monitor**: A built-in command-line tool to monitor your heat pump telemetry in real-time.
+
+## Installation
+
+Currently, this library can be installed locally:
+
+```bash
+pip install .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from weishaupt_webif_api import WebifConnection
+
+async def main():
+    # Initialize the connection
+    async with WebifConnection(
+        ip="10.10.1.225", 
+        username="user", 
+        password="pass",
+        storage_path="./data"
+    ) as api:
+        # Fetch specific categories
+        data = await api.update_all(["Statistik", "Heizkreis"])
+
+        # Fetch mockup data for developement puposes. This is no real data and wont change!
+        mcok_data = await api.update_all_mock(["Statistik", "Heizkreis"])
+        
+        for category, values in data.items():
+            print(f"--- {category} ---")
+            for key, value in values.items():
+                print(f"{key}: {value}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+
+
+## Configuration & State
+
+The library creates several files in the `storage_path` to maintain state:
+
+- `lwp_cookies.txt`: Stores session cookies to avoid redundant logins.
+- `lwp_state.json`: Stores internal metadata, such as request cooldown timers.
+- `weishaupt_webif_api.log`: Contains diagnostic logs for troubleshooting.
+
+These files are excluded from version control by default via `.gitignore`.
+
+## Development
+
+### Running Tests
+
+The project uses `pytest` with `pytest-asyncio` and `respx` for mocking API responses.
+
+```bash
+pytest
+```
+
+Tests utilize HTML fixtures located in `tests/fixtures/` to simulate real device responses without requiring access to physical hardware.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Disclaimer
+
+*This project is not affiliated with or endorsed by Weishaupt. Use it at your own risk. Frequent polling can put significant stress on the device's web interface.*

weishaupt_webif_api-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "weishaupt-webif-api"
+version = "0.1.0"
+description = "Async Python library for the Weishaupt WebIF heat pump interface."
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    {name = "Mad_One", email = "madone85@googlemail.com"},
+]
+dependencies = [
+    "httpx>=0.24",
+    "beautifulsoup4>=4.12",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+]
+
+keywords = [
+    "weishaupt",
+    "heatpump",
+    "heat-pump",
+    "home-assistant",
+    "hvac",
+    "webif",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21.0",
+    "respx>=0.20.0",
+]
+
+[project.scripts]
+weishaupt-api = "weishaupt_webif_api.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/MadOne/weishaupt_webif_api"
+Repository = "https://github.com/MadOne/weishaupt_webif_api"
+Issues = "https://github.com/MadOne/weishaupt_webif_api/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = "test_*.py"
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+src = ["weishaupt_webif_api", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "ALL"
+]
+
+ignore = [
+    "D203", # one-blank-line-before-class (incompatible with D211)
+    "D213", # multi-line-summary-second-line (incompatible with D212)
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Ignore S101 (assert statements) in all test files
+"tests/**/*.py" = ["S101"]
+
+
+
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true

weishaupt_webif_api-0.1.0/setup.cfg

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

weishaupt_webif_api-0.1.0/src/weishaupt_webif_api/__init__.py

@@ -0,0 +1,24 @@
+"""Asynchronous API for Weishaupt WebIF (Heat Pumps)."""
+
+__version__ = "0.1.0"
+
+from .api import WebifConnection
+from .const import EXPECTED_COUNTS, ColoredFormatter, Info
+from .exceptions import (
+    ConnectionTimeoutError,
+    McuResourceError,
+    SessionExpiredError,
+    WeishauptWebifError,
+)
+
+__all__ = [
+    "EXPECTED_COUNTS",
+    "ColoredFormatter",
+    "ConnectionTimeoutError",
+    "Info",
+    "McuResourceError",
+    "SessionExpiredError",
+    "WebifConnection",
+    "WeishauptWebifError",
+    "__version__",
+]

weishaupt_webif_api-0.1.0/src/weishaupt_webif_api/__main__.py

@@ -0,0 +1,158 @@
+"""Command line interface for the Weishaupt WebIF API."""
+
+import argparse
+import asyncio
+import contextlib
+import logging
+import os
+from pathlib import Path
+
+from .api import WebifConnection
+from .const import ColoredFormatter
+
+
+async def _main(args: argparse.Namespace) -> None:
+    storage_path = Path(args.path) if args.path else Path.cwd()
+
+    # Configure logging for the console
+    logger = logging.getLogger("weishaupt_webif_api")
+    log_level = logging.DEBUG if args.debug else logging.INFO
+    logger.setLevel(log_level)
+
+    # Console Handler (Colored)
+    sh = logging.StreamHandler()
+    sh.setFormatter(ColoredFormatter())
+    logger.addHandler(sh)
+
+    # File Handler (Persistent log)
+    log_file = storage_path / "weishaupt_webif_api.log"
+    fh = logging.FileHandler(str(log_file))
+    fh.setFormatter(
+        logging.Formatter("%(asctime)s [%(levelname)s] %(name)s: %(message)s"),
+    )
+    logger.addHandler(fh)
+
+    logger.info("Starting Weishaupt WebIF API monitor for %s...", args.ip)
+    async with WebifConnection(
+        args.ip,
+        args.user,
+        args.password,
+        request_delay=args.request_delay,
+        cooldown_delay=args.cooldown_delay,
+        storage_path=storage_path,
+    ) as con:
+        try:
+            while True:
+                try:
+                    # Fetch all data
+                    if args.mock:
+                        data = await con.update_all_mock()
+                    else:
+                        data = await con.update_all()
+                    summary = ", ".join(
+                        [f"[{cat}]: {len(vals)}" for cat, vals in data.items()],
+                    )
+                    logger.info(
+                        "Update Success: %s. Next check in %ds.",
+                        summary,
+                        args.interval,
+                    )
+                    await asyncio.sleep(args.interval)
+                except (asyncio.CancelledError, KeyboardInterrupt):
+                    raise
+                except Exception as err:  # noqa: BLE001
+                    logger.error(  # noqa: TRY400
+                        "Update failed: %s. Retrying in %ds...",
+                        err,
+                        args.retry_interval,
+                    )
+                    await asyncio.sleep(args.retry_interval)
+        except (asyncio.CancelledError, KeyboardInterrupt):
+            # Graceful exit on Ctrl+C
+            pass
+        except Exception as err:  # noqa: BLE001
+            logger.critical("Monitor encountered an error: %s", err)
+        finally:
+            logger.info("--- Final Communication Statistics ---")
+            for key, value in con.stats.items():
+                logger.info("%-20s: %s", key, value)
+
+
+def main() -> None:
+    """Sync wrapper for the entry point."""
+    parser = argparse.ArgumentParser(
+        description="Weishaupt WebIF API CLI",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "ip",
+        nargs="?" if os.environ.get("WEISHAUPT_IP") else None,
+        default=os.environ.get("WEISHAUPT_IP"),
+        help="IP address of the Weishaupt module (env: WEISHAUPT_IP)",
+    )
+    parser.add_argument(
+        "user",
+        nargs="?" if os.environ.get("WEISHAUPT_USER") else None,
+        default=os.environ.get("WEISHAUPT_USER"),
+        help="Login username (env: WEISHAUPT_USER)",
+    )
+    parser.add_argument(
+        "password",
+        nargs="?" if os.environ.get("WEISHAUPT_PASSWORD") else None,
+        default=os.environ.get("WEISHAUPT_PASSWORD"),
+        help="Login password (env: WEISHAUPT_PASSWORD)",
+    )
+    parser.add_argument(
+        "--path",
+        help="Directory to store logs and state files (defaults to execution folder)",
+        default=None,
+    )
+    parser.add_argument(
+        "--interval",
+        type=int,
+        help="Polling interval in seconds (default: 300)",
+        default=300,
+    )
+    parser.add_argument(
+        "--retry-interval",
+        type=int,
+        help="Retry interval after failure in seconds",
+        default=60,
+    )
+    parser.add_argument(
+        "--request-delay",
+        type=float,
+        help="Internal breather delay between requests in seconds",
+        default=60.0,
+    )
+    parser.add_argument(
+        "--cooldown-delay",
+        type=float,
+        help="Internal cooldown penalty after failure in seconds",
+        default=300.0,
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    parser.add_argument(
+        "--mock",
+        action="store_true",
+        help="Use mock data for development without polling the device",
+    )
+
+    args = parser.parse_args()
+
+    if not all([args.ip, args.user, args.password]):
+        parser.error(
+            "IP, user, and password must be provided via arguments or "
+            "environment variables.",
+        )
+
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(_main(args))
+
+
+if __name__ == "__main__":
+    main()