# Python App Template

A Cookiecutter template for building CLI-first Python applications with `uv`, Typer, Pydantic, and strict typing.

## Features

- CLI-first architecture with Typer
- Local-first config (XDG paths) with env override
- `uv_build` backend and lockfile-first reproducibility
- Ruff for linting/formatting
- MyPy strict mode
- Pytest with coverage support
- Invoke tasks for common operations
- `py.typed` marker for typed packages
- Example command wired from core `commands/` into CLI

## Quick Start

1. Install cookiecutter:
   ```bash
   pipx install cookiecutter
   ```

2. Generate a new project:
   ```bash
   cruft create https://gitlab.com/roxautomation/templates/python-app-template
   ```

   Or locally:
   ```bash
   cookiecutter /path/to/python-app-template
   ```

3. Post-generation hook runs `uv lock` to create `uv.lock`.

4. Bootstrap the generated project:
   ```bash
   uv sync --frozen --group dev
   uv run invoke lint
   uv run invoke test
   ```

## Template Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `project_name` | Human-readable project name | "My CLI App" |
| `project_slug` | Repository/directory name | "my-cli-app" |
| `package_name` | Python package name | "my_cli_app" |
| `description` | Short project description | "A modern CLI tool" |
| `author_name` | Author's full name | "Your Name" |
| `author_email` | Author's email | "your.email@example.com" |
| `version` | Initial version | "0.1.0" |

Python is fixed to 3.12+ by template policy.

## Generated Project Structure

```
your-project/
├── README.md
├── pyproject.toml
├── tasks.py
├── uv.lock
├── src/
│   └── your_package/
│       ├── __init__.py
│       ├── py.typed
│       ├── cli/
│       │   ├── __init__.py
│       │   ├── app.py
│       │   ├── common.py
│       │   ├── config.py
│       │   └── hello.py
│       ├── config/
│       │   ├── __init__.py
│       │   ├── paths.py
│       │   └── settings.py
│       ├── commands/
│       │   ├── __init__.py
│       │   └── hello.py
│       ├── models/
│       │   └── __init__.py
│       └── utils/
│           ├── __init__.py
│           └── logging.py
├── tests/
│   ├── conftest.py
│   ├── test_cli.py
│   ├── test_internals.py
│   └── test_public.py
└── examples/
    └── config_init.sh
```

## Development Workflow

### Setup
```bash
uv sync --frozen --group dev
```

### Code Quality
```bash
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv run invoke lint
```

### Testing
```bash
uv run pytest
uv run invoke test
```

## Template Development

To modify this template:

1. Edit files in `{{cookiecutter.project_slug}}/`
2. Update variables in `cookiecutter.json`
3. Modify the post-generation hook in `hooks/post_gen_project.py`
4. Test changes:
   ```bash
   ./test.sh
   ```

## Requirements

- Python 3.12+
- `uv`
- `cruft` or `cookiecutter`
- `git` (optional, for your project workflow)

## License

MIT License - see LICENSE file for details.