139 lines
3.2 KiB
Markdown
139 lines
3.2 KiB
Markdown
# 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.
|