aiomelcloudhome 0.1.0__tar.gz

aiomelcloudhome-0.1.0/.gitignore

@@ -0,0 +1,83 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# Visual Studio Code
+.vscode
+
+# ruff
+.ruff_cache
+
+# Pyre type checker
+.pyre/
+
+setup.py
+.python-version
+
+# Examples
+examples/example_dev.py

aiomelcloudhome-0.1.0/LICENSE

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

aiomelcloudhome-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: aiomelcloudhome
+Version: 0.1.0
+Summary: Asynchronous Python client for the Melcloud Home API
+Project-URL: Homepage, https://github.com/erwindouna/aiomelcloudhome
+Project-URL: Repository, https://github.com/erwindouna/aiomelcloudhome
+Project-URL: Documentation, https://github.com/erwindouna/aiomelcloudhome
+Project-URL: Bug Tracker, https://github.com/erwindouna/aiomelcloudhome/issues
+Project-URL: Changelog, https://github.com/erwindouna/aiomelcloudhome/releases
+Author-email: Erwin Douna <e.douna@gmail.com>
+Maintainer-email: Erwin Douna <e.douna@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,async,client,heat-pump,hvac,melcloud,melcloudhome
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4,>=3.11
+Requires-Dist: aiohttp>=3.0.0
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: tenacity>=8.0.0
+Requires-Dist: yarl>=1.6.0
+Description-Content-Type: text/markdown
+
+# aiomelcloudhome
+
+[![GitHub Release][releases-shield]][releases]
+[![Python Versions][python-versions-shield]][pypi]
+![Project Stage][project-stage-shield]
+![Project Maintenance][maintenance-shield]
+[![License][license-shield]](LICENSE)
+
+[![GitHub Activity][commits-shield]][commits-url]
+[![PyPI Downloads][downloads-shield]][downloads-url]
+[![GitHub Last Commit][last-commit-shield]][commits-url]
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+[![Build Status][build-shield]][build-url]
+[![Typing Status][typing-shield]][typing-url]
+[![Code Coverage][codecov-shield]][codecov-url]
+
+Asynchronous Python client for MELCloud Home.
+
+## About
+
+aiomelcloudhome is an async client for the MELCloud Home API, focused on:
+
+- Fetching account context (buildings and devices)
+- Controlling Air-to-Air units
+- Controlling Air-to-Water units
+- Reading telemetry (energy and actual measurements)
+
+The library is under active development and endpoint coverage will keep expanding.
+
+## Installation
+
+~~~bash
+pip install aiomelcloudhome
+~~~
+
+## Usage
+
+### Authenticate with username and password
+
+~~~python
+import asyncio
+
+from aiohttp import ClientSession
+
+from aiomelcloudhome import MELCloudHome
+
+
+async def main() -> None:
+    async with ClientSession() as session:
+        async with MELCloudHome(
+            username="your@email.com",
+            password="your_password",
+            session=session,
+        ) as client:
+            context = await client.get_context()
+
+            for building in context.buildings:
+                print(f"Building: {building.name}")
+
+                for unit in building.air_to_air_units:
+                    print(f"ATA: {unit.name} (room: {unit.room_temperature} C)")
+
+                for unit in building.air_to_water_units:
+                    print(f"ATW: {unit.name} (tank: {unit.tank_water_temperature} C)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+~~~
+
+### Authenticate with an existing access token
+
+~~~python
+from aiomelcloudhome import MELCloudHome
+
+
+client = MELCloudHome(access_token="YOUR_ACCESS_TOKEN")
+~~~
+
+### Control an Air-to-Air unit
+
+~~~python
+from aiomelcloudhome import ATAFanSpeed, ATAOperationMode, MELCloudHome
+
+
+await client.control_ata_unit(
+    "ata-unit-id",
+    power=True,
+    operation_mode=ATAOperationMode.HEAT,
+    set_temperature=21.0,
+    set_fan_speed=ATAFanSpeed.AUTO,
+)
+~~~
+
+### Control an Air-to-Water unit
+
+~~~python
+from aiomelcloudhome import ATWZoneMode
+
+
+await client.control_atw_unit(
+    "atw-unit-id",
+    power=True,
+    operation_mode_zone1=ATWZoneMode.HEAT_ROOM_TEMPERATURE,
+    set_temperature_zone1=21.0,
+    set_tank_water_temperature=50.0,
+)
+~~~
+
+### Fetch telemetry
+
+~~~python
+from datetime import UTC, datetime, timedelta
+
+
+energy = await client.get_energy_telemetry(
+    "unit-id",
+    from_dt=datetime.now(UTC) - timedelta(days=1),
+    to_dt=datetime.now(UTC),
+)
+
+outdoor = await client.get_outdoor_temperature("ata-unit-id")
+~~~
+
+More examples can be found in the examples directory.
+
+## Documentation
+
+Project documentation and API reference:
+https://github.com/erwindouna/aiomelcloudhome
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request.
+
+For local development:
+
+~~~bash
+uv sync --all-groups && uv run pre-commit install
+~~~
+
+Run checks:
+
+~~~bash
+uv run pre-commit run --all-files
+~~~
+
+Run tests:
+
+~~~bash
+uv run pytest
+~~~
+
+Update snapshot tests:
+
+~~~bash
+uv run pytest --snapshot-update
+~~~
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Erwin Douna
+
+<!-- MARKDOWN LINKS & IMAGES -->
+
+[build-shield]: https://github.com/erwindouna/aiomelcloudhome/actions/workflows/tests.yaml/badge.svg
+[build-url]: https://github.com/erwindouna/aiomelcloudhome/actions/workflows/tests.yaml
+[codecov-shield]: https://codecov.io/gh/erwindouna/aiomelcloudhome/branch/main/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/erwindouna/aiomelcloudhome
+[commits-shield]: https://img.shields.io/github/commit-activity/y/erwindouna/aiomelcloudhome.svg
+[commits-url]: https://github.com/erwindouna/aiomelcloudhome/commits/main
+[devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
+[devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/erwindouna/aiomelcloudhome
+[downloads-shield]: https://img.shields.io/pypi/dm/aiomelcloudhome
+[downloads-url]: https://pypistats.org/packages/aiomelcloudhome
+[last-commit-shield]: https://img.shields.io/github/last-commit/erwindouna/aiomelcloudhome.svg
+[license-shield]: https://img.shields.io/github/license/erwindouna/aiomelcloudhome.svg
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg
+[pypi]: https://pypi.org/project/aiomelcloudhome/
+[python-versions-shield]: https://img.shields.io/pypi/pyversions/aiomelcloudhome
+[releases-shield]: https://img.shields.io/github/release/erwindouna/aiomelcloudhome.svg
+[releases]: https://github.com/erwindouna/aiomelcloudhome/releases
+[typing-shield]: https://github.com/erwindouna/aiomelcloudhome/actions/workflows/typing.yaml/badge.svg
+[typing-url]: https://github.com/erwindouna/aiomelcloudhome/actions/workflows/typing.yaml

aiomelcloudhome-0.1.0/README.md

@@ -0,0 +1,188 @@
+# aiomelcloudhome
+
+[![GitHub Release][releases-shield]][releases]
+[![Python Versions][python-versions-shield]][pypi]
+![Project Stage][project-stage-shield]
+![Project Maintenance][maintenance-shield]
+[![License][license-shield]](LICENSE)
+
+[![GitHub Activity][commits-shield]][commits-url]
+[![PyPI Downloads][downloads-shield]][downloads-url]
+[![GitHub Last Commit][last-commit-shield]][commits-url]
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+[![Build Status][build-shield]][build-url]
+[![Typing Status][typing-shield]][typing-url]
+[![Code Coverage][codecov-shield]][codecov-url]
+
+Asynchronous Python client for MELCloud Home.
+
+## About
+
+aiomelcloudhome is an async client for the MELCloud Home API, focused on:
+
+- Fetching account context (buildings and devices)
+- Controlling Air-to-Air units
+- Controlling Air-to-Water units
+- Reading telemetry (energy and actual measurements)
+
+The library is under active development and endpoint coverage will keep expanding.
+
+## Installation
+
+~~~bash
+pip install aiomelcloudhome
+~~~
+
+## Usage
+
+### Authenticate with username and password
+
+~~~python
+import asyncio
+
+from aiohttp import ClientSession
+
+from aiomelcloudhome import MELCloudHome
+
+
+async def main() -> None:
+    async with ClientSession() as session:
+        async with MELCloudHome(
+            username="your@email.com",
+            password="your_password",
+            session=session,
+        ) as client:
+            context = await client.get_context()
+
+            for building in context.buildings:
+                print(f"Building: {building.name}")
+
+                for unit in building.air_to_air_units:
+                    print(f"ATA: {unit.name} (room: {unit.room_temperature} C)")
+
+                for unit in building.air_to_water_units:
+                    print(f"ATW: {unit.name} (tank: {unit.tank_water_temperature} C)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+~~~
+
+### Authenticate with an existing access token
+
+~~~python
+from aiomelcloudhome import MELCloudHome
+
+
+client = MELCloudHome(access_token="YOUR_ACCESS_TOKEN")
+~~~
+
+### Control an Air-to-Air unit
+
+~~~python
+from aiomelcloudhome import ATAFanSpeed, ATAOperationMode, MELCloudHome
+
+
+await client.control_ata_unit(
+    "ata-unit-id",
+    power=True,
+    operation_mode=ATAOperationMode.HEAT,
+    set_temperature=21.0,
+    set_fan_speed=ATAFanSpeed.AUTO,
+)
+~~~
+
+### Control an Air-to-Water unit
+
+~~~python
+from aiomelcloudhome import ATWZoneMode
+
+
+await client.control_atw_unit(
+    "atw-unit-id",
+    power=True,
+    operation_mode_zone1=ATWZoneMode.HEAT_ROOM_TEMPERATURE,
+    set_temperature_zone1=21.0,
+    set_tank_water_temperature=50.0,
+)
+~~~
+
+### Fetch telemetry
+
+~~~python
+from datetime import UTC, datetime, timedelta
+
+
+energy = await client.get_energy_telemetry(
+    "unit-id",
+    from_dt=datetime.now(UTC) - timedelta(days=1),
+    to_dt=datetime.now(UTC),
+)
+
+outdoor = await client.get_outdoor_temperature("ata-unit-id")
+~~~
+
+More examples can be found in the examples directory.
+
+## Documentation
+
+Project documentation and API reference:
+https://github.com/erwindouna/aiomelcloudhome
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request.
+
+For local development:
+
+~~~bash
+uv sync --all-groups && uv run pre-commit install
+~~~
+
+Run checks:
+
+~~~bash
+uv run pre-commit run --all-files
+~~~
+
+Run tests:
+
+~~~bash
+uv run pytest
+~~~
+
+Update snapshot tests:
+
+~~~bash
+uv run pytest --snapshot-update
+~~~
+
+## License
+
+MIT License
+
+Copyright (c) 2026 Erwin Douna
+
+<!-- MARKDOWN LINKS & IMAGES -->
+
+[build-shield]: https://github.com/erwindouna/aiomelcloudhome/actions/workflows/tests.yaml/badge.svg
+[build-url]: https://github.com/erwindouna/aiomelcloudhome/actions/workflows/tests.yaml
+[codecov-shield]: https://codecov.io/gh/erwindouna/aiomelcloudhome/branch/main/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/erwindouna/aiomelcloudhome
+[commits-shield]: https://img.shields.io/github/commit-activity/y/erwindouna/aiomelcloudhome.svg
+[commits-url]: https://github.com/erwindouna/aiomelcloudhome/commits/main
+[devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
+[devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/erwindouna/aiomelcloudhome
+[downloads-shield]: https://img.shields.io/pypi/dm/aiomelcloudhome
+[downloads-url]: https://pypistats.org/packages/aiomelcloudhome
+[last-commit-shield]: https://img.shields.io/github/last-commit/erwindouna/aiomelcloudhome.svg
+[license-shield]: https://img.shields.io/github/license/erwindouna/aiomelcloudhome.svg
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg
+[pypi]: https://pypi.org/project/aiomelcloudhome/
+[python-versions-shield]: https://img.shields.io/pypi/pyversions/aiomelcloudhome
+[releases-shield]: https://img.shields.io/github/release/erwindouna/aiomelcloudhome.svg
+[releases]: https://github.com/erwindouna/aiomelcloudhome/releases
+[typing-shield]: https://github.com/erwindouna/aiomelcloudhome/actions/workflows/typing.yaml/badge.svg
+[typing-url]: https://github.com/erwindouna/aiomelcloudhome/actions/workflows/typing.yaml

aiomelcloudhome-0.1.0/pyproject.toml

@@ -0,0 +1,178 @@
+[project]
+name = "aiomelcloudhome"
+version = "0.1.0"
+description = "Asynchronous Python client for the Melcloud Home API"
+authors = [{ name = "Erwin Douna", email = "e.douna@gmail.com" }]
+requires-python = ">=3.11,<4"
+readme = "README.md"
+license = "MIT"
+maintainers = [{ name = "Erwin Douna", email = "e.douna@gmail.com" }]
+keywords = [
+    "melcloud",
+    "melcloudhome",
+    "hvac",
+    "heat-pump",
+    "async",
+    "api",
+    "client",
+]
+classifiers = [
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "aiohttp>=3.0.0",
+    "yarl>=1.6.0",
+    "pydantic>=2.0,<3",
+    "tenacity>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/erwindouna/aiomelcloudhome"
+Repository = "https://github.com/erwindouna/aiomelcloudhome"
+Documentation = "https://github.com/erwindouna/aiomelcloudhome"
+"Bug Tracker" = "https://github.com/erwindouna/aiomelcloudhome/issues"
+Changelog = "https://github.com/erwindouna/aiomelcloudhome/releases"
+
+[dependency-groups]
+dev = [
+    "aresponses==3.0.0",
+    "freezegun==1.5.5",
+    "codespell==2.4.2",
+    "covdefaults==2.3.0",
+    "coverage[toml]==7.14.1",
+    "mypy==2.1.0",
+    "pre-commit==4.6.0",
+    "pre-commit-hooks==6.0.0",
+    "pylint==4.0.5",
+    "pytest==9.0.3",
+    "pytest-asyncio==1.4.0",
+    "pytest-cov==7.1.0",
+    "ruff==0.15.15",
+    "syrupy==5.3.1",
+    "yamllint==1.38.0",
+]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocstrings[python]>=0.30.1,<1.1.0",
+    "mkdocs-material>=9.6.22,<10",
+]
+
+[tool.uv]
+default-groups = [
+    "dev",
+    "docs",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/aiomelcloudhome"]
+
+[tool.hatch.build.targets.wheel]
+include = ["src/aiomelcloudhome"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/aiomelcloudhome" = "aiomelcloudhome"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["aiomelcloudhome"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.mypy]
+platform = "linux"
+python_version = "3.11"
+show_column_numbers = true
+follow_imports = "normal"
+ignore_missing_imports = true
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+no_implicit_reexport = true
+strict_optional = true
+warn_incomplete_stub = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+[tool.pylint.MASTER]
+ignore-paths = ["^tests/.*$"]
+
+[tool.pylint.BASIC]
+good-names = ["_", "ex", "fp", "i", "id", "j", "k", "on", "Run", "T"]
+
+[tool.pylint."MESSAGES CONTROL"]
+disable = [
+    "duplicate-code",
+    "format",
+    "unsubscriptable-object",
+    "too-many-public-methods",
+]
+
+[tool.pylint.SIMILARITIES]
+ignore-imports = true
+
+[tool.pylint.FORMAT]
+max-line-length = 88
+
+[tool.pylint.DESIGN]
+max-attributes = 20
+
+[tool.pytest.ini_options]
+addopts = "--cov"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+lint.select = ["ALL"]
+lint.ignore = [
+    "ANN401",
+    "D203",
+    "D213",
+    "D417",
+    "PLR2004",
+    "SLOT000",
+    "PLR0913",
+    "PLR0912",
+    "COM812",
+    "ISC001",
+    "TRY003",
+    "TRY301",
+    "EM101",
+    "EM102",
+]
+line-length = 150
+
+[tool.ruff.lint.flake8-pytest-style]
+mark-parentheses = false
+fixture-parentheses = false
+
+[tool.ruff.lint.isort]
+known-first-party = ["aiomelcloudhome"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 25
+
+[tool.ruff.lint.per-file-ignores]
+"src/aiomelcloudhome/aiomelcloudhome.py" = ["ASYNC109"]
+"tests/**/*.py" = ["S101", "S105", "S106", "S108", "DTZ001", "DTZ006", "PLC0415", "ARG001", "ARG002", "TC001", "TC002", "TC003", "SIM117", "SLF001"]
+"examples/**/*.py" = ["T201", "S106", "INP001"]