![Copier-Astral](docs/static/copier-astral.png)

---

My opinionated [Copier](https://copier.readthedocs.io/) template for bootstrapping Python projects. Batteries included: linting, testing, CI/CD, docs, and containerization — all pre-configured and ready to go.

Built for my own workflow, but you're welcome to use it!

![Demo](docs/static/demo.gif)

| Tool | Purpose | Benefit |
|------|---------|---------|
| **[uv](https://docs.astral.sh/uv/)** | Package management, venv, dependencies | 10-100x faster than pip |
| **[ty](https://docs.astral.sh/ty/)** | Type checking | Astral's new fast type checker |
| **[ruff](https://docs.astral.sh/ruff/)** | Linting + formatting | Replaces flake8, black, isort |
| **[pytest](https://pytest.org/)** | Testing | Industry standard |
| **[hatch](https://hatch.pypa.io/)** | Multi-version testing | Matrix testing with envs |
| **[MkDocs](https://www.mkdocs.org/)** | Documentation | Material theme + mkdocstrings |
| **[prek](https://prek.j178.dev/)** | Git hooks | Code quality enforcement |
| **[Typer](https://typer.tiangolo.com/)** | CLI framework | Type-hint based, modern |
| **[git-cliff](https://git-cliff.org/)** | Changelog | Auto-generated from conventional commits |
| **[gitleaks](https://github.com/gitleaks/gitleaks)**| Search repo for secrets | Alert on leaked secrets |
| **[pysentry-rs](https://pysentry.com/)** | Vulnerability Scanner | Highlight _potential_ dependency security issues |
| **[semgrep](https://semgrep.dev/)** | Static Application Security Testing | SAST scans highlight potential [security issues](https://semgrep.dev/docs/languages/python) in repo code |
| **[Renovate](https://renovateapp.com/)** | Dependency updates | Automated PRs to keep dependencies up to date |

## Quick Start

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended), [pipx](https://pipx.pypa.io/), or pip
- [Copier](https://copier.readthedocs.io/) and [copier-template-extensions](https://github.com/copier-org/copier-template-extensions)

**Install uv:**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Install copier with uv (recommended):**

```bash
uv tool install copier --with copier-template-extensions
```

**With pipx:**

```bash
pipx install copier
pipx inject copier copier-template-extensions
```

**With pip:**

```bash
pip install copier copier-template-extensions
```

### Generate a Project

```bash
copier copy --trust gh:ritwiktiwari/copier-astral my-project
```

Or from a local clone:

```bash
copier copy --trust /path/to/copier-astral my-project
```

> **Note:** The `--trust` flag is required because this template uses custom Jinja2 extensions for features like auto-detecting git user info and generating slugified package names. These extensions are safe to use but Copier warns about them by default.

## Documentation

For the full user guide, template options, and contributing instructions, see the [documentation site](https://ritwiktiwari.github.io/copier-astral/).

## License

This template is released under the MIT License.