Skip to content

Commit fe0caa1

Browse files
bassemkarouibassemkaroui
committed
📝 docs: add README.md
1 parent 5cfc9d2 commit fe0caa1

2 files changed

Lines changed: 200 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
<div align="center">
2+
3+
# python-template-uv
4+
5+
A modern, batteries‑included [Copier](https://github.com/copier-org/copier) template for bootstrapping Python packages and applications managed with [uv](https://github.com/Astral-Projects/uv)
6+
7+
[![Copier Template](https://img.shields.io/badge/copier-9.6.0-blue.svg)](https://copier.readthedocs.io/)
8+
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
9+
[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue.svg)]()
10+
11+
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
12+
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
13+
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
14+
[![GitHub](https://img.shields.io/github/license/bassemkaroui/python-template-uv)](https://github.com/bassemkaroui/python-template-uv/blob/main/LICENSE)
15+
16+
17+
</div>
18+
19+
## 🚀 Features
20+
21+
- **Copier-powered scaffolding**:
22+
Effortlessly generate or update projects with one command.
23+
24+
- **Task runner integration**:
25+
Project tasks are organized using [duty](https://github.com/pawamoy/duty) and exposed via a [Makefile](https://github.com/bassemkaroui/python-template-uv/blob/main/template/Makefile.jinja) for easy command-line usage.
26+
Simply run tasks with `make <task>` (e.g. `make check`, `make docs`).
27+
28+
- **Quality & standards**
29+
- **Formatting** and **Linting**: [Ruff](https://github.com/astral-sh/ruff) ➜ `make format` & `make check-quality`
30+
- **Type checking**: [Mypy](https://github.com/python/mypy) ➜ `make check-types`
31+
- **Pre-commit hooks**: [pre-commit](https://pre-commit.com/)
32+
33+
- **Testing & coverage**
34+
- [**pytest**](https://github.com/pytest-dev/pytest) ➜ `make test`
35+
- [**Coverage**](https://github.com/nedbat/coveragepy) (text, HTML, XML) ➜ `make coverage`
36+
- Compatibility testing for multiple versions of Python with [**Tox**](https://github.com/tox-dev/tox) and its plugin [tox-uv](https://github.com/tox-dev/tox-uv) ➜ `make tox`
37+
38+
- **Documentation**
39+
- [**MkDocs**](https://github.com/mkdocs/mkdocs) with [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme
40+
- Live server: `make docs` (serves on localhost:8080)
41+
- Deploy to GitHub Pages: `make docs-deploy`
42+
43+
- **Release & changelog**
44+
- [Conventional Commits](https://www.conventionalcommits.org/) + [Commitizen](https://github.com/commitizen-tools/commitizen) + [gitmoji](https://github.com/ljnsn/cz-conventional-gitmoji)
45+
- Automated `CHANGELOG.md` updates
46+
- Release new versions ➜ `make release`
47+
48+
49+
- **Docker & Docker Compose**
50+
- Generate `Dockerfile` + `compose.yml` for local development and deployment (GPU support)
51+
- Docker targets: `make docker-build`, `make docker-start`, `make docker-stop`
52+
53+
- **Optional tooling**
54+
- Typer CLI scaffold
55+
- Strict typing
56+
- Run tests with parallel execution via pytest-xdist
57+
- Preconfigured dependency categories (ML, data, web, etc.)
58+
59+
- **Future CI support**:
60+
CI workflows are scaffolded for upcoming releases.
61+
62+
63+
## 🛠 Prerequisites
64+
65+
- **Python** ≥ 3.10
66+
- **Copier** ≥ 9.6.0
67+
- **copier-template-extensions** ≥ 0.3.1
68+
- **uv** (if not installed check [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/))
69+
70+
71+
## 🎉 Quickstart
72+
73+
```bash
74+
# 1. Scaffold a new project
75+
76+
# Option 1: Use uvx to run Copier with extensions
77+
uvx --with copier-templates-extensions copier copy --trust gh:bassemkaroui/python-template-uv /path/to/my-project
78+
79+
# Option 2: Install Copier globally
80+
uv tool install copier --with copier-templates-extensions
81+
82+
# Then run
83+
copier copy --trust gh:bassemkaroui/python-template-uv /path/to/my-project
84+
85+
# Notes:
86+
# • copier.yaml automatically runs `git init`, so `--trust` is required
87+
# • Add `--prereleases` to include pre-release versions
88+
# • Add `--vcs-ref=HEAD` to use the latest commit
89+
90+
# 2. Enter your project
91+
cd /path/to/my-project
92+
93+
# 3. Set up development environment and hooks
94+
make setup-dev
95+
96+
# 4. (Optional) Install your CLI globally via uv
97+
make setup-cli
98+
99+
# 5. Run quality & tests
100+
make check # runs all checks: lint, types, docs build, API, etc.
101+
```
102+
103+
**Stay up to date**
104+
```bash
105+
cd /path/to/my-project
106+
107+
uvx copier update --trust --exclude src/ --exclude tests/ .
108+
```
109+
110+
> [!WARNING]
111+
> To be able to [update your project](https://copier.readthedocs.io/en/stable/updating/), do not delete or manually modify the generated `.copier-answers.yml` file.
112+
113+
114+
## 📋 Available Duties
115+
116+
All tasks are defined in `duties.py` and exposed through `make`. Common duties include:
117+
118+
```
119+
build Build source and wheel distributions.
120+
check Check it all!
121+
check-api Check for API breaking changes.
122+
check-docs Check if the documentation builds correctly.
123+
check-quality Run linters and format checks.
124+
check-types Run static type checks.
125+
clean Delete build artifacts.
126+
clean-cache Remove cache files.
127+
coverage Generate coverage reports (text, HTML, XML).
128+
docker-build Build Docker images.
129+
docker-exec-* Dockerized executions of checks, tests, docs, coverage.
130+
docker-start Start Docker Compose services.
131+
docker-stop Stop and remove Docker Compose services.
132+
docs Serve the documentation (localhost:8080).
133+
docs-deploy Publish docs to GitHub Pages.
134+
format Auto-format code (Ruff).
135+
publish Upload distributions to PyPI.
136+
release Automate version bump, changelog, and publish.
137+
setup Bootstrap prod environment.
138+
setup-cli Install the project's CLI globally via uv.
139+
setup-dev Bootstrap dev environment & install pre-commit hooks.
140+
test Run tests with pytest.
141+
tox Run tests across multiple Python versions.
142+
```
143+
144+
For the full list and details, see [duties.py](https://github.com/bassemkaroui/python-template-uv/blob/main/template/duties.py.jinja).
145+
146+
147+
## 🔧 Template Variables
148+
149+
When running `copier`, you’ll be prompted for:
150+
151+
| Variable | Description | Default |
152+
| -------------------------- | ---------------------------------------------------------------- | ------------------ |
153+
| `project_name` | Your project’s **name** (lowercase, letters/digits/dashes) | *—* |
154+
| `project_description` | A short summary of what your project does | *—* |
155+
| `author_fullname` | Your full name | from `git` |
156+
| `author_email` | Your email address | from `git` |
157+
| `repository_provider` | Where you host your repo (`github` or `other`) | `github` |
158+
| `homepage` | Project homepage URL | `https://<user>.github.io/<proj>` |
159+
| `python_version` | Default Python interpreter for development | `3.12` |
160+
| `min_python_version` | Minimum supported Python version | `3.10` |
161+
| `with_typer_cli` | Include a Typer CLI scaffold? | `false` |
162+
| `with_strict_typing` | Enable strict typing enforcement? | `false` |
163+
| `tox` | Include Tox configuration? | `true` |
164+
| `coverage_threshold` | Minimum test coverage % | `100` |
165+
| `with_conventional_commits`| Enforce Conventional Commits? | `true` |
166+
| `cz_gitmoji` | Include emojis in commit messages? | `true` |
167+
| `dockerfile` | Generate Dockerfile and Compose file? | `true` |
168+
| `gpus` | Enable GPU support in Docker builds? | `false` |
169+
170+
> See the full list in [copier.yaml](https://github.com/bassemkaroui/python-template-uv/blob/main/copier.yaml).
171+
172+
173+
## 📄 License
174+
175+
This project is released under the **MIT License**. See [LICENSE](https://github.com/bassemkaroui/python-template-uv/blob/main/LICENSE) for details.

‎template/README.md.jinja‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,28 @@
1+
<div align="center">
2+
13
# {{ project_name }}
24

3-
{% if repository_provider == 'github' -%}
4-
[![Release](https://img.shields.io/github/v/release/{{ author_github_handle }}/{{ project_name }})](https://img.shields.io/github/v/release/{{ author_github_handle }}/{{ project_name }})
5-
[![Build status](https://img.shields.io/github/actions/workflow/status/{{ author_github_handle }}/{{ project_name }}/main.yml?branch=main)](https://github.com/{{ author_github_handle }}/{{ project_name }}/actions/workflows/main.yml?query=branch%3Amain)
6-
[![codecov](https://codecov.io/gh/{{ author_github_handle }}/{{ project_name }}/branch/main/graph/badge.svg)](https://codecov.io/gh/{{ author_github_handle }}/{{ project_name }})
7-
[![Commit activity](https://img.shields.io/github/commit-activity/m/{{ author_github_handle }}/{{ project_name }})](https://img.shields.io/github/commit-activity/m/{{ author_github_handle }}/{{ project_name }})
8-
[![License](https://img.shields.io/github/license/{{ author_github_handle }}/{{ project_name }})](https://img.shields.io/github/license/{{ author_github_handle }}/{{ project_name }})
5+
{{ project_description }}
6+
7+
[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier)
8+
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
9+
[![Python Versions](https://img.shields.io/badge/python-{{ min_python_version }}%20|%20{% for minor in range(min_python_version.split('.')[1]|int, 14) %}3.{{ minor }}{% if not loop.last %}%20|%20{% endif %}{% endfor %}-blue.svg)]()
10+
{%- if publish_to_pypi %}
11+
[![PyPI](https://img.shields.io/pypi/v/{{ project_name }})](https://pypi.org/project/{{ project_name }}/)
12+
{%- endif %}
13+
{%- if repository_provider == 'github' %}
14+
[![Release](https://img.shields.io/github/v/release/{{ author_github_handle }}/{{ project_name }})](https://github.com/{{ author_github_handle }}/{{ project_name }}/releases)
15+
[![Commit activity](https://img.shields.io/github/commit-activity/m/{{ author_github_handle }}/{{ project_name }})](https://github.com/{{ author_github_handle }}/{{ project_name }}/commits)
16+
[![GitHub](https://img.shields.io/github/license/{{ author_github_handle }}/{{ project_name }})](https://github.com/{{ author_github_handle }}/{{ project_name }}/blob/main/LICENSE)
917
{%- endif %}
18+
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
19+
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
20+
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
21+
{%- if with_conventional_commits %}
22+
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
23+
{%- endif %}
24+
{%- if repository_provider == 'github' %}
25+
[![documentation](https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat)]({{ documentation }})
26+
{%- endif %}
27+
28+
</div>

0 commit comments

Comments
 (0)