aiohpprinter 1.0.0__py3-none-any.whl

aiohpprinter/__init__.py

@@ -0,0 +1,51 @@
+# Copyright 2026 Simone Chemelli and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Async Python library for HP printers exposing an embedded web server (EWS)."""
+
+from .client import HpPrinter
+from .exceptions import (
+    HpPrinterConnectionError,
+    HpPrinterError,
+    HpPrinterHttpError,
+    HpPrinterParseError,
+    HpPrinterTimeoutError,
+    HpPrinterUnsupportedError,
+)
+from .models import (
+    HpAdapter,
+    HpConsumable,
+    HpCopyUsage,
+    HpEPrint,
+    HpFaxUsage,
+    HpPrinterData,
+    HpPrinterDevice,
+    HpPrinterStatus,
+    HpPrinterUsage,
+    HpScannerUsage,
+    HpWifi,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "HpAdapter",
+    "HpConsumable",
+    "HpCopyUsage",
+    "HpEPrint",
+    "HpFaxUsage",
+    "HpPrinter",
+    "HpPrinterConnectionError",
+    "HpPrinterData",
+    "HpPrinterDevice",
+    "HpPrinterError",
+    "HpPrinterHttpError",
+    "HpPrinterParseError",
+    "HpPrinterStatus",
+    "HpPrinterTimeoutError",
+    "HpPrinterUnsupportedError",
+    "HpPrinterUsage",
+    "HpScannerUsage",
+    "HpWifi",
+    "__version__",
+]

aiohpprinter/client.py

@@ -0,0 +1,322 @@
+# Copyright 2026 Simone Chemelli and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Async client for an HP printer's embedded web server (EWS)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import aiohttp
+
+from .const import (
+    _LOGGER,
+    DEFAULT_PORT,
+    DEFAULT_TIMEOUT,
+    ENDPOINT_ADAPTERS,
+    ENDPOINT_CONSUMABLE_CONFIG,
+    ENDPOINT_EPRINT_CONFIG,
+    ENDPOINT_NET_APPS_SECURE,
+    ENDPOINT_PRODUCT_CONFIG,
+    ENDPOINT_PRODUCT_STATUS,
+    ENDPOINT_PRODUCT_USAGE,
+    JSON_CONTENT_TYPES,
+)
+from .exceptions import (
+    HpPrinterConnectionError,
+    HpPrinterError,
+    HpPrinterHttpError,
+    HpPrinterParseError,
+    HpPrinterTimeoutError,
+)
+from .models import HpPrinterData
+from .parsers import (
+    parse_adapters,
+    parse_consumables,
+    parse_copy_usage,
+    parse_device,
+    parse_eprint,
+    parse_fax_usage,
+    parse_printer_usage,
+    parse_scanner_usage,
+    parse_status,
+    parse_wifi,
+)
+from .xml import parse_document, parse_json_document
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from types import TracebackType
+    from typing import Any, Self
+
+    from .models import (
+        HpAdapter,
+        HpConsumable,
+        HpCopyUsage,
+        HpEPrint,
+        HpFaxUsage,
+        HpPrinterDevice,
+        HpPrinterStatus,
+        HpPrinterUsage,
+        HpScannerUsage,
+        HpWifi,
+    )
+
+
+class HpPrinter:
+    """Async client for an HP printer's embedded web server (EWS).
+
+    Session ownership: when no `session` is given, `HpPrinter` creates and
+    owns an `aiohttp.ClientSession` for the lifetime of the `async with`
+    block (or until :meth:`close` is called). When a `session` is injected
+    - the recommended approach for applications such as Home Assistant that
+    manage their own connection pooling - the caller owns it and remains
+    responsible for closing it; `HpPrinter` never closes a session it did
+    not create.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        session: aiohttp.ClientSession | None = None,
+        *,
+        port: int = DEFAULT_PORT,
+        ssl: bool = False,
+        timeout: aiohttp.ClientTimeout = DEFAULT_TIMEOUT,
+    ) -> None:
+        """Initialize the client for the printer at `host`."""
+        self._host = host
+        self._port = port
+        self._ssl = ssl
+        self._timeout = timeout
+        self._session = session
+        self._owns_session = session is None
+
+    @property
+    def base_url(self) -> str:
+        """Return the printer's EWS base URL."""
+        protocol = "https" if self._ssl else "http"
+        return f"{protocol}://{self._host}:{self._port}"
+
+    async def __aenter__(self) -> Self:
+        """Open the client, creating a session if none was injected."""
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the client, releasing only a session it created itself."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying session, if this client owns it."""
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    async def is_online(self) -> bool:
+        """Return whether the printer currently responds to status requests.
+
+        Any failure - offline, powered down, unreachable, or an unexpected
+        response - is treated as "not online" rather than raised, since that
+        is what this check exists to answer. Call :meth:`status` directly to
+        distinguish those failure modes.
+        """
+        try:
+            await self.status()
+        except HpPrinterError:
+            return False
+
+        return True
+
+    async def device(self) -> HpPrinterDevice:
+        """Fetch printer identity information."""
+        document = await self._request(ENDPOINT_PRODUCT_CONFIG)
+
+        return parse_device(document)
+
+    async def status(self) -> HpPrinterStatus:
+        """Fetch the printer's current operational status."""
+        document = await self._request(ENDPOINT_PRODUCT_STATUS)
+
+        return parse_status(document)
+
+    async def consumables(self) -> list[HpConsumable]:
+        """Fetch the merged list of ink/toner consumables."""
+        config_document = await self._request(ENDPOINT_CONSUMABLE_CONFIG)
+        usage_document = await self._request(ENDPOINT_PRODUCT_USAGE)
+
+        return parse_consumables(config_document, usage_document)
+
+    async def printer_usage(
+        self,
+        document: dict[str, Any] | None = None,
+    ) -> HpPrinterUsage:
+        """Fetch cumulative printer engine page counters.
+
+        `document` lets callers that already fetched `ProductUsageDyn` (for
+        example :meth:`update`) reuse it instead of requesting it again.
+        """
+        if document is None:
+            document = await self._request(ENDPOINT_PRODUCT_USAGE)
+
+        return parse_printer_usage(document)
+
+    async def scanner_usage(
+        self,
+        document: dict[str, Any] | None = None,
+    ) -> HpScannerUsage:
+        """Fetch cumulative scanner engine page counters.
+
+        See :meth:`printer_usage` for the meaning of `document`.
+        """
+        if document is None:
+            document = await self._request(ENDPOINT_PRODUCT_USAGE)
+
+        return parse_scanner_usage(document)
+
+    async def copy_usage(
+        self,
+        document: dict[str, Any] | None = None,
+    ) -> HpCopyUsage:
+        """Fetch cumulative copy application page counters.
+
+        See :meth:`printer_usage` for the meaning of `document`.
+        """
+        if document is None:
+            document = await self._request(ENDPOINT_PRODUCT_USAGE)
+
+        return parse_copy_usage(document)
+
+    async def fax_usage(
+        self,
+        document: dict[str, Any] | None = None,
+    ) -> HpFaxUsage:
+        """Fetch cumulative fax application page counters.
+
+        See :meth:`printer_usage` for the meaning of `document`.
+        """
+        if document is None:
+            document = await self._request(ENDPOINT_PRODUCT_USAGE)
+
+        return parse_fax_usage(document)
+
+    async def adapters(self) -> list[HpAdapter]:
+        """Fetch the printer's network adapters."""
+        document = await self._request(ENDPOINT_ADAPTERS)
+
+        return parse_adapters(document)
+
+    async def eprint(self) -> HpEPrint:
+        """Fetch HP ePrint cloud printing configuration."""
+        document = await self._request(ENDPOINT_EPRINT_CONFIG)
+
+        return parse_eprint(document)
+
+    async def wifi(self) -> HpWifi:
+        """Fetch Wireless Direct configuration."""
+        document = await self._request(ENDPOINT_NET_APPS_SECURE)
+
+        return parse_wifi(document)
+
+    async def update(self) -> HpPrinterData:
+        """Fetch everything the printer currently supports.
+
+        Only the status endpoint is treated as required: if the printer
+        does not answer it, `update` returns immediately with
+        `online=False` and every other field left at its default. Every
+        other endpoint is optional - a missing or failing one leaves its
+        field `None` (or an empty list) without aborting the rest of the
+        update, since printer models differ in which features they expose.
+        """
+        try:
+            status = await self.status()
+        except HpPrinterError:
+            return HpPrinterData(online=False)
+
+        usage_document = await self._safe_request(ENDPOINT_PRODUCT_USAGE)
+        config_document = await self._safe_request(ENDPOINT_CONSUMABLE_CONFIG)
+
+        return HpPrinterData(
+            online=True,
+            device=await self._safe(self.device),
+            status=status,
+            consumables=parse_consumables(config_document, usage_document),
+            printer_usage=(
+                parse_printer_usage(usage_document)
+                if usage_document is not None
+                else None
+            ),
+            scanner_usage=(
+                parse_scanner_usage(usage_document)
+                if usage_document is not None
+                else None
+            ),
+            copy_usage=(
+                parse_copy_usage(usage_document) if usage_document is not None else None
+            ),
+            fax_usage=(
+                parse_fax_usage(usage_document) if usage_document is not None else None
+            ),
+            adapters=await self._safe(self.adapters) or [],
+            eprint=await self._safe(self.eprint),
+            wifi=await self._safe(self.wifi),
+        )
+
+    async def _safe[T](self, func: Callable[[], Awaitable[T]]) -> T | None:
+        """Await `func`, turning any `HpPrinterError` into `None`."""
+        try:
+            return await func()
+        except HpPrinterError:
+            _LOGGER.debug("Optional endpoint unavailable for %s", func.__name__)
+            return None
+
+    async def _safe_request(self, endpoint: str) -> dict[str, Any] | None:
+        """Fetch and parse `endpoint`, turning any `HpPrinterError` into `None`."""
+        try:
+            return await self._request(endpoint)
+        except HpPrinterError:
+            _LOGGER.debug("Optional endpoint unavailable: %s", endpoint)
+            return None
+
+    async def _request(self, endpoint: str) -> dict[str, Any]:
+        """Fetch `endpoint` and parse it into a nested dict document."""
+        if self._session is None:
+            message = (
+                "HpPrinter has no active session; "
+                "use it as an async context manager or inject one"
+            )
+            raise HpPrinterConnectionError(message)
+
+        url = f"{self.base_url}{endpoint}"
+
+        try:
+            async with self._session.get(url, timeout=self._timeout) as response:
+                if response.status >= 400:  # noqa: PLR2004
+                    message = f"{url} returned HTTP {response.status}"
+                    raise HpPrinterHttpError(response.status, message)
+
+                try:
+                    content = await response.text()
+                except UnicodeDecodeError as ex:
+                    message = f"Could not decode response from {url}: {ex}"
+                    raise HpPrinterParseError(message) from ex
+
+                content_type = response.content_type
+        except TimeoutError as ex:
+            message = f"Timed out requesting {url}"
+            raise HpPrinterTimeoutError(message) from ex
+        except aiohttp.ClientError as ex:
+            message = f"Could not connect to {url}: {ex}"
+            raise HpPrinterConnectionError(message) from ex
+
+        if content_type in JSON_CONTENT_TYPES:
+            return parse_json_document(content)
+
+        return parse_document(content)

aiohpprinter/const.py

@@ -0,0 +1,39 @@
+# Copyright 2026 Simone Chemelli and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Constants for aiohpprinter."""
+
+import logging
+
+from aiohttp import ClientTimeout
+
+_LOGGER = logging.getLogger(__package__)
+
+DEFAULT_PORT = 80
+DEFAULT_TIMEOUT = ClientTimeout(total=10)
+
+# HP embedded web server (EWS) DevMgmt/ePrint/IoMgmt endpoints. These are the
+# same URIs used by the upstream ha-hpprinter integration.
+ENDPOINT_PRODUCT_STATUS = "/DevMgmt/ProductStatusDyn.xml"
+ENDPOINT_PRODUCT_CONFIG = "/DevMgmt/ProductConfigDyn.xml"
+ENDPOINT_CONSUMABLE_CONFIG = "/DevMgmt/ConsumableConfigDyn.xml"
+ENDPOINT_PRODUCT_USAGE = "/DevMgmt/ProductUsageDyn.xml"
+ENDPOINT_ADAPTERS = "/IoMgmt/Adapters"
+ENDPOINT_EPRINT_CONFIG = "/ePrint/ePrintConfigDyn.xml"
+ENDPOINT_NET_APPS_SECURE = "/DevMgmt/NetAppsSecureDyn.xml"
+
+# A small number of endpoints (observed on `/IoMgmt/Adapters`) answer with a
+# JSON body instead of XML, using either of these content types.
+JSON_CONTENT_TYPES = frozenset({"application/javascript", "application/json"})
+
+# Keys present on every response's root element that carry protocol/schema
+# metadata rather than printer data, dropped once parsed.
+IGNORED_ROOT_KEYS = ("@schemaLocation", "Version")
+
+MARKER_COLOR_TO_LABEL_CODE = {
+    "Cyan": "C",
+    "Yellow": "Y",
+    "Magenta": "M",
+    "CyanMagentaYellow": "CMY",
+    "Black": "K",
+}

aiohpprinter/exceptions.py

@@ -0,0 +1,35 @@
+# Copyright 2026 Simone Chemelli and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""aiohpprinter library exceptions."""
+
+from __future__ import annotations
+
+
+class HpPrinterError(Exception):
+    """Base class for all aiohpprinter errors."""
+
+
+class HpPrinterConnectionError(HpPrinterError):
+    """Raised when the printer cannot be reached over the network."""
+
+
+class HpPrinterTimeoutError(HpPrinterError):
+    """Raised when a request to the printer times out."""
+
+
+class HpPrinterHttpError(HpPrinterError):
+    """Raised when the printer returns an unsuccessful HTTP status code."""
+
+    def __init__(self, status: int, message: str) -> None:
+        """Initialize the error with the offending HTTP status code."""
+        super().__init__(message)
+        self.status = status
+
+
+class HpPrinterParseError(HpPrinterError):
+    """Raised when a printer response cannot be parsed as valid XML."""
+
+
+class HpPrinterUnsupportedError(HpPrinterError):
+    """Raised when the printer does not expose a required endpoint."""

aiohpprinter/models.py

@@ -0,0 +1,179 @@
+# Copyright 2026 Simone Chemelli and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Typed printer-domain models returned by :class:`aiohpprinter.HpPrinter`.
+
+These describe HP printer concepts (device identity, status, consumables,
+usage counters, ...), not Home Assistant entities. Every field is optional
+unless the printer protocol guarantees it, since firmware and product
+generation determine which elements a given model actually reports.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+@dataclass(frozen=True, slots=True)
+class HpPrinterDevice:
+    """Identity information for the printer as a whole."""
+
+    make_and_model: str | None = None
+    make_and_model_family: str | None = None
+    sku_identifier: str | None = None
+    serial_number: str | None = None
+    product_number: str | None = None
+    manufacturer_name: str | None = None
+    manufactured_at: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HpPrinterStatus:
+    """The printer's current operational status."""
+
+    device_status: str | None = None
+
+    @property
+    def is_ready(self) -> bool:
+        """Return whether the printer is idle and ready to accept jobs."""
+        return self.device_status == "ready"
+
+    @property
+    def is_off(self) -> bool:
+        """Return whether the printer is powered off or unreachable."""
+        return self.device_status is None or self.device_status == "off"
+
+
+@dataclass(frozen=True, slots=True)
+class HpConsumable:
+    """A single ink/toner consumable, merged from config and usage data.
+
+    ``consumable_id`` is the value the two source endpoints are joined on:
+    the consumable label code (for example ``"C"``, ``"M"``, ``"Y"``,
+    ``"K"``, or ``"CMY"`` for a combined cartridge).
+    """
+
+    consumable_id: str
+    consumable_type: str | None = None
+    marker_color: str | None = None
+    state: str | None = None
+    usage_state: str | None = None
+    brand: str | None = None
+    station: str | None = None
+    percentage_level_remaining: float | None = None
+    raw_percentage_level_remaining: float | None = None
+    estimated_pages_remaining: int | None = None
+    max_capacity: float | None = None
+    selectibility_number: str | None = None
+    manufacturer_name: str | None = None
+    manufactured_at: datetime | None = None
+    installed_at: datetime | None = None
+    warranty_expires_at: datetime | None = None
+    serial_number: str | None = None
+    product_number: str | None = None
+    supply_serial_number: str | None = None
+    unique_id: str | None = None
+    counterfeit_refilled_count: int | None = None
+    genuine_refilled_count: int | None = None
+    total_impressions: int | None = None
+
+    @property
+    def is_ok(self) -> bool:
+        """Return whether the consumable reports a healthy life state."""
+        return self.state in {"ok", "newGenuineHP"}
+
+
+@dataclass(frozen=True, slots=True)
+class HpPrinterUsage:
+    """Cumulative page counters for the printer engine."""
+
+    total_impressions: int | None = None
+    monochrome_impressions: int | None = None
+    color_impressions: int | None = None
+    simplex_sheets: int | None = None
+    duplex_sheets: int | None = None
+    jam_events: int | None = None
+    mispick_events: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HpScannerUsage:
+    """Cumulative page counters for the scanner engine."""
+
+    scan_images: int | None = None
+    adf_images: int | None = None
+    duplex_sheets: int | None = None
+    flatbed_images: int | None = None
+    jam_events: int | None = None
+    mispick_events: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HpCopyUsage:
+    """Cumulative page counters for the copy application."""
+
+    total_impressions: int | None = None
+    adf_images: int | None = None
+    flatbed_images: int | None = None
+    monochrome_impressions: int | None = None
+    color_impressions: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HpFaxUsage:
+    """Cumulative page counters for the fax application."""
+
+    total_impressions: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HpAdapter:
+    """A network adapter reported by the printer's I/O management."""
+
+    name: str | None = None
+    connectivity_port_type: str | None = None
+    is_connected: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HpEPrint:
+    """HP ePrint cloud printing configuration."""
+
+    printer_id: str | None = None
+    is_registered: bool | None = None
+    cloud_services_enabled: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HpWifi:
+    """Wireless Direct configuration."""
+
+    ssid_prefix: str | None = None
+    connection_method: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HpPrinterData:
+    """Aggregate snapshot of everything :meth:`HpPrinter.update` collected.
+
+    Every section besides ``online`` is `None` (or an empty list) when its
+    endpoint is not supported by this printer model, or could not be
+    retrieved on this update cycle - see the client's optional-endpoint
+    handling for details.
+    """
+
+    online: bool
+    device: HpPrinterDevice | None = None
+    status: HpPrinterStatus | None = None
+    consumables: list[HpConsumable] = field(default_factory=list)
+    printer_usage: HpPrinterUsage | None = None
+    scanner_usage: HpScannerUsage | None = None
+    copy_usage: HpCopyUsage | None = None
+    fax_usage: HpFaxUsage | None = None
+    adapters: list[HpAdapter] = field(default_factory=list)
+    eprint: HpEPrint | None = None
+    wifi: HpWifi | None = None

aiohpprinter/parsers/__init__.py

@@ -0,0 +1,38 @@
+# Copyright 2026 Simone Chemelli and contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pure, synchronous XML-to-model parsers, one module per EWS endpoint.
+
+Parsing in-memory XML/dict data is not I/O, so unlike the HTTP client these
+functions are plain synchronous callables. Each takes the dict produced by
+:func:`aiohpprinter.xml.parse_document` and returns typed models from
+:mod:`aiohpprinter.models`.
+"""
+
+from __future__ import annotations
+
+from .adapter import parse_adapters
+from .consumable import parse_consumables
+from .device import parse_device
+from .eprint import parse_eprint
+from .status import parse_status
+from .usage import (
+    parse_copy_usage,
+    parse_fax_usage,
+    parse_printer_usage,
+    parse_scanner_usage,
+)
+from .wifi import parse_wifi
+
+__all__ = [
+    "parse_adapters",
+    "parse_consumables",
+    "parse_copy_usage",
+    "parse_device",
+    "parse_eprint",
+    "parse_fax_usage",
+    "parse_printer_usage",
+    "parse_scanner_usage",
+    "parse_status",
+    "parse_wifi",
+]