aiopapouch 0.1.0__tar.gz

aiopapouch-0.1.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.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
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

aiopapouch-0.1.0/LICENSE

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

aiopapouch-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.5
+Name: aiopapouch
+Version: 0.1.0
+Summary: API client and device models for Papouch's devices
+Project-URL: Source, https://github.com/VladislavLevitskii/aiopapouch
+Author-email: VladislavLevitskii <vladlevitskii@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.0.0
+Requires-Dist: defusedxml>=0.7.1
+Description-Content-Type: text/markdown
+
+# aiopapouch
+The repository contains I/O Python library for Papouch s.r.o. devices.
+
+# TODO structure and big picture

aiopapouch-0.1.0/README.md

@@ -0,0 +1,4 @@
+# aiopapouch
+The repository contains I/O Python library for Papouch s.r.o. devices.
+
+# TODO structure and big picture

aiopapouch-0.1.0/aiopapouch/__init__.py

@@ -0,0 +1,12 @@
+"""This file is used as a hub for imports."""
+
+from .client import PapouchHTTPClient, PapouchTransport
+from .devices import PapouchDevice, create_device, is_device_supported
+
+__all__ = [
+    "PapouchDevice",
+    "PapouchHTTPClient",
+    "PapouchTransport",
+    "create_device",
+    "is_device_supported",
+]

aiopapouch-0.1.0/aiopapouch/client.py

@@ -0,0 +1,240 @@
+"""This file is used for communicating with the device."""
+
+from abc import ABC, abstractmethod
+import logging
+import re
+from typing import Any, override
+
+import aiohttp
+import defusedxml.ElementTree as defused_ET
+
+from homeassistant.helpers.device_registry import format_mac
+
+from .exceptions import DeviceAuthError, DeviceConnectionError, DeviceLogicError
+
+INFO_URL = "is.xml"
+DATA_URL = "fresh.xml"
+SETTINGS_URL = "settings.xml"
+SET_URL = "set.xml"
+SAVE_URL = "save.xml"
+
+ENCODING = "iso-8859-2"
+WEB_MODE_INDEX = 3
+TIMEOUT_REQUEST = 10
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class PapouchTransport(ABC):
+    """Abstract base class for all Papouch communication methods."""
+
+    @abstractmethod
+    async def fetch_info(self) -> str:
+        """Fetch the device identification data."""
+
+    @abstractmethod
+    async def fetch_settings(self) -> str:
+        """Fetch the device configuration."""
+
+    @abstractmethod
+    async def fetch_data(self) -> str:
+        """Fetch the latest sensor readings."""
+
+    @abstractmethod
+    async def read_command(
+        self, params: dict, context: str, endpoint: str = SET_URL
+    ) -> str:
+        """Command for communicating with any device by using GET request.
+
+        Parameters are GET queries that will be added to the request.
+        Context string is used for error message
+        and it will be populated with a device information.
+        """
+
+    @abstractmethod
+    async def write_command(
+        self, payload: str, context: str, endpoint: str = SAVE_URL
+    ) -> str:
+        """Send a complex payload (like XML settings).
+
+        Context string is used for error message
+        and it will be populated with a device information.
+        """
+
+    @abstractmethod
+    async def get_device_info(self) -> tuple[str | None, str | None]:
+        """Return name and location of the device."""
+
+    @abstractmethod
+    async def get_device_mac(self) -> str:
+        """Return MAC of the device."""
+
+    @property
+    @abstractmethod
+    def protocol(self) -> str:
+        """Return type of the protocol to communicate with a device."""
+
+
+class PapouchHTTPClient(PapouchTransport):
+    """API client for communicating with a device."""
+
+    def __init__(
+        self, ip_address: str, session: aiohttp.ClientSession, password: str = ""
+    ) -> None:
+        """Constructor for API client."""
+        self.base_url = f"http://{ip_address}/"
+        self.session = session
+        self.ip_address = ip_address
+
+        if password != "":
+            self._auth = aiohttp.BasicAuth("admin", password)
+        else:
+            self._auth = aiohttp.BasicAuth("", "")
+
+    @property
+    @override
+    def protocol(self) -> str:
+        return "http"
+
+    async def _fetch(self, endpoint: str) -> str:
+        raw_xml = await self._send_request("GET", endpoint, context=endpoint)
+        return re.sub(r'\s+xmlns="[^"]+"', "", raw_xml)
+
+    @override
+    async def fetch_info(self) -> str:
+        """Fetching information about a device."""
+        return await self._fetch(INFO_URL)
+
+    @override
+    async def fetch_data(self) -> str:
+        """Fetching data about a device."""
+        return await self._fetch(DATA_URL)
+
+    @override
+    async def fetch_settings(self) -> str:
+        """Fetching settings about a device."""
+        return await self._fetch(SETTINGS_URL)
+
+    @override
+    async def get_device_info(self) -> tuple[str | None, str | None]:
+        info = await self.fetch_info()
+
+        try:
+            root = defused_ET.fromstring(info)
+        except defused_ET.ParseError:
+            return (None, None)
+
+        heartbeat = None
+        for element in root.iter():
+            if element.tag.endswith("heartbeat"):
+                heartbeat = element
+                break
+
+        if heartbeat is None:
+            return (None, None)
+
+        device_name = heartbeat.attrib.get("device")
+        device_location = heartbeat.attrib.get("location")
+
+        return (device_name, device_location)
+
+    @override
+    async def get_device_mac(self) -> str:
+        settings = await self.fetch_settings()
+        root = defused_ET.fromstring(settings)
+        box = root.find(".//set[@box='12']")
+
+        if box is not None:
+            return format_mac(str(box.attrib.get("mac", "")))
+
+        raise DeviceLogicError(
+            f"Device: {self.ip_address} doesn't have a box 12 with MAC address"
+        )
+
+    async def _send_request(
+        self, method: str, endpoint: str, context: str, **kwargs: Any
+    ) -> str:
+
+        timeout = aiohttp.ClientTimeout(total=TIMEOUT_REQUEST)
+
+        try:
+            async with self.session.request(
+                method,
+                self.base_url + endpoint,
+                timeout=timeout,
+                auth=self._auth,
+                **kwargs,
+            ) as response:
+                if response.status != 200:
+                    if response.status == 401:
+                        raise DeviceAuthError("Invalid password")
+
+                    raise DeviceConnectionError(
+                        f"Failed to send command: {response.status}"
+                    )
+                return await response.text(encoding=ENCODING)
+
+        except (aiohttp.ClientError, TimeoutError) as exception:
+            raise DeviceConnectionError(
+                f"Failed to connect to {context} - {self.ip_address}: {exception}"
+            ) from exception
+
+    @override
+    async def read_command(
+        self, params: dict, context: str, endpoint: str = SET_URL
+    ) -> str:
+        """Command for communicating with any device by using GET request.
+
+        Parameters are GET queries that will be added to the request.
+        """
+
+        return await self._send_request("GET", endpoint, context, params=params)
+
+    @override
+    async def write_command(
+        self, payload: str, context: str, endpoint: str = SAVE_URL
+    ) -> str:
+        """Command for communicating with any device by using POST request.
+
+        Data contains the POST payload that will be sent in the request body.
+        Context is a information about the device:
+
+        e.g. f"{self.name} ({self.location})"
+
+        Return response text.
+        """
+
+        return await self._send_request("POST", endpoint, context, data=payload)
+
+    async def get_device_mode(self) -> int:
+        """Function is used for the resolving the mode of the device."""
+        info_xml = await self.fetch_info()
+        root = defused_ET.fromstring(info_xml)
+
+        heartbeat_tag = None
+        for element in root.iter():
+            if element.tag.endswith("heartbeat"):
+                heartbeat_tag = element
+                break
+
+        if heartbeat_tag is not None:
+            mode = heartbeat_tag.attrib.get("mode")
+            if mode is not None:
+                return int(mode)
+
+            device_name = heartbeat_tag.attrib.get("device")
+            if self._check_exceptions_device_web_mode(device_name):
+                return WEB_MODE_INDEX
+
+            _LOGGER.error("Heartbeat tag found, but 'mode' attribute is missing!")
+            return -1
+
+        _LOGGER.error("Response doesn't have heartbeat tag!")
+        return -1
+
+    def _check_exceptions_device_web_mode(self, device_name: str) -> bool:
+        if device_name == "TME":
+            return True
+        if "Papago" in device_name and "ETH" in device_name:
+            return True
+        return False

aiopapouch-0.1.0/aiopapouch/devices/__init__.py

@@ -0,0 +1,46 @@
+"""This file is used as a hub for imports."""
+
+from ..client import PapouchTransport
+from .base import PapouchDevice
+from .papago import async_setup_papago
+from .quido import async_setup_quido
+from .th2e import async_setup_th2e
+from .tme import async_setup_tme
+
+DEVICE_SETUP_HANDLERS = {
+    "Quido": async_setup_quido,
+    "TH2E": async_setup_th2e,
+    "TME": async_setup_tme,
+    "Papago": async_setup_papago,
+}
+
+
+def is_device_supported(device_name: str | None) -> bool:
+    """Check if the extracted device name matches any supported prefix."""
+    if not device_name:
+        return False
+
+    return any(prefix in device_name for prefix in DEVICE_SETUP_HANDLERS)
+
+
+async def create_device(api_client: PapouchTransport) -> PapouchDevice | None:
+    """Create a proper device instance dynamically based on the fetched info.
+
+    Returns None if the device is not supported.
+    """
+
+    device_name, _ = await api_client.get_device_info()
+
+    if not is_device_supported(device_name):
+        return None
+
+    assert device_name is not None
+
+    for prefix, setup_func in DEVICE_SETUP_HANDLERS.items():
+        if prefix in device_name:
+            return await setup_func(api_client)
+
+    return None
+
+
+__all__ = ["PapouchDevice", "create_device", "is_device_supported"]