flashforge-python-api 1.0.0__tar.gz → 1.0.1__tar.gz

flashforge_python_api-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,141 @@
+name: Publish to GitHub Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., 1.0.1). Leave empty to auto-generate timestamped version (e.g. 1.0.0-2023...) if tag exists.'
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Hatch
+        run: |
+          pip install hatch
+
+      - name: Determine and Update Version
+        id: version
+        shell: python
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          import os
+          import re
+          import subprocess
+          import sys
+          from datetime import datetime
+
+          def get_current_version():
+              with open("pyproject.toml", "r") as f:
+                  content = f.read()
+              match = re.search(r'version\s*=\s*["\']([^"\']+)["\']', content)
+              if match:
+                  return match.group(1)
+              sys.exit("Could not find version in pyproject.toml")
+
+          def update_pyproject(new_version):
+              with open("pyproject.toml", "r") as f:
+                  content = f.read()
+
+              new_content = re.sub(r'version\s*=\s*["\'][^"\']+["\']', f'version = "{new_version}"', content, count=1)
+
+              with open("pyproject.toml", "w") as f:
+                  f.write(new_content)
+              print(f"Updated pyproject.toml to version {new_version}")
+
+          def tag_exists(tag):
+              try:
+                  subprocess.check_output(["git", "rev-parse", tag], stderr=subprocess.STDOUT)
+                  return True
+              except subprocess.CalledProcessError:
+                  return False
+
+          input_version = os.environ.get("INPUT_VERSION")
+          ref_name = os.environ.get("REF_NAME")
+          current_version = get_current_version()
+          print(f"Current version in pyproject.toml: {current_version}")
+
+          new_version = current_version
+          should_commit = False
+          should_push_commit = False
+
+          if input_version:
+              # Manual version input
+              if input_version != current_version:
+                  new_version = input_version
+                  should_commit = True
+                  should_push_commit = True
+                  print(f"Using input version: {new_version} (Will update, commit, and push)")
+              else:
+                  print("Input version matches current version. (No file change needed)")
+          else:
+              # No input - Check for existing tag
+              tag = f"v{current_version}"
+              if tag_exists(tag):
+                  # Tag exists, generate timestamp version
+                  timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
+                  new_version = f"{current_version}-{timestamp}"
+                  should_commit = True
+                  should_push_commit = False # Do not push ephemeral version to main
+                  print(f"Tag {tag} exists. Generated timestamp version: {new_version} (Will commit locally but NOT push to branch)")
+              else:
+                  print(f"Tag {tag} does not exist. Using current version: {current_version} (First release of this version)")
+
+          # Configure git
+          subprocess.run(["git", "config", "user.name", "github-actions[bot]"], check=True)
+          subprocess.run(["git", "config", "user.email", "github-actions[bot]@users.noreply.github.com"], check=True)
+
+          if should_commit:
+              update_pyproject(new_version)
+              subprocess.run(["git", "add", "pyproject.toml"], check=True)
+              subprocess.run(["git", "commit", "-m", f"Release {new_version}"], check=True)
+
+              if should_push_commit:
+                   # Pull changes to avoid conflicts before pushing
+                  subprocess.run(["git", "fetch", "origin", ref_name], check=True)
+                  subprocess.run(["git", "pull", "--rebase", "origin", ref_name], check=True)
+                  # Push to specific branch
+                  subprocess.run(["git", "push", "origin", f"HEAD:{ref_name}"], check=True)
+              else:
+                  print("Skipping push of commit (Ephemeral/Timestamp release).")
+
+          # Create tag if it doesn't exist
+          tag_name = f"v{new_version}"
+          if not tag_exists(tag_name):
+              print(f"Creating tag {tag_name}")
+              subprocess.run(["git", "tag", tag_name], check=True)
+              subprocess.run(["git", "push", "origin", tag_name], check=True)
+          else:
+             print(f"Tag {tag_name} already exists.")
+
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as fh:
+              fh.write(f"version={new_version}\n")
+
+      - name: Build
+        run: hatch build
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.version }}
+          name: Release ${{ steps.version.outputs.version }}
+          files: dist/*
+          generate_release_notes: true

{flashforge_python_api-1.0.0 → flashforge_python_api-1.0.1}/.gitignore

@@ -116,3 +116,6 @@ coverage.xml
 thumb_*.png
 thumbnail_*.png
 test_*.png
+
+# PyPI credentials
+.pypirc

{flashforge_python_api-1.0.0 → flashforge_python_api-1.0.1}/CHANGELOG.md

@@ -5,6 +5,11 @@ 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).
 
+## [1.0.1] - 2025-12-24
+
+### Fixed
+- Fixed Pydantic validation error for `estimated_time` field in `FFPrinterDetail` and `FFMachineInfo` models. Changed type from `int` to `float` to handle printer API responses that return fractional time values.
+
 ## [1.0.0] - 2025-01-02
 
 ### Added

flashforge_python_api-1.0.1/CLAUDE.md

@@ -0,0 +1,25 @@
+# Claude Development Notes
+
+## PyPI Publishing
+
+### Configuration Files
+- `.pypirc` - Contains PyPI authentication token for publishing packages
+  - Location: Project root directory
+  - Status: Git-ignored (not tracked in version control)
+  - Contains username and API token for automated PyPI uploads
+  - Note: This file exists locally but won't be visible in git status
+
+### Publishing to PyPI
+To publish a new version:
+
+1. Update version in `pyproject.toml`
+2. Clean previous builds: `rm -rf dist/ build/ *.egg-info`
+3. Build: `python -m build`
+4. Upload: `python -m twine upload dist/*`
+   - Credentials will be read automatically from `.pypirc`
+
+### Package Info
+- Package name: `flashforge-python-api`
+- PyPI URL: https://pypi.org/project/flashforge-python-api/
+- Build system: Hatchling
+- Current version: 1.0.0

flashforge_python_api-1.0.1/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: flashforge-python-api
+Version: 1.0.1
+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
+Project-URL: Repository, https://github.com/GhostTypes/ff-5mp-api-py.git
+Project-URL: Issues, https://github.com/GhostTypes/ff-5mp-api-py/issues
+Author-email: GhostTypes <notghosttypes@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d-printer,api,async,control,flashforge,python
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.8
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: netifaces>=0.11.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: all
+Requires-Dist: black>=23.0.0; extra == 'all'
+Requires-Dist: mypy>=1.0.0; extra == 'all'
+Requires-Dist: pillow>=10.0.0; extra == 'all'
+Requires-Dist: pre-commit>=3.0.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
+Requires-Dist: pytest>=7.0.0; extra == 'all'
+Requires-Dist: ruff>=0.1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: imaging
+Requires-Dist: pillow>=10.0.0; extra == 'imaging'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# FlashForge Python API
+
+A comprehensive Python library for controlling FlashForge 3D printers.
+
+[![PyPI](https://img.shields.io/pypi/v/flashforge-python-api?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/flashforge-python-api/)
+[![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](LICENSE)
+
+</div>
+
+<div align="center">
+
+## Features & Capabilities
+
+| Feature | Description |
+| :--- | :--- |
+| **Printer Discovery** | Automatic UDP broadcast discovery of printers on the network |
+| **Full Control** | Movement (G1), Homing (G28), Temperature (M104/M140), Fans, LED |
+| **Real-time Monitoring** | Live status (M119), Temperatures (M105), Print Progress (M27) |
+| **Job Management** | Start, Pause, Resume, Cancel, File Upload & Listing |
+| **Advanced Parsing** | Thumbnail extraction (M662), Endstop monitoring, Machine state |
+| **Dual Protocol** | Modern HTTP API + Legacy TCP G-code support |
+| **Async Support** | Native async/await implementation for all operations |
+| **Type Safety** | Full type hints and Pydantic models for robust development |
+
+<br>
+
+## Supported Hardware
+
+| Model | Support Level | Connection Type |
+| :--- | :--- | :--- |
+| **FlashForge Adventurer 5M / 5M Pro** | Full Support | HTTP + TCP |
+| **FlashForge Adventurer 5X** | Full Support | HTTP + TCP |
+| **FlashForge Adventurer 3 / 4** | Partial Support | TCP (Legacy) |
+| **Other Networked FlashForge Printers** | Experimental | TCP (Generic) |
+
+<br>
+
+## Compatible Slicers
+
+| Slicer | Compatibility | Notes |
+| :--- | :--- | :--- |
+| **OrcaSlicer** | High | Recommended for Adventurer 5M series |
+| **FlashPrint** | Full | Official FlashForge slicer |
+| **Orca-FlashForge** | High | Optimized for FlashForge printers |
+| **Cura / PrusaSlicer** | Basic | Requires correct G-code flavor |
+
+<br>
+
+## Installation
+
+| Command |
+| :--- |
+| `pip install flashforge-python-api` |
+
+</div>
+
+<div align="center">
+<h2>Usage Examples</h2>
+</div>
+
+<div align="center">
+<h3>Printer Discovery</h3>
+Discover printers on your local network automatically.
+</div>
+
+```python
+from flashforge import FlashForgePrinterDiscovery
+import asyncio
+
+async def discover():
+    discovery = FlashForgePrinterDiscovery()
+    printers = await discovery.discover_printers_async()
+    for printer in printers:
+        print(f"Found: {printer.name} at {printer.ip_address}")
+
+asyncio.run(discover())
+```
+
+<div align="center">
+<h3>Basic Control</h3>
+Connect to a printer and perform basic operations like setting temperature and homing.
+</div>
+
+```python
+from flashforge import FlashForgeClient
+import asyncio
+
+async def control_printer():
+    # Initialize client with printer details
+    client = FlashForgeClient("192.168.1.100", "SERIAL_NUMBER", "CHECK_CODE")
+
+    if await client.initialize():
+        print(f"Connected to {client.printer_name}")
+
+        # Set bed temperature to 60°C
+        await client.temp_control.set_bed_temp(60)
+
+        # Home all axes
+        await client.control.home_xyz()
+
+        await client.dispose()
+
+asyncio.run(control_printer())
+```
+
+<div align="center">
+<h3>Real-time Status Monitoring</h3>
+Monitor printer status, temperatures, and print progress.
+</div>
+
+```python
+from flashforge import FlashForgeClient
+import asyncio
+
+async def monitor_printer():
+    async with FlashForgeClient("192.168.1.100", "SERIAL", "CODE") as client:
+        # Get comprehensive status
+        status = await client.get_printer_status()
+        print(f"Machine State: {status.machine_state}")
+
+        # Get temperatures via TCP
+        temps = await client.tcp_client.get_temp_info()
+        if temps:
+            bed = temps.get_bed_temp()
+            extruder = temps.get_extruder_temp()
+            print(f"Bed: {bed.get_current()}°C / {bed.get_target()}°C")
+            print(f"Extruder: {extruder.get_current()}°C / {extruder.get_target()}°C")
+
+        # Check print progress
+        layer_p, sd_p, current_layer = await client.tcp_client.get_print_progress()
+        print(f"Progress: {layer_p}% (Layer {current_layer})")
+
+asyncio.run(monitor_printer())
+```
+
+<div align="center">
+<h3>File Operations & Thumbnails</h3>
+List files on the printer and extract thumbnails.
+</div>
+
+```python
+from flashforge import FlashForgeClient
+import asyncio
+
+async def file_ops():
+    async with FlashForgeClient("192.168.1.100", "SERIAL", "CODE") as client:
+        # List files
+        files = await client.files.get_file_list()
+        for filename in files:
+            print(f"File: {filename}")
+
+            # Get thumbnail
+            thumb = await client.tcp_client.get_thumbnail(filename)
+            if thumb and thumb.has_image_data():
+                print(f"Thumbnail found: {len(thumb.get_image_bytes())} bytes")
+                # thumb.save_to_file_sync(f"{filename}.png")
+
+asyncio.run(file_ops())
+```

flashforge_python_api-1.0.1/README.md

@@ -0,0 +1,162 @@
+<div align="center">
+
+# FlashForge Python API
+
+A comprehensive Python library for controlling FlashForge 3D printers.
+
+[![PyPI](https://img.shields.io/pypi/v/flashforge-python-api?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/flashforge-python-api/)
+[![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](LICENSE)
+
+</div>
+
+<div align="center">
+
+## Features & Capabilities
+
+| Feature | Description |
+| :--- | :--- |
+| **Printer Discovery** | Automatic UDP broadcast discovery of printers on the network |
+| **Full Control** | Movement (G1), Homing (G28), Temperature (M104/M140), Fans, LED |
+| **Real-time Monitoring** | Live status (M119), Temperatures (M105), Print Progress (M27) |
+| **Job Management** | Start, Pause, Resume, Cancel, File Upload & Listing |
+| **Advanced Parsing** | Thumbnail extraction (M662), Endstop monitoring, Machine state |
+| **Dual Protocol** | Modern HTTP API + Legacy TCP G-code support |
+| **Async Support** | Native async/await implementation for all operations |
+| **Type Safety** | Full type hints and Pydantic models for robust development |
+
+<br>
+
+## Supported Hardware
+
+| Model | Support Level | Connection Type |
+| :--- | :--- | :--- |
+| **FlashForge Adventurer 5M / 5M Pro** | Full Support | HTTP + TCP |
+| **FlashForge Adventurer 5X** | Full Support | HTTP + TCP |
+| **FlashForge Adventurer 3 / 4** | Partial Support | TCP (Legacy) |
+| **Other Networked FlashForge Printers** | Experimental | TCP (Generic) |
+
+<br>
+
+## Compatible Slicers
+
+| Slicer | Compatibility | Notes |
+| :--- | :--- | :--- |
+| **OrcaSlicer** | High | Recommended for Adventurer 5M series |
+| **FlashPrint** | Full | Official FlashForge slicer |
+| **Orca-FlashForge** | High | Optimized for FlashForge printers |
+| **Cura / PrusaSlicer** | Basic | Requires correct G-code flavor |
+
+<br>
+
+## Installation
+
+| Command |
+| :--- |
+| `pip install flashforge-python-api` |
+
+</div>
+
+<div align="center">
+<h2>Usage Examples</h2>
+</div>
+
+<div align="center">
+<h3>Printer Discovery</h3>
+Discover printers on your local network automatically.
+</div>
+
+```python
+from flashforge import FlashForgePrinterDiscovery
+import asyncio
+
+async def discover():
+    discovery = FlashForgePrinterDiscovery()
+    printers = await discovery.discover_printers_async()
+    for printer in printers:
+        print(f"Found: {printer.name} at {printer.ip_address}")
+
+asyncio.run(discover())
+```
+
+<div align="center">
+<h3>Basic Control</h3>
+Connect to a printer and perform basic operations like setting temperature and homing.
+</div>
+
+```python
+from flashforge import FlashForgeClient
+import asyncio
+
+async def control_printer():
+    # Initialize client with printer details
+    client = FlashForgeClient("192.168.1.100", "SERIAL_NUMBER", "CHECK_CODE")
+
+    if await client.initialize():
+        print(f"Connected to {client.printer_name}")
+
+        # Set bed temperature to 60°C
+        await client.temp_control.set_bed_temp(60)
+
+        # Home all axes
+        await client.control.home_xyz()
+
+        await client.dispose()
+
+asyncio.run(control_printer())
+```
+
+<div align="center">
+<h3>Real-time Status Monitoring</h3>
+Monitor printer status, temperatures, and print progress.
+</div>
+
+```python
+from flashforge import FlashForgeClient
+import asyncio
+
+async def monitor_printer():
+    async with FlashForgeClient("192.168.1.100", "SERIAL", "CODE") as client:
+        # Get comprehensive status
+        status = await client.get_printer_status()
+        print(f"Machine State: {status.machine_state}")
+
+        # Get temperatures via TCP
+        temps = await client.tcp_client.get_temp_info()
+        if temps:
+            bed = temps.get_bed_temp()
+            extruder = temps.get_extruder_temp()
+            print(f"Bed: {bed.get_current()}°C / {bed.get_target()}°C")
+            print(f"Extruder: {extruder.get_current()}°C / {extruder.get_target()}°C")
+
+        # Check print progress
+        layer_p, sd_p, current_layer = await client.tcp_client.get_print_progress()
+        print(f"Progress: {layer_p}% (Layer {current_layer})")
+
+asyncio.run(monitor_printer())
+```
+
+<div align="center">
+<h3>File Operations & Thumbnails</h3>
+List files on the printer and extract thumbnails.
+</div>
+
+```python
+from flashforge import FlashForgeClient
+import asyncio
+
+async def file_ops():
+    async with FlashForgeClient("192.168.1.100", "SERIAL", "CODE") as client:
+        # List files
+        files = await client.files.get_file_list()
+        for filename in files:
+            print(f"File: {filename}")
+
+            # Get thumbnail
+            thumb = await client.tcp_client.get_thumbnail(filename)
+            if thumb and thumb.has_image_data():
+                print(f"Thumbnail found: {len(thumb.get_image_bytes())} bytes")
+                # thumb.save_to_file_sync(f"{filename}.png")
+
+asyncio.run(file_ops())
+```

flashforge_python_api-1.0.1/docs/README.md

@@ -0,0 +1,87 @@
+# FlashForge API Documentation
+
+Welcome to the documentation for the FlashForge Python API. This library provides a comprehensive interface for controlling and monitoring FlashForge 3D printers, including the Adventurer 5M and 5M Pro series.
+
+## Overview
+
+The FlashForge API allows you to interact with your printer using both TCP and HTTP protocols. It provides a unified client that handles connection management, command execution, and status monitoring.
+
+## Key Features
+
+- **Unified Client**: A single entry point (`FlashForgeClient`) for all printer operations.
+- **Automatic Discovery**: Find printers on your local network automatically.
+- **Full Control**: Manage print jobs, movement, temperature, fans, LEDs, and more.
+- **Real-time Monitoring**: Get detailed status updates, including temperatures, progress, and camera feed URL.
+- **File Management**: List, upload, and delete files on the printer.
+- **Type Safety**: Fully typed with Pydantic models for robust data handling.
+- **Async Support**: Built on `asyncio` for efficient non-blocking operations.
+
+## Navigation
+
+- [Getting Started](#getting-started)
+- [Client API](client.md): Documentation for the main `FlashForgeClient` and `FlashForgePrinterDiscovery`.
+- [Data Models](models.md): Detailed reference for all data objects (MachineInfo, Temperature, etc.).
+- [Protocols](protocols.md): Understanding the underlying TCP and HTTP protocols.
+- [Advanced Topics](advanced.md): Async patterns, error handling, and more.
+- [API Reference](api_reference.md): Complete list of classes and methods.
+
+## Getting Started
+
+### Installation
+
+```bash
+pip install flashforge-api
+```
+
+### Basic Usage
+
+Here's a simple example of how to discover a printer and connect to it:
+
+```python
+import asyncio
+from flashforge import FlashForgePrinterDiscovery, FlashForgeClient
+
+async def main():
+    # 1. Discover printers
+    discovery = FlashForgePrinterDiscovery()
+    printers = await discovery.discover_printers_async()
+
+    if not printers:
+        print("No printers found.")
+        return
+
+    printer_info = printers[0]
+    print(f"Found printer: {printer_info.name} at {printer_info.ip_address}")
+
+    # 2. Connect to the printer
+    # Note: 'check_code' is currently unused by some printers but required by the constructor
+    client = FlashForgeClient(printer_info.ip_address, printer_info.serial_number, check_code="")
+
+    await client.initialize()
+
+    # 3. Get printer status
+    status = await client.get_printer_status()
+    print(f"Status: {status.machine_state}")
+    print(f"Bed Temp: {status.print_bed.current}°C")
+    print(f"Nozzle Temp: {status.extruder.current}°C")
+
+    # 4. Clean up
+    await client.dispose()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Context Manager Support
+
+The client supports Python's async context manager protocol for automatic resource management:
+
+```python
+async with FlashForgeClient(ip, serial, check_code="") as client:
+    status = await client.get_printer_status()
+    print(f"Ready: {status.machine_state == 'ready'}")
+```
+
+## Support
+
+If you encounter any issues or have questions, please check the [Issues](https://github.com/yourusername/flashforge-api/issues) page on GitHub.