Skip to main content

scaffold-ca-python

PyPI version Python License: MIT

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

  1. Create a new Clean Architecture project.
scaffold ca --name my-app
  1. Move into the generated project directory.
cd my-app
  1. Generate a domain model.
scaffold gm --name order
  1. 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.

scaffold guc --name create_order
scaffold guc --name create_order --dry-run

scaffold gda

Scaffold a driven adapter such as an HTTP client, secrets adapter, or generic outbound adapter.

scaffold gda --type rest-consumer
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 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

Technologies

Tool / Library Version Role
Python >=3.13 Runtime
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.
  • Generates driven adapters with scaffold gda.
  • Generates entry points for REST API, 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-run previews 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

  1. Fork the upstream repository on GitHub: https://github.com/bancolombia/scaffold-clean-architecture-py
  2. Clone your fork.
git clone https://github.com/YOUR-USER/scaffold-clean-architecture-py.git
cd scaffold-clean-architecture-py
  1. Set up the development environment.
uv sync
  1. Create a feature branch.
git checkout -b your-branch-feature-name
  1. Run the test suite.
uv run pytest
  1. Check linting.
uv run ruff check src tests
  1. Check types.
uv run mypy src
  1. 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 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for scaffold-ca-python 0.4.0
File Size Uploaded Provenance Actions
scaffold_ca_python-0.4.0.tar.gz 578.4 kB Without provenance Details for scaffold_ca_python-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for scaffold-ca-python 0.4.0
File Interpreter ABI Platform Actions
scaffold_ca_python-0.4.0-py3-none-any.whl Python 3 none any Details for scaffold_ca_python-0.4.0-py3-none-any.whl

Total release size: 679.5 kB

Release files / scaffold_ca_python-0.4.0.tar.gz

Download URL scaffold_ca_python-0.4.0.tar.gz
Size 578.4 kB
Tags Source
SHA-256 checksum
How to use checksums
b358afb13c6c6d9e6ed54e58c6853003f0a888b2f7a9a493fc63fda9566e31f6
BLAKE2b-256 checksum
How to use checksums
35914e36b1482479cd18531ba669602d244c8df7da2981fcaff86f92608d2124
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","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-0.4.0-py3-none-any.whl

Download URL scaffold_ca_python-0.4.0-py3-none-any.whl
Size 101.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f8f9176b5c0527e2d13b32178b6c3e21a2b6bf15575e34b58a411ded496676cf
BLAKE2b-256 checksum
How to use checksums
b14959539a55220d8179ddaa490c73cb1b1e619b2a93ea50159c1c21b45d9950
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","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 0.4.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page