README.md

uv-fastapi-example

An example of a FastAPI application managed as a uv project.

Based on the multi-file example from the FastAPI documentation.

This fork of the Astral example repository adds a detailed README of all used commands, structured logging with structlog and testing examples with pytest, optionally with coverage with pytest-cov.

• uv-fastapi-example
  • Description
  • Prerequisites
    • 1. Install Python 3 and uv
    • 2. Create a virtual environment with all necessary dependencies
  • Run application
    • Development mode
    • Production mode
  • Testing
    • With coverage
    • With coverage and HTML output
  • Linting
  • Formatting
  • Containerisation
    • 1. Build image and tag it as uv-fastapi-example
    • 2. Run a container of the previously tagged image ( uv-fastapi-example)
    • 3. Check running containers
    • 4. Hit sample endpoint
  • License

Description

A project starter for personal usage containing the following:

• Python 3.13.*
• FastAPI web framework
• Structured logging using structlog
• Dependency management using uv
• Containerisation using a Dockerfile
• Testing with pytest and optionally with coverage with pytest-cov
• Linting/formatting using ruff
• .gitignore

Prerequisites

• Python 3.13.*
• uv

1. Install Python 3 and uv

MacOS (using brew)

brew install python3 uv

Ubuntu/Debian

sudo apt install python3 python3-venv
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create a virtual environment with all necessary dependencies

From the root of the project execute:

uv sync

Run application

Development mode

uv run fastapi dev

Production mode

uv run fastapi run

Testing

uv run pytest

With coverage

uv run pytest --cov=app

With coverage and HTML output

uv run pytest --cov-report html --cov=app

Linting

uv run ruff check app/* tests/*

Formatting

uv run ruff format app/* tests/*

Containerisation

The following podman commands are direct replacements of the Docker CLI. You can see that their syntax is identical:

1. Build image and tag it as uv-fastapi-example

podman image build -t uv-fastapi-example .

2. Run a container of the previously tagged image (uv-fastapi-example)

Run our FastAPI application and map our local port 8000 to 80 on the running container:

podman container run -d --name uv-fastapi-example -p 8000:80 --network bridge uv-fastapi-example

3. Check running containers

podman ps

CONTAINER ID  IMAGE                            COMMAND               CREATED         STATUS             PORTS                 NAMES
78586e5b4683  localhost/uv-fastapi-example:latest  uvicorn main:app ...  13 minutes ago  Up 5 minutes ago  0.0.0.0:8000->80/tcp  nifty_roentgen

4. Hit sample endpoint

Our FastAPI server now runs on port 8000 on our local machine. We can test it with:

curl -i http://localhost:8000/healthcheck

Output:

HTTP/1.1 200 OK
server: uvicorn
content-length: 0

License

MIT