Uv workflow

.github/workflows/python-tests.yml

@@ -4,6 +4,7 @@ name: "python tests and coverage"
 # https://github.com/actions/checkout : 11bd71901bbe5b1630ceea73d27597364c9af683
 # https://github.com/actions/download-artifact : fa0a91b85d4f404e444e00e005971372dc801d16
 # https://github.com/actions/upload-artifact : 6f51ac03b9356f520e9adb1b1b7802705f340c2b
+# https://github.com/astral-sh/setup-uv : 1edb52594c857e2b5b13128931090f0640537287
 
 on:
   pull_request:
@@ -13,6 +14,10 @@ on:
     branches:
       - "main"
 
+env:
+  UV_PYTHON_PREFERENCE: "only-system"
+  UV_LOCKED: "true"
+
 jobs:
   run-tests-and-coverage:
     name: "Run nox for tests and coverage"
@@ -41,13 +46,16 @@ jobs:
           python-version: "${{ matrix.python-version }}"
           allow-prereleases: true
 
-      - name: "Install nox"
-        run: |
-          python -m pip install --upgrade pip nox
+      - name: "Install the latest version of uv"
+        uses: "astral-sh/setup-uv@1edb52594c857e2b5b13128931090f0640537287"
+        with:
+          version: "latest"
+          python-version: "${{ matrix.python-version }}"
+          enable-cache: true
 
       - name: "Run tests and coverage via nox"
         run: |
-          nox --session version_coverage-${{ matrix.python-version }}
+          uv run nox --session version_coverage-${{ matrix.python-version }}
 
       - name: "Save coverage artifact"
         uses: "actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b"
@@ -70,19 +78,25 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: "Install nox"
-        run: |
-          python -m pip install --upgrade pip nox
+      - name: "Install the latest version of uv"
+        uses: "astral-sh/setup-uv@1edb52594c857e2b5b13128931090f0640537287"
+        with:
+          version: "latest"
+          python-version: "3.12"
+          enable-cache: true
 
       - name: "Download coverage artifacts"
         uses: "actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16"
         with:
           pattern: "coverage-artifact-*"
           merge-multiple: true
 
-      - name: "Compile coverage data, print report"
+      - name: "Compile coverage data"
+        run: |
+          uv run nox --session coverage_combine
+
+      - name: "Post summary to step summary."
         run: |
-          nox --session coverage_combine
           export TOTAL=$(python -c "import json;print(json.load(open('coverage.json'))['totals']['percent_covered_display'])")
           echo "TOTAL=$TOTAL" >> $GITHUB_ENV
           echo "### Total coverage: ${TOTAL}%" >> $GITHUB_STEP_SUMMARY
@@ -99,10 +113,13 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: "Install nox"
-        run: |
-          python -m pip install --upgrade pip nox
+      - name: "Install the latest version of uv"
+        uses: "astral-sh/setup-uv@1edb52594c857e2b5b13128931090f0640537287"
+        with:
+          version: "latest"
+          python-version: "3.12"
+          enable-cache: true
 
       - name: "Enforce strict type annotations with mypy"
         run: |
-          nox --session mypy
+          uv run nox --session mypy

CONTRIBUTING.md

@@ -35,139 +35,74 @@ prior to submitting a pull request.
   - No test should be dependent on another
   - No test should be dependent on secrets/tokens
 
-
 ---
 
-# Local developer installation
-
-The following steps outline how to install this repo for local development.
+# Developer installation
 
 ## Prerequisites
 
-### Clone repo
-
-```console
-git clone https://github.com/[ORG NAME]/[REPO NAME]
-
-cd [REPO NAME]
-```
-
-### Virtual Environment
-
-Use a ([`venv`](https://docs.python.org/3/library/venv.html)), or equivalent,
-when working with python projects. Leveraging a `venv` will ensure the installed
-dependency files will not impact other python projects or any system
-dependencies.
-
-**Windows users**: Depending on your python install you will use `py` in place
-of `python` to create the `venv`.
+- [**uv**](https://docs.astral.sh/uv) >= 0.6.3
 
-**Linux/Mac users**: Replace `python`, if needed, with the appropriate call to
-the desired version while creating the `venv`. (e.g. `python3` or `python3.12`)
+[Installation options can be found here.](https://docs.astral.sh/uv/getting-started/installation/)
 
-**All users**: Once inside an active `venv` all systems should allow the use of
-`python` for command line instructions. This will ensure you are using the
-`venv`'s python and not the system level python.
+Or just use [pipx](https://pypi.org/project/pipx/)
 
-### Create the `venv`:
-
-```console
-python -m venv .venv
-```
-
-Activate the `venv`:
-
-```console
-# Linux/Mac
-. .venv/bin/activate
-
-# Windows
-.venv\Scripts\activate
+```bash
+pipx install uv
 ```
 
-The command prompt should now have a `(venv)` prefix on it. `python` will now
-call the version of the interpreter used to create the `venv`
 
-To deactivate (exit) the `venv`:
+### Clone repo
 
-```console
-deactivate
+```bash
+git clone https://github.com/[ORG NAME]/[REPO NAME]
 ```
 
 ---
 
-## Developer Installation Steps
+## Developer Installation Commands
 
-### Install editable library and development requirements
+### 1. Install editable library and development requirements
 
-```console
-python -m pip install --editable .[dev,test]
+```bash
+uv sync
 ```
 
-### Install pre-commit [(see below for details)](#pre-commit)
+### 2. Install pre-commit [(see below for details)](#pre-commit)
 
-```console
+```bash
 pre-commit install
 ```
 
-### Install with nox
-
-If you have `nox` installed with `pipx` or in the current venv you can use the
-following session. This is an alternative to the two steps above.
-
-```console
-nox -s install
-```
-
 ---
 
-## Pre-commit and nox tools
+## Nox sessions
 
-### Run pre-commit on all files
+This repo uses [nox](https://nox.thea.codes/en/stable/index.html) to simplify
+workflow actions.
 
-```console
-pre-commit run --all-files
-```
+### Run tests and report coverage (quick):
 
-### Run tests with coverage (quick)
-
-```console
-nox -e coverage
+```bash
+nox --session coverage
 ```
 
-### Run tests (slow)
+### Run tests against all supported versions (slow):
 
-```console
+```bash
 nox
 ```
 
-### Build dist
-
-```console
-nox -e build
-```
-
----
-
-## Updating dependencies
-
-New dependencys can be added to the `requirements-*.in` file. It is recommended
-to only use pins when specific versions or upgrades beyond a certain version are
-to be avoided. Otherwise, allow `pip-compile` to manage the pins in the
-generated `requirements-*.txt` files.
-
-Once updated following the steps below, the package can be installed if needed.
-
-### Update the generated files with changes
+### Run pre-commit on all files
 
-```console
-nox -e update
+```bash
+nox --session pre_commit
 ```
 
-### Upgrade all generated dependencies
+### Build dist
 
-```console
-nox -e upgrade
+```bash
+nox --session build
 ```
 
 ---
@@ -178,9 +113,3 @@ nox -e upgrade
 
 This repo is setup with a `.pre-commit-config.yaml` with the expectation that
 any code submitted for review already passes all selected pre-commit checks.
-
----
-
-## Error: File "setup.py" not found
-
-Update `pip` to at least version 22.3.1

README.md

@@ -14,27 +14,23 @@ This is not the one-shot solution to project structure or packaging. This is
 just what works well for one egg on the Internet. Feel free to use it as you see
 fit.
 
+## Prerequisites
+
+- [**uv**](https://docs.astral.sh/uv) >= 0.6.3
+
 ## FAQ
 
+- **Q:** Why uv over venv and setup-tools?
+  - **A:** Primarily because of the lower barrier of entry that the uv workflow
+    offers to the next-dev and the non-dev. Speed is nice, but where Astral has
+    really pushed value with uv is in the simplicity.
+
 - **Q:** Should I follow everything to the absolute letter in this template?
   - **A:** Heck no, I don't even do that! This is just the closest
     one-size-fits-most template I've put together. Use what you want how you
     want.
 
-- **Q:** Why not put the requirements into the `pyproject.toml`?
-  - **A:** Mostly because `pip-compile` does all the work for me and doesn't
-    target the `pyproject.toml`. Partly because many of my projects need to be
-    scanned by utilities that still think `requirements.txt` is the only pattern
-    to use.
-
 - **Q:** Why does this template change so often?
   - **A:** I'm constantly finding new tweaks that make the template fit just a
     little better. I'm also open to ideas and suggestions so please drop an
     issue if you have one.
-
-- **Q:** Have I heard of uv?
-  - **A:** Yes. I'm already exploring a uv driven workflow for this template.
-    You can see it on the `uv-workflow` branch. I will be waiting until the
-    April 2025 release of pip for support of
-    [dependency-groups](https://packaging.python.org/en/latest/specifications/dependency-groups/)
-    before committing to any changes.