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 lightweight alpine.
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.
Based on distroless image
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 my-project
$ cd my-project
$ my-project serve
# or
$ poetry run my-project serve

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

Usage

This package exposes simple CLI for easier interaction:

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

  Generate and manage fastapi-mvc projects.

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

Commands:
  new  Create a new FastAPI application.
$ 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.

To generate new project:

$ fastapi-mvc new my-project
[install] Begin installing project.
Updating dependencies
Resolving dependencies... (0.7s)

Writing lock file

No dependencies to install or update

Installing the current project: my-project (0.1.0)
Project successfully installed.
To activate virtualenv run: $ poetry shell
Now you should access CLI script: $ my-project --help
Alternatively you can access CLI script via poetry run: $ poetry run my-project --help
To deactivate virtualenv simply type: $ deactivate
To activate shell completion:
 - for bash: $ echo 'eval "$(_MY_PROJECT_COMPLETE=source_bash my-project)' >> ~/.bashrc
 - for zsh: $ echo 'eval "$(_MY_PROJECT_COMPLETE=source_zsh my-project)' >> ~/.zshrc
 - for fish: $ echo 'eval "$(_MY_PROJECT_COMPLETE=source_fish my-project)' >> ~/.config/fish/completions/my-project.fish

To serve api:

$ cd my-project/
$ my-project serve
[2022-01-08 21:47:06 +0100] [2268861] [INFO] Start gunicorn WSGI with ASGI workers.
[2022-01-08 21:47:06 +0100] [2268861] [INFO] Starting gunicorn 20.1.0
[2022-01-08 21:47:06 +0100] [2268861] [INFO] Listening at: http://127.0.0.1:8000 (2268861)
[2022-01-08 21:47:06 +0100] [2268861] [INFO] Using worker: uvicorn.workers.UvicornWorker
[2022-01-08 21:47:06 +0100] [2268861] [INFO] Server is ready. Spawning workers
[2022-01-08 21:47:06 +0100] [2268867] [INFO] Booting worker with pid: 2268867
[2022-01-08 21:47:06 +0100] [2268867] [INFO] Worker spawned (pid: 2268867)
[2022-01-08 21:47:06 +0100] [2268867] [INFO] Started server process [2268867]
[2022-01-08 21:47:06 +0100] [2268867] [INFO] Waiting for application startup.
[2022-01-08 21:47:06 +0100] [2268867] [INFO] Application startup complete.
[2022-01-08 21:47:06 +0100] [2268873] [INFO] Booting worker with pid: 2268873
[2022-01-08 21:47:06 +0100] [2268873] [INFO] Worker spawned (pid: 2268873)
[2022-01-08 21:47:06 +0100] [2268873] [INFO] Started server process [2268873]
[2022-01-08 21:47:06 +0100] [2268873] [INFO] Waiting for application startup.
[2022-01-08 21:47:06 +0100] [2268873] [INFO] Application startup complete.

To confirm it's working:

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

Contributing

Questions, comments or improvements? Please create an issue on Github. I do my best to include every contribution proposed in any way that I can.

License

MIT

r2r-dev/fastapi-mvc