How waydotnet/zen-generator works
Project Type & Purpose
• This is a bidirectional code generator that converts between AsyncAPI 3.0 specifications and Python code. The project supports generating pure Python or FastAPI implementations from an AsyncAPI document and vice versa. The command-line interface (CLI) built on Typer lets users run commands like “fastapi”, “pure-python”, and “asyncapi-documentation” to perform these conversions.
Analyzing the File Structure
• Top-Level Files and Directories:
• .github: Contains GitHub workflows for CI/CD (e.g., python-publish.yml).
• LICENSE, README.md, pyproject.toml, .gitignore: Standard project files.
• asyncapi.yaml: A sample/specification file outlining the AsyncAPI structure.
• tests: Contains various test modules for verifying functionality.
• zen_generator: The main package holding the application logic.
∙ cli.py: Likely the entry point for the CLI.
∙ core: Contains submodules such as ast_utils, exception, formatting, io, parsing, and type_system – these modules manage the main business logic, utility functions, and error-handling.
∙ generators: Houses specific generator implementations for asyncapi, common Python, and python code generation.
Components
• CLI Interface:
• Command-line layer that accepts input (commands and options). This triggers specific generator functions.
• How the CLI parses the user-provided arguments and directs processing to the right generator.
• Core Module:
• Detail the “core” folder’s responsibilities: AST utilities for parsing and manipulating code, parsing functions for analyzing AsyncAPI specs, I/O modules for file operations, formatting, type system management, and custom exception handling.
• Generators:
• Three primary generator components – asyncapi, common_python, and python – each handling a specific conversion direction.
• That these generators both consume AsyncAPI specifications (input) and produce Python implementations (pure or FastAPI) and vice versa.
• Test Suite:
• Although not part of the runtime architecture, the tests directory indicates a structured approach to ensure each module’s correctness. You might model this as a quality assurance layer interacting with all other components.
• CI/CD and Dependency Management:
• A note for the CI part (.github/workflows) to indicate automated testing, linting (using Ruff), and publishing steps.
• External Tools:
• The integration with uv, pipx, and uvx for installation and command execution can be shown as user interactions with the system.
Relationships and Interactions
• The CLI (built with Typer) serves as the entry point for commands. It calls the corresponding functions in the generators.
• Each generator module, in turn, leverages the utilities provided in the core module (e.g., parsing AsyncAPI files, formatting outputs, type checking via type_system) to reliably convert between specifications and code.
• Error handling flows from generator functions to the CLI layer, where exceptions defined in the core/exception module manage failures.
• The testing suite interacts with all core and generator modules to simulate real-world usage by invoking these interactions.
Architectural Patterns & Principles
• Separation of Concerns: Clear division exists between CLI input handling, core utility logic (e.g., parsing, formatting), and conversion logic implemented in the generator modules.
• Modularity: Each module in the core and generators packages is designed to be as independent as possible, aiding testing and future enhancements.
• Bidirectional Conversion: The code architecture is built to support both directions—from AsyncAPI specification to Python code and vice versa.
• Extensibility: The folder structure and command modularization (via Typer) allow for future expansion, such as adding new types of code outputs or specifications.