# 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** for fast dependency management and reproducible installs
- **Ruff** for linting/formatting
- **MyPy** with strict typing
- **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. The template will prompt for project details and automatically:
   - Initialize git repository
   - Set up uv environment
   - Run initial linting and formatting
   - Execute tests to verify setup

## 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_version` | Minimum Python version | "3.12" |

## Generated Project Structure

```
your-project/
├── README.md
├── pyproject.toml
├── tasks.py
├── 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_public.py
│   └── test_internals.py
└── examples/
    └── config_init.sh
```

## Development Workflow

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

### Code Quality
```bash
uv run ruff check src tests
uv run ruff format 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
   cookiecutter . --output-dir /tmp
   ```

## Requirements

- Python 3.12+
- uv (automatically installed during generation)
- git (for version control)

## License

MIT License - see LICENSE file for details.