scaffold-ca-python
What is this?
scaffold-ca-python is a CLI tool that scaffolds production-ready Python projects that follow Clean Architecture. It helps teams start faster by generating the project structure, modules, adapters, entry points, helpers, and pipeline files needed to keep architectural boundaries explicit. It is designed for developers who want repeatable code generation instead of hand-creating the same project pieces over and over.
Installation
Python 3.13 or newer is required.
Install with pip:
pip install scaffold-ca-python
Install with uv:
uv add scaffold-ca-python
You could also use uvx:
uvx scaffold-ca-python [command]
Use --help to see all available command.
Quick Start
- Create a new Clean Architecture project.
scaffold ca --name my-app
- Move into the generated project directory.
cd my-app
- Generate a domain model.
scaffold gm --name order
- Validate the project structure.
scaffold vs
Commands & Examples
scaffold ca
Scaffold a new Clean Architecture project.
scaffold ca --name my-project
scaffold ca --name my-project --dry-run
scaffold gm
Scaffold a Pydantic v2 domain model, its gateway (an empty abstract repository contract), and test stubs.
scaffold gm --name order
Generated structure:
domain/model/order/
├── __init__.py
├── order.py
└── gateways/
├── __init__.py
└── order_repository.py
scaffold gm --name order --dry-run
scaffold guc
Scaffold a use case in domain/usecase/. The module is always named <name>_usecase.py and the class <Name>UseCase. Writing _usecase in --name is optional and the suffix is never duplicated: create_order, create_order_usecase and create_order_use_case all create create_order_usecase.py with CreateOrderUseCase.
Use --uses with one or more domain gateway names (comma-separated) to generate a typed constructor and a wireup factory under application/config/usecases/. Gateway names must match ABCs in domain/model/*/gateways/. Helpers and adapters are not valid --uses targets.
scaffold guc --name create_order
scaffold guc --name create_order --uses order_repository
scaffold guc --name create_order --dry-run
scaffold gda
Scaffold a driven adapter such as an HTTP client, secrets adapter, or generic outbound adapter.
Use --gateway with a domain gateway ABC name so the adapter is registered as @injectable(as_type=<Gateway>) and wired to that port.
scaffold gda --type rest-consumer
scaffold gda --type generic --name order_repository_adapter --gateway order_repository
scaffold gda --type generic --name my_adapter --dry-run
scaffold gep
Scaffold an entry-point adapter for REST APIs, A2A agents, MCP servers, or generic entry points.
scaffold gep --type restapi
scaffold gep --type mcp --with-resources --with-prompts --dry-run
scaffold gep --type mcp --add-tool --name create_file --param path:str --param content:str --returns str --description "Creates a file on disk"
scaffold gep --type agent
--type agent generates an A2A server (a2a-sdk, Starlette, uvicorn) under infrastructure/entry_points/a2a_server/ and replaces main.py with server.py. It runs with zero configuration (uv run <project-script>):
GET /api/v1/health— liveness probe.GET /.well-known/agent-card.json— agent card built fromAGENT_NAME,AGENT_DESCRIPTION,AGENT_VERSION, andAGENT_PUBLIC_URL.POST /(JSON-RPC) andPOST /message:send(REST) —SendMessageanswersHello, World! You said: <text>. Clients send theA2A-Version: 1.0header.
HOST and PORT (default 0.0.0.0:8000) are added to application/config/config.py. To call a use case, uncomment the some_usecase hooks in a2a_config.py and agent_executor.py. Only one entry-point type per project: agent conflicts with restapi and mcp.
scaffold gh
Scaffold a helper utility module and its test stub.
scaffold gh --name json_parser
scaffold gh --name json_parser --dry-run
scaffold gpipe
Scaffold a CI/CD pipeline configuration for GitHub Actions or Azure Pipelines.
scaffold gpipe --provider github
scaffold gpipe --provider azure --dry-run
scaffold vs
Scan the project for Clean Architecture import violations.
scaffold vs
scaffold vs --dry-run
scaffold dm
Delete a previously generated module and its mirrored test file.
scaffold dm --name order
scaffold dm --name order --dry-run
scaffold up
Update project dependencies using uv lock --upgrade and uv sync.
scaffold up --dry-run
scaffold update-project --dry-run
Dependency injection (wireup)
New projects generated with scaffold ca use wireup for async-first dependency injection:
application/config/wiring.pydefinescreate_container()and package scan targets (driven_adapters,helpers,usecases).- Use cases declare gateway dependencies with
scaffold guc --uses …; adapters bind to gateways withscaffold gda --gateway …. - Entry points inject use cases with
Injected[…](REST/MCP), through constructor injection in a wireup factory (agent), or resolve types from the container (generic)—without importingapplicationfrom infrastructure. - Generated code enables ruff rule
ASYNCand pytestasyncio_mode = auto.
Legacy projects (generated with scaffold-ca-python ≤ 0.5.0, dependency-injector, no scaffold_version in [tool.scaffold-ca-python]) are not modified by generate commands. Migrate to wireup manually, then set scaffold_version in pyproject.toml before using newer scaffold commands on that repo.
Technologies
| Tool / Library | Version | Role |
|---|---|---|
| Python | >=3.13 | Runtime |
| wireup | 2.13.0 | DI in generated projects |
| uv | latest | Dependency management, build, and publish |
| Typer | >=0.27.2 | CLI framework |
| Rich | >=15.0.0 | Terminal output formatting |
| Jinja2 | >=3.1 | Template engine for code generation |
| Pydantic v2 | >=2.0 | Runtime validation of template context |
| hatchling | latest | Build backend |
| uv-dynamic-versioning | latest | PEP 440 versioning from git tags |
| ruff | latest | Linting and formatting |
| mypy | latest (strict) | Static type checking |
| pytest + pytest-cov | latest | Test execution and coverage gating |
Current Features
- Generates full Clean Architecture project skeletons with
scaffold ca. - Generates domain models with
scaffold gm. - Generates domain use cases with
scaffold guc(optional--usesfor gateway wiring and DI factories). - Generates driven adapters with
scaffold gda(optional--gatewayfor port binding). - Generates entry points for REST API, A2A agent, MCP, and generic modes with
scaffold gep. - Generates helper utilities with
scaffold gh. - Generates CI/CD pipeline files with
scaffold gpipe. - Validates import boundaries with
scaffold vs. - Deletes generated modules safely with
scaffold dm. - Updates project dependencies with
scaffold up. - Supports
--dry-runpreviews across commands. - Uses Jinja2 templates for all generated code.
- Validates template context with Pydantic v2.
- Formats terminal output with Rich.
- Enforces static checks with mypy strict and ruff.
- Maintains an 80%+ coverage gate with pytest-cov.
Contributing
- Fork the upstream repository on GitHub: https://github.com/bancolombia/scaffold-clean-architecture-py
- Clone your fork.
git clone https://github.com/YOUR-USER/scaffold-clean-architecture-py.git
cd scaffold-clean-architecture-py
- Set up the development environment.
uv sync
- Create a feature branch.
git checkout -b your-branch-feature-name
- Run the test suite.
uv run pytest
To run end-to-end tests (these generate real projects and run quality checks on them):
uv run pytest -m e2e
Troubleshooting E2E tests: If you see uv sync failed errors during e2e tests due to TLS/certificate issues (typically in corporate environments with custom CAs or proxies), set UV_SYSTEM_CERTS=1 to make uv use your system's certificate store:
UV_SYSTEM_CERTS=1 uv run pytest -m e2e
You can also export this variable in your shell configuration (.zshrc, .bashrc) to make it permanent for your local environment.
- Check linting.
uv run ruff check src tests
- Check types.
uv run mypy src
- Commit your changes and open a pull request.
License
This project is licensed under the MIT License. See LICENSE for the full text.
Metadata
Release files for scaffold-ca-python 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scaffold_ca_python-1.0.1.tar.gz | 652.4 kB | Without provenance | Details for scaffold_ca_python-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scaffold_ca_python-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for scaffold_ca_python-1.0.1-py3-none-any.whl |
Total release size: 774.9 kB
Release files / scaffold_ca_python-1.0.1.tar.gz
| Download URL | scaffold_ca_python-1.0.1.tar.gz |
|---|---|
| Size | 652.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
820655a686108715a930ad745b595fd7c4dd3d95e3ef8174041992b39c56b447
|
|
BLAKE2b-256 checksum How to use checksums |
b135d8694b25afc154f66ae7e05d00fdddf11fc4c987206aa7cc3b0a425c1ec6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / scaffold_ca_python-1.0.1-py3-none-any.whl
| Download URL | scaffold_ca_python-1.0.1-py3-none-any.whl |
|---|---|
| Size | 122.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
83810d5b4e208f206f5e120bfe99348a093278ac993e5f43ed026dedb22770d9
|
|
BLAKE2b-256 checksum How to use checksums |
f3554a50d8e1e3ae22103ecb6b10a637e2c7a709324e716d4cf05cde8f03a9ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for scaffold-ca-python 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.