# 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.