flashforge-python-api 1.0.2__py3-none-any.whl → 1.2.0__py3-none-any.whl

flashforge/models/__init__.py

@@ -1,28 +1,29 @@
 """
 FlashForge Python API - Models Package
 """
+
 from .machine_info import (
-    FFMachineInfo,
-    FFPrinterDetail,
     FFGcodeFileEntry,
     FFGcodeToolData,
+    FFMachineInfo,
+    FFPrinterDetail,
+    IndepMatlInfo,
     MachineState,
-    Temperature,
-    SlotInfo,
     MatlStationInfo,
-    IndepMatlInfo,
+    SlotInfo,
+    Temperature,
 )
 from .responses import (
+    AD5XLocalJobParams,
+    AD5XMaterialMapping,
+    AD5XSingleColorJobParams,
+    AD5XUploadParams,
     DetailResponse,
     FilamentArgs,
+    GCodeListResponse,
     GenericResponse,
     Product,
     ProductResponse,
-    AD5XMaterialMapping,
-    AD5XLocalJobParams,
-    AD5XSingleColorJobParams,
-    AD5XUploadParams,
-    GCodeListResponse,
     ThumbnailResponse,
 )
 

flashforge/models/machine_info.py

@@ -1,17 +1,18 @@
 """
 FlashForge Python API - Data Models
 """
+
 from __future__ import annotations
 
 from datetime import datetime
 from enum import Enum
-from typing import Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 
 class MachineState(Enum):
     """Enumerates the possible operational states of the FlashForge 3D printer."""
+
     READY = "ready"
     BUSY = "busy"
     CALIBRATING = "calibrating"
@@ -27,68 +28,168 @@ class MachineState(Enum):
 
 class Temperature(BaseModel):
     """Represents a pair of current and target temperatures for a component like an extruder or print bed."""
-    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")
+
+    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"
+    )
 
 
 class SlotInfo(BaseModel):
     """Information about a single slot in the material station."""
-    has_filament: bool = Field(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')")
-    material_name: str = Field(alias="materialName", description="Name of the material in this slot (e.g., 'PLA')")
-    slot_id: int = Field(alias="slotId", description="Identifier for this slot")
 
-    class Config:
-        populate_by_name = True
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    has_filament: bool = Field(
+        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')"
+    )
+    material_name: str = Field(
+        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)")
+
+    @field_validator("material_color")
+    @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}")
 
 
 class MatlStationInfo(BaseModel):
     """Detailed information about the material station."""
-    current_load_slot: int = Field(alias="currentLoadSlot", description="Currently loading slot ID (0 if none)")
-    current_slot: int = Field(alias="currentSlot", description="Currently active/printing slot ID (0 if none)")
-    slot_cnt: int = Field(alias="slotCnt", description="Total number of slots in the station")
-    slot_infos: list[SlotInfo] = Field(default_factory=list, alias="slotInfos", description="Array of information for each slot")
-    state_action: int = Field(alias="stateAction", description="Current action state of the material station")
-    state_step: int = Field(alias="stateStep", description="Current step within the state action")
 
-    class Config:
-        populate_by_name = True
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    current_load_slot: int = Field(
+        alias="currentLoadSlot", ge=0, le=4, 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)"
+    )
+    slot_cnt: int = Field(
+        alias="slotCnt", ge=1, le=4, 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"
+    )
+    state_step: int = Field(
+        alias="stateStep", ge=0, description="Current step within the state action"
+    )
 
 
 class IndepMatlInfo(BaseModel):
     """Information related to independent material loading, often used when a single extruder printer has a material station."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
     material_color: str = Field(alias="materialColor", description="Color of the material")
-    material_name: str = Field(alias="materialName", description="Name of the material (can be '?' if unknown)")
-    state_action: int = Field(alias="stateAction", description="Current action state")
-    state_step: int = Field(alias="stateStep", description="Current step within the state action")
+    material_name: str = Field(
+        alias="materialName", description="Name of the material (can be '?' if unknown)"
+    )
+    state_action: int = Field(alias="stateAction", ge=0, description="Current action state")
+    state_step: int = Field(
+        alias="stateStep", ge=0, description="Current step within the state action"
+    )
+
+    @field_validator("material_color")
+    @classmethod
+    def validate_hex_color(cls, v: str) -> str:
+        """Validate that the color is a valid hex color code or empty string."""
+        import re
 
-    class Config:
-        populate_by_name = True
+        if v == "" or re.match(r"^#[0-9A-Fa-f]{6}$", v):
+            return v
+        raise ValueError(f"Invalid hex color format: {v}")
 
 
 class FFGcodeToolData(BaseModel):
     """Represents data for a single tool/material used in a G-code file, typically part of a multi-material print."""
-    filament_weight: float = Field(alias="filamentWeight", 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')")
-    material_name: str = Field(alias="materialName", description="Name of the material (e.g., 'PLA')")
-    slot_id: int = Field(alias="slotId", description="Slot ID from the material station, if applicable (0 if not or direct)")
-    tool_id: int = Field(alias="toolId", description="Tool ID or extruder number")
 
-    class Config:
-        populate_by_name = True
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    filament_weight: float = Field(
+        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')"
+    )
+    material_name: str = Field(
+        alias="materialName", description="Name of the material (e.g., 'PLA')"
+    )
+    slot_id: int = Field(
+        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)")
+
+    @field_validator("material_color")
+    @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}")
 
 
 class FFGcodeFileEntry(BaseModel):
     """Represents a single G-code file entry as returned by the /gcodeList endpoint, especially for printers like AD5X that provide detailed material info."""
-    gcode_file_name: str = Field(alias="gcodeFileName", description="The name of the G-code file (e.g., 'FISH_PLA.3mf')")
-    gcode_tool_cnt: Optional[int] = Field(default=None, alias="gcodeToolCnt", description="Number of tools/materials used in this G-code file")
-    gcode_tool_datas: Optional[list[FFGcodeToolData]] = Field(default=None, alias="gcodeToolDatas", description="Array of detailed information for each tool/material")
-    printing_time: int = Field(alias="printingTime", description="Estimated printing time in seconds")
-    total_filament_weight: Optional[float] = Field(default=None, alias="totalFilamentWeight", description="Total estimated filament weight for the print")
-    use_matl_station: Optional[bool] = Field(default=None, alias="useMatlStation", description="Indicates if the G-code file is intended for use with a material station")
 
-    class Config:
-        populate_by_name = True
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    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"
+    )
+    total_filament_weight: float | None = Field(
+        default=None,
+        ge=0,
+        alias="totalFilamentWeight",
+        description="Total estimated filament weight for the print",
+    )
+    use_matl_station: bool | None = Field(
+        default=None,
+        alias="useMatlStation",
+        description="Indicates if the G-code file is intended for use with a material station",
+    )
 
 
 class FFPrinterDetail(BaseModel):
@@ -97,64 +198,78 @@ class FFPrinterDetail(BaseModel):
     Properties are often in the printer's native naming format and may include string representations
     of boolean states (e.g., "open", "close").
     """
-    auto_shutdown: Optional[str] = Field(default=None, alias="autoShutdown")
-    auto_shutdown_time: Optional[int] = Field(default=None, alias="autoShutdownTime")
-    camera_stream_url: Optional[str] = Field(default=None, alias="cameraStreamUrl")
-    chamber_fan_speed: Optional[int] = Field(default=None, alias="chamberFanSpeed")
-    chamber_target_temp: Optional[float] = Field(default=None, alias="chamberTargetTemp")
-    chamber_temp: Optional[float] = Field(default=None, alias="chamberTemp")
-    cooling_fan_speed: Optional[int] = Field(default=None, alias="coolingFanSpeed")
-    cooling_fan_left_speed: Optional[int] = Field(default=None, alias="coolingFanLeftSpeed")
-    cumulative_filament: Optional[float] = Field(default=None, alias="cumulativeFilament")
-    cumulative_print_time: Optional[int] = Field(default=None, alias="cumulativePrintTime")
-    current_print_speed: Optional[int] = Field(default=None, alias="currentPrintSpeed")
-    door_status: Optional[str] = Field(default=None, alias="doorStatus")
-    error_code: Optional[str] = Field(default=None, alias="errorCode")
-    estimated_left_len: Optional[float] = Field(default=None, alias="estimatedLeftLen")
-    estimated_left_weight: Optional[float] = Field(default=None, alias="estimatedLeftWeight")
-    estimated_right_len: Optional[float] = Field(default=None, alias="estimatedRightLen")
-    estimated_right_weight: Optional[float] = Field(default=None, alias="estimatedRightWeight")
-    estimated_time: Optional[float] = Field(default=None, alias="estimatedTime")
-    external_fan_status: Optional[str] = Field(default=None, alias="externalFanStatus")
-    fill_amount: Optional[float] = Field(default=None, alias="fillAmount")
-    firmware_version: Optional[str] = Field(default=None, alias="firmwareVersion")
-    flash_register_code: Optional[str] = Field(default=None, alias="flashRegisterCode")
-    has_matl_station: Optional[bool] = Field(default=None, alias="hasMatlStation")
-    matl_station_info: Optional[MatlStationInfo] = Field(default=None, alias="matlStationInfo")
-    indep_matl_info: Optional[IndepMatlInfo] = Field(default=None, alias="indepMatlInfo")
-    has_left_filament: Optional[bool] = Field(default=None, alias="hasLeftFilament")
-    has_right_filament: Optional[bool] = Field(default=None, alias="hasRightFilament")
-    internal_fan_status: Optional[str] = Field(default=None, alias="internalFanStatus")
-    ip_addr: Optional[str] = Field(default=None, alias="ipAddr")
-    left_filament_type: Optional[str] = Field(default=None, alias="leftFilamentType")
-    left_target_temp: Optional[float] = Field(default=None, alias="leftTargetTemp")
-    left_temp: Optional[float] = Field(default=None, alias="leftTemp")
-    light_status: Optional[str] = Field(default=None, alias="lightStatus")
-    location: Optional[str] = Field(default=None, alias="location")
-    mac_addr: Optional[str] = Field(default=None, alias="macAddr")
-    measure: Optional[str] = Field(default=None, alias="measure")
-    name: Optional[str] = Field(default=None, alias="name")
-    nozzle_cnt: Optional[int] = Field(default=None, alias="nozzleCnt")
-    nozzle_model: Optional[str] = Field(default=None, alias="nozzleModel")
-    nozzle_style: Optional[int] = Field(default=None, alias="nozzleStyle")
-    pid: Optional[int] = Field(default=None, alias="pid")
-    plat_target_temp: Optional[float] = Field(default=None, alias="platTargetTemp")
-    plat_temp: Optional[float] = Field(default=None, alias="platTemp")
-    polar_register_code: Optional[str] = Field(default=None, alias="polarRegisterCode")
-    print_duration: Optional[int] = Field(default=None, alias="printDuration")
-    print_file_name: Optional[str] = Field(default=None, alias="printFileName")
-    print_file_thumb_url: Optional[str] = Field(default=None, alias="printFileThumbUrl")
-    print_layer: Optional[int] = Field(default=None, alias="printLayer")
-    print_progress: Optional[float] = Field(default=None, alias="printProgress")
-    print_speed_adjust: Optional[int] = Field(default=None, alias="printSpeedAdjust")
-    remaining_disk_space: Optional[float] = Field(default=None, alias="remainingDiskSpace")
-    right_filament_type: Optional[str] = Field(default=None, alias="rightFilamentType")
-    right_target_temp: Optional[float] = Field(default=None, alias="rightTargetTemp")
-    right_temp: Optional[float] = Field(default=None, alias="rightTemp")
-    status: Optional[str] = Field(default=None, alias="status")
-    target_print_layer: Optional[int] = Field(default=None, alias="targetPrintLayer")
-    tvoc: Optional[float] = Field(default=None, alias="tvoc")
-    z_axis_compensation: Optional[float] = Field(default=None, alias="zAxisCompensation")
+
+    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")
+    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")
+    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"
+    )
+    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=200, 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")
+    external_fan_status: str | None = Field(default=None, alias="externalFanStatus")
+    fill_amount: float | None = Field(default=None, ge=0, le=100, alias="fillAmount")
+    firmware_version: str | None = Field(default=None, alias="firmwareVersion")
+    flash_register_code: str | None = Field(default=None, alias="flashRegisterCode")
+    has_matl_station: bool | None = Field(default=None, alias="hasMatlStation")
+    matl_station_info: MatlStationInfo | None = Field(default=None, alias="matlStationInfo")
+    indep_matl_info: IndepMatlInfo | None = Field(default=None, alias="indepMatlInfo")
+    has_left_filament: bool | None = Field(default=None, alias="hasLeftFilament")
+    has_right_filament: bool | None = Field(default=None, alias="hasRightFilament")
+    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")
+    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")
+    name: str | None = Field(default=None, alias="name")
+    nozzle_cnt: int | None = Field(default=None, ge=1, le=4, alias="nozzleCnt")
+    nozzle_model: str | None = Field(default=None, alias="nozzleModel")
+    nozzle_style: int | None = Field(default=None, ge=0, alias="nozzleStyle")
+    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")
+    polar_register_code: str | None = Field(default=None, alias="polarRegisterCode")
+    print_duration: int | None = Field(default=None, ge=0, 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=200, alias="printSpeedAdjust")
+    remaining_disk_space: float | None = Field(default=None, ge=0, 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")
+    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"
+    )
 
 
 class FFMachineInfo(BaseModel):
@@ -162,6 +277,9 @@ class FFMachineInfo(BaseModel):
     Represents a structured and user-friendly model of the printer's information and state.
     This interface is populated by transforming data from FFPrinterDetail.
     """
+
+    model_config = ConfigDict(extra="forbid")
+
     # Auto-shutdown settings
     auto_shutdown: bool = False
     auto_shutdown_time: int = 0
@@ -172,7 +290,7 @@ class FFMachineInfo(BaseModel):
     # Fan speeds
     chamber_fan_speed: int = 0
     cooling_fan_speed: int = 0
-    cooling_fan_left_speed: Optional[int] = None
+    cooling_fan_left_speed: int | None = None
 
     # Cumulative stats
     cumulative_filament: float = 0.0
@@ -242,6 +360,13 @@ class FFMachineInfo(BaseModel):
     formatted_total_run_time: str = "0h:0m"
 
     # AD5X Material Station
-    has_matl_station: Optional[bool] = None
-    matl_station_info: Optional[MatlStationInfo] = None
-    indep_matl_info: Optional[IndepMatlInfo] = None
+    has_matl_station: bool | None = None
+    matl_station_info: MatlStationInfo | None = None
+    indep_matl_info: IndepMatlInfo | None = None
+
+    @model_validator(mode="after")
+    def validate_print_progress(self) -> FFMachineInfo:
+        """Ensure print progress integer matches float value."""
+        if self.print_progress is not None:
+            self.print_progress_int = max(0, min(100, int(self.print_progress * 100)))
+        return self