{"id":26276722,"url":"https://github.com/waydotnet/zen-generator","last_synced_at":"2025-09-08T00:45:45.008Z","repository":{"id":281834693,"uuid":"946140555","full_name":"WaYdotNET/zen-generator","owner":"WaYdotNET","description":"A bidirectional Python code generator that converts between AsyncAPI 3.0 specifications and Python code (pure Python or FastAPI implementations).","archived":false,"fork":false,"pushed_at":"2025-04-29T20:50:12.000Z","size":397,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-06T00:42:29.899Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WaYdotNET.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-10T17:12:08.000Z","updated_at":"2025-06-22T23:18:38.000Z","dependencies_parsed_at":"2025-03-11T12:20:03.284Z","dependency_job_id":"1eb5952e-a9a9-4a8d-bf4f-2113acd5eea7","html_url":"https://github.com/WaYdotNET/zen-generator","commit_stats":null,"previous_names":["waydotnet/zen-generator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/WaYdotNET/zen-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaYdotNET%2Fzen-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaYdotNET%2Fzen-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaYdotNET%2Fzen-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaYdotNET%2Fzen-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WaYdotNET","download_url":"https://codeload.github.com/WaYdotNET/zen-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WaYdotNET%2Fzen-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274117525,"owners_count":25225104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-14T11:19:10.292Z","updated_at":"2025-09-08T00:45:44.999Z","avatar_url":"https://github.com/WaYdotNET.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://github.com/WaYdotNET/zen-generator/raw/main/zen-generator-small.png\" alt=\"Zen Generator Logo\" width=\"200\" height=\"200\"\u003e\n\n# Zen Generator 🚀\n\n[![PyPI version](https://badge.fury.io/py/zen-generator.svg)](https://badge.fury.io/py/zen-generator)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100/)\n[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-orange.svg)](https://github.com/charliermarsh/ruff)\n[![PyPI Downloads](https://static.pepy.tech/badge/zen-generator)](https://pepy.tech/projects/zen-generator)\n\n\nA bidirectional Python code generator that converts between AsyncAPI 3.0 specifications and Python code (pure Python or FastAPI implementations).\n\n## Features ✨\n\n- 🔄 Bidirectional conversion between [AsyncAPI 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) and Python code\n- 🐍 Generate Python code from AsyncAPI 3.0 specifications:\n  - 🐍 Pure Python implementations with type hints\n  - ⚡ FastAPI endpoints with Pydantic models\n- 📄 Generate AsyncAPI 3.0 specifications from Python code\n- 🧠 Automatic type inference and mapping\n- ⚡ Support for both async and sync functions\n\n## Installation 📦\n\n**with [uv](https://docs.astral.sh/uv/)**:\n```bash\nuv tool install zen-generator\n```\n\n**with [pipx](https://pipx.pypa.io/stable/)**:\n```bash\npipx install zen-generator\n```\n\n**with [uvx](https://docs.astral.sh/uv/guides/tools/)**:\n```bash\nuvx zen-generator\n```\n\n\u003e [!IMPORTANT]\n\u003e Currently, only model and function definitions in the `components` block of the AsyncAPI file are supported.\n\u003e Inline definitions are not supported.\n\n\u003e [!NOTE] \n\u003e This code snippet includes a custom definition for declaring required parameters in model/function definitions.\n\u003e Specifically, the `required` keyword is used to specify mandatory fields, as shown below:\n\n```yaml\nrequired:\n  - user_id\n```\n\u003e This ensures that the `user_id` parameter is always provided when the model or function is utilized.\n\n## Quick Start 🏃\n\nConvert between AsyncAPI 3.0 specifications and Python code:\n\n```bash\n# Generate FastAPI implementation from AsyncAPI spec\nuvx zen-generator fastapi\n\n# Generate pure Python implementation from AsyncAPI spec\nuvx zen-generator pure-python\n\n# Generate AsyncAPI spec from Python code\nuvx zen-generator asyncapi-documentation\n```\n\n### Command Line Interface\n\nThe CLI is built with Typer and provides three main commands:\n\n**Usage**:\n\n```console\n$ [OPTIONS] COMMAND [ARGS]...\n```\n\n**Options**:\n\n- `--install-completion`: Install completion for the current shell.\n- `--show-completion`: Show completion for the current shell, to copy it or customize the installation.\n- `--help`: Show this message and exit.\n\n**Commands**:\n\n- `asyncapi-documentation`\n- `pure-python`\n- `fastapi`\n\n## `asyncapi-documentation`\n\n**Usage**:\n\n```console\n$ asyncapi-documentation [OPTIONS]\n```\n\n**Options**:\n\n- `--models-file PATH`: [default: models.py]\n- `--functions-file PATH`: [default: functions.py]\n- `--output-file PATH`: [default: asyncapi.yaml]\n- `--application-name TEXT`: [default: Zen]\n- `--help`: Show this message and exit.\n\n## `pure-python`\n\n**Usage**:\n\n```console\n$ pure-python [OPTIONS]\n```\n\n**Options**:\n\n- `--asyncapi-file PATH`: [default: asyncapi.yaml]\n- `--models-file PATH`: [default: models.py]\n- `--functions-file PATH`: [default: functions.py]\n- `--application-name TEXT`: [default: Zen]\n- `--is-async / --no-is-async`: [default: no-is-async]\n- `--help`: Show this message and exit.\n\n## `fastapi`\n\n**Usage**:\n\n```console\n$ fastapi [OPTIONS]\n```\n\n**Options**:\n\n- `--asyncapi-file PATH`: [default: asyncapi.yaml]\n- `--models-file PATH`: [default: models.py]\n- `--functions-file PATH`: [default: functions.py]\n- `--application-name TEXT`: [default: Zen]\n- `--is-async / --no-is-async`: [default: no-is-async]\n- `--help`: Show this message and exit.\n\n## Generated Code Examples 📝\n\n### Pure Python Implementation (models.py)\n\n```python\nfrom __future__ import annotations\n\nfrom typing import TypedDict\n\n\nclass UserModel(TypedDict):\n    id: int\n    name: str\n    email: str | None = None\n```\n\n### Pure Python Implementation (functions.py)\n\n```python\nfrom __future__ import annotations\n\nfrom .models import UserModel\n\ndef get_user(user_id: int) -\u003e UserModel:\n    ...\n```\n\n### FastAPI Implementation (models.py)\n\n```python\nfrom __future__annotations\n\nfrom pydantic import BaseModel\n\nclass UserModel(BaseModel):\n    id: int\n    name: str\n    email: str | None = None\n```\n\n### FastAPI Implementation (functions.py)\n\n```python\nfrom __future__annotations\n\nfrom fastapi import FastAPI\n\nfrom .models import UserModel\n\napp = FastAPI()\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: int) -\u003e UserModel:\n    ...\n```\n\n### Asyncapi documentation (asyncapi.yaml)\n\n```yaml\nasyncapi: 3.0.0\ninfo:\n  title: Zen\n  version: 0.0.1\n  description: ''\nchannels:\n  get_user:\n    $ref: '#/components/channels/get_user'\noperations:\n  get_user:\n    $ref: '#/components/operations/get_user'\ncomponents:\n  channels:\n    get_user:\n      messages:\n        request:\n          $ref: '#/components/messages/get_user_request'\n        response:\n          $ref: '#/components/messages/get_user_response'\n  operations:\n    get_user:\n      action: receive\n      description: ''\n      channel:\n        $ref: '#/channels/get_user'\n      messages:\n      - $ref: '#/channels/get_user/messages/request'\n      reply:\n        channel:\n          $ref: '#/channels/get_user'\n        messages:\n        - $ref: '#/channels/get_user/messages/response'\n  messages:\n    get_user_request:\n      title: Request params for get_user\n      summary: ''\n      description: ''\n      payload:\n        type: object\n        required:\n        - user_id\n        properties:\n          user_id:\n            type: integer\n            description: ''\n    get_user_response:\n      title: Response params for get_user\n      summary: ''\n      description: ''\n      payload:\n        $ref: '#/components/schemas/UserModel'\n        format: required\n  schemas:\n    UserModel:\n      type: object\n      base_class: BaseModel\n      required:\n      - id\n      - name\n      properties:\n        id:\n          type: integer\n        name:\n          type: string\n        email:\n          type: string\n```\n\n## Development Setup 🛠️\n\nRequirements:\n- Python 3.10+\n- uv (Python packaging toolchain)\n\n```bash\n# Install uv if not already installed\n# see https://docs.astral.sh/uv/getting-started/installation/\n\n# Clone repository\ngit clone https://github.com/WaYdotNET/zen-generator.git\ncd zen-generator\n\n# Install dependencies with uv\nuv sync\n\n# Run tests\nuv run pytest\n```\n\n## Best Practices 💡\n\n1. **AsyncAPI Specification**\n   - Follow [AsyncAPI 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) guidelines\n   - Define clear schema types\n   - Include comprehensive examples\n   - Use semantic versioning\n\n2. **Code Generation**\n   - Review generated code for correctness\n   - Implement business logic in function stubs\n   - Keep generated files synchronized\n   - Use type hints consistently\n\n3. **Project Organization**\n   - Maintain clear separation between models and functions\n   - Follow standard Python package structure\n   - Implement proper error handling\n\n## Contributing 🤝\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Submit a pull request\n\n## License 📄\n\nMIT License - see LICENSE file for details\n\n## Support 💬\n\n- GitHub Issues: [Report bugs or suggest features](https://github.com/WaYdotNET/zen-generator/issues)\n\n---\n\nMade with ❤️ by [WaYdotNET](https://github.com/WaYdotNET)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaydotnet%2Fzen-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaydotnet%2Fzen-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaydotnet%2Fzen-generator/lists"}