124 lines
3.2 KiB
Markdown
124 lines
3.2 KiB
Markdown
# Python Library Template
|
|
|
|
A [Cookiecutter](https://github.com/cookiecutter/cookiecutter) template for creating modern Python libraries with uv, ruff, mypy, and pytest.
|
|
|
|
## Features
|
|
|
|
- **Modern Python setup** with Python 3.12+ support
|
|
- **uv** for fast dependency management
|
|
- **Ruff** for linting and formatting
|
|
- **MyPy** for type checking
|
|
- **Pytest** with coverage support
|
|
- **bump-my-version** for automated version management
|
|
- **Invoke** tasks for common operations
|
|
- **Pre-configured** development workflow
|
|
- **Type hints** support with py.typed marker
|
|
- **CLAUDE.md** guidance for Claude Code integration
|
|
|
|
## Quick Start
|
|
|
|
1. Install cookiecutter:
|
|
```bash
|
|
pipx install cookiecutter
|
|
```
|
|
|
|
2. Generate a new project:
|
|
```bash
|
|
cruft create https://gitlab.com/roxautomation/templates/python-lib-template
|
|
```
|
|
|
|
Or locally:
|
|
```bash
|
|
cookiecutter /path/to/python-lib-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 Python Library" |
|
|
| `project_slug` | Repository/directory name | "my-python-library" |
|
|
| `package_name` | Python package name | "my_python_library" |
|
|
| `description` | Short project description | "A modern Python library" |
|
|
| `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/
|
|
├── CLAUDE.md # Claude Code guidance
|
|
├── README.md # Project documentation
|
|
├── pyproject.toml # Project configuration
|
|
├── tasks.py # Invoke tasks
|
|
├── src/
|
|
│ └── your_package/
|
|
│ ├── __init__.py
|
|
│ ├── core.py
|
|
│ └── py.typed
|
|
├── tests/
|
|
│ └── test_your_package.py
|
|
└── examples/
|
|
└── basic_usage.py
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
The generated project includes these common tasks:
|
|
|
|
### Setup
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
### Code Quality
|
|
```bash
|
|
uv run ruff check --fix # Linting
|
|
uv run ruff format # Formatting
|
|
uv run mypy . # Type checking
|
|
uv run invoke lint # All quality checks
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
uv run pytest # Run tests
|
|
uv run invoke test # Run tests with coverage
|
|
```
|
|
|
|
### Version Management
|
|
```bash
|
|
uv run bump-my-version bump patch # 0.1.0 → 0.1.1
|
|
uv run bump-my-version bump minor # 0.1.0 → 0.2.0
|
|
uv run bump-my-version bump major # 0.1.0 → 1.0.0
|
|
```
|
|
|
|
## 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.
|