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

{flashforge_python_api-1.3.1 → flashforge_python_api-1.3.3}/.gitignore

@@ -119,3 +119,6 @@ test_*.png
 
 # PyPI credentials
 .pypirc
+
+# Local codegraph index (tooling artifact)
+.codegraph/

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

@@ -5,7 +5,25 @@ 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).
 
-## [Unreleased]
+## [1.3.3] - 2026-07-26
+
+### Changed
+
+- **Diagnostic output now goes to the `logging` module instead of `print()`.** 95 `print()` calls across 10 modules were the library's only record of why an operation failed — and under Home Assistant, the largest consumer, stdout reaches nowhere the user can see. Every silent failure therefore looked identical from the outside: a `/detail` response the library could not parse, an unreachable printer, and a rejected check code all produced the same bare `None` or `False` with no explanation anywhere. That is the ambiguity behind both reports on `ff-5mp-hass#18`, where one reporter concluded their check code was wrong and another concluded the integration needed TCP port 8899; neither could see the actual cause. Failures and refused commands now log at `WARNING`, request/response tracing at `DEBUG`, under per-module loggers (`flashforge.api.controls.info`, `…job_control`, and so on) so consumers can raise the level for one area alone. Two intentional exceptions remain on stdout: `FlashForgePrinterDiscovery.print_debug_info()`, whose entire purpose is to dump a hex/ASCII view for a human, and the `_async_main` CLI demo.
+
+### Security
+
+- **Credentials, network identifiers, and cloud registration codes are redacted from logs.** Moving diagnostics into `logging` would otherwise have written secrets to a file users routinely paste into bug reports. The upload paths logged their full HTTP headers — including `serialNumber` and `checkCode`, which together are complete control of the printer over the LAN API — and `send_control_command` printed its whole payload, credentials included, on *every single command*. The new `flashforge.api.misc.redaction` helpers mask `serialNumber`, `checkCode`, `macAddr`, `ipAddr`, `flashRegisterCode`, and `polarRegisterCode` (in both firmware camelCase and library snake_case, recursing into nested structures) before any value can be formatted into a log record. The key set deliberately matches what `ff-5mp-hass` already strips from its diagnostics download, so a log paste and a diagnostics upload cannot disagree about what is safe to share.
+
+## [1.3.2] - 2026-07-26
+
+### Fixed
+
+- **A firmware field this library has not seen no longer presents to the user as a wrong check code.** `Product`, `ProductResponse`, `ThumbnailResponse`, and `GenericResponse` — the envelope every inbound response inherits — were `extra="forbid"`, so one unrecognized key raised `ValidationError`. `send_product_command` caught it and returned a bare `False`, which is exactly what a printer refusing the credentials returns; `ff-5mp-hass` turns that into "the check code is incorrect". The same trap sat one level deeper on `/detail`: `FFPrinterDetail` has been `extra="allow"` since 1.3.0, but its children `MatlStationInfo`, `SlotInfo`, `IndepMatlInfo`, and `FFGcodeToolData` still forbade extras, and a child that rejects a field fails the whole response — most likely on a 4-head Creator 5 Pro reporting four loaded slots, the model least covered by existing fixtures. All inbound models now allow extras. Outbound request-parameter models (`AD5X*Params`, `Creator5*Params`, `FilamentArgs`) and the internally constructed `FFMachineInfo` / `Temperature` keep `extra="forbid"`, where it catches our own typos rather than a firmware revision. `send_product_command` now logs the `ValidationError` distinctly instead of letting an unparsed response impersonate rejected credentials. Reported as `ff-5mp-hass#18`.
+
+- **`FFMachineInfo.has_matl_station` no longer misses the Material Station on the Creator 5 series.** It was a straight copy of the raw `hasMatlStation` value from `/detail`, which is an AD5X-only field — a Creator 5 Pro omits it entirely (verified on real hardware, pid 41, firmware 1.9.4) while reporting a fully populated `matlStationInfo` with four loaded slots. It therefore parsed as `None`, and consumers gating on it saw no station on exactly the models that have one. The parser already computed the correct value for its own AD5X heuristic (flag `is True` OR `slot_cnt > 0` OR non-empty `slot_infos`) and then discarded it; that derived value is now what the property exposes. Its type narrows from `bool | None` to `bool` — a capability has no "unknown" state, and offering one is what allowed an unreported flag to read as absent hardware. `FFPrinterDetail.has_matl_station` still carries the untouched firmware value.
+
+- **`/gcodeList` no longer loses every file's metadata when the firmware adds a field.** `GCodeListResponse` and `FFGcodeFileEntry` were `extra="forbid"`, and `Files.get_recent_file_list()` caught the resulting `ValidationError` and fell back to a names-only list — `printing_time=0` and every other field `None`, for every file. One unrecognized key anywhere in the payload was therefore enough to silently strip print time, filament weight, and the per-tool material data on all models, and the result is byte-for-byte what a printer that genuinely reports names only looks like. Both models now use `extra="allow"` (matching `FFPrinterDetail`), and the remaining fallback logs a warning naming what was lost instead of degrading in silence.
 
 ## [1.3.1] - 2026-06-28
 
@@ -185,7 +203,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Type hints for all public APIs
 - Inline code documentation
 
-[Unreleased]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.3...HEAD
+[1.3.3]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.2...v1.3.3
+[1.3.2]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.2.3...v1.3.0
 [1.2.3]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.2.2...v1.2.3

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

@@ -5,7 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Project Overview
 
 FlashForge Python API is a comprehensive Python library for controlling FlashForge 3D printers. The library provides **dual-protocol** support:
-- **HTTP API**: Modern REST-like API for Adventurer 5M/5X series printers
+- **HTTP API**: Modern REST-like API for Adventurer 5M/5X and Creator 5 series printers
 - **TCP/G-code API**: Legacy protocol supporting all networked FlashForge printers
 
 The architecture is fully async/await throughout and uses Pydantic for type-safe data models.
@@ -26,7 +26,7 @@ The library has a layered client architecture:
      - `info`: Status and machine information
      - `files`: File operations (upload/download/list)
      - `temp_control`: Temperature settings
-   - Automatically detects printer capabilities (is_ad5x, is_pro) based on model
+   - Automatically detects printer capabilities (is_ad5x, is_pro, is_creator5, is_creator5_pro) based on model
 
 2. **`flashforge.tcp.ff_client.FlashForgeClient`** (TCP high-level client)
    - Extends `FlashForgeTcpClient`
@@ -69,7 +69,8 @@ flashforge/
 │   │   ├── job_control.py      # JobControl class
 │   │   ├── info.py             # Info class
 │   │   ├── files.py            # Files class (named 'files' for user API)
-│   │   └── temp_control.py     # TempControl class
+│   │   ├── temp_control.py     # TempControl class
+│   │   └── creator5_palette.py # Creator 5 material-station palette (CIEDE2000)
 │   ├── network/                # Network utilities
 │   │   ├── utils.py            # NetworkUtils for HTTP requests
 │   │   └── fnet_code.py        # FNetCode for authentication
@@ -84,7 +85,7 @@ flashforge/
 
 **Dual Protocol Strategy**: HTTP is used for high-level operations (printer status, file listing, job control commands) while TCP/G-code is used for real-time operations (temperature monitoring via M105, print progress via M27, thumbnails via M662).
 
-**Model Detection**: `MachineInfoParser.from_detail()` derives `is_pro` / `is_ad5x` on `FFMachineInfo` from the firmware-set integer `pid` field on `/detail` (35 = Adventurer 5M, 36 = 5M Pro, 38 = AD5X — see `KNOWN_HTTP_PIDS` in `flashforge/api/controls/info.py`). The `pid` value is also passed through to `FFMachineInfo.pid` for downstream consumers. When `pid` is absent (older firmware) the parser falls back to a name+capability heuristic, but new code should NOT rely on substring-matching `detail.name` — that field is user-mutable via the printer's LCD or cloud account and changing it broke detection in pre-1.2.3 builds (see CHANGELOG entry for 1.2.3, ref `ff-5mp-hass#13`).
+**Model Detection**: `MachineInfoParser.from_detail()` derives `is_pro` / `is_ad5x` / `is_creator5` / `is_creator5_pro` on `FFMachineInfo` from the firmware-set integer `pid` field on `/detail` (35 = Adventurer 5M, 36 = 5M Pro, 38 = AD5X, plus Creator 5 / Creator 5 Pro PIDs — see `KNOWN_HTTP_PIDS` and the `PID_*` constants in `flashforge/api/controls/info.py`). The `pid` value is also passed through to `FFMachineInfo.pid` for downstream consumers. When `pid` is absent (older firmware) the parser falls back to a name+capability heuristic, but new code should NOT rely on substring-matching `detail.name` — that field is user-mutable via the printer's LCD or cloud account and changing it broke detection in pre-1.2.3 builds (see CHANGELOG entry for 1.2.3, ref `ff-5mp-hass#13`). The Creator 5 series is **HTTP-only**: it exposes no TCP/8899 service, so `client._http_only` is true and the client routes temperature control through the HTTP `temperatureCtl_cmd` instead of TCP M105.
 
 **Parser Pattern**: TCP responses are parsed by specialized parser classes in `tcp/parsers/` that extract structured data from text responses (e.g., `M105` returns text like `T0:25/0 T1:25/0 B:25/0` which TempInfo parses).
 
@@ -206,7 +207,7 @@ twine check dist/*
 ```
 
 **Version Management**:
-- Current version: **1.3.0** (as of 2026-06-28)
+- Current version: **1.3.3** (as of 2026-07-26)
 - Package name: `flashforge-python-api`
 - PyPI: https://pypi.org/project/flashforge-python-api/
 - Build system: Hatchling (defined in `pyproject.toml`)
@@ -269,8 +270,20 @@ async with FlashForgeClient(ip, serial, check) as client:
 Certain features only work on specific models:
 - **LED control**: Adventurer 5M/5X only (check `client.led_control`)
 - **Filtration**: Adventurer 5M Pro only (check `client.filtration_control`)
+- **Per-nozzle & chamber temperature control, material-station slot configuration / color mapping**: Creator 5 / Creator 5 Pro only (HTTP `temperatureCtl_cmd`; slot colors snap to the firmware palette via CIEDE2000 in `api/controls/creator5_palette.py`)
 
-Capability flags (`client.is_pro`, `client.is_ad5x`) are populated from `FFMachineInfo` after `verify_connection()`, which itself reads `pid` off `/detail`. Trust those flags — do not re-derive them from `info.name`.
+Capability flags (`client.is_pro`, `client.is_ad5x`, `client.is_creator5`, `client.is_creator5_pro`) are populated from `FFMachineInfo` after `verify_connection()`, which itself reads `pid` off `/detail`. Trust those flags — do not re-derive them from `info.name`.
+
+**Never surface a raw `/detail` field as a capability flag, and never give a capability an "unknown" state.** Firmware omits fields that don't apply to a model, so an absent value means "not reported", not "no" — and any type that can hold `None` invites a consumer to read the two as the same thing. `hasMatlStation` is the known case: it is AD5X-only, and a Creator 5 Pro leaves it out of `/detail` entirely (verified on firmware 1.9.4) while reporting a fully populated `matlStationInfo` with four loaded slots. `FFMachineInfo.has_matl_station` is therefore **derived** in `MachineInfoParser.from_detail` (flag `is True` OR `slot_cnt > 0` OR non-empty `slot_infos`) and typed `bool`, not `bool | None`; the raw value stays on `FFPrinterDetail`. The same trap caught `led_control_override` downstream, where a caller's unset `False` was read as "force the capability off". Apply the rule to any new capability: derive it from the data the capability actually produces, give it no unknown state, and cover it with a fixture built from a real payload — the Creator 5 fixtures originally had no material station at all, which is why this went unnoticed through v1.3.1.
+
+**The rule for response models: `extra="allow"` on anything parsed from a printer response, `extra="forbid"` on anything this library constructs itself.** A model that forbids unknown fields turns a firmware addition into a parse failure, and every parse failure here degrades into something that looks like a working printer with less to report — or worse. `ff-5mp-hass#18` is the canonical case: `Product` forbade extras, so an unrecognized control-state flag raised `ValidationError`, `send_product_command` returned the same bare `False` it returns for bad credentials, and the user was told their check code was wrong when it was not.
+
+Two things this rule is easy to get half-right:
+
+1. **It applies to nested models, not just the top-level response.** A child that forbids extras fails validation for the entire response, so `FFPrinterDetail` being `extra="allow"` bought nothing while `MatlStationInfo` / `SlotInfo` / `IndepMatlInfo` underneath it still forbade them. Every model reachable from a parsed payload has to allow extras, all the way down.
+2. **The inverse half is load-bearing — do not strip `extra="forbid"` indiscriminately.** Outbound request-parameter models (`AD5XLocalJobParams`, `Creator5UploadParams`, `FilamentArgs`, …) are request bodies *we* build, so no firmware update can break them, and forbidding extras turns a caller's typo'd keyword into an error instead of a field the printer silently ignores. Same for `FFMachineInfo` and `Temperature`, which are only ever constructed by `MachineInfoParser.from_detail` from keyword arguments — there, forbidding extras is a typo check on our own parser.
+
+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:
@@ -308,6 +321,10 @@ The HTTP `/detail` endpoint requires authentication (`serialNumber` + `checkCode
 - FlashForge Adventurer 5M / 5M Pro
 - FlashForge Adventurer 4
 
+**Full Support** (HTTP only — no TCP/8899 service):
+- FlashForge Creator 5
+- FlashForge Creator 5 Pro
+
 **Partial Support** (TCP only):
 - FlashForge Adventurer 3
 
@@ -327,7 +344,7 @@ The HTTP `/detail` endpoint requires authentication (`serialNumber` + `checkCode
 **Imaging** (optional `[imaging]`):
 - `pillow>=10.0.0` - For thumbnail image processing
 
-**Python version**: Requires Python 3.8+
+**Python version**: Requires Python 3.11+
 
 ## Common Gotchas
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashforge-python-api
-Version: 1.3.1
+Version: 1.3.3
 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.1 → flashforge_python_api-1.3.3}/ai_specs/TEST_COVERAGE_SPEC.md

@@ -727,7 +727,7 @@ class Test5MProLiveIntegration:
             info = await client.info.get()
             assert info is not None
             assert info.is_ad5x == False
-            assert info.has_matl_station is None  # Not AD5X, shouldn't have this
+            assert info.has_matl_station is False  # derived capability: no station present
 
     async def test_get_file_list_5m_pro(self):
         """Test getting file list from 5M Pro (non-AD5X format)."""

{flashforge_python_api-1.3.1 → flashforge_python_api-1.3.3}/docs/models.md

@@ -71,14 +71,24 @@ The primary model for printer status, aggregating data from various sources into
 | `flash_cloud_register_code` | `str` | FlashCloud registration code |
 | `polar_cloud_register_code` | `str` | PolarCloud registration code |
 
-#### Material Station (AD5X)
+#### Material Station (AD5X / Creator 5 series)
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `has_matl_station` | `Optional[bool]` | Material station present |
+| `has_matl_station` | `bool` | Material station present (derived — see below) |
 | `matl_station_info` | `Optional[MatlStationInfo]` | Material station details |
 | `indep_matl_info` | `Optional[IndepMatlInfo]` | Independent material info |
 
+`has_matl_station` is **derived**, not copied from the printer's raw
+`hasMatlStation` field. That field is AD5X-only: a Creator 5 Pro omits it from
+`/detail` entirely even with four loaded slots, so an absent value means "not
+reported", never "no station". The parser therefore also accepts a populated
+`matlStationInfo` (`slot_cnt` / `slot_infos`) as proof, and the property is a
+plain `bool` — the capability has no unknown state to represent.
+
+Gate features on this property. `FFPrinterDetail.has_matl_station` keeps the
+untouched firmware value and is `Optional[bool]` for that reason.
+
 ### Temperature
 
 Represents temperature readings for a component.

{flashforge_python_api-1.3.1 → flashforge_python_api-1.3.3}/flashforge/api/controls/control.py

@@ -2,6 +2,7 @@
 FlashForge Python API - Control Module
 """
 
+import logging
 from typing import TYPE_CHECKING, Any
 
 from ...models.responses import FilamentArgs
@@ -14,6 +15,8 @@ if TYPE_CHECKING:
     from ...client import FlashForgeClient
     from ...tcp.ff_client import FlashForgeClient as TcpClient
 
+logger = logging.getLogger(__name__)
+
 
 class Control:
     """
@@ -75,7 +78,7 @@ class Control:
             return await self._send_filtration_command(
                 FilamentArgs(internal="close", external="open")
             )
-        print("SetExternalFiltrationOn() error, filtration not equipped.")
+        logger.warning("set_external_filtration_on: filtration is not equipped on this printer.")
         return False
 
     async def set_internal_filtration_on(self) -> bool:
@@ -90,7 +93,7 @@ class Control:
             return await self._send_filtration_command(
                 FilamentArgs(internal="open", external="close")
             )
-        print("SetInternalFiltrationOn() error, filtration not equipped.")
+        logger.warning("set_internal_filtration_on: filtration is not equipped on this printer.")
         return False
 
     async def set_filtration_off(self) -> bool:
@@ -105,7 +108,7 @@ class Control:
             return await self._send_filtration_command(
                 FilamentArgs(internal="close", external="close")
             )
-        print("SetFiltrationOff() error, filtration not equipped.")
+        logger.warning("set_filtration_off: filtration is not equipped on this printer.")
         return False
 
     async def turn_camera_on(self) -> bool:
@@ -188,7 +191,7 @@ class Control:
             True if the command is successful, False otherwise.
         """
         if not self.client.led_control:
-            print("SetLedOn() error, LED control not equipped.")
+            logger.warning("set_led_on: LED control is not equipped on this printer.")
             return False
         return await self.send_control_command(Commands.LIGHT_CONTROL_CMD, {"status": "open"})
 
@@ -200,7 +203,7 @@ class Control:
             True if the command is successful, False otherwise.
         """
         if not self.client.led_control:
-            print("SetLedOff() error, LED control not equipped.")
+            logger.warning("set_led_off: LED control is not equipped on this printer.")
             return False
         return await self.send_control_command(Commands.LIGHT_CONTROL_CMD, {"status": "close"})
 
@@ -259,7 +262,9 @@ class Control:
             True if the command is successful, False otherwise.
         """
         if not self.client.is_ad5x and not self.client.is_creator5:
-            print("configure_slot() error, material station only available on AD5X / Creator 5.")
+            logger.warning(
+                "configure_slot: the material station is only available on the AD5X / Creator 5."
+            )
             return False
         # The AD5X and Creator 5 use MUTUALLY EXCLUSIVE color wire formats (see
         # creator5_palette for the firmware match rules), so model-gate here:
@@ -293,7 +298,9 @@ class Control:
             "payload": {"cmd": command, "args": args},
         }
 
-        print(f"SendControlCommand:\n{payload}")
+        # Log the command, never `payload`: it carries the serial number and
+        # check code, and these lines end up pasted into bug reports.
+        logger.debug("Sending control command %s with args %s", command, args)
 
         try:
             await self.client.is_http_client_busy()
@@ -305,12 +312,12 @@ class Control:
                 headers={"Content-Type": "application/json"},
             ) as response:
                 data = await json_from_response(response)
-                print(f"Command reply: {data}")
+                logger.debug("Control command %s reply: %s", command, data)
 
                 return NetworkUtils.is_ok(data)
 
         except Exception as e:
-            print(f"Error in send_control_command: {e}")
+            logger.warning("Error in send_control_command (%s): %s", command, e)
             return False
         finally:
             self.client.release_http_client()

{flashforge_python_api-1.3.1 → flashforge_python_api-1.3.3}/flashforge/api/controls/creator5_palette.py

@@ -16,6 +16,7 @@ for the model-gating that splits them.
 
 from __future__ import annotations
 
+import logging
 import math
 import re
 from dataclasses import dataclass
@@ -25,6 +26,8 @@ from dataclasses import dataclass
 # reference. PEP 8 lowercase locals are therefore relaxed here on purpose.
 # ruff: noqa: N806
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass(frozen=True)
 class Creator5PaletteColor:
@@ -70,7 +73,7 @@ CREATOR5_PALETTE: tuple[Creator5PaletteColor, ...] = (
 )
 
 # 25^7, the CIEDE2000 chroma weighting constant.
-_25_POW_7 = 25.0 ** 7
+_25_POW_7 = 25.0**7
 
 # D65 reference white point used by the sRGB -> XYZ transform.
 _D65_XN = 0.95047
@@ -132,7 +135,7 @@ def _delta_e_2000(c1: tuple[float, float, float], c2: tuple[float, float, float]
     C1 = math.sqrt(a1 * a1 + b1 * b1)
     C2 = math.sqrt(a2 * a2 + b2 * b2)
     Cbar = (C1 + C2) / 2.0
-    Cbar7 = Cbar ** 7
+    Cbar7 = Cbar**7
     G = 0.5 * (1 - math.sqrt(Cbar7 / (Cbar7 + _25_POW_7)))
 
     a1p = (1 + G) * a1
@@ -178,7 +181,7 @@ def _delta_e_2000(c1: tuple[float, float, float], c2: tuple[float, float, float]
     )
 
     dTheta = 30 * math.exp(-(((hbarp - 275) / 25.0) ** 2))
-    Cbarp7 = Cbarp ** 7
+    Cbarp7 = Cbarp**7
     RC = 2 * math.sqrt(Cbarp7 / (Cbarp7 + _25_POW_7))
     SL = 1 + (0.015 * (Lbarp - 50) ** 2) / math.sqrt(20 + (Lbarp - 50) ** 2)
     SC = 1 + 0.045 * Cbarp
@@ -238,9 +241,9 @@ def snap_to_creator5_palette(hex_str: str) -> Creator5PaletteColor:
     """
     rgb = _hex_to_rgb(hex_str)
     if rgb is None:
-        print(
-            f'snap_to_creator5_palette: could not parse "{hex_str}" as hex; '
-            "falling back to White."
+        logger.warning(
+            'snap_to_creator5_palette: could not parse "%s" as hex; falling back to White.',
+            hex_str,
         )
         return CREATOR5_PALETTE[0]
 

{flashforge_python_api-1.3.1 → flashforge_python_api-1.3.3}/flashforge/api/controls/files.py

@@ -3,6 +3,7 @@ FlashForge Python API - Files Module
 """
 
 import base64
+import logging
 from typing import TYPE_CHECKING
 
 from pydantic import ValidationError
@@ -15,6 +16,8 @@ from ..network.utils import NetworkUtils, json_from_response
 if TYPE_CHECKING:
     from ...client import FlashForgeClient
 
+logger = logging.getLogger(__name__)
+
 
 class Files:
     """
@@ -87,13 +90,27 @@ class Files:
                 data = await json_from_response(response)
 
                 if not NetworkUtils.is_ok(data):
-                    print(f"Error retrieving file list: {NetworkUtils.get_error_message(data)}")
+                    logger.warning(
+                        "Error retrieving the file list: %s",
+                        NetworkUtils.get_error_message(data),
+                    )
                     return []
 
                 # Parse the response using GCodeListResponse
                 try:
                     result = GCodeListResponse(**data)
-                except ValidationError:
+                except ValidationError as err:
+                    # The names-only fallback below silently costs the caller
+                    # every per-file field, which is indistinguishable from a
+                    # printer that only reports names. Say so, loudly enough to
+                    # reach an integration's log, or the next model that changes
+                    # this payload looks like it reports no metadata at all.
+                    logger.warning(
+                        "Could not parse the /gcodeList response; falling back to file "
+                        "names only, so print time, filament weight, and per-tool "
+                        "material data are unavailable for every file. %s",
+                        err,
+                    )
                     raw_list = data.get("gcodeList", [])
                     if isinstance(raw_list, list):
                         entries: list[FFGcodeFileEntry] = []
@@ -127,15 +144,13 @@ class Files:
                     elif isinstance(first_item, FFGcodeFileEntry):
                         # Already FFGcodeFileEntry objects - need explicit type narrowing
                         return [
-                            item
-                            for item in result.gcode_list
-                            if isinstance(item, FFGcodeFileEntry)
+                            item for item in result.gcode_list if isinstance(item, FFGcodeFileEntry)
                         ]
 
                 return []
 
         except Exception as err:
-            print(f"GetRecentFileList error: {err}")
+            logger.warning("get_recent_file_list error: %s", err)
             return []
 
     async def get_gcode_thumbnail(self, file_name: str) -> bytes | None:
@@ -173,9 +188,12 @@ class Files:
                     result = ThumbnailResponse(**data)
                     return base64.b64decode(result.image_data)
                 else:
-                    print(f"Error retrieving thumbnail: {NetworkUtils.get_error_message(data)}")
+                    logger.warning(
+                        "Error retrieving the thumbnail: %s",
+                        NetworkUtils.get_error_message(data),
+                    )
                     return None
 
         except Exception as err:
-            print(f"GetGcodeThumbnail error: {err}")
+            logger.warning("get_gcode_thumbnail error: %s", err)
             return None

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

@@ -2,6 +2,7 @@
 FlashForge Python API - Info Module
 """
 
+import logging
 import re
 from datetime import datetime, timedelta
 from typing import TYPE_CHECKING
@@ -9,11 +10,14 @@ from typing import TYPE_CHECKING
 from ...models.machine_info import FFMachineInfo, MachineState, Temperature
 from ...models.responses import DetailResponse, FFPrinterDetail
 from ..constants.endpoints import Endpoints
+from ..misc.redaction import redact_model
 from ..network.utils import json_from_response
 
 if TYPE_CHECKING:
     from ...client import FlashForgeClient
 
+logger = logging.getLogger(__name__)
+
 
 # Firmware-reported PIDs from FlashForge's /detail endpoint. These are stable
 # identifiers set by firmware, unlike the user-mutable `name` field.
@@ -89,10 +93,17 @@ class MachineInfoParser:
             print_progress = getattr(detail, "print_progress", 0) or 0
             est_length = total_job_filament_meters * print_progress
             est_weight = (getattr(detail, "estimated_right_weight", 0) or 0) * print_progress
+            # Material Station presence, derived rather than read off a single
+            # field. `hasMatlStation` is AD5X-only: the Creator 5 series omits it
+            # from /detail entirely (verified on a Creator 5 Pro, pid 41, firmware
+            # 1.9.4) while reporting a fully populated matlStationInfo with four
+            # loaded slots, so an absent flag means "not reported", never "absent
+            # hardware". Populated slot data is the reliable signal.
             has_material_station = (
                 getattr(detail, "has_matl_station", None) is True
                 or (getattr(getattr(detail, "matl_station_info", None), "slot_cnt", 0) or 0) > 0
-                or len(getattr(getattr(detail, "matl_station_info", None), "slot_infos", []) or []) > 0
+                or len(getattr(getattr(detail, "matl_station_info", None), "slot_infos", []) or [])
+                > 0
             )
             printer_name = getattr(detail, "name", "") or ""
             pid = getattr(detail, "pid", None)
@@ -236,7 +247,9 @@ class MachineInfoParser:
                 print_speed_adjust=getattr(detail, "print_speed_adjust", 0) or 0,
                 filament_type=getattr(detail, "right_filament_type", "") or "",
                 # Machine state
-                machine_state=MachineInfoParser._get_machine_state(getattr(detail, "status", "") or ""),
+                machine_state=MachineInfoParser._get_machine_state(
+                    getattr(detail, "status", "") or ""
+                ),
                 status=getattr(detail, "status", "") or "",
                 total_print_layers=getattr(detail, "target_print_layer", 0) or 0,
                 tvoc=getattr(detail, "tvoc", 0) or 0,
@@ -249,8 +262,8 @@ class MachineInfoParser:
                 completion_time=completion_time,
                 formatted_run_time=formatted_run_time,
                 formatted_total_run_time=formatted_total_run_time,
-                # AD5X Material Station
-                has_matl_station=getattr(detail, "has_matl_station", None),
+                # Material Station (AD5X / Creator 5 series)
+                has_matl_station=has_material_station,
                 matl_station_info=getattr(detail, "matl_station_info", None),
                 indep_matl_info=getattr(detail, "indep_matl_info", None),
             )
@@ -258,8 +271,14 @@ class MachineInfoParser:
             return machine_info
 
         except Exception as error:
-            print(f"Error in MachineInfoParser.from_detail: {error}")
-            print(f"Detail object causing error: {detail}")
+            logger.warning(
+                "Could not parse the /detail payload into FFMachineInfo; the caller sees "
+                "this as an unreachable printer. %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("Detail object that failed to parse: %s", redact_model(detail))
             return None
 
     @staticmethod
@@ -294,7 +313,7 @@ class MachineInfoParser:
             return state_mapping[valid_status]
 
         if valid_status:
-            print(f"Unknown machine status received: '{status}'")
+            logger.warning("Unknown machine status received: %r", status)
         return MachineState.UNKNOWN
 
 
@@ -375,12 +394,17 @@ class Info:
                 headers={"Content-Type": "application/json"},
             ) as response:
                 if response.status != 200:
-                    print(f"Non-200 status from detail endpoint: {response.status}")
+                    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:
-            print(f"GetDetailResponse Request error: {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",
+                error,
+            )
             return None