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

flashforge/__init__.py

@@ -128,7 +128,7 @@ from .tcp import (
 )
 
 FiveMClient = FlashForgeClient
-__version__ = "1.3.4"
+__version__ = "1.4.0"
 __author__ = "FlashForge Python API Contributors"
 __email__ = "notghosttypes@gmail.com"
 __description__ = "Python library for controlling FlashForge 3D printers"

flashforge/api/controls/files.py

@@ -69,8 +69,19 @@ class Files:
     async def get_recent_file_list(self) -> list[FFGcodeFileEntry]:
         """
         Retrieves a list of the 10 most recently printed files from the printer's API.
-        For AD5X and newer printers, returns detailed file entries with material info.
-        For older printers, returns basic file entries with normalized data.
+
+        Only the **AD5X** answers with `gcodeListDetail`, the per-file block carrying
+        print time, filament weight, and the per-tool material data that material
+        matching is built from. Every other model - the 5M, the 5M Pro, **and the
+        Creator 5 / Creator 5 Pro** - returns bare file names, and their entries come
+        back with `gcode_tool_datas=None` and `printing_time=0`.
+
+        The Creator 5 is the surprise there, and it is firmware, not a parsing gap:
+        it is a newer printer than the AD5X but reports less (confirmed against a
+        Creator 5 Pro, 2026-08-05). Do not describe this method as "AD5X and newer" -
+        that phrasing cost a downstream integration three releases of chasing a bug
+        that was never in the code. Callers that need per-tool data on a Creator 5
+        must parse the 3mf themselves at upload time.
 
         Returns:
             A list of FFGcodeFileEntry objects. Returns an empty list if the request fails or an error occurs.
@@ -125,7 +136,8 @@ class Files:
                         return entries
                     return []
 
-                # AD5X and newer printers provide detailed info in gcodeListDetail
+                # Only the AD5X provides detailed info in gcodeListDetail. The
+                # Creator 5 series does not, despite being the newer hardware.
                 if result.gcode_list_detail and len(result.gcode_list_detail) > 0:
                     return result.gcode_list_detail
 

flashforge/api/controls/info.py

@@ -46,6 +46,19 @@ PID_MODEL_NAMES: dict[int, str] = {
 }
 
 
+# The one state in which the firmware actually counts `estimatedTime` down.
+# Outside it the field freezes at its last value while the wall clock keeps
+# moving, so `now() + estimatedTime` walks forward one minute per minute instead
+# of holding still - a paused print appears to recede forever. The duration
+# stays correct throughout; only its conversion to an absolute timestamp is
+# invalid, which is why `print_eta` is ungated and `completion_time` is not.
+#
+# HEATING is deliberately excluded. The pre-print warmup does not advance the
+# job either, so the same drift applies - it just lasts minutes rather than
+# hours, which is why it is easy to miss.
+_ADVANCING_STATES = frozenset({MachineState.PRINTING})
+
+
 class MachineInfoParser:
     """
     Transforms printer detail data from the API response format into a structured FFMachineInfo object.
@@ -75,7 +88,14 @@ class MachineInfoParser:
             formatted_run_time = MachineInfoParser._format_time_from_seconds(
                 getattr(detail, "print_duration", 0) or 0
             )
-            completion_time = datetime.now() + timedelta(seconds=estimated_time)
+            machine_state = MachineInfoParser._get_machine_state(
+                getattr(detail, "status", "") or ""
+            )
+            completion_time = (
+                datetime.now() + timedelta(seconds=estimated_time)
+                if machine_state in _ADVANCING_STATES
+                else None
+            )
 
             total_minutes = getattr(detail, "cumulative_print_time", 0) or 0
             hours = total_minutes // 60
@@ -255,9 +275,7 @@ 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=machine_state,
                 status=getattr(detail, "status", "") or "",
                 total_print_layers=getattr(detail, "target_print_layer", 0) or 0,
                 tvoc=getattr(detail, "tvoc", 0) or 0,
@@ -302,7 +320,21 @@ class MachineInfoParser:
 
     @staticmethod
     def _get_machine_state(status: str) -> MachineState:
-        """Map raw status strings into the public machine state enum."""
+        """Map raw status strings into the public machine state enum.
+
+        An unmapped value costs the consumer everything the field is for: it
+        becomes ``UNKNOWN``, which in Home Assistant renders as "unknown" - the
+        one state that says nothing, at the moment the user most needs to know
+        what the printer is doing. Both additions below were found that way, in
+        a log full of `Unknown machine status received` while a Creator 5 Pro sat
+        paused on a detected clog.
+
+        Consumers may map this enum onto a fixed set of values - the Home
+        Assistant integration's Machine Status sensor is a `device_class=ENUM`
+        with an explicit `options` list - so a *new* member is a breaking change
+        for them, while mapping onto an existing one is not. Prefer the closest
+        existing state unless a new one is worth coordinating.
+        """
         valid_status = status.lower() if isinstance(status, str) else ""
         state_mapping = {
             "ready": MachineState.READY,
@@ -312,9 +344,20 @@ class MachineInfoParser:
             "heating": MachineState.HEATING,
             "printing": MachineState.PRINTING,
             "pausing": MachineState.PAUSING,
+            # The Creator 5 Pro reports "pause" for a print that is paused,
+            # where the documented value is "paused" - both are mapped, because
+            # firmware that reports one is not a reason to drop the other.
+            # Observed on pid 41, firmware 1.9.4, whenever the printer paused
+            # itself on a detected clog.
+            "pause": MachineState.PAUSED,
             "paused": MachineState.PAUSED,
             "cancel": MachineState.CANCELLED,
             "completed": MachineState.COMPLETED,
+            # Reported while a file is being transferred to the printer. Not a
+            # print, but not idle either, so BUSY is the honest existing fit; a
+            # dedicated state would need consumers to add it to their option
+            # lists first.
+            "downloading": MachineState.BUSY,
         }
 
         if valid_status in state_mapping:

flashforge/models/machine_info.py

@@ -514,7 +514,12 @@ class FFMachineInfo(BaseModel):
 
     # Extras
     print_eta: str = "00:00"
-    completion_time: datetime = Field(default_factory=datetime.now)
+    # None whenever the print is not advancing (paused, heating, ready, error,
+    # ...). The firmware freezes `estimatedTime` outside the PRINTING state, so
+    # an absolute timestamp derived from it would recede in real time rather
+    # than hold. Use `print_eta` / `estimated_time` for the remaining duration,
+    # which stays valid in every state.
+    completion_time: datetime | None = None
     formatted_run_time: str = "00:00"
     formatted_total_run_time: str = "0h:0m"
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashforge-python-api
-Version: 1.3.4
+Version: 1.4.0
 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.4.dist-info → flashforge_python_api-1.4.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-flashforge/__init__.py,sha256=pTj91BlyK6rFMy9yD03q8IowcSrUm9ra-b1vMCYEJDo,5472
+flashforge/__init__.py,sha256=cYJmX39_FZxN6yyHkwepT_g9mnU2hHuVYuv3Lpg6seY,5472
 flashforge/client.py,sha256=nDtnv3y9XlEQknIkgIUiuOYAiyTEGbQ7tHBdCs2fg1I,21432
 flashforge/exceptions.py,sha256=rZwBJHyqqtoI6cgd8iGOvPH8EDcytA3lyU3FoVMJgyU,1732
 flashforge/api/__init__.py,sha256=vQz-DkG6LTH39bI4fyiUc0D9jQzemLh45pORLptSOlg,335
@@ -8,8 +8,8 @@ flashforge/api/constants/endpoints.py,sha256=oZtOFfkU64THDeCMUIVv6_0L-BOUZzgLKAU
 flashforge/api/controls/__init__.py,sha256=53s-H25Pjwr0kvPk8MZ2Twy8VHGqGcO6Q6uBphhEOh4,293
 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=AZ5529HbB1LBfae6voz_4mz30pQd8R8HpcRrPa5qXCw,22451
+flashforge/api/controls/files.py,sha256=Jk2ySrJdw2QDk1CJlGfY4bTmZJocx4GXztkEqE4rRaI,8830
+flashforge/api/controls/info.py,sha256=7E2TtfFgT79m9lI3nBIvO-536dhl4xzwe1L9XCWVZ78,24836
 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
@@ -24,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=o0rpT6DPWojg8VMfYleMFIqEaidDvsY6E0MstaVHOT0,24065
+flashforge/models/machine_info.py,sha256=OvvpjjUtmOHyogYADFfRJRQnwwPQnjiGVCkXRNdka7Y,24397
 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
@@ -42,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.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,,
+flashforge_python_api-1.4.0.dist-info/METADATA,sha256=VQsv_msrpBzurF7zMQUadt7jpyy1ljomJQxV_XhALIg,4970
+flashforge_python_api-1.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+flashforge_python_api-1.4.0.dist-info/entry_points.txt,sha256=AkOxlsLvQ7cvMLxn7tlzfKp_DCH2hXhbVceHIXxawpU,66
+flashforge_python_api-1.4.0.dist-info/licenses/LICENSE,sha256=-cTA-hrmvlb3pqlQrBZQXUnKayhUjsLJMPb7TD91frM,1067
+flashforge_python_api-1.4.0.dist-info/RECORD,,