flashforge-python-api 1.3.3__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/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/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)

flashforge/models/machine_info.py

@@ -4,11 +4,76 @@ FlashForge Python API - Data Models
 
 from __future__ import annotations
 
+import re
 from datetime import datetime
 from enum import Enum
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
+# ---------------------------------------------------------------------------
+# Validation policy for inbound firmware payloads
+# ---------------------------------------------------------------------------
+#
+# Models parsed FROM the printer carry types but NOT value ranges, and no
+# required fields beyond what we genuinely cannot work without. The reason is
+# blast radius: pydantic fails a model as a unit, and `Info.get_detail_response`
+# turns any failure into "no data", which Home Assistant shows as an offline
+# printer. So a `ge=0` on a field nobody reads could take the whole integration
+# down. That is exactly what happened in issue #18, where a Creator 5 reporting
+# `chamberTemp: -108` made every entity unavailable and the config flow report
+# `cannot_connect`.
+#
+# Range constraints belong on OUTBOUND command models (see responses.py), where
+# the values are ours and a bad one is our bug. Inbound, we take what we need
+# and tolerate the rest. This mirrors the TypeScript client (ff-5mp-api-ts),
+# which has never hit this class of failure.
+#
+# Firmware signals "this sensor does not exist" with an out-of-band negative
+# sentinel rather than by omitting the field: -108 on a chamber-less Creator 5,
+# and -100 is our own "heater off" value (TempControl.TEMP_OFF). Anything at or
+# below this floor is a marker, not a reading.
+TEMP_SENTINEL_FLOOR = -50.0
+
+_HEX_COLOR_RE = re.compile(r"^#[0-9A-Fa-f]{6}$")
+
+
+def sanitize_temperature(value: Any) -> Any:
+    """
+    Map firmware temperature sentinels to None, passing everything else through.
+
+    Non-numeric input is returned untouched so normal type validation still
+    reports it. Used as a `mode="before"` validator on every inbound
+    temperature field.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return value
+    return None if value <= TEMP_SENTINEL_FLOOR else value
+
+
+def _normalize_hex_color(value: Any) -> Any:
+    """
+    Coerce a material color into `#RRGGBB`, or an empty string when it is not
+    recognizable.
+
+    Never raises. An unparseable color costs a swatch its color; it must not
+    cost the caller the entire /detail response.
+    """
+    if not isinstance(value, str):
+        return "" if value is None else value
+
+    candidate = value.strip()
+    if candidate == "" or _HEX_COLOR_RE.match(candidate):
+        return candidate
+
+    # Accept the shorthand `#RGB` form by expanding it, and a bare `RRGGBB`
+    # without the leading hash - both are plausible firmware variations.
+    if re.match(r"^#[0-9A-Fa-f]{3}$", candidate):
+        return "#" + "".join(char * 2 for char in candidate[1:])
+    if re.match(r"^[0-9A-Fa-f]{6}$", candidate):
+        return f"#{candidate}"
+    return ""
+
 
 class MachineState(Enum):
     """Enumerates the possible operational states of the FlashForge 3D printer."""
@@ -35,12 +100,11 @@ class Temperature(BaseModel):
     # `extra="allow"` would silently absorb.
     model_config = ConfigDict(extra="forbid")
 
-    current: float = Field(
-        default=0.0, ge=-50, le=500, description="The current temperature in Celsius"
-    )
-    set: float = Field(
-        default=0.0, ge=-50, le=500, description="The target (set) temperature in Celsius"
-    )
+    # No range constraints: MachineInfoParser feeds these straight from firmware
+    # values, so a range here fails `from_detail` for the same reason a range on
+    # FFPrinterDetail fails the response - one odd reading, no data at all.
+    current: float = Field(default=0.0, description="The current temperature in Celsius")
+    set: float = Field(default=0.0, description="The target (set) temperature in Celsius")
 
 
 class SlotInfo(BaseModel):
@@ -53,26 +117,32 @@ class SlotInfo(BaseModel):
     # integration reports as "could not retrieve printer information".
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
+    # Every field defaulted: a slot missing one attribute must cost that
+    # attribute, not the whole /detail response. `slot_id` carries no 1-4 range
+    # for the same reason - a station reporting a fifth slot should show up as a
+    # slot we ignore, not as an offline printer.
     has_filament: bool = Field(
-        alias="hasFilament", description="Indicates if filament is present in this slot"
+        default=False,
+        alias="hasFilament",
+        description="Indicates if filament is present in this slot",
     )
     material_color: str = Field(
-        alias="materialColor", description="Color of the material in this slot (e.g., '#FFFFFF')"
+        default="",
+        alias="materialColor",
+        description="Color of the material in this slot (e.g., '#FFFFFF')",
     )
     material_name: str = Field(
-        alias="materialName", description="Name of the material in this slot (e.g., 'PLA')"
+        default="",
+        alias="materialName",
+        description="Name of the material in this slot (e.g., 'PLA')",
     )
-    slot_id: int = Field(alias="slotId", ge=1, le=4, description="Identifier for this slot (1-4)")
+    slot_id: int = Field(default=0, alias="slotId", description="Identifier for this slot (1-4)")
 
-    @field_validator("material_color")
+    @field_validator("material_color", mode="before")
     @classmethod
-    def validate_hex_color(cls, v: str) -> str:
-        """Validate that the color is a valid hex color code or empty string."""
-        import re
-
-        if v == "" or re.match(r"^#[0-9A-Fa-f]{6}$", v):
-            return v
-        raise ValueError(f"Invalid hex color format: {v}")
+    def normalize_material_color(cls, v: Any) -> Any:
+        """Normalize the material color, falling back to '' rather than raising."""
+        return _normalize_hex_color(v)
 
 
 class MatlStationInfo(BaseModel):
@@ -81,27 +151,29 @@ class MatlStationInfo(BaseModel):
     # `extra="allow"`: inbound, see SlotInfo.
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
+    # Defaulted and unconstrained throughout, per the inbound policy at the top
+    # of this module. `slot_infos` in particular had `min_length=1`, which made
+    # an explicitly empty `slotInfos: []` - a station with nothing loaded - fail
+    # the entire /detail response.
     current_load_slot: int = Field(
-        alias="currentLoadSlot", ge=0, le=4, description="Currently loading slot ID (0 if none)"
+        default=0, alias="currentLoadSlot", description="Currently loading slot ID (0 if none)"
     )
     current_slot: int = Field(
-        alias="currentSlot", ge=0, le=4, description="Currently active/printing slot ID (0 if none)"
+        default=0, alias="currentSlot", description="Currently active/printing slot ID (0 if none)"
     )
     slot_cnt: int = Field(
-        alias="slotCnt", ge=1, le=4, description="Total number of slots in the station"
+        default=0, alias="slotCnt", description="Total number of slots in the station"
     )
     slot_infos: list[SlotInfo] = Field(
-        min_length=1,
-        max_length=4,
         default_factory=list,
         alias="slotInfos",
         description="Array of information for each slot",
     )
     state_action: int = Field(
-        alias="stateAction", ge=0, description="Current action state of the material station"
+        default=0, alias="stateAction", description="Current action state of the material station"
     )
     state_step: int = Field(
-        alias="stateStep", ge=0, description="Current step within the state action"
+        default=0, alias="stateStep", description="Current step within the state action"
     )
 
 
@@ -111,24 +183,24 @@ class IndepMatlInfo(BaseModel):
     # `extra="allow"`: inbound, see SlotInfo.
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
-    material_color: str = Field(alias="materialColor", description="Color of the material")
+    material_color: str = Field(
+        default="", alias="materialColor", description="Color of the material"
+    )
     material_name: str = Field(
-        alias="materialName", description="Name of the material (can be '?' if unknown)"
+        default="",
+        alias="materialName",
+        description="Name of the material (can be '?' if unknown)",
     )
-    state_action: int = Field(alias="stateAction", ge=0, description="Current action state")
+    state_action: int = Field(default=0, alias="stateAction", description="Current action state")
     state_step: int = Field(
-        alias="stateStep", ge=0, description="Current step within the state action"
+        default=0, alias="stateStep", description="Current step within the state action"
     )
 
-    @field_validator("material_color")
+    @field_validator("material_color", mode="before")
     @classmethod
-    def validate_hex_color(cls, v: str) -> str:
-        """Validate that the color is a valid hex color code or empty string."""
-        import re
-
-        if v == "" or re.match(r"^#[0-9A-Fa-f]{6}$", v):
-            return v
-        raise ValueError(f"Invalid hex color format: {v}")
+    def normalize_material_color(cls, v: Any) -> Any:
+        """Normalize the material color, falling back to '' rather than raising."""
+        return _normalize_hex_color(v)
 
 
 class FFGcodeToolData(BaseModel):
@@ -140,33 +212,28 @@ class FFGcodeToolData(BaseModel):
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
     filament_weight: float = Field(
+        default=0.0,
         alias="filamentWeight",
-        ge=0,
         description="Calculated filament weight for this tool/material in the print",
     )
     material_color: str = Field(
-        alias="materialColor", description="Material color hex string (e.g., '#FFFF00')"
+        default="", alias="materialColor", description="Material color hex string (e.g., '#FFFF00')"
     )
     material_name: str = Field(
-        alias="materialName", description="Name of the material (e.g., 'PLA')"
+        default="", alias="materialName", description="Name of the material (e.g., 'PLA')"
     )
     slot_id: int = Field(
+        default=0,
         alias="slotId",
-        ge=0,
-        le=4,
         description="Slot ID from the material station, if applicable (0 if not or direct)",
     )
-    tool_id: int = Field(alias="toolId", ge=0, le=3, description="Tool ID or extruder number (0-3)")
+    tool_id: int = Field(default=0, alias="toolId", description="Tool ID or extruder number (0-3)")
 
-    @field_validator("material_color")
+    @field_validator("material_color", mode="before")
     @classmethod
-    def validate_hex_color(cls, v: str) -> str:
-        """Validate that the color is a valid hex color code or empty string."""
-        import re
-
-        if v == "" or re.match(r"^#[0-9A-Fa-f]{6}$", v):
-            return v
-        raise ValueError(f"Invalid hex color format: {v}")
+    def normalize_material_color(cls, v: Any) -> Any:
+        """Normalize the material color, falling back to '' rather than raising."""
+        return _normalize_hex_color(v)
 
 
 class FFGcodeFileEntry(BaseModel):
@@ -178,28 +245,27 @@ class FFGcodeFileEntry(BaseModel):
     # filament weight, and the per-tool material data for EVERY file.
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
+    # `gcode_file_name` stays required - it is the one field without which the
+    # entry means nothing, so failing here is honest. Everything else is
+    # metadata and gets a default.
     gcode_file_name: str = Field(
         alias="gcodeFileName", description="The name of the G-code file (e.g., 'FISH_PLA.3mf')"
     )
     gcode_tool_cnt: int | None = Field(
         default=None,
-        ge=0,
-        le=4,
         alias="gcodeToolCnt",
         description="Number of tools/materials used in this G-code file",
     )
     gcode_tool_datas: list[FFGcodeToolData] | None = Field(
         default=None,
-        max_length=4,
         alias="gcodeToolDatas",
         description="Array of detailed information for each tool/material",
     )
     printing_time: int = Field(
-        alias="printingTime", ge=0, description="Estimated printing time in seconds"
+        default=0, alias="printingTime", description="Estimated printing time in seconds"
     )
     total_filament_weight: float | None = Field(
         default=None,
-        ge=0,
         alias="totalFilamentWeight",
         description="Total estimated filament weight for the print",
     )
@@ -220,33 +286,29 @@ class FFPrinterDetail(BaseModel):
     model_config = ConfigDict(extra="allow")
 
     auto_shutdown: str | None = Field(default=None, alias="autoShutdown")
-    auto_shutdown_time: int | None = Field(default=None, ge=0, alias="autoShutdownTime")
-    camera: int | None = Field(default=None, ge=0, alias="camera")
+    auto_shutdown_time: int | None = Field(default=None, alias="autoShutdownTime")
+    camera: int | None = Field(default=None, alias="camera")
     camera_stream_url: str | None = Field(default=None, alias="cameraStreamUrl")
-    chamber_fan_speed: int | None = Field(default=None, ge=0, le=100, alias="chamberFanSpeed")
-    chamber_target_temp: float | None = Field(
-        default=None, ge=-50, le=500, alias="chamberTargetTemp"
-    )
-    chamber_temp: float | None = Field(default=None, ge=-50, le=500, alias="chamberTemp")
+    chamber_fan_speed: int | None = Field(default=None, alias="chamberFanSpeed")
+    chamber_target_temp: float | None = Field(default=None, alias="chamberTargetTemp")
+    chamber_temp: float | None = Field(default=None, alias="chamberTemp")
     clear_fan_status: str | None = Field(default=None, alias="clearFanStatus")
-    cooling_fan_speed: int | None = Field(default=None, ge=0, le=100, alias="coolingFanSpeed")
-    cooling_fan_left_speed: int | None = Field(
-        default=None, ge=0, le=100, alias="coolingFanLeftSpeed"
-    )
+    cooling_fan_speed: int | None = Field(default=None, alias="coolingFanSpeed")
+    cooling_fan_left_speed: int | None = Field(default=None, alias="coolingFanLeftSpeed")
     coordinate: list[float] | None = Field(default=None, alias="coordinate")
-    cumulative_filament: float | None = Field(default=None, ge=0, alias="cumulativeFilament")
-    cumulative_print_time: int | None = Field(default=None, ge=0, alias="cumulativePrintTime")
-    current_print_speed: int | None = Field(default=None, ge=0, le=1000, alias="currentPrintSpeed")
+    cumulative_filament: float | None = Field(default=None, alias="cumulativeFilament")
+    cumulative_print_time: int | None = Field(default=None, alias="cumulativePrintTime")
+    current_print_speed: int | None = Field(default=None, alias="currentPrintSpeed")
     door_status: str | None = Field(default=None, alias="doorStatus")
     error_code: str | None = Field(default=None, alias="errorCode")
-    estimated_left_len: float | None = Field(default=None, ge=0, alias="estimatedLeftLen")
-    estimated_left_weight: float | None = Field(default=None, ge=0, alias="estimatedLeftWeight")
-    estimated_right_len: float | None = Field(default=None, ge=0, alias="estimatedRightLen")
-    estimated_right_weight: float | None = Field(default=None, ge=0, alias="estimatedRightWeight")
-    estimated_time: float | None = Field(default=None, ge=0, alias="estimatedTime")
-    extrude_ctrl: int | None = Field(default=None, ge=0, alias="extrudeCtrl")
+    estimated_left_len: float | None = Field(default=None, alias="estimatedLeftLen")
+    estimated_left_weight: float | None = Field(default=None, alias="estimatedLeftWeight")
+    estimated_right_len: float | None = Field(default=None, alias="estimatedRightLen")
+    estimated_right_weight: float | None = Field(default=None, alias="estimatedRightWeight")
+    estimated_time: float | None = Field(default=None, alias="estimatedTime")
+    extrude_ctrl: int | None = Field(default=None, alias="extrudeCtrl")
     external_fan_status: str | None = Field(default=None, alias="externalFanStatus")
-    fill_amount: float | None = Field(default=None, ge=0, le=100, alias="fillAmount")
+    fill_amount: float | None = Field(default=None, alias="fillAmount")
     firmware_version: str | None = Field(default=None, alias="firmwareVersion")
     flash_register_code: str | None = Field(default=None, alias="flashRegisterCode")
     # AD5X-only, and firmware omits what does not apply: the Creator 5 series
@@ -261,48 +323,78 @@ class FFPrinterDetail(BaseModel):
     internal_fan_status: str | None = Field(default=None, alias="internalFanStatus")
     ip_addr: str | None = Field(default=None, alias="ipAddr")
     left_filament_type: str | None = Field(default=None, alias="leftFilamentType")
-    left_target_temp: float | None = Field(default=None, ge=-50, le=500, alias="leftTargetTemp")
-    left_temp: float | None = Field(default=None, ge=-50, le=500, alias="leftTemp")
+    left_target_temp: float | None = Field(default=None, alias="leftTargetTemp")
+    left_temp: float | None = Field(default=None, alias="leftTemp")
     light_status: str | None = Field(default=None, alias="lightStatus")
     location: str | None = Field(default=None, alias="location")
     mac_addr: str | None = Field(default=None, alias="macAddr")
     measure: str | None = Field(default=None, alias="measure")
-    move_ctrl: int | None = Field(default=None, ge=0, alias="moveCtrl")
+    move_ctrl: int | None = Field(default=None, alias="moveCtrl")
     name: str | None = Field(default=None, alias="name")
-    nozzle_cnt: int | None = Field(default=None, ge=1, le=4, alias="nozzleCnt")
+    nozzle_cnt: int | None = Field(default=None, alias="nozzleCnt")
     nozzle_model: str | None = Field(default=None, alias="nozzleModel")
-    nozzle_style: int | None = Field(default=None, ge=0, alias="nozzleStyle")
+    nozzle_style: int | None = Field(default=None, alias="nozzleStyle")
     # --- Creator 5 series raw fields ---
     # Immutable factory model name (e.g. "Creator 5 Pro"); unlike `name` this is
     # not user-editable. May be absent on older firmware.
     model: str | None = Field(default=None, alias="model")
     # Per-tool current nozzle temperatures (one entry per nozzle). Multi-nozzle
     # Creator 5 series report these; single-nozzle models use rightTemp/leftTemp.
-    nozzle_temps: list[float] | None = Field(default=None, alias="nozzleTemps")
+    # Entries are nullable because a sentinel reading is normalized to None by
+    # `drop_nozzle_temperature_sentinels` below.
+    nozzle_temps: list[float | None] | None = Field(default=None, alias="nozzleTemps")
     # Per-tool target nozzle temperatures (one entry per nozzle).
-    nozzle_target_temps: list[float] | None = Field(default=None, alias="nozzleTargetTemps")
+    nozzle_target_temps: list[float | None] | None = Field(
+        default=None, alias="nozzleTargetTemps"
+    )
     # Lidar / first-layer scanner presence flag (1 = present, 0 = absent).
-    lidar: int | None = Field(default=None, ge=0, alias="lidar")
-    pid: int | None = Field(default=None, ge=0, alias="pid")
-    plat_target_temp: float | None = Field(default=None, ge=-50, le=500, alias="platTargetTemp")
-    plat_temp: float | None = Field(default=None, ge=-50, le=500, alias="platTemp")
+    lidar: int | None = Field(default=None, alias="lidar")
+    pid: int | None = Field(default=None, alias="pid")
+    plat_target_temp: float | None = Field(default=None, alias="platTargetTemp")
+    plat_temp: float | None = Field(default=None, alias="platTemp")
     polar_register_code: str | None = Field(default=None, alias="polarRegisterCode")
-    print_duration: int | None = Field(default=None, ge=0, alias="printDuration")
+    print_duration: int | None = Field(default=None, alias="printDuration")
     print_file_name: str | None = Field(default=None, alias="printFileName")
     print_file_thumb_url: str | None = Field(default=None, alias="printFileThumbUrl")
-    print_layer: int | None = Field(default=None, ge=0, alias="printLayer")
-    print_progress: float | None = Field(default=None, ge=0, le=100, alias="printProgress")
-    print_speed_adjust: int | None = Field(default=None, ge=0, le=1000, alias="printSpeedAdjust")
-    remaining_disk_space: float | None = Field(default=None, ge=0, alias="remainingDiskSpace")
+    print_layer: int | None = Field(default=None, alias="printLayer")
+    print_progress: float | None = Field(default=None, alias="printProgress")
+    print_speed_adjust: int | None = Field(default=None, alias="printSpeedAdjust")
+    remaining_disk_space: float | None = Field(default=None, alias="remainingDiskSpace")
     right_filament_type: str | None = Field(default=None, alias="rightFilamentType")
-    right_target_temp: float | None = Field(default=None, ge=-50, le=500, alias="rightTargetTemp")
-    right_temp: float | None = Field(default=None, ge=-50, le=500, alias="rightTemp")
+    right_target_temp: float | None = Field(default=None, alias="rightTargetTemp")
+    right_temp: float | None = Field(default=None, alias="rightTemp")
     status: str | None = Field(default=None, alias="status")
-    target_print_layer: int | None = Field(default=None, ge=0, alias="targetPrintLayer")
-    tvoc: float | None = Field(default=None, ge=0, alias="tvoc")
-    z_axis_compensation: float | None = Field(
-        default=None, ge=-10, le=10, alias="zAxisCompensation"
+    target_print_layer: int | None = Field(default=None, alias="targetPrintLayer")
+    tvoc: float | None = Field(default=None, alias="tvoc")
+    z_axis_compensation: float | None = Field(default=None, alias="zAxisCompensation")
+
+    # Firmware reports absent temperature hardware with a negative sentinel
+    # (-108 on a chamber-less Creator 5, issue #18) rather than by omitting the
+    # field. Map those to None here so "no sensor" reads as "not reported"
+    # everywhere downstream, instead of as a -108 C reading or a hard failure.
+    @field_validator(
+        "chamber_temp",
+        "chamber_target_temp",
+        "left_temp",
+        "left_target_temp",
+        "plat_temp",
+        "plat_target_temp",
+        "right_temp",
+        "right_target_temp",
+        mode="before",
     )
+    @classmethod
+    def drop_temperature_sentinels(cls, v: Any) -> Any:
+        """Replace out-of-band 'no sensor' temperature markers with None."""
+        return sanitize_temperature(v)
+
+    @field_validator("nozzle_temps", "nozzle_target_temps", mode="before")
+    @classmethod
+    def drop_nozzle_temperature_sentinels(cls, v: Any) -> Any:
+        """Apply the same sentinel handling to the per-tool temperature arrays."""
+        if not isinstance(v, list):
+            return v
+        return [sanitize_temperature(entry) for entry in v]
 
 
 class FFMachineInfo(BaseModel):
@@ -393,6 +485,11 @@ class FFMachineInfo(BaseModel):
     # Only true on models with confirmed hardware (Creator 5 Pro). When false,
     # `door_open` is cosmetic and should not be surfaced.
     has_door_sensor: bool = False
+    # True only when the printer actually reported a chamber temperature. The
+    # heated chamber is a Creator 5 series *option*, not a family trait: units
+    # without it report the -108 sentinel, which FFPrinterDetail normalizes to
+    # None. Gate chamber entities on this, never on `is_creator5`.
+    has_chamber_sensor: bool = False
 
     # Current print stats
     print_duration: int = 0

{flashforge_python_api-1.3.3.dist-info → flashforge_python_api-1.3.4.dist-info}/METADATA

@@ -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.dist-info → flashforge_python_api-1.3.4.dist-info}/RECORD

@@ -1,5 +1,6 @@
-flashforge/__init__.py,sha256=0PGa08cJ2RjAlIyJqX4MW3w1I-FUIg8ftaJ6I-A5cc0,5336
+flashforge/__init__.py,sha256=pTj91BlyK6rFMy9yD03q8IowcSrUm9ra-b1vMCYEJDo,5472
 flashforge/client.py,sha256=nDtnv3y9XlEQknIkgIUiuOYAiyTEGbQ7tHBdCs2fg1I,21432
+flashforge/exceptions.py,sha256=rZwBJHyqqtoI6cgd8iGOvPH8EDcytA3lyU3FoVMJgyU,1732
 flashforge/api/__init__.py,sha256=vQz-DkG6LTH39bI4fyiUc0D9jQzemLh45pORLptSOlg,335
 flashforge/api/constants/__init__.py,sha256=Q0HL2tqSBYPd4Oz49VHLS3qUvRuv__GCvTGecaLrQ-Y,163
 flashforge/api/constants/commands.py,sha256=XM2rooBESPDaywlZrfW2ECTaLLFaSKXkJ7FQ-RBmVdY,578
@@ -8,7 +9,7 @@ flashforge/api/controls/__init__.py,sha256=53s-H25Pjwr0kvPk8MZ2Twy8VHGqGcO6Q6uBp
 flashforge/api/controls/control.py,sha256=OgE7K6NkFLwFN1r_q5g1RPwYC8MCt0f6L5CZxDW44d8,15151
 flashforge/api/controls/creator5_palette.py,sha256=zdD3PIXx7hCVj2Fmv1CSFOaqogRUPeBaymgY2DFiMxk,8835
 flashforge/api/controls/files.py,sha256=25yxln9NROas9TtFMZR9e8LtA8ruk8RUu2C81vpNgTk,8043
-flashforge/api/controls/info.py,sha256=jvP4mCkywfV79Uz_z1uJ7qWvEx0MwRoB6ziuvwps_YU,18206
+flashforge/api/controls/info.py,sha256=AZ5529HbB1LBfae6voz_4mz30pQd8R8HpcRrPa5qXCw,22451
 flashforge/api/controls/job_control.py,sha256=NnACm4LPUz4n8lnRiUl33jilWekS1b6HQTbP--nDzZc,33225
 flashforge/api/controls/temp_control.py,sha256=EOO5TkODirjFcnQ7rZrirxAweHBdVin032AWj-Z8VQs,13040
 flashforge/api/filament/__init__.py,sha256=isT2dl0hzUS0xMTXMm4Tip0GTG1gCsm8LKWa9xPu4Y8,104
@@ -23,7 +24,7 @@ flashforge/api/network/utils.py,sha256=Q5-Vj_1VN611QV_TGpDzrrZ2X8PqaGT0j00BhSHv5
 flashforge/discovery/__init__.py,sha256=G0WiP70EhfHdjXR1RNlv6xjhyHOdo-HWyOm9J0ds4SM,828
 flashforge/discovery/discovery.py,sha256=-hOmVIpn8gu-rPYo8FRBfhKb_tBqwamLfmoPVYaDzLI,27614
 flashforge/models/__init__.py,sha256=hdcK0E4KeDfv_A8Y2aPOHgHziwTjP1RPb_VP-89dOzQ,1086
-flashforge/models/machine_info.py,sha256=UD-BQ-VzceSIoFFrpuFPJLpaisdgxBRxVD8SZ20mF4E,19384
+flashforge/models/machine_info.py,sha256=o0rpT6DPWojg8VMfYleMFIqEaidDvsY6E0MstaVHOT0,24065
 flashforge/models/responses.py,sha256=10-8yFfZtLuDmH1TK2xVYl-Uf-zT2WEJnpb2H5ZK3ZU,10637
 flashforge/tcp/__init__.py,sha256=hpnqoWHeRtTwJPzdsVlwGt1njKbAkrgIHKADkLSIRec,1317
 flashforge/tcp/a3_client.py,sha256=Aqb6MuKkjnNUVdE2LbZKd7bPlFK8XPIm17C_BG_PuNU,15867
@@ -41,8 +42,8 @@ flashforge/tcp/parsers/print_status.py,sha256=C-KzukhK0TR86AP3t3XrMH4dief6pa3I-y
 flashforge/tcp/parsers/printer_info.py,sha256=CHPs6nJfEByXyG3co7Nb8_ygggxkYuc7A9O9bpQEqXE,5441
 flashforge/tcp/parsers/temp_info.py,sha256=9wRGUM9cKvDiZD3SIxBx_qVLZbeXoYsoY3-R3vN3H4g,7938
 flashforge/tcp/parsers/thumbnail_info.py,sha256=1U1S_gcIZ2lDpEA4622ywUew6TVw0BnzjlBAiihQwzk,10478
-flashforge_python_api-1.3.3.dist-info/METADATA,sha256=UpYv26NPSHt5nqH57396UOE9s-JcirHPuNsD8e1afBM,4970
-flashforge_python_api-1.3.3.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-flashforge_python_api-1.3.3.dist-info/entry_points.txt,sha256=AkOxlsLvQ7cvMLxn7tlzfKp_DCH2hXhbVceHIXxawpU,66
-flashforge_python_api-1.3.3.dist-info/licenses/LICENSE,sha256=-cTA-hrmvlb3pqlQrBZQXUnKayhUjsLJMPb7TD91frM,1067
-flashforge_python_api-1.3.3.dist-info/RECORD,,
+flashforge_python_api-1.3.4.dist-info/METADATA,sha256=Kdqkl6GJBRr3vRFf6p6Qk-qZ_8TtSUCNS0jdzEIxvHE,4970
+flashforge_python_api-1.3.4.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+flashforge_python_api-1.3.4.dist-info/entry_points.txt,sha256=AkOxlsLvQ7cvMLxn7tlzfKp_DCH2hXhbVceHIXxawpU,66
+flashforge_python_api-1.3.4.dist-info/licenses/LICENSE,sha256=-cTA-hrmvlb3pqlQrBZQXUnKayhUjsLJMPb7TD91frM,1067
+flashforge_python_api-1.3.4.dist-info/RECORD,,