🧪 RESTful API with Python 3 and FastAPI

Status

About

Proof of Concept for a RESTful API made with Python 3 and FastAPI.

Features

• 🏗️ Modern async architecture - Async/await throughout, Pydantic validation, and SQLAlchemy 2.0+ patterns
• 📚 Interactive API exploration - Auto-generated OpenAPI docs with FastAPI's built-in Swagger UI
• ⚡ Performance optimizations - Async SQLAlchemy, in-memory caching with aiocache, and efficient database operations
• 🧪 High test coverage - Pytest suite with 80% minimum coverage and automated reporting to Codecov
• 📖 Token-efficient documentation - AGENTS.md + auto-loaded Copilot instructions for AI-assisted development
• 🐳 Full containerization - Production-ready Docker setup with Docker Compose orchestration
• 🔄 Complete CI/CD pipeline - Automated linting (Black/Flake8), testing, Docker publishing, and GitHub releases
• ♟️ Coach-themed semantic versioning - Memorable, alphabetical release names honoring legendary football coaches

Structure

Figure: Simplified, conceptual project structure and main application flow. Not all dependencies are shown.

Python Version Management

This project uses .python-version to specify the required Python version. If you use pyenv, asdf, or mise, the correct Python version will be automatically activated when you enter the project directory.

Alternatively, ensure you have Python 3.13.3 (or the version specified in .python-version) installed.

Setup

Prerequisites

• Python 3.13+
• uv (recommended) or pip

Installation

1. Install uv (if you haven't already):

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create a virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install --group dev

Install

Dependencies are defined in pyproject.toml using PEP 735 standards. Install them with:

uv pip install --group dev

Or with specific groups:

• uv pip install - Install production dependencies only
• uv pip install --group test - Install test dependencies
• uv pip install --group lint - Install linting dependencies
• uv pip install --group dev - Install all (test + lint + production)

Start

uv run uvicorn main:app --reload --port 9000

Or using pip:

uvicorn main:app --reload --port 9000

Docs

http://localhost:9000/docs

HTTP Requests

The rest/players.rest file covers all CRUD operations and can be run directly in VS Code with the REST Client extension.

Running Tests

uv run pytest -v

Code Quality

Linting

uv run flake8 .

Code Formatting

uv run black --check .
uv run black .  # Auto-format

Coverage

uv run pytest --cov=./ --cov-report=term

Container

Docker Compose

This setup uses Docker Compose to build and run the app and manage a persistent SQLite database stored in a Docker volume. The Dockerfile uses PEP 735 dependency groups defined in pyproject.toml.

Build the image

docker compose build

Start the app

docker compose up

On first run, the container copies a pre-seeded SQLite database into a persistent volume On subsequent runs, that volume is reused and the data is preserved

Stop the app

docker compose down

Optional: database reset

docker compose down -v

This removes the volume and will reinitialize the database from the built-in seed file the next time you up.

Releases

This project uses famous football coaches as release names ♟️

Create a Release

To create a new release, follow this workflow:

1. Update CHANGELOG.md

First, document your changes in CHANGELOG.md:

# Move items from [Unreleased] to new release section
# Example: [1.0.0 - Ancelotti] - 2026-02-15
git add CHANGELOG.md
git commit -m "docs: prepare changelog for v1.0.0-ancelotti release"
git push

2. Create and Push Tag

Then create and push the version tag:

git tag -a v1.0.0-ancelotti -m "Release 1.0.0 - Ancelotti"
git push origin v1.0.0-ancelotti

3. Automated CD Workflow

This triggers the CD workflow which automatically:

1. Validates the coach name
2. Builds and tests the project with coverage
3. Publishes Docker images to GitHub Container Registry with three tags
4. Creates a GitHub Release with auto-generated changelog from commits

💡 Always update CHANGELOG.md before creating the tag. See CHANGELOG.md for detailed release instructions.

Pull Docker Images

Official releases are published to GitHub Container Registry (GHCR):

# By semantic version (recommended)
docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:1.0.0

# By coach name
docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:ancelotti

# Latest
docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:latest

💡 See CHANGELOG.md for the complete coach list (A-Z) and release history.

Credits

The solution has been coded using Visual Studio Code with the official Python extension.

Terms

All trademarks, registered trademarks, service marks, product names, company names, or logos mentioned on this repository are the property of their respective owners. All usage of such terms herein is for identification purposes only and constitutes neither an endorsement nor a recommendation of those items. Furthermore, the use of such terms is intended to be for educational and informational purposes only.