Merge pull request #38 from developmentseed/feature/switch-to-uv

update python/dockerimage and switch to uv

Author: vincentsarago

.github/workflows/ci.yml

@@ -19,36 +19,37 @@ on:
   # Run tests on pull requests.
   pull_request:
 env:
-  LATEST_PY_VERSION: '3.12'
+  LATEST_PY_VERSION: '3.13'
 
 
 jobs:
   tests:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.11', '3.12', '3.13']
 
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - uses: actions/checkout@v5
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
+          version: "0.9.*" 
+          enable-cache: true
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          python -m pip install -e .["test"]
+          uv sync
 
       - name: run pre-commit
         if: ${{ matrix.python-version == env.LATEST_PY_VERSION }}
         run: |
-          python -m pip install pre-commit
-          pre-commit run --all-files
+          uv run pre-commit run --all-files
 
       - name: Run tests
-        run: python -m pytest --cov titiler.stacapi --cov-report term-missing -s -vv
+        run: uv run pytest --cov titiler.stacapi --cov-report term-missing -s -vv
 
       - name: Upload Results
         if: ${{ matrix.python-version == env.LATEST_PY_VERSION }}
@@ -64,17 +65,17 @@ jobs:
     runs-on: ubuntu-latest
     if: startsWith(github.event.ref, 'refs/tags') || github.event_name == 'release'
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: ${{ env.LATEST_PY_VERSION }}
+          version: "0.9.*" 
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          python -m pip install wheel twine build
-          python -m pip install .
+          uv sync
 
       - name: Set tag version
         id: tag
@@ -90,12 +91,12 @@ jobs:
       - name: Build and publish
         if: ${{ steps.tag.outputs.version }} == ${{ steps.module.outputs.version}}
         env:
-          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
-          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+          UV_PUBLISH_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          UV_PUBLISH_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
         run: |
           rm -rf dist
-          python -m build
-          twine upload dist/*
+          uv build
+          uv publish dist/*
 
   publish-docker:
     needs: [tests]
@@ -105,7 +106,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3

.github/workflows/deploy_mkdocs.yml

@@ -19,17 +19,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout main
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
-      - name: Set up Python 3.11
-        uses: actions/setup-python@v5
+      - 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 mkdocs mkdocs-material pygments
+          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

.pre-commit-config.yaml

@@ -1,29 +1,24 @@
 repos:
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.12.1
+    rev: v0.24
     hooks:
       - id: validate-pyproject
 
-  - repo: https://github.com/psf/black
-    rev: 22.12.0
-    hooks:
-      - id: black
-        language_version: python
-
   - repo: https://github.com/PyCQA/isort
     rev: 5.12.0
     hooks:
       - id: isort
         language_version: python
 
-  - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.290
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
     hooks:
       - id: ruff
         args: ["--fix"]
+      - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.5.1
+    rev: v1.11.2
     hooks:
       - id: mypy
         language_version: python

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+* switch to `uv` for development
+* switch to `hatch` for python package build-system
+* remove `titiler` metapackage **breaking change**
+* add support for python version 3.13
+* bump minimum python version to 3.11
+* update docker image to python:3.13
+
 ## [0.3.3] - 2025-11-06
 
 * fix single date query to only select one day (author @wschoors, https://github.com/developmentseed/titiler-stacapi/pull/34)

CONTRIBUTING.md

@@ -2,23 +2,53 @@
 
 Issues and pull requests are more than welcome: https://github.com/developmentseed/titiler-stacapi/issues
 
+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/developmentseed/titiler-stacapi.git
 cd titiler-stacapi
 
-python -m pip install pre-commit -e .["dev,test"]
+uv sync
 ```
 
 You can then run the tests with the following command:
 
 ```sh
-python -m pytest --cov titiler.stacapi --cov-report term-missing
+uv run pytest --cov titiler.stacapi --cov-report term-missing
 ```
 
 This repo is set to use `pre-commit` to run *isort*, *flake8*, *pydocstring*, *black* ("uncompromising Python code formatter") 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/developmentseed/titiler-stacapi.git
+cd titiler-stacapi
+
+# Build docs
+uv run --group docs mkdocs build -f docs/mkdocs.yml
+```
+
+Hot-reloading docs:
+
+```bash
+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
+uv run --group docs mkdocs gh-deploy -f docs/mkdocs.yml
+```

Dockerfile

@@ -0,0 +1,34 @@
+ARG PYTHON_VERSION=3.13
+
+FROM python:${PYTHON_VERSION}
+RUN apt update && apt upgrade -y \
+  && apt install curl -y \
+  && rm -rf /var/lib/apt/lists/*
+
+# Ensure root certificates are always updated at evey container build
+# and curl is using the latest version of them
+RUN mkdir /usr/local/share/ca-certificates/cacert.org
+RUN cd /usr/local/share/ca-certificates/cacert.org && curl -k -O https://www.cacert.org/certs/root.crt
+RUN cd /usr/local/share/ca-certificates/cacert.org && curl -k -O https://www.cacert.org/certs/class3.crt
+RUN update-ca-certificates
+ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
+
+RUN python -m pip install -U pip
+RUN python -m pip install uvicorn uvicorn-worker gunicorn
+
+COPY titiler/ titiler/
+COPY pyproject.toml pyproject.toml
+COPY README.md README.md
+COPY LICENSE LICENSE
+
+RUN python -m pip install --no-cache-dir --upgrade .
+RUN rm -rf titiler/ pyproject.toml README.md LICENSE
+
+###################################################
+# For compatibility (might be removed at one point)
+ENV MODULE_NAME=titiler.stacapi.main
+ENV VARIABLE_NAME=app
+ENV HOST=0.0.0.0
+ENV PORT=80
+ENV WEB_CONCURRENCY=1
+CMD gunicorn -k uvicorn.workers.UvicornWorker ${MODULE_NAME}:${VARIABLE_NAME} --bind ${HOST}:${PORT} --workers ${WEB_CONCURRENCY}

README.md

@@ -69,7 +69,7 @@ $ export TITILER_STACAPI_STAC_API_URL=https://api.stac
 $ docker-compose up --build api
 ```
 
-It runs `titiler.stacapi` using Gunicorn web server.
+It runs `titiler.stacapi` using Uvicorn web server.
 
 ### How it works
 

docker-compose.yml

@@ -1,13 +1,10 @@
-version: '3'
-
 services:
   api:
     # At the time of writing, rasterio wheels are not available for arm64 arch
     # so we force the image to be built with linux/amd64
     platform: linux/amd64
     build:
       context: .
-      dockerfile: dockerfiles/Dockerfile
     ports:
       - "8081:8081"
     environment:
@@ -45,6 +42,4 @@ services:
       # TiTiler STAC API Config
       - TITILER_STACAPI_API_DEBUG=TRUE
       - TITILER_STACAPI_STAC_API_URL=${TITILER_STACAPI_STAC_API_URL}
-    command:
-      # You can also overwrite the CMD option and use simple `uvicorn` ASGI server
-      bash -c "uvicorn titiler.stacapi.main:app --port 8081 --host 0.0.0.0"
+    command: ["uvicorn", "titiler.stacapi.main:app", "--host", "0.0.0.0", "--port", "8081", "--workers", "1"]

dockerfiles/Dockerfile

@@ -141,7 +141,6 @@
     }
    ],
    "source": [
-    "\n",
     "from owslib.wmts import WebMapTileService\n",
     "\n",
     "wmts = WebMapTileService(\n",
@@ -164,7 +163,7 @@
     "print(layer.tilematrixsetlinks[\"WebMercatorQuad\"].tilematrixlimits)\n",
     "print()\n",
     "print(\"Layer dimensions\")\n",
-    "print(layer.dimensions)\n"
+    "print(layer.dimensions)"
    ]
   },
   {
@@ -174,10 +173,10 @@
    "outputs": [],
    "source": [
     "tile = wmts.gettile(\n",
-    "    layer='MAXAR_Emilia_Romagna_Italy_flooding_may23_visual',\n",
+    "    layer=\"MAXAR_Emilia_Romagna_Italy_flooding_may23_visual\",\n",
     "    style=\"default\",\n",
-    "    tilematrixset='WebMercatorQuad',\n",
-    "    tilematrix='13',\n",
+    "    tilematrixset=\"WebMercatorQuad\",\n",
+    "    tilematrix=\"13\",\n",
     "    column=4373,\n",
     "    row=2963,\n",
     "    format=\"image/png\",\n",
@@ -298,22 +297,15 @@
    "source": [
     "from folium import Map, TileLayer\n",
     "\n",
-    "m = Map(\n",
-    "    location=(44.52, 12.22),\n",
-    "    zoom_start=14\n",
-    ")\n",
+    "m = Map(location=(44.52, 12.22), zoom_start=14)\n",
     "\n",
     "collection = \"MAXAR_Emilia_Romagna_Italy_flooding_may23\"\n",
     "TIME = \"2023-05-23\"\n",
     "TileMatrixSet = \"WebMercatorQuad\"\n",
     "\n",
     "tiles_url = f\"http://127.0.0.1:8000/{collection}/default/{TIME}/{TileMatrixSet}/{{z}}/{{x}}/{{y}}.png?assets=visual&asset_bidx=visual%7C1%2C2%2C3\"\n",
     "\n",
-    "TileLayer(\n",
-    "    tiles=tiles_url,\n",
-    "    opacity=1,\n",
-    "    attr=\"DigitalGlobe OpenData\"\n",
-    ").add_to(m)\n",
+    "TileLayer(tiles=tiles_url, opacity=1, attr=\"DigitalGlobe OpenData\").add_to(m)\n",
     "\n",
     "m"
    ]