afuetterer · afuetterer · Feb 5, 2025 · Feb 2, 2025
@@ -45,18 +45,10 @@ If you are proposing a feature:
 
 Ready to contribute?
 
-You need Python >= 3.10 and [hatch](https://github.com/pypa/hatch). You can install it globally with
-[pipx](https://github.com/pypa/pipx):
-
-```console
-$ pipx install hatch
-```
-
-or locally with (this will install it in the local virtual environment):
-
-```console
-$ python -m pip install hatch
-```
+You need Python >= 3.10 and [uv](https://github.com/astral-sh/uv). Please refer to the
+[installation instructions](https://docs.astral.sh/uv/getting-started/installation/) in the `uv` documentation. For
+convenience in running project tasks, we recommend using the `just` command runner. See the documentation for
+[installation instructions](https://github.com/casey/just#installation).
 
 Here's how to set up `python-re3data` for local development.
 
@@ -68,12 +60,12 @@ Here's how to set up `python-re3data` for local development.
     $ git clone git@github.com:username/python-re3data.git
     ```
 
-3. Install your local copy into a virtual environment. Assuming you have hatch installed, this is how you set up your
+3. Install your local copy into a virtual environment. Assuming you have `uv` installed, this is how you set up your
     fork for local development:
 
     ```console
     $ cd python-re3data
-    $ hatch shell
+    $ uv sync --frozen
     ```
 
 4. Create a branch for local development:
@@ -84,11 +76,11 @@ Here's how to set up `python-re3data` for local development.
 
     Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass pre-commit and the tests:
+5. When you're done making changes, check that your changes pass `pre-commit` and the tests:
 
     ```console
-    $ hatch run check
-    $ hatch run cov
+    $ just check
+    $ just cov
     ```
 
 6. Commit your changes and push your branch to GitHub:

@@ -18,14 +18,30 @@ permissions: {}
 env:
   PYTHONUNBUFFERED: 1
   FORCE_COLOR: 1
+  UV_FROZEN: true # do not update the lockfile during `uv sync` and `uv run` commands
 
 jobs:
   test:
     uses: ./.github/workflows/test.yml
+
   docs:
-    permissions:
-      contents: write
-    uses: ./.github/workflows/docs.yml
+    # disables this workflow from running in a repository that is not part of the indicated organization/user
+    if: github.repository_owner == 'afuetterer'
+    runs-on: ubuntu-24.04
+    steps:
+    - name: Set up just
+      uses: extractions/setup-just@v2
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+    - name: Set up uv
+      uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
+      with:
+        python-version: '3.13'
+        enable-cache: true
+        prune-cache: false
+        cache-suffix: docs
+    - run: just sync-docs
+    - run: just docs-build
+
   required-checks-pass:
     if: always()
     needs:

@@ -8,6 +8,9 @@ on:
 # Set permissions at the job level.
 permissions: {}
 
+env:
+  UV_FROZEN: true # do not update the lockfile during `uv sync` and `uv run` commands
+
 jobs:
   build:
     name: Build the package
@@ -17,6 +20,7 @@ jobs:
     steps:
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
     - uses: hynek/build-and-inspect-python-package@b5076c307dc91924a82ad150cdd1533b444d3310 # v2.12.0
+
   upload:
     name: Upload package distributions to GitHub Releases
     # disables this workflow from running in a repository that is not part of the indicated organization/user
@@ -35,6 +39,7 @@ jobs:
       uses: softprops/action-gh-release@c95fe1489396fe8a9eb87c0abf8aa5b2ef267fda # v2.2.1
       with:
         files: dist/*
+
   publish:
     # disables this workflow from running in a repository that is not part of the indicated organization/user
     if: github.repository_owner == 'afuetterer'
@@ -95,3 +100,28 @@ jobs:
         labels: ${{ steps.meta.outputs.labels }}
         # Ref: https://docs.docker.com/build/attestations/slsa-provenance/
         provenance: false
+
+  docs:
+    # disables this workflow from running in a repository that is not part of the indicated organization/user
+    if: github.repository_owner == 'afuetterer'
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+    - name: Set up just
+      uses: extractions/setup-just@v2
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      with:
+        fetch-depth: 0 # fetch all commits and branches
+    - name: Set up uv
+      uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
+      with:
+        python-version: '3.13'
+        enable-cache: true
+        prune-cache: false
+        cache-suffix: docs
+    - run: just sync-docs
+    - run: just docs-deploy
+      env:
+        GIT_COMMITTER_NAME: github-actions[bot]
+        GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
@@ -9,6 +9,7 @@ permissions: {}
 env:
   PYTHONUNBUFFERED: 1
   FORCE_COLOR: 1
+  UV_FROZEN: true # do not update the lockfile during `uv sync` and `uv run` commands
 
 jobs:
   test:
@@ -18,23 +19,26 @@ jobs:
       matrix:
         python-version: ['3.10', '3.12', '3.13']
     steps:
+    - name: Set up just
+      uses: extractions/setup-just@v2
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+    - name: Set up uv
+      uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
       with:
         python-version: ${{ matrix.python-version }}
-        cache: pip
-    - name: Install pre-requisites (e.g. hatch)
-      run: python -m pip install --require-hashes --requirement=requirements/ci
+        enable-cache: true
+        prune-cache: false
+    - name: Install project, including dev dependencies
+      run: just sync
     - name: Run test suite
-      run: hatch run cov
+      run: just cov
       env:
         TERM: dumb # keep rich from printing escape sequences, which made testing CLI outputs messy
     - name: Generate coverage report
       run: |
         export TOTAL_COV=$(hatch run cov-total)
         echo "TOTAL_COV=$TOTAL_COV" >> $GITHUB_ENV
-        hatch run cov-report-markdown
+        just cov-report-markdown
         echo "### Total coverage: ${TOTAL_COV}%" >> $GITHUB_STEP_SUMMARY
         cat coverage.md >> $GITHUB_STEP_SUMMARY
       if: matrix.python-version == '3.13'
@@ -66,31 +70,32 @@ jobs:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
     steps:
+    - name: Set up just
+      uses: extractions/setup-just@v2
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-    - uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
+    - name: Set up uv
+      uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
       with:
         python-version: '3.13'
-        cache: pip
-    - run: python -Im pip install --editable .[dev]
+        enable-cache: true
+        prune-cache: false
+    - run: just sync
     - run: python -Ic 'import re3data; print(re3data.__version__)'
     - run: re3data --version
-    - name: Set up pipdeptree
-      if: matrix.os == 'ubuntu-latest'
-      run: python -m pip install --require-hashes --requirement=requirements/ci
     - name: Write info to step summary
       if: matrix.os == 'ubuntu-latest'
       run: |
         {
           echo -e "### ✓ All dependencies installed successfully\n\n"
           echo '<details><summary>Installed Python packages (dependency tree)</summary>'
           echo -e "\n\`\`\`console"
-          echo "$ uv pip tree --package=python-re3data"
-          uv pip tree --package=python-re3data
+          echo "$ uv tree --no-group={dev,test}"
+          uv tree --no-group={dev,test}
           echo -e "\`\`\`\n</details>"
           echo '<details><summary>Outdated Python packages</summary>'
           echo -e "\n\`\`\`console"
-          echo "$ python -m pip list --outdated"
-          python -m pip list --outdated
+          echo "$ uv pip list --outdated"
+          uv pip list --outdated
           echo -e "\`\`\`\n</details>"
         } >> $GITHUB_STEP_SUMMARY
 
@@ -107,11 +112,14 @@ jobs:
     env:
       NO_COLOR: 1
     steps:
+    - name: Set up just
+      uses: extractions/setup-just@v2
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-    - uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
+    - name: Set up uv
+      uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
     - name: Get package version
       id: package-version
-      run: echo "version=$(uvx hatch version)" >> $GITHUB_OUTPUT
+      run: echo "version=$(just project-version)" >> $GITHUB_OUTPUT
     - uses: docker/setup-buildx-action@6524bf65af31da8d45b59e8c27de4bd072b392f5 # v3.8.0
     - name: Build and push
       uses: docker/build-push-action@ca877d9245402d1537745e0e356eab47c3520991 # v6.13.0

@@ -9,7 +9,7 @@
 | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | __Docs__    | [![docs][docs-badge]][docs-workflow]                                                                                                                                                                                                                                           |
 | __Package__ | [![pypi-status][status-badge]][pypi-url] [![pypi-version][pypi-version-badge]][pypi-url] [![pypi-python-versions][pypi-python-versions-badge]][pypi-url] [![all-downloads][all-downloads-badge]][pepy-tech-url] [![monthly-downloads][monthly-downloads-badge]][pepy-tech-url] |
-| __Meta__    | [![doi][doi-badge]][doi-url] [![OpenSSF Scorecard][scorecard-badge]][scorecard-url] [![hatch][hatch-badge]][hatch] [![ruff][ruff-badge]][ruff] [![mypy][mypy-badge]][mypy] [![License][license-badge]][license-url]                                                            |
+| __Meta__    | [![doi][doi-badge]][doi-url] [![OpenSSF Scorecard][scorecard-badge]][scorecard-url] [![uv][uv-badge]][uv] [![ruff][ruff-badge]][ruff] [![mypy][mypy-badge]][mypy] [![License][license-badge]][license-url]                                                                     |
 
 `python-re3data` is a Python library that simplifies interacting with the [re3data](https://www.re3data.org) (Registry
 of Research Data Repositories) [REST API](https://www.re3data.org/api/doc), allowing you to easily retrieve and process
@@ -113,8 +113,6 @@ There are a couple of similar projects available on GitHub, e.g. via the topic
 [docs-workflow]: https://github.com/afuetterer/python-re3data/actions/workflows/docs.yml
 [doi-badge]: https://zenodo.org/badge/DOI/10.5281/zenodo.11264510.svg
 [doi-url]: https://doi.org/10.5281/zenodo.11264510
-[hatch]: https://github.com/pypa/hatch
-[hatch-badge]: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg
 [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg
 [license-url]: https://spdx.org/licenses/MIT.html
 [monthly-downloads-badge]: https://static.pepy.tech/badge/python-re3data/month
@@ -131,3 +129,5 @@ There are a couple of similar projects available on GitHub, e.g. via the topic
 [scorecard-badge]: https://api.securityscorecards.dev/projects/github.com/afuetterer/python-re3data/badge
 [scorecard-url]: https://securityscorecards.dev/viewer/?uri=github.com/afuetterer/python-re3data
 [status-badge]: https://img.shields.io/pypi/status/python-re3data?logo=pypi
+[uv]: https://github.com/astral-sh/uv
+[uv-badge]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json