fastapi-mvc

Documentation: https://fastapi-mvc.netlify.app

Source Code: https://github.com/rszamszur/fastapi-mvc

Example generated project: https://github.com/rszamszur/fastapi-mvc-example

Features

Generated project core implemented using MVC architectural pattern

Generated project is structured in MVC architectural pattern to help developers who don't know FastAPI yet but are familiar with MVC to get up to speed quickly.

WSGI + ASGI for high performance and better configuration

TLDR;

Running WSGI as a master worker with ASGI workers gives better results than running pure ASGI (for FastAPI for now):

better performance (requests per second)
better support for different protocols
broader configuration
better support with using reverse proxy

First of all, whether it's ASGI, WSGI, or combined, think of this as something that serves the application. For instance, Ruby on Rails uses Puma. The result of any of those servers is a TCP/IP or UNIX socket which is later on utilized by reverse proxy ex: Nginx (a TCP/IP socket you can access directly over the network, but still in production, usually it'll be behind a reverse proxy).

Now to WSGI + ASGI part. FastAPI is implemented with asyncio (https://docs.python.org/3/library/asyncio.html), so having a pure WSGI server doesn't make sense since you'd lose all the benefits of asynchronous concurrency. That's where ASGI comes in. However, Python journey with asyncio is still pretty young. Most projects have yet to reach maturity level (you should expect early bugs and a limited feature set). FastAPI, as ASGI server uses uvicorn, which is still prior 1.x.x release (17 in total so far, current 0.16.0) and lacks support for some protocols (ex: no HTTP/2). Moreover, some reverse proxy might not know how to work with asynchronous servers, and some problems or early bugs on this layer might happen as well.

I'm not saying uvicorn is bad. Quite contrary, if you'd run 4 pure uvicorn workes, you'd still get great results. But if you'd run the same amount of workers with gunicorn (WSGI) as a master worker, it turns out you can even pump those numbers up.

Gunicorn with 4 Uvicorn Workers (source: https://stackoverflow.com/a/62977786/10566747):

Requests per second: 7891.28 [#/sec] (mean)
Time per request: 126.722 [ms] (mean)
Time per request: 0.127 [ms] (mean, across all concurrent requests)

Pure Uvicorn with 4 workers:

Requests per second: 4359.68 [#/sec] (mean)
Time per request: 229.375 [ms] (mean)
Time per request: 0.229 [ms] (mean, across all concurrent requests)

~80% better

I guess gunicorn does a better job in worker management. However, it's a more mature project, so it's probably a matter of time when uvicorn (or other ASGI for that matter) will catch up to this benchmark.

Last but not least, gunicorn gives a ton of settings to configure (https://docs.gunicorn.org/en/stable/settings.html), which can come in handy.

Generated project comes with tests at 99% coverage

Unit test coverage is at 99% regardless of chosen configuration. There is also a placeholder for integration tests with an example dummy test.

Proper Dockerfile created with best practices for the cloud and Kubernetes

Container image features:

Based on distroless image
Run as PID 1 (with child processes)
Utilizes multi-stage build for smallest size possible, also this results in having only necessary libraries/dependencies/tools in outcome container image.
DigestSHA - immutable identifier instead of tags, for better reproducibility and security.
Signal handling, for Kubernetes to be able to gracefully shut down pods.
Created with common layers.
By default runs as non-root user

Based on Google Best practices for building containers, Top 20 Dockerfile best practices, and own experience.

Extensive GitHub actions for CI

Helm chart for Kubernetes

For easily deploying application in Kubernetes cluster.

Reproducible virtualized development environment

Easily boot virtual machine with Vagrant. Code and test straight away.

Note: Project directory is rsync'ed between Host and Guest.

Note2: provided Vagrant vm doesn't have port forwarding configured which means, that application won't be accessible on Host OS.

Redis and aiohttp utilities

For your discretion, I've provided some basic utilities:

RedisClient .app.utils.redis
AiohttpClient .app.utils.aiohttp_client

They're initialized in asgi.py on FastAPI startup event handler, and are available for whole application scope without passing object instances between controllers.

Kubernetes deployment with HA Redis cluster

Application stack in Kubernetes:

Readable and documented code

The metrics stage in CI workflow ensures important PEP rules are enforced. For additional readability and formatting checks - black is used. Every piece of generated code is documented with docstrings. Last but not least there is also extended README with how to.

Configurable from env

Generated application provides flexibility of configuration. All significant settings are defined by the environment variables, each with the default value.

Generated project uses Poetry dependency management

Poetry comes with all the tools you might need to manage your project in a deterministic way. Moreover, it's based on new unified Python project settings file - PEP 518 that replaces setup.py.

Quick start

pip install fastapi-mvc
fastapi-mvc new /tmp/demo-project
cd /tmp/demo-project
fastapi-mvc run

Prerequisites

Python 3.7 or later installed How to install python
Poetry How to install poetry or pip How to install pip installed
make (optional)

Installation

pip install fastapi-mvc

Or directly from source:

git clone git@github.com:rszamszur/fastapi-mvc.git
cd fastapi-mvc
make install

Getting started

Creating a new FastAPI project is as easy as:

fastapi-mvc new my-project

To run development uvicorn server:

cd my-project
fastapi-mvc run

To run production WSGI + ASGI server:

cd my-project
poetry run my-project serve
# or if project virtualenv PATH is set
my-project serve

To confirm it's working:

curl localhost:8000/api/ready
{"status":"ok"}

CLI

This package exposes simple CLI for easier interaction:

$ fastapi-mvc --help
Usage: fastapi-mvc [OPTIONS] COMMAND [ARGS]...

  Create and develop production grade FastAPI projects.

  Documentation: https://fastapi-mvc.netlify.app

  Source Code: https://github.com/rszamszur/fastapi-mvc

Options:
  -v, --verbose  Enable verbose logging.
  --help         Show this message and exit.

Commands:
  new  Create a new FastAPI application.
  run  Run development uvicorn server.

$ fastapi-mvc new --help
Usage: fastapi-mvc new [OPTIONS] APP_PATH

  Create a new FastAPI application.

  The 'fastapi-mvc new' command creates a new FastAPI application with a
  default directory structure and configuration at the path you specify.

Options:
  -R, --skip-redis                Skip Redis utility files.
  -A, --skip-aiohttp              Skip aiohttp utility files.
  -V, --skip-vagrantfile          Skip Vagrantfile.
  -H, --skip-helm                 Skip Helm chart files.
  -G, --skip-actions              Skip GitHub actions files.
  -C, --skip-codecov              Skip codecov in GitHub actions.
  -I, --skip-install              Dont run make install
  --license [MIT|BSD2|BSD3|ISC|Apache2.0|LGPLv3+|LGPLv3|LGPLv2+|LGPLv2|no]
                                  Choose license.  [default: MIT]
  --repo-url TEXT                 Repository url.
  --help                          Show this message and exit.

$ fastapi-mvc run --help
Usage: fastapi-mvc run [OPTIONS]

  Run development uvicorn server.

  The 'fastapi-mvc run' commands runs development uvicorn server for a
  fastapi-mvc project at the current working directory.

Options:
  --host TEXT                  Host to bind.  [default: 127.0.0.1]
  -p, --port INTEGER           Port to bind.  [default: 8000]
  -w, --workers INTEGER RANGE  The number of worker processes for handling
                               requests.  [default: 1]

  --no-reload                  Disable auto-reload.
  --help                       Show this message and exit.

Contributing

CONTRIBUTING

License

MIT

flavidetosnow/fastapi-mvc