flashforge-python-api 1.3.2__py3-none-any.whl → 1.3.4__py3-none-any.whl

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/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/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:
@@ -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/api/controls/files.py

@@ -90,7 +90,10 @@ 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
@@ -147,7 +150,7 @@ class Files:
                 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:
@@ -185,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/api/controls/info.py

@@ -2,18 +2,23 @@
 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
+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.
@@ -161,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.
@@ -233,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 "",
@@ -267,8 +279,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
@@ -303,7 +321,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
 
 
@@ -328,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:
@@ -352,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:
@@ -362,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}
 
@@ -384,12 +439,59 @@ 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 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