switch to uv and pyproject.toml (#855)

* switch to uv and pyproject.toml

* refactor docs

* use uvx

* remove strict

* update python version

* use dependency-groups more, upgrade setup-uv action

* fix publish

* limit fastapi to <0.118.0

* add uv installation note

---------

Co-authored-by: hrodmn <[email protected]>

Author: vincentsarago

.github/workflows/cicd.yaml

@@ -5,53 +5,59 @@ on:
   pull_request:
     branches: [main]
 
+env:
+  LATEST_PY_VERSION: '3.14'
+
 jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
     timeout-minutes: 20
 
     steps:
       - name: Check out repository code
         uses: actions/checkout@v5
-
-      # Setup Python (faster than using Python container)
-      - name: Setup Python
-        uses: actions/setup-python@v6
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Lint code
-        if: ${{ matrix.python-version == 3.13 }}
-        run: |
-          python -m pip install pre-commit
-          pre-commit run --all-files
+          version: "0.9.*" 
+          enable-cache: true
+    
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
 
-      - name: Install types
+      - name: Install dependencies
         run: |
-          python -m pip install ./stac_fastapi/types[dev]
+          uv sync
 
-      - name: Install core api
-        run: |
-          python -m pip install ./stac_fastapi/api[dev]
-
-      - name: Install Extensions
+      - name: Lint code
+        if: ${{ matrix.python-version == env.LATEST_PY_VERSION }}
         run: |
-          python -m pip install ./stac_fastapi/extensions[dev]
+          uv run pre-commit run --all-files
 
-      - name: Test
-        run: python -m pytest -svvv
+      - name: Run tests
+        run: uv run pytest -svvv
         env:
           ENVIRONMENT: testing
 
   test-docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - name: Test generating docs
-        run: make docs
+      - name: Checkout main
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.9.*" 
+          enable-cache: true
+    
+      - name: Test docs
+        run: |
+          uv run --group docs mkdocs build -f docs/mkdocs.yml 
 
   benchmark:
     needs: [test]
@@ -60,25 +66,18 @@ jobs:
       - name: Check out repository code
         uses: actions/checkout@v5
 
-      - name: Setup Python
-        uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: "3.13"
-
-      - name: Install types
-        run: |
-          python -m pip install ./stac_fastapi/types[dev]
-
-      - name: Install core api
-        run: |
-          python -m pip install ./stac_fastapi/api[dev,benchmark]
-
-      - name: Install extensions
+          version: "0.9.*" 
+          enable-cache: true
+    
+      - name: Install dependencies
         run: |
-          python -m pip install ./stac_fastapi/extensions
+          uv sync 
 
       - name: Run Benchmark
-        run: python -m pytest stac_fastapi/api/tests/benchmarks.py --benchmark-only --benchmark-columns 'min, max, mean, median' --benchmark-json output.json
+        run: uv run pytest stac_fastapi/api/tests/benchmarks.py --benchmark-only --benchmark-columns 'min, max, mean, median' --benchmark-json output.json
 
       - name: Store and benchmark result
         if: github.repository == 'stac-utils/stac-fastapi'

.github/workflows/deploy_mkdocs.yml

@@ -20,18 +20,11 @@ jobs:
       - name: Checkout main
         uses: actions/checkout@v5
 
-      - name: Set up Python 3.11
-        uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: 3.11
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install \
-            stac_fastapi/types[docs] \
-            stac_fastapi/api[docs] \
-            stac_fastapi/extensions[docs] \
-
+          version: "0.9.*" 
+          enable-cache: true
+    
       - name: Deploy docs
-        run: mkdocs gh-deploy --force -f docs/mkdocs.yml
+        run: uv run --group docs mkdocs gh-deploy --force -f docs/mkdocs.yml

.github/workflows/publish.yml

@@ -12,19 +12,15 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
-      - name: Set up Python 3.x
-        uses: actions/setup-python@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: "3.x"
-
-      - name: Install release dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install setuptools wheel twine
-
+          version: "0.9.*" 
+          enable-cache: true
+    
       - name: Build and publish package
         env:
-          TWINE_USERNAME: ${{ secrets.PYPI_STACUTILS_USERNAME }}
-          TWINE_PASSWORD: ${{ secrets.PYPI_STACUTILS_PASSWORD }}
+          UV_PUBLISH_USERNAME: ${{ secrets.PYPI_STACUTILS_USERNAME }}
+          UV_PUBLISH_PASSWORD: ${{ secrets.PYPI_STACUTILS_PASSWORD }}
         run: |
           scripts/publish

CHANGES.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+### Changed 
+
+- switch to pyproject.toml for package metadata
+- use `uv` for project managment
+- add python 3.14 support
+
 ## [6.0.0] - 2025-06-19
 
 ### Changed

CONTRIBUTING.md

@@ -2,40 +2,48 @@
 
 Issues and pull requests are more than welcome.
 
+We recommand using [`uv`](https://docs.astral.sh/uv) as project manager for development.
+
+See https://docs.astral.sh/uv/getting-started/installation/ for installation 
+
 **dev install**
 
 ```bash
 git clone https://github.com/stac-utils/stac-fastapi.git
 cd stac-fastapi
-python -m pip install -e stac_fastapi/api[dev]
+uv sync --dev
 ```
 
 **pre-commit**
 
 This repo is set to use `pre-commit` to run *ruff*, *pydocstring* and mypy when committing new code.
 
 ```bash
-pre-commit install
+uv run pre-commit install 
+
+# If needed, you can run pre-commit script manually 
+uv run pre-commit run --all-files 
 ```
 
 ### Docs
 
 ```bash
 git clone https://github.com/stac-utils/stac-fastapi.git
 cd stac-fastapi
-python pip install -e stac_fastapi/api["docs"]
+# Build docs
+uv run --group docs mkdocs build -f docs/mkdocs.yml
 ```
 
 Hot-reloading docs:
 
 ```bash
-$ mkdocs serve -f docs/mkdocs.yml
+uv run --group docs mkdocs serve -f docs/mkdocs.yml --livereload
 ```
 
 To manually deploy docs (note you should never need to do this because GitHub
 Actions deploys automatically for new commits.):
 
 ```bash
 # deploy
-$ mkdocs gh-deploy -f docs/mkdocs.yml
+uv run --group docs mkdocs gh-deploy -f docs/mkdocs.yml
 ```

Dockerfile

@@ -1,22 +1,16 @@
-FROM python:3.12-slim AS base
-
-# Any python libraries that require system libraries to be installed will likely
-# need the following packages in order to build
-RUN apt-get update && \
-    apt-get -y upgrade && \
-    apt-get install -y build-essential git && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
-
-ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
-
-FROM base AS builder
+FROM ghcr.io/astral-sh/uv:python3.14-bookworm-slim
 
 WORKDIR /app
 
+RUN apt-get update && apt-get install -y gcc
 COPY . /app
 
-RUN python -m pip install \
-    -e ./stac_fastapi/types[dev] \
-    -e ./stac_fastapi/api[dev] \
-    -e ./stac_fastapi/extensions[dev]
+ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+ENV UV_TOOL_BIN_DIR=/usr/local/bin
+RUN --mount=type=cache,target=/root/.cache/uv \
+  --mount=type=bind,source=uv.lock,target=uv.lock \
+  uv sync --locked --no-dev
+
+ENV PATH="/app/.venv/bin:$PATH"

Dockerfile.docs

@@ -4,21 +4,16 @@ image:
 
 .PHONY: install
 install:
-	python -m pip install wheel && \
-	python -m pip install -e ./stac_fastapi/types[dev] && \
-	python -m pip install -e ./stac_fastapi/api[dev] && \
-	python -m pip install -e ./stac_fastapi/extensions[dev]
+	uv sync --dev
 
-.PHONY: docs-image
-docs-image:
-	docker compose -f compose.docs.yml \
-		build
+.PHONY: test
+test: install
+	uv run pytest
 
 .PHONY: docs
-docs: docs-image
-	docker compose -f compose.docs.yml \
-		run docs
+docs:
+	uv run --group docs mkdocs build -f docs/mkdocs.yml
 
-.PHONY: test
-test: image
-	python -m pytest .
+.PHONY: benchmark
+benchmark: install
+	uv run pytest stac_fastapi/api/tests/benchmarks.py --benchmark-only --benchmark-columns 'min, max, mean, median' 

Makefile

@@ -77,17 +77,18 @@ Other backends may be available from other sources, search [PyPI](https://pypi.o
 
 Install the packages in editable mode:
 
+We recommand using [`uv`](https://docs.astral.sh/uv) as project manager for development.
+
+See https://docs.astral.sh/uv/getting-started/installation/ for installation 
+
 ```shell
-python -m pip install \
-  -e 'stac_fastapi/types[dev]' \
-  -e 'stac_fastapi/api[dev]' \
-  -e 'stac_fastapi/extensions[dev]'
+uv sync --dev
 ```
 
 To run the tests:
 
 ```shell
-python -m pytest
+uv run pytest
 ```
 
 ## Releasing

README.md

@@ -8,7 +8,7 @@ This is a checklist for releasing a new version of **stac-fastapi**.
 
     Note: You can use [`bump-my-version`](https://github.com/callowayproject/bump-my-version) CLI
     ```
-    bump-my-version bump --new-version 3.1.0
+    uv run bump-my-version bump --new-version 3.1.0
     ```
 
 4. Update [CHANGES.md](./CHANGES.md) for the new version. Add the appropriate header, and update the links at the bottom of the file.