Demo uv tooling

Demonstrates the modern Python tooling with uv.

Description

This is a demo for the modern Python tooling of Astral's uv. There are several design decisions to be made:

• Use uv via Docker, docker run ghcr.io/astral-sh/uv help for example.
• Use the most recent torch-compatible Python version 3.12.
• Use anyIO for async I/O, as recommended by FastAPI.
• Use Pydantic for data validation.
• Use pytest and pytest-cov for coverage-aware testing.
• Use Astral's Ruff for fast and comprehensive linting.
• Use type hints for optional type annotations.
• Use MyPy for type-checking tooling.
• Use FastAPI for a modern, high-performance, async web framework.
• Use Docker for containerization.
• Use uv run to run tooling like MyPy and Pytest locally.
• Use HTTPX as a modern HTTP Client to test the application.

Prerequisites

• Docker
• git
• Python3

Clone the repository

git clone git@gitlab.com:openknowledge-gmbh/openknowledge/university/learning-hours/learning-hour-uv-tooling.git demo-uv-tooling

Go to clone

cd demo-uv-tooling

Note: All following commands assume to run in this project's root directory.

(Re)create a virtual environment

rm -rf .venv | true && python3 -m venv .venv

Upgrade pip

.venv/bin/python -m pip install --upgrade pip

[...]
Successfully installed pip-24.3.1

Install uv

.venv/bin/python -m pip install uv

[...]
Successfully installed uv-0.5.15

Source: https://docs.astral.sh/uv/getting-started/installation/

Install interpreter

.venv/bin/python -m uv python install 3.10 3.11 3.12

Installed 3 versions [...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-python-install

Get help on uv

.venv/bin/python -m uv help

[...]
Use `uv help` for more details.

Source: https://docs.astral.sh/uv/reference/cli/#uv-help

Get uv version

.venv/bin/python -m uv version

uv 0.5.15 (eb6ad9a4f 2025-01-06)

Source: https://docs.astral.sh/uv/reference/cli/#uv-version

Initialize an uv project

.venv/bin/python -m uv init .

[...]Project is already initialized[...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-init

Pin Python version

.venv/bin/python -m uv python pin 3.12

Pinned `.python-version` to `3.12`

Source: https://docs.astral.sh/uv/reference/cli/#uv-python-pin

Resolve dependencies

Resolve the dependencies listed in the pyproject.toml to the uv.lock.

.venv/bin/python -m uv lock

Resolved 53 packages in 0.30ms

Source: https://docs.astral.sh/uv/reference/cli/#uv-lock

Upgrade

--upgrade

(Resolve &) install dependencies

Ensure the virtual environment .venv contains the uv.lock dependencies.

.venv/bin/python -m uv sync

Add (& lock & install) dependencies

.venv/bin/python -m uv add accelerate

Installed 34 packages in 256ms

Source: https://docs.astral.sh/uv/reference/cli/#uv-add

Review dependencies

.venv/bin/python -m uv tree

[...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-tree

Remove dependencies

.venv/bin/python -m uv remove sentencepiece

Resolved 52 packages in 568ms
Uninstalled 1 package in 1ms
 - sentencepiece==0.2.0

Source: https://docs.astral.sh/uv/reference/cli/#uv-remove

Install Ruff

.venv/bin/python -m uv tool install ruff

Installed 1 executable: ruff

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-install

Run Ruff

.venv/bin/python -m uv tool run ruff check src tests

All checks passed!

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-run

Install MyPy

.venv/bin/python -m uv tool install mypy

Installed 1 executable: mypy

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-install

Run MyPy

.venv/bin/python -m uv tool run mypy --install-types src tests

Success: no issues found [...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-run

Install Pytest

.venv/bin/python -m uv tool install pytest

Installed 1 executable: pytest

TODO Install pytest-cov

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-install

Run Pytest

# .venv/bin/python -m uv tool run pytest tests
.venv/bin/python -m pytest tests --cov=src --cov=tests

============================= test session starts ==============================
[...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-run

List uv tools

.venv/bin/python -m uv tool list

mypy v1.14.1
- dmypy
- mypy
- mypyc
- stubgen
- stubtest
pytest v8.3.4
- py.test
- pytest
ruff v0.8.6
- ruff

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-list

Run the application

.venv/bin/python src/text_generation.py

Loading checkpoint shards: 100%|████████████████████████████████████████████████
Explain quantum computing in simple terms:

Quantum computing represents a significant shift from traditional computing.
[...]

Run FastAPI development server with reload

.venv/bin/python -m uv run fastapi dev --reload src/main.py

FastAPI   Starting development server 🚀

List development completions

http://localhost:8000/completions

[]

Stop the development server

Press Ctrl+C.

Run production web server

.venv/bin/python -m uv run uvicorn src.main:app --reload

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

List production completions

http://localhost:8000/completions

[]

Request a completion

curl \
    -X POST "http://localhost:8000/completions/" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -d "{\"prompt\":\"Explain quantum computing in simple terms:\"}"

{
    "prompt":"Explain quantum computing in simple terms:",
    "response":"Quantum computing is a type of computing.",
    "id":1
}

Stop the production server

Press Ctrl+C.

Install Docker

.venv/bin/python -m uv tool install docker

[...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-install

Build Docker image

.venv/bin/python -m uv tool run docker build -t demo-uv-tooling .

[...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-run

Run Docker container

.venv/bin/python -m uv tool run docker run -p 8000:8000 demo-uv-tooling

Source: https://docs.astral.sh/uv/reference/cli/#uv-tool-run

Request completion

curl \
    -X POST "http://localhost:8000/completions/" \
    -H "accept: application/json" \
    -H "Content-Type: application/json" \
    -d "{\"prompt\":\"Explain quantum computing in simple terms:\"}"

Note: This takes a lot of time the first time as it downloads the model.

{
    "prompt":"Explain quantum computing in simple terms:",
    "response":"Quantum computing is a type of computing.",
    "id":1
}

Stop the container

docker stop $(docker ps -q)

Remove the container

docker rm $(docker ps -a -q)

Remove the image

docker rmi demo-uv-tooling

Build the distribution

.venv/bin/python -m uv build

Successfully built [...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-build

Install the distribution

.venv/bin/python -m uv pip install dist/demo_uv_tooling-0.1.0-py3-none-any.whl

Installed 1 package [...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-pip-install

Install the source editable

.venv/bin/python -m uv pip install --editable .

Installed 1 package [...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-pip-install

Create PyPI API token

• Open https://pypi.org/manage/account/token/
• Save to .pypi_api_token.txt.

Publish the distribution

.venv/bin/python -m uv publish \
    --username=__token__ \
    --password=$(cat .pypi_api_token.txt)

Uploading demo_uv_tooling [...]

Source: https://docs.astral.sh/uv/reference/cli/#uv-publish