132 lines
3.2 KiB
Markdown
132 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** 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.
|