From b3276b8e2b8ff86dc7bb8d838165c6e232f4e204 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 2 Apr 2026 00:18:48 +0000 Subject: [PATCH 1/2] docs: modernize READMEs Co-authored-by: buddingengineers12345 --- README.md | 94 ++++++++++++++++++++++++++++------------ template/README.md.jinja | 39 ++++++++++++----- 2 files changed, 95 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 86213cb..7eb2025 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,100 @@ -# Copier uv-first Python template +# uv-first Python project template (Copier) -This repository is a **Copier** template that generates a modern Python library or application layout using **uv** for dependency management, **ruff** for formatting/linting, and **basedpyright** for type checking. Optional prompts add **NumPy**, **pandas**, and **MkDocs** when you want a data-oriented or documented project. +This repository is a **Copier template** for generating a modern, batteries-included Python project that is: -Reference: [copier-org/copier README](https://github.com/copier-org/copier?tab=readme-ov-file) +- **uv-first**: reproducible installs with a committed `uv.lock` +- **fast to iterate**: one `just ci` command mirrors your local/CI checks +- **strict by default**: ruff for lint/format and basedpyright for type checking +- **optionally data- and docs-ready**: toggle NumPy/pandas and MkDocs during generation -## Prerequisites +This repo is the **template source** (a meta-project), not the generated project itself. + +## What you get + +- **Dependency workflow**: `uv` + lockfile-first installs (`uv sync --frozen`) +- **Quality gates**: ruff (format + lint), basedpyright (strict typing), pytest +- **Automation**: pre-commit hooks and a `justfile` with common commands +- **CI-ready defaults**: GitHub Actions workflow and coverage upload wiring (optional) +- **Update-friendly**: conservative `copier update` behavior via `_skip_if_exists` + +## Quickstart: generate a new project + +Prerequisites: - Python 3.11+ - Git -- `uv` -- `copier` - -## Getting started (developing this template) +- `copier` (installed however you prefer) -Sync dev dependencies (uses the committed lockfile): +Generate a project from this repo root: ```bash -uv sync --frozen --extra dev +copier copy . /path/to/new-project --trust --defaults ``` -Run template tests: +Common flags: + +- **`--defaults`**: accept defaults for all questions +- **`--trust`**: allow running post-generation tasks (install, format, type-check, hooks) +- **`--data key=value`**: answer questions non-interactively (useful in scripts/CI) + +After generation, the new project will include a `justfile`. Typical first run: ```bash -uv run pytest +just ci ``` -## Generating a project from this template +## Template options (prompts) + +During `copier copy`, you’ll be asked for: + +- **Project identity**: `project_name`, `project_slug`, `package_name`, description, author, GitHub org/user +- **Python baseline**: minimum version (3.11 / 3.12 / 3.13) +- **Add-ons**: + - **Docs**: MkDocs setup (`include_docs`) + - **Data stack**: NumPy (`include_numpy`) and pandas (`include_pandas_support`) +- **Codecov**: leave the `codecov_token` prompt empty; prefer the GitHub secret described below + +## Updating a generated project -From this repo root: +Generated projects store answers in `.copier-answers.yml`. To update a project to the latest template: ```bash -copier copy . /path/to/new-project --trust --defaults +copier update --trust --defaults ``` -Common flags: +This template is intentionally conservative about overwriting user-edited files (see `copier.yml`’s `_skip_if_exists`). -- `--defaults`: accept defaults for all questions -- `--trust`: allow running template tasks (post-generation commands) -- `--data key=value`: provide answers non-interactively +## Developing this template -## Updating a generated project +Install dev dependencies for the template repo (uses the committed lockfile): -If you generated a project from this template, Copier stores answers in `.copier-answers.yml` in the generated project. +```bash +just sync +``` -To update: +Run the full local CI mirror: ```bash -copier update --trust --defaults +just ci ``` +Other useful commands: + +- **`just fmt`**: format +- **`just lint`**: lint +- **`just type`**: type check +- **`just test`**: run template integration tests (renders the template and asserts output) + ## FAQ -### Why does CI use `uv sync --frozen`? +### Why is this “uv-first”? + +Both this template repo and generated projects expect a committed `uv.lock`. In CI and locally, `uv sync --frozen` keeps installs reproducible and fails fast on drift. + +### How does Codecov work in generated projects? -This template repository and generated projects are expected to commit a `uv.lock`. That keeps installs reproducible in CI and locally. +If you enable coverage upload in your CI setup, configure a **repository secret** named `CODECOV_TOKEN` in GitHub. You typically do not need to provide a token as a Copier answer. -### Codecov in generated projects +## References -The template can wire GitHub Actions to upload coverage. Configure a **repository secret** named `CODECOV_TOKEN` in GitHub (Codecov’s token); you do not need to paste that token into Copier answers. +- Copier docs: `https://github.com/copier-org/copier` diff --git a/template/README.md.jinja b/template/README.md.jinja index eea4e4a..5f1567a 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -2,34 +2,51 @@ {{ project_description }} +## What this project includes + +- **uv-first workflow** with a committed lockfile (`uv.lock`) +- **Quality gates**: ruff (format + lint), basedpyright (type checking), pytest +- **One-command workflows** via `just` (mirrors local/CI checks) +{% if include_docs -%} +- **Docs**: MkDocs site in `docs/` (served via `just docs`) +{%- endif %} + ## Quickstart -Install `uv` (see `https://astral.sh/uv/`), then: +Prerequisites: -```bash -uv sync --frozen --extra dev --extra test{% if include_docs %} --extra docs{% endif %} -``` +- Python {{ python_min_version }}+ +- `uv` (install from `https://astral.sh/uv/`) -Run tests: +Create the environment and install dependencies: ```bash -uv run pytest +uv sync --frozen --extra dev --extra test{% if include_docs %} --extra docs{% endif %} ``` -## Development - -Common commands: +Run the full local CI mirror: ```bash just ci ``` +## Common commands + +- `just test` +- `just fmt` +- `just lint` +- `just type` +- `just ci` +{% if include_docs -%} +- `just docs` +{%- endif %} + ## Project layout -- `src/{{ package_name }}/`: library code +- `src/{{ package_name }}/`: package source - `tests/`: test suite {% if include_docs -%} -- `docs/`: documentation source +- `docs/`: documentation {%- endif %} ## License From be98355f3a71c8521fd83ab0b434bb5a5657c74b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 2 Apr 2026 00:22:06 +0000 Subject: [PATCH 2/2] docs: rename README title Co-authored-by: buddingengineers12345 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7eb2025..82f8d2c 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# uv-first Python project template (Copier) +# Python Starter Template This repository is a **Copier template** for generating a modern, batteries-included Python project that is: