flashforge-python-api 1.3.3__tar.gz → 1.3.4__tar.gz

{flashforge_python_api-1.3.3 → flashforge_python_api-1.3.4}/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.4] - 2026-07-26
+
+### Fixed
+
+- **A single out-of-range field no longer costs the caller the entire `/detail` response.** A Creator 5 with no heated chamber reports `chamberTemp: -108` — the firmware's "this sensor does not exist" sentinel, a sibling of the `-100` this library itself sends as `TEMP_OFF`. `FFPrinterDetail.chamber_temp` carried `ge=-50`, so that one value failed validation for the whole model, `get_detail_response` returned `None`, and `ff-5mp-hass` reported an unreachable printer. Three releases went into `ff-5mp-hass#18` on the assumption it was a network or credential problem. The temperature fields now map any value at or below `-50` to `None`, so "no sensor" reads as "not reported" rather than as a `-108 °C` reading or a hard failure; `MachineInfoParser` exposes this as the new `FFMachineInfo.has_chamber_sensor`, which consumers should gate chamber entities on instead of the Creator 5 model family (the chamber is an option within it, not a family trait).
+
+- **Every remaining range constraint was removed from inbound models, not just the one that was reported.** Fixing `chamberTemp` alone would only have relocated the next outage: `tvoc`, `printSpeedAdjust`, `zAxisCompensation`, `fillAmount`, `remainingDiskSpace`, `nozzleCnt` and ~20 more each carried a `ge`/`le` that could fail the entire response on a firmware revision or an unusual state. Pydantic validates a model all-or-nothing, so a constraint on a field nobody reads is enough to take a consumer down. `FFPrinterDetail`, `Temperature`, `SlotInfo`, `MatlStationInfo`, `IndepMatlInfo`, `FFGcodeToolData`, and `FFGcodeFileEntry` now validate types but not value ranges. Outbound request models (`AD5X*Params`, `Creator5*Params`, `FilamentArgs`, `AD5XMaterialMapping`) keep their constraints, where a bad value is our own bug rather than a firmware difference. This matches the TypeScript client (`ff-5mp-api-ts`), which takes what it needs from a response and has never hit this class of failure.
+
+- **Nested inbound models no longer fail the parent over a missing or unusual field.** `SlotInfo` required `hasFilament`, `materialColor`, `materialName`, and `slotId`, so one absent attribute on one slot failed the whole `/detail` response; all four are now defaulted. Its hex-color validator *raised* on anything that was not `#RRGGBB` or empty — it now normalizes (expanding `#RGB`, adding a missing `#`) and degrades to an empty string, because an unrecognized color should cost a swatch its color, not cost the caller every entity. `MatlStationInfo.slot_infos` carried `min_length=1`, which made an explicitly empty `slotInfos: []` — a station with nothing loaded — invalid, and `max_length=4`, which would have failed on any future larger station.
+
+### Added
+
+- **`FlashForgeResponseError`, so callers can tell "unreadable answer" from "no answer".** Every failure path returned `None`, which meant a schema mismatch was indistinguishable from an unreachable printer — the reason `ff-5mp-hass#18` spent three releases pointing its reporter at the network. `get_detail_response()` now *raises* when the printer answered with a body that failed validation, and still returns `None` when the request never got through. `info.get()` raises the same error when a validated payload cannot be converted into `FFMachineInfo`. The convenience wrappers (`is_printing`, `get_status`, `get_machine_state`) keep their documented fallback returns and absorb it, so only callers that asked for the distinction have to handle it.
+
+- **`Info.get_detail_raw()`**, returning the decoded `/detail` JSON with no model validation. This lets a consumer read identity fields — above all `pid` — without first validating ~50 unrelated fields, so a supported printer can no longer be rejected because of a field that has nothing to do with whether it is supported.
+
+- **`FFMachineInfo.has_chamber_sensor`**, set from whether the printer actually reported a chamber temperature.
+
+### Changed
+
+- **`__init__.py` reported `__version__ = "1.3.1"` while `pyproject.toml` said `1.3.3`.** Both now read `1.3.4`.
+
+- **`CLAUDE.md`'s "Why TCP Bootstrap Is Still Required for Modern Printers" section described behavior the library deliberately does not have.** It claimed `client.initialize()` performs a TCP `M115` alongside the authenticated `/detail` call, but `verify_connection()` has decided `http_only` from the parsed model *before* touching TCP since the Creator 5 work — that family exposes no service on 8899, where an `M115` would hang until the connect timeout rather than fail fast. Model detection is PID-based end to end: the UDP discovery packet before pairing, `/detail` after. Rewritten as "Model Detection Without TCP", with the `http_only` guard stated as the rule and the two remaining ungated legacy call sites (`init_control`, `get_temperatures`, neither used by `ff-5mp-hass`) flagged. No code change — the guard and `tests/test_http_only_guard.py` were already correct; the document that exists to stop agents reintroducing TCP was the thing telling them to.
+
 ## [1.3.3] - 2026-07-26
 
 ### Changed

{flashforge_python_api-1.3.3 → flashforge_python_api-1.3.4}/CLAUDE.md

@@ -285,12 +285,32 @@ Two things this rule is easy to get half-right:
 
 The one cost of `extra="allow"` on inbound models: a typo'd `alias=` stops raising and silently becomes an extra field. Keep asserting on parsed *values* in fixtures rather than just successful construction, which is what still catches it.
 
-### Why TCP Bootstrap Is Still Required for Modern Printers
-The HTTP `/detail` endpoint requires authentication (`serialNumber` + `checkCode` via `FNetCode`). During discovery and the very first connection attempt — before a check code has been entered — there are no credentials, so the parser cannot read `pid` from `/detail`. The library handles this by:
+**`extra="allow"` was only ever half the rule — the other half is value constraints and required fields.** Extras were fixed in 1.3.2 and the very next release still shipped a total outage from the same underlying cause, because `chamberTemp` carried `ge=-50`. The generalized rule, as of 1.3.4:
 
-1. Discovery (UDP) returns the printer's USB-style PID in the broadcast packet, which `discovery/discovery.py` already maps to a `PrinterModel`. Consumers can use this to pre-select a model class before pairing.
-2. After a check code is provided, `client.initialize()` performs both an authenticated `/detail` call and an unauthenticated TCP `M115` (`tcp_client.get_printer_info()`). The TCP `M115` response carries `Machine Type` (firmware-controlled, e.g. `"FlashForge Adventurer 5M Pro"`) which is safe to substring-match for capability inference; do NOT use the M115 `Machine Name` field for that — like `detail.name` it is user-set.
-3. Once `verify_connection()` finishes, `FFMachineInfo.pid` / `is_pro` / `is_ad5x` are authoritative. All later capability gating should read those, not re-parse strings.
+> **Inbound models validate types. They do not validate ranges, and they require only what the payload is meaningless without.**
+
+Three reasons this is not negotiable:
+
+1. **Pydantic fails a model as a unit.** A constraint on a field no consumer reads is enough to lose every other field in the response. `get_detail_response` turned that into "no data", which `ff-5mp-hass` showed as an offline printer — so `ge=-50` on one optional temperature made a whole printer configuration unusable and reported it as a network fault.
+2. **Firmware uses out-of-band values as signals, not as errors.** Absent hardware is reported with a sentinel rather than by omitting the field: a Creator 5 with no chamber heater sends `chamberTemp: -108`, and this library itself sends `-100` as `TEMP_OFF`. Values that look impossible are routine, and the correct response is to normalize them (see `sanitize_temperature` in `models/machine_info.py`), never to reject the payload.
+3. **We do not own the schema.** Every constraint is a guess about firmware we have not seen, and the cost of guessing wrong is total rather than proportional. The TypeScript client (`ff-5mp-api-ts`) takes what it needs from a response and has never hit this failure class — that is the behavior to match.
+
+Range constraints remain correct on **outbound** models (`AD5XMaterialMapping`, `Creator5UploadParams`, `FilamentArgs`, …), where the values are ours and a bad one is our bug, caught before it reaches the printer. When adding an inbound field: give it a default, give it no range, and if it needs bounds to be useful, clamp or normalize it in `MachineInfoParser`.
+
+**Distinguish "no answer" from "an answer we could not read".** Returning `None` for both is what made `ff-5mp-hass#18` take three releases to diagnose — the printer was reachable and the credentials were correct, but every signal the library emitted said otherwise. `get_detail_response()` returns `None` only for transport failures and raises `FlashForgeResponseError` when the body failed validation; `info.get()` raises it when a validated payload cannot be converted. `get_detail_raw()` exists so consumers can read identity fields (`pid`) without validating the rest of the payload first. Preserve this split in any new endpoint: a caller that cannot tell the two apart cannot tell its user anything useful.
+
+### Model Detection Without TCP
+**TCP is never required for model detection, and the Creator 5 / Creator 5 Pro have no TCP service at all** — nothing listens on 8899, so an `M115` handshake there does not fail fast, it hangs until the connect timeout. Detection is PID-based end to end:
+
+1. **Before pairing:** discovery (UDP) returns the printer's PID in the broadcast packet, which `discovery/discovery.py` maps to a `PrinterModel`. This is what resolves the bootstrap problem — `/detail` needs `serialNumber` + `checkCode` (via `FNetCode`), which do not exist yet at discovery time, and the UDP packet needs no credentials.
+2. **After a check code is provided:** the authenticated `/detail` call carries the same firmware-set `pid`, which `MachineInfoParser.from_detail` turns into `is_pro` / `is_ad5x` / `is_creator5` / `is_creator5_pro`.
+3. **From then on:** `FFMachineInfo.pid` and those flags are authoritative. Never re-parse strings, and never substring-match `detail.name` — it is user-set (broke `ff-5mp-hass` in v1.1.8, see issue #13).
+
+`verify_connection()` decides `http_only` from the parsed model *before* touching TCP (`client.py:408`), so the Creator 5 series never opens a socket; an explicit `http_only_override` always wins. Guarded by `tests/test_http_only_guard.py` — keep any new TCP call site behind `if not self._http_only`.
+
+TCP `M115` remains available for older printers that actually serve it, and its `Machine Type` field (firmware-controlled, e.g. `"FlashForge Adventurer 5M Pro"`) is safe to read where it exists — its `Machine Name` field is not, being user-set like `detail.name`. It is a legacy path, not part of model detection.
+
+> Known gap: `client.initialize()` → `init_control()` (`client.py:262`) and `get_temperatures()` (`client.py:531`) call the TCP client unguarded and would hang on a Creator 5. Neither is used by `ff-5mp-hass`. Gate them before calling either from new code.
 
 ### Error Handling
 - HTTP errors: Wrapped in aiohttp exceptions

{flashforge_python_api-1.3.3 → flashforge_python_api-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashforge-python-api
-Version: 1.3.3
+Version: 1.3.4
 Summary: A comprehensive Python library for controlling FlashForge 3D printers
 Project-URL: Homepage, https://github.com/GhostTypes/ff-5mp-api-py
 Project-URL: Documentation, https://github.com/GhostTypes/ff-5mp-api-py#readme

{flashforge_python_api-1.3.3 → flashforge_python_api-1.3.4}/flashforge/__init__.py

@@ -69,6 +69,7 @@ from .discovery import (
     PrinterStatus,
     SocketCreationError,
 )
+from .exceptions import FlashForgeError, FlashForgeResponseError
 
 # Import key models for convenience
 from .models import (
@@ -127,7 +128,7 @@ from .tcp import (
 )
 
 FiveMClient = FlashForgeClient
-__version__ = "1.3.1"
+__version__ = "1.3.4"
 __author__ = "FlashForge Python API Contributors"
 __email__ = "notghosttypes@gmail.com"
 __description__ = "Python library for controlling FlashForge 3D printers"
@@ -138,6 +139,9 @@ __all__ = [
     "FlashForgeClient",
     "FiveMClient",
     "FiveMClientConnectionOptions",
+    # Exceptions
+    "FlashForgeError",
+    "FlashForgeResponseError",
     # Data models
     "FFMachineInfo",
     "FFPrinterDetail",

{flashforge_python_api-1.3.3 → flashforge_python_api-1.3.4}/flashforge/api/controls/info.py

@@ -5,8 +5,9 @@ FlashForge Python API - Info Module
 import logging
 import re
 from datetime import datetime, timedelta
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
+from ...exceptions import FlashForgeResponseError
 from ...models.machine_info import FFMachineInfo, MachineState, Temperature
 from ...models.responses import DetailResponse, FFPrinterDetail
 from ..constants.endpoints import Endpoints
@@ -165,6 +166,12 @@ class MachineInfoParser:
             )
             has_lidar = getattr(detail, "lidar", None) == 1
             has_door_sensor = is_creator5_pro
+            # Not every Creator 5 has the heated chamber. FFPrinterDetail maps
+            # the firmware's "no sensor" sentinel (-108) to None, so an absent
+            # reading is the signal - never the model family, which is what left
+            # chamber-less units with three entities pinned at 0 C.
+            chamber_temp_value = getattr(detail, "chamber_temp", None)
+            has_chamber_sensor = chamber_temp_value is not None
 
             # Immutable model name resolution: prefer the firmware `model`
             # field, then a PID-derived name, then the user-set name.
@@ -237,6 +244,7 @@ class MachineInfoParser:
                 has_camera=has_camera,
                 has_lidar=has_lidar,
                 has_door_sensor=has_door_sensor,
+                has_chamber_sensor=has_chamber_sensor,
                 # Current print stats
                 print_duration=getattr(detail, "print_duration", 0) or 0,
                 print_file_name=getattr(detail, "print_file_name", "") or "",
@@ -338,21 +346,41 @@ class Info:
         This method fetches detailed data from the printer and transforms it.
 
         Returns:
-            An FFMachineInfo object, or None if an error occurs or no data is returned.
+            An FFMachineInfo object, or None if the printer could not be reached.
+
+        Raises:
+            FlashForgeResponseError: The printer answered but the payload could
+                not be understood. Distinct from a None return, which means the
+                request never got through.
         """
         detail_response = await self.get_detail_response()
-        if detail_response and detail_response.detail:
-            return MachineInfoParser.from_detail(detail_response.detail)
-        return None
+        if detail_response is None or detail_response.detail is None:
+            return None
+
+        machine_info = MachineInfoParser.from_detail(detail_response.detail)
+        if machine_info is None:
+            # We validated the payload but could not build our own model from
+            # it - that is a bug on our side, not an unreachable printer, and
+            # reporting it as the latter is what issue #18 was about.
+            raise FlashForgeResponseError(
+                "The /detail payload was read but could not be converted into machine info",
+                endpoint=Endpoints.DETAIL,
+            )
+        return machine_info
 
     async def is_printing(self) -> bool:
         """
         Checks if the printer is currently in the "printing" state.
 
+        These three convenience wrappers keep their documented "return the
+        fallback on any failure" contract, so a caller polling for a boolean is
+        not forced to handle an exception. The failure is still logged, and
+        callers that need to distinguish causes should use `get()` directly.
+
         Returns:
             True if the printer is printing, False otherwise or if status cannot be determined.
         """
-        info = await self.get()
+        info = await self._get_or_none()
         return info.status == "printing" if info else False
 
     async def get_status(self) -> str | None:
@@ -362,7 +390,7 @@ class Info:
         Returns:
             The status string, or None if it cannot be determined.
         """
-        info = await self.get()
+        info = await self._get_or_none()
         return info.status if info else None
 
     async def get_machine_state(self) -> MachineState | None:
@@ -372,17 +400,34 @@ class Info:
         Returns:
             A MachineState enum value, or None if it cannot be determined.
         """
-        info = await self.get()
+        info = await self._get_or_none()
         return info.machine_state if info else None
 
-    async def get_detail_response(self) -> DetailResponse | None:
+    async def _get_or_none(self) -> FFMachineInfo | None:
+        """Call `get()`, absorbing a response error into a None for the convenience wrappers."""
+        try:
+            return await self.get()
+        except FlashForgeResponseError as error:
+            logger.warning("Could not read machine info: %s", error)
+            return None
+
+    async def get_detail_raw(self) -> dict[str, Any] | None:
         """
-        Retrieves the raw detailed response from the printer's detail endpoint.
-        This contains a wealth of information about the printer's current state.
+        Retrieves the /detail response as the plain decoded JSON dict, with no
+        model validation applied.
+
+        This exists so callers can inspect identity fields - above all `pid` -
+        without first having to successfully validate the ~50 unrelated fields
+        in the payload. A supported printer must never be rejected because of a
+        field that has nothing to do with whether it is supported (issue #18).
 
         Returns:
-            A DetailResponse object containing the raw printer details,
-            or None if the request fails or an error occurs.
+            The decoded response body, or None if the printer could not be
+            reached or answered with a non-200 status.
+
+        Raises:
+            FlashForgeResponseError: The printer answered with a body that is
+                not decodable JSON.
         """
         payload = {"serialNumber": self.client.serial_number, "checkCode": self.client.check_code}
 
@@ -396,15 +441,57 @@ class Info:
                 if response.status != 200:
                     logger.warning("Non-200 status from the /detail endpoint: %s", response.status)
                     return None
-
                 data = await json_from_response(response)
-                return DetailResponse(**data)
-
         except Exception as error:
             logger.warning(
-                "Could not read /detail; callers cannot tell this from an unreachable "
-                "printer or a rejected check code, so this line is the only record of "
-                "the real cause. %s",
+                "Could not reach the printer's /detail endpoint. This is a transport "
+                "failure (unreachable printer, timeout, or refused connection), not a "
+                "payload the library failed to read. %s",
                 error,
             )
             return None
+
+        if not isinstance(data, dict):
+            raise FlashForgeResponseError(
+                f"The /detail endpoint returned {type(data).__name__}, expected a JSON object",
+                endpoint=Endpoints.DETAIL,
+            )
+        return data
+
+    async def get_detail_response(self) -> DetailResponse | None:
+        """
+        Retrieves the validated detailed response from the printer's detail endpoint.
+        This contains a wealth of information about the printer's current state.
+
+        Returns:
+            A DetailResponse object containing the raw printer details, or None
+            if the printer could not be reached.
+
+        Raises:
+            FlashForgeResponseError: The printer answered, but the body did not
+                validate. Callers should surface this differently from a None
+                return: None means "we never got an answer", this means "the
+                answer was not one we could read", and only the second is
+                actionable as a bug report.
+        """
+        data = await self.get_detail_raw()
+        if data is None:
+            return None
+
+        try:
+            return DetailResponse(**data)
+        except Exception as error:
+            logger.warning(
+                "The printer answered /detail with a payload that failed validation. This "
+                "is NOT a connectivity problem - please report it with the debug dump "
+                "below. %s",
+                error,
+            )
+            # Redacted: this dump carries the MAC, IP and cloud registration
+            # codes, and it exists to be pasted into a bug report.
+            logger.debug("Payload that failed validation: %s", redact_model(data))
+            raise FlashForgeResponseError(
+                "The printer's /detail response could not be validated",
+                endpoint=Endpoints.DETAIL,
+                cause=error,
+            ) from error

flashforge_python_api-1.3.4/flashforge/exceptions.py

@@ -0,0 +1,51 @@
+"""
+FlashForge Python API - Exceptions
+"""
+
+from __future__ import annotations
+
+
+class FlashForgeError(Exception):
+    """Base class for every error this library raises deliberately."""
+
+
+class FlashForgeResponseError(FlashForgeError):
+    """
+    The printer answered, but the payload could not be understood.
+
+    This is deliberately distinct from a ``None`` return, which every HTTP
+    control method uses for "could not reach the printer / the printer refused
+    us". Collapsing the two is what made issue #18 take three releases to
+    diagnose: a Creator 5 reporting ``chamberTemp: -108`` (the firmware's "no
+    chamber sensor" sentinel) surfaced in Home Assistant as ``cannot_connect``,
+    pointing the user at their network for a schema problem.
+
+    Raise this whenever the transport succeeded and the *content* was the
+    problem, so callers can tell the user something actionable.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        endpoint: str | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        """
+        Args:
+            message: Human-readable description of what could not be parsed.
+            endpoint: The endpoint whose response failed, e.g. "/detail".
+            cause: The underlying validation/decode error, kept for logs.
+        """
+        super().__init__(message)
+        self.message = message
+        self.endpoint = endpoint
+        self.cause = cause
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.endpoint:
+            parts.append(f"(endpoint: {self.endpoint})")
+        if self.cause:
+            parts.append(f"caused by {type(self.cause).__name__}: {self.cause}")
+        return " ".join(parts)