How maxioum/peeler works
Project Type and Purpose
• The tool is not a full-stack web application but rather a CLI-based packaging tool focused on Blender add-ons.
• Its primary purpose is twofold:
• Generating a Blender-compatible manifest file (using data from pyproject.toml).
• Managing dependencies by downloading wheels for the project’s dependencies.
• It also integrates with the external tool “uv” for some functionality related to wheels.
File Structure
• Key directories:
• The root directory contains general configuration files (e.g., .gitignore, CHANGELOG.md, LICENSE, pyproject.toml) and CI/CD configurations under the .github directory.
• “peeler-json-schema” handles JSON schemas used for validating some project aspects (likely for the manifest).
• “peeler” is the core module where functionalities are implemented:
▫ The CLI entry point is defined in peeler/cli.py.
▫ Subdirectories under “peeler/command” encapsulate different commands (manifest generation, version handling, wheels management).
▫ “peeler/manifest” holds the functions for validating and writing out the manifest.
▫ “peeler/pyproject” handles parsing, validation, and utilities for processing pyproject.toml.
▫ “peeler/wheels” manages downloading and locking of wheels.
▫ Utility modules (e.g., toml_utils.py, uv_utils.py, utils.py) provide supporting features.
• “tests” mirrors the project structure for comprehensive unit testing.
• The directory structure reveals a modular architecture that separates concerns by command (manifest, wheels, etc.) and utility areas (parsing, validation, downloading).
README for Additional Insights
• The README clearly shows two major functionalities: “Manifest” and “Wheels.”
• It details how the tool converts information from pyproject.toml to blender_manifest.toml.
• It describes the dependency resolution process, including handling nested dependencies.
• Integration with the external tool “uv” is critical, particularly for handling wheels.
• The flow from specifying dependencies in pyproject.toml, running the peeler command, and updating the manifest is the backbone of the tool.
a. Components to Include:
• CLI Interface: Represented by peeler/cli.py which acts as the entry point.
• Command Modules:
▫ Manifest Command Module (peeler/command/manifest.py) – handles parsing of pyproject.toml and writing the blender_manifest.toml.
▫ Wheels Command Module (peeler/command/wheels.py) – retrieves dependency wheels, organizes them, and updates the manifest.
▫ Version Command Module (peeler/command/version.py), if applicable.
• PyProject Parser and Validator (peeler/pyproject/parse.py, validator.py, utils.py) – responsible for reading and validating the pyproject.toml.
• Manifest Generator (peeler/manifest/validate.py, write.py) – applies schema rules (using schemas in peeler-json-schema/data) to generate a valid blender_manifest.
• Wheels Downloader and Locking Mechanism (peeler/wheels/download.py, lock.py) – fetches and manages dependency wheels including the dependency tree.
• Utilities Modules (uv_utils, toml_utils, etc.) – provide support for version control, uv integration, and file handling.
• JSON Schemas Component: Under “peeler-json-schema,” these provide the schema definitions for validating both the manifest and potentially the pyproject format.
• External Integration: “uv” for wheels and Blender commands for add-on builds.
b. Relationships & Workflow:
• The CLI component routes user commands to the relevant command modules.
• The Manifest Command reads the pyproject.toml using the PyProject Parser, validates and extracts required metadata, then uses the Manifest Generator to produce (or update) the blender_manifest.toml.
• When the Wheels Command is invoked, it leverages the Wheels Downloader to resolve and download all required wheels (including dependencies) while updating the manifest with their file paths.
• Utility modules interact across these components, particularly for configuration, file path resolution, and version checking (e.g., uv_utils interact with uv).
• The JSON Schema definitions are used by the parser/validator components to ensure the generated manifest complies with the expected structure.
c. Architectural Patterns & Design Principles:
• Modular design: Separation of concerns among CLI, commands, parsing/validation, wheels handling, and manifest generation.
• Single Responsibility Principle: Each module focuses on a specific aspect of the process.
• Extensibility: The clear structure and separation enable potential extension (e.g., adding new commands or support for additional packaging strategies later on).
d. Technologies, Frameworks, and Libraries:
• Python: The language used to build the tool.
• TOML parsing libraries (implied by use of pyproject.toml and mypy.ini, ruff.toml, etc.).
• Workflow configuration for CI/CD (GitHub Actions).
• External tool “uv” integration indicated in the readme.
• Relevant testing frameworks as seen from the “tests” directory.