Metadata-Version: 2.4
Name: create-pyproj
Version: 2.1.1
Summary: Scaffold uv-first Python projects with a DDD and hexagonal baseline.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mako>=1.3.5
Dynamic: license-file

# create-pyproj

`create-pyproj` scaffolds canonical Python projects with a `uv`-first workflow,
semantic-release, DDD and hexagonal defaults, optional CLI and web stubs,
starter MkDocs documentation, and an `AGENTS.md` tuned for the canonical
engineering skills.

## What It Generates

The default scaffold includes:

- `.python-version`
- `pyproject.toml` with `uv`-friendly dependency groups and Ruff configuration
- `mise.toml` with tool pins and common tasks
- semantic-release configuration for version stamping in `pyproject.toml` and `src/<package>/__init__.py`
- `src/<package>` with `domain`, `application`, and `infrastructure` package structure
- `docs/` plus `mkdocs.yml`
- `AGENTS.md`
- `.vscode/`, `.pre-commit-config.yaml`, and `.env.example`

Optional adapters:

- `--interface cli` adds an argparse-based CLI stub and console script entrypoint
- `--interface web` adds a FastAPI application stub plus a server-rendered UI:
  Jinja2 templates and HTMX fragment swaps served by the same app

Optional CI:

- `--ci github`
- `--ci gitlab`

Both CI options include lint, test, and semantic-release jobs.

Optional infrastructure:

- `--terraform` adds a starter Terraform deployment skeleton

## Usage

```bash
create-pyproj demo-app --interface cli --interface web --ci github --terraform --no-install
```

To install the local repo as a global command with `uv`:

```bash
uv tool install --force .
```

Common flags:

- `--python-version 3.12`
- `--description "Short project summary"`
- `--author "Your Name"`
- `--author-email "you@example.com"`
- `--output-dir /path/to/projects`
- `--terraform`
- `--no-git-init`
- `--no-install`

If the target directory already exists, `create-pyproj` will reuse it. Any
scaffold-managed files with the same path will be overwritten, while unrelated
existing files and folders are left in place.

## Scaffold Contract

The generated project is intended to:

- keep the domain and application layers framework-independent
- make CLI and web adapters optional delivery concerns
- expose Mise, uv, Ruff, pytest, and pre-commit as the default workflow
- include semantic-release as the default CI/CD release toolset
- provide structure without inventing sample business behavior
- include the same semantic-release approach used elsewhere in this workspace
- add Terraform only when requested for a deployable service
- document the architecture and domain through MkDocs
- include an `AGENTS.md` that points contributors at the canonical skills

## Development

```bash
mise run setup
mise run lint
mise run complexity
mise run typecheck
mise run format
mise run test
uv run python -m create_pyproj.main --help
```

The local test suite verifies the emitted scaffold contract rather than just
individual template files.

## Docs

This repo now includes MkDocs content for `create_pyproj` itself under `docs/`,
with navigation configured in `mkdocs.yml`.

```bash
mise run docs
```
