Minimal Project in FastAPI

Initial Application

The most elementar Hello World project in FastAPI consists of a main file (main.py) and a test file (test_hello_world.py).

Hello World Elementar
=====================

hello_world
├── main.py
└── test_hello_world.py

The file main.py contains:

from fastapi import FastAPI

app = FastAPI()


@app.get('/')
def say_hello() -> dict[str, str]:
    return {'message': 'Hello World'}

As there is no specific Python or FastAPI command to run the application, it is necessary to use an ASGI web server such as Hypercorn or Uvicorn. Installing FastAPI and hypercorn in a virtual environment and running the hypercorn command is shown below:

where main:app (line 5) specifies the use of the app variable within the main.py module.

Accessing http://localhost:8000 through httpie, we get the following result:

$ http :8000
HTTP/1.1 200
content-length: 25
content-type: application/json
date: ...
server: hypercorn-h11

{
    "message": "Hello World"
}

You prefer, you can use curl instead:

$ curl http://localhost:8000
{"message":"Hello World"}

The file test_hello_world.py contains:

from fastapi.testclient import TestClient
from main import app

client = TestClient(app)


def test_say_hello() -> None:
    response = client.get('/')
    assert response.status_code == 200
    assert response.json() == {'message': 'Hello World'}

To run the tests, you also need pytest and httpx to be installed:

(.venv) $ pip install pytest httpx
...

Then run the command:

(.venv) $ pytest
================================= test session starts ==================================
platform linux -- Python 3.10.7, pytest-7.2.0, pluggy-1.0.0
rootdir: /tmp/hello_world
plugins: anyio-3.6.2
collected 1 item

test_hello.py .                                                                  [100%]

================================== 1 passed in 0.23s ===================================

These two files are sufficient for an illustrative example, but they do not form a project that can be used in production. We will improve the project in the next sections.

Python Perfect Project + FastAPI

Since every FastAPI project is also a Python project, you can take advantage of all the structure and configuration set up in the article How to Set up a Perfect Python Project and apply it to the Hello World FastAPI project. That automatically fixes:

1. Virtual environment
2. Version control
3. Linting
4. Automated testing
5. Continuous integration

The listing below shows the structure of the Hello, World project side by side before (left side) and after (right side) applying the perfect Python project template:

Hello World Elementar          Hello World + Perfect Python Project
=====================          ====================================

hello_world                    hello_world
│                              ├── .github
│                              │   └── workflows
│                              │       └── continuous_integration.yml
│                              ├── .hgignore
│                              ├── hello_world
│                              │   ├── __init__.py
├── main.py                    │   └── main.py
│                              ├── Makefile
│                              ├── poetry.lock
│                              ├── pyproject.toml
│                              ├── README.rst
│                              ├── scripts
│                              │   └── install_hooks.sh
│                              └── tests
└── test_hello_world.py            └── test_hello_world.py

Installation of Dependencies

The dependencies that came from the template are only related to testing and linting. It is still necessary to install specific dependencies that we will use in the minimal FastAPI project:

$ poetry add fastapi=="*" hypercorn=="*" loguru=="*" orjson=="*" python-dotenv=="*" uvloop=="*"
$ poetry add --dev asgi-lifespan=="*" alt-pytest-asyncio=="*" httpx=="*"

The first command installs libraries that are necessary for the application to work in production. The second one installs libraries only used during application development and testing.

Main libraries:

• FastAPI
• Hypercorn is an ASGI web server
• Loguru is a library that aims to make logging more enjoyable
• orjson is a high efficiency JSON library
• python-dotenv reads name=value pairs from a .env file and sets corresponding environment variables
• uvloop is a high-efficiency implementation that replaces the default solution used in asyncio

Development libraries:

• alt-pytest-asyncio is a pytest plugin that enables asynchronous fixtures and testing
• asgi-lifespan programmatically send startup/shutdown lifespan events into ASGI applications. It allows mocking or testing ASGI applications without having to spin up an ASGI server.
• httpx is a synchronous and asynchronous HTTP library

Reorganizing main.py

The original main.py file only contains the declaration of the project's single route. However, the number of routes tends to grow over time, and main.py will eventually become unmanageable.

It is essential to prepare the project so that it can grow in an organized way. A better structure is obtained by declaring routes, models, schemes, etc. in directories and files specific to each abstraction.

The directory structure can be organized by function or entity. The organization by function of a FastAPI project containing a user entity would look like this:

.
├── models
│   ├── __init__.py
│   └── user.py
├── routers
│   ├── __init__.py
│   └── user.py
└── schemas
    ├── __init__.py
    └── user.py

The other option is to group by entity instead of function. In this case, models, routes and schemas live inside the user directory:

user
├── __init__.py
├── models.py
├── routers.py
└── schemas.py

Using one structure or another is a matter of preference. I prefer to use the grouping structure by function rather than by entity because it is easier to group Python imports this way.

As we only have one route to hello world and there are no templates or schemas the resulting structure is:

routers
├── __init__.py
└── hello.py

hello.py contains a route to the /hello endpoint, extracted from main.py:

from fastapi import APIRouter
from loguru import logger

router = APIRouter()


@router.get('/hello')
async def hello_world() -> dict[str, str]:
    logger.info('Hello world!')
    return {'message': 'Hello World'}

Configuration

Configuration is everything that needs to be tweaked so the application works in a certain environment (development, test, production), such as addresses and credentials to access other services. As recommended by The Twelve-Factor App, configuration should be obtained from environment variables rather than being maintained directly in the project's source code.

Tests

The biggest problem with synchronous tests such as test_hello_world.py is that it limits and makes it difficult to test an application based on asynchronous processing. For example, if your application uses a asynchronous database library such as Encode/Databases or aioredis, you may need to make an asynchronous call in a test to confirm that certain information was correctly written to the database after an API call.

These problems just go away if we switch from synchronous to asynchronous tests because making a synchronous call into an async function is effortless.

To adopt asynchronous tests, it will be necessary:

1. install an additional pytest plugin for asynchronous tests. There are three options: pytest-asyncio, alt-pytest-asyncio, and anyio. We are going to use alt-pytest-asyncio in this project because it solves the problem and doesn't require any additional configuration to use. It's not even necessary to mark the tests with pytest.mark.asyncio.
2. replace TestClient with httpx.AsyncClient as base class for tests

The asynchronous test equivalent of test_hello_world.py is:

from httpx import AsyncClient
from hello_world.main import app


async def test_say_hello() -> None:
    async with AsyncClient(app=app, base_url='http://test') as client:
        response = await client.get('/')
    assert response.status_code == 200
    assert response.json() == {'message': 'Hello World'}

As a configured AsynClient instance will be used frequently, let's define it once in a fixture in conftest.py and receive it as a parameter in all tests where necessary.

Using the fixture, test_hello_world.py is:

from httpx import AsyncClient


async def test_say_hello(client: AsyncClient) -> None:
    response = await client.get('/')
    assert response.status_code == 200
    assert response.json() == {'message': 'Hello World'}

During the reorganization of the project structure, test_hello_world.py becomes tests/routes/test_hello.py since the test directory structure mirrors the application directory structure.

Aditional Development Automated Tasks

In addition to the test, lint, format and install_hooks tasks inherited from the perfect Python project template, let's add a new action that makes it easier to run the application without having to remember the hypercorn parameters:

run:
    hypercorn --reload --config=hypercorn.toml 'hello_world.main:app'

To keep the command line short, part of the hypercorn parameters stays in a configuration file called hypercorn.toml:

worker_class = "uvloop"
bind = "0.0.0.0:5000"
accesslog = "-"
errorlog = "-"
access_log_format = "%(t)s %(h)s %(S)s %(r)s %(s)s"

Final Structure

The initial "Hello World" project evolved by first absorbing the structure of the perfect Python project, and then it was changed to have a more suitable structure for a FastAPI application. The difference between the previous and final directory structure is presented in the listing below:

Hello World + Perfect Python Project          Minimum FastaAPI Project
====================================          ========================

hello_world                                   hello_world
├── .github                                   ├── .github
│   └── workflows                             │   └── workflows
│       └── continuous_integration.yml        │       └── continuous_integration.yml
├── .hgignore                                 ├── .hgignore
├── hello_world                               ├── hello_world
│   ├── __init__.py                           │   ├── __init__.py
│   │                                         │   ├── config.py
│   └── main.py                               │   ├── main.py
│                                             │   ├── resources.py
│                                             │   └── routers
│                                             │       ├── __init__.py
│                                             │       └── hello.py
│                                             ├── hypercorn.toml
├── Makefile                                  ├── Makefile
├── poetry.lock                               ├── poetry.lock
├── pyproject.toml                            ├── pyproject.toml
├── README.rst                                ├── README.rst
├── scripts                                   ├── scripts
│   └── install_hooks.sh                      │   └── install_hooks.sh
└── tests                                     └── tests
    ├── __init__.py                               ├── __init__.py
    └── test_hello_world.py                       │
                                                  ├── conftest.py
                                                  └── routers
                                                      ├── __init__.py
                                                      └── test_hello.py

Final Considerations

During the creation of the minimal FastAPI project, some choices were made based on my personal preferences. For example, the adoption of orjson and uvloop for optimization, and alt-pytest-asyncio to allow asynchronous tests. But as they are few and generic, they compromise neither the objective nor the extensibility of the template.

The minimal FastAPI project, as the name implies, aims to provide a basis for new projects, be they serverless, data science, that use different types of databases, for building REST APIs and even for other templates.

Instead of manually typing all the presented code, use the template available on GitHub.

To instantiate a new project, you need to use cookiecutter. I recommend combining it with pipx:

$ pipx run cookiecutter gh:andredias/perfect_python_project \
       -c fastapi-minimum