{"id":20020494,"url":"https://github.com/shakfu/xtgen","last_synced_at":"2026-05-03T07:45:13.311Z","repository":{"id":41356325,"uuid":"437519407","full_name":"shakfu/xtgen","owner":"shakfu","description":"A tool to generate skeleton puredata \u0026 Max/MSP external files.","archived":false,"fork":false,"pushed_at":"2025-09-21T04:16:22.000Z","size":2037,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-21T04:24:30.707Z","etag":null,"topics":["c","max","maxmsp","puredata","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shakfu.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}},"created_at":"2021-12-12T10:55:27.000Z","updated_at":"2025-09-21T04:16:26.000Z","dependencies_parsed_at":"2024-11-13T08:33:17.542Z","dependency_job_id":"63946a91-2b0a-49ce-942c-35bb4b9bab61","html_url":"https://github.com/shakfu/xtgen","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shakfu/xtgen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakfu%2Fxtgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakfu%2Fxtgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakfu%2Fxtgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakfu%2Fxtgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shakfu","download_url":"https://codeload.github.com/shakfu/xtgen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shakfu%2Fxtgen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32562118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["c","max","maxmsp","puredata","python3"],"created_at":"2024-11-13T08:32:36.722Z","updated_at":"2026-05-03T07:45:13.305Z","avatar_url":"https://github.com/shakfu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xtgen\n\nA modern, type-safe Python package for generating skeleton PureData and Max/MSP external files from YAML or JSON specifications.\n\n## Features\n\n- **Python package** with CLI entry point and library interface\n- **Command-line interface** with comprehensive options and validation\n- **Generate PureData external projects** with complete build system\n- **Generate Max/MSP external projects** with proper SDK structure\n- **Template-based code generation** using Mako templates\n- **Type-safe specification parsing** (YAML and JSON formats)\n- **Automatic format detection** with intelligent fallback\n- **Validation mode** to check specifications without generating\n- **Comprehensive test coverage** (38 tests)\n- **Support for both regular and DSP** (signal processing) externals\n- **Bundled resources** (templates, examples, headers included in package)\n\n## Installation\n\n### From Source\n\nClone this repository and install with uv:\n\n```sh\ngit clone \u003crepository-url\u003e\ncd xtgen\nuv sync\n```\n\n### From Wheel\n\nBuild and install the package:\n\n```sh\nuv build\npip install dist/xtgen-*.whl\n```\n\n### Dependencies\n\nThe package requires:\n- Python 3.13+\n- Mako (templating engine)\n- PyYAML (YAML parsing)\n\n## Usage\n\n### Command Line Interface\n\nThe easiest way to use xtgen is through its command-line interface:\n\n```sh\nusage: xtgen [-h] [-t {pd,max}] [-o DIR] [-v] [-q] [-f] [--list-examples]\n             [--validate]\n             [spec_file]\n\nGenerate PureData and Max/MSP external projects from YAML or JSON specifications\n\npositional arguments:\n  spec_file             Path to YAML or JSON specification file (default: counter.yml from examples)\n\noptions:\n  -h, --help            show this help message and exit\n  -t, --target {pd,max}\n                        Target platform: 'pd' for PureData, 'max' for Max/MSP\n                        (default: pd)\n  -o, --output DIR      Output directory for generated projects (default: build)\n  -v, --verbose         Enable verbose output with detailed generation information\n  -q, --quiet           Suppress all output except errors\n  -f, --force           Force overwrite existing project directory without warning\n  --list-examples       List available example specification files and exit\n  --validate            Validate specification file without generating project\n\nExamples:\n  xtgen counter.yml                    # Generate PD project from YAML\n  xtgen counter.json                   # Generate PD project from JSON\n  xtgen -t max counter.yml             # Generate Max/MSP project\n  xtgen -o /tmp/build counter.yml      # Custom output directory\n  xtgen -v counter.yml                 # Verbose output\n  xtgen --list-examples                # List available examples\n\nSupported file formats:\n  .yml, .yaml  - YAML specification files\n  .json        - JSON specification files\n```\n\n### Development Usage\n\nWhen developing locally with uv:\n\n```sh\n# Run with default example (generates PD project)\nuv run xtgen\n\n# Generate Max/MSP project\nuv run xtgen -t max resources/examples/counter.json\n\n# Use custom output directory\nuv run xtgen -o /tmp/my-externals counter.yml\n\n# Verbose output with detailed information\nuv run xtgen -v counter.yml\n\n# Validate specification without generating\nuv run xtgen --validate counter.yml\n\n# List available example files\nuv run xtgen --list-examples\n```\n\n### Installed Package Usage\n\nWhen xtgen is installed as a package:\n\n```sh\n# Generate PureData project (default behavior)\npython -m xtgen resources/examples/counter.yml\n\n# Generate Max/MSP project\npython -m xtgen -t max resources/examples/counter.json\n\n# Use custom output directory\npython -m xtgen -o /tmp/my-externals counter.yml\n```\n\n#### CLI Options\n\n- `-t, --target {pd,max}` - Target platform (default: pd)\n- `-o, --output DIR` - Output directory (default: build)\n- `-v, --verbose` - Enable verbose output\n- `-q, --quiet` - Suppress all output except errors\n- `-f, --force` - Force overwrite existing directories\n- `--validate` - Validate specification file without generating\n- `--list-examples` - List available example files\n\n### Python Library Usage\n\nYou can also use xtgen as a Python library:\n\n```python\nfrom xtgen import PdProject, MaxProject\nfrom pathlib import Path\n\n# Generate PureData project from your own specification\nproject = PdProject('my_external.yml')\nproject.generate()\n\n# Generate Max/MSP project\nproject = MaxProject('my_external.json')\nproject.generate()\n\n# Generate with custom output directory\nproject = PdProject('spec.yml', target_dir='custom_output')\nproject.generate()\n```\n\n### Project Compilation\n\nGenerated projects are ready to compile:\n\n```sh\n# For PureData projects\nmake -C build/counter\n\n# For Max/MSP projects (requires Max SDK)\n# Follow Max SDK build instructions\n```\n\n## Development\n\n### Running Tests\n\n```sh\nuv run pytest tests/ -v\n```\n\n### Type Checking\n\n```sh\nuv run mypy src/xtgen/\n```\n\n### Linting and Formatting\n\n```sh\nuv run ruff check src/xtgen/\nuv run ruff format src/xtgen/\n```\n\n### Quick Development Tasks\n\nUse the Makefile for common development tasks:\n\n```sh\nmake demo        # Generate demo project in build/demo_output/\nmake test        # Run test suite\nmake clean       # Clean build artifacts\nmake help        # Show available targets\n```\n\n## Specification Format\n\nExternal specifications can be defined in either YAML or JSON format. Both formats support the same structure and features.\n\n### YAML Format\n\n```yaml\nexternals:\n  - namespace: my\n    name: counter\n    prefix: ctr\n    alias: cntr\n    help: help-counter\n    n_channels: 1\n    params:\n      - name: step\n        type: float\n        min: 0.0\n        max: 1.0\n        initial: 0.5\n        arg: true\n        inlet: true\n        desc: \"step size\"\n    outlets:\n      - name: out\n        type: float\n    message_methods:\n      - name: reset\n        params: []\n        doc: \"reset counter to zero\"\n    type_methods:\n      - type: bang\n        doc: \"increment counter\"\n    meta:\n      desc: \"A simple counter external\"\n      author: \"Your Name\"\n      repo: \"https://github.com/yourname/counter\"\n      features: [\"counting\", \"resettable\"]\n```\n\n### JSON Format\n\n```json\n{\n  \"externals\": [\n    {\n      \"namespace\": \"my\",\n      \"name\": \"counter\",\n      \"prefix\": \"ctr\",\n      \"alias\": \"cntr\",\n      \"help\": \"help-counter\",\n      \"n_channels\": 1,\n      \"params\": [\n        {\n          \"name\": \"step\",\n          \"type\": \"float\",\n          \"min\": 0.0,\n          \"max\": 1.0,\n          \"initial\": 0.5,\n          \"arg\": true,\n          \"inlet\": true,\n          \"desc\": \"step size\"\n        }\n      ],\n      \"outlets\": [\n        {\n          \"name\": \"out\",\n          \"type\": \"float\"\n        }\n      ],\n      \"message_methods\": [\n        {\n          \"name\": \"reset\",\n          \"params\": [],\n          \"doc\": \"reset counter to zero\"\n        }\n      ],\n      \"type_methods\": [\n        {\n          \"type\": \"bang\",\n          \"doc\": \"increment counter\"\n        }\n      ],\n      \"meta\": {\n        \"desc\": \"A simple counter external\",\n        \"author\": \"Your Name\",\n        \"repo\": \"https://github.com/yourname/counter\",\n        \"features\": [\"counting\", \"resettable\"]\n      }\n    }\n  ]\n}\n```\n\n### File Format Detection\n\n- Files with `.yml` or `.yaml` extensions are parsed as YAML\n- Files with `.json` extension are parsed as JSON\n- Files with other extensions (or no extension) are automatically detected by trying YAML first, then JSON\n- Both formats produce identical results and support all the same features\n\n## Project Status\n\n### Completed Features\n\n- [x] **Command-line interface** with argparse-based argument parsing\n- [x] **Complete specification parsing** (YAML and JSON) with validation\n- [x] **PureData external project generation** with build system\n- [x] **Max/MSP external project generation** with SDK integration\n- [x] **Template-based code generation** system using Mako\n- [x] **Support for DSP externals** (signal processing)\n- [x] **Comprehensive type system** with validation and error handling\n- [x] **Full test coverage** (35 tests including CLI tests)\n- [x] **Type safety** with mypy validation\n- [x] **Code quality** with ruff linting and formatting\n- [x] **Validation mode** for specification checking\n- [x] **Automatic format detection** with intelligent fallback\n- [x] **Inlet and outlet generation** with proper type mapping\n- [x] **Parameter handling** with constructor arguments\n- [x] **Message method generation** with argument type checking\n- [x] **Type method generation** (bang, float, symbol, list, etc.)\n- [x] **Build system integration** (Makefiles for PD, project files for Max)\n- [x] **Documentation generation** (README files)\n\n### Future Enhancements\n\n- [x] xtgen to become a python package\n- [ ] Hybrid dual Max/PD template\n- [ ] Additional DSP utility functions\n- [ ] Extended help file generation for PureData\n- [ ] Plugin packaging and distribution tools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshakfu%2Fxtgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshakfu%2Fxtgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshakfu%2Fxtgen/lists"}