FastAPI Project Template
The base to start an openapi project featuring: SQLModel, Typer, FastAPI, JWT Token Auth, Interactive Shell, Management Commands.
See also
- Python-Project-Template for a lean, low dependency Python app.
- Flask-Project-Template for a full feature Flask project including database, API, admin interface, etc.
HOW TO USE THIS TEMPLATE
DO NOT FORK this is meant to be used from Use this template feature.
- Click on Use this template
- Give a name to your project
(e.g.my_awesome_projectrecommendation is to use all lowercase and underscores separation for repo names.) - Wait until the first run of CI finishes
(Github Actions will process the template and commit to your new repo) - If you want codecov Reports and Automatic Release to PyPI
On the new repositorysettings->secretsadd yourPIPY_API_TOKENandCODECOV_TOKEN(get the tokens on respective websites) - Read the file CONTRIBUTING.md
- Then clone your new project and happy coding!
NOTE: WAIT until first CI run on github actions before cloning your new project.
What is included on this template?
-
🖼️ The base to start an openapi project featuring: SQLModel, Typer, FastAPI, VueJS. -
📦 A basic setup.py file to provide installation, packaging and distribution for your project.
Template uses setuptools because it's the de-facto standard for Python packages, you can runmake switch-to-poetrylater if you want. -
🤖 A Makefile with the most useful commands to install, test, lint, format and release your project. -
📃 Documentation structure using mkdocs -
💬 Auto generation of change log using gitchangelog to keep a HISTORY.md file automatically based on your commit history on every release. -
🐋 A simple Containerfile to build a container image for your project.
Containerfileis a more open standard for building container images than Dockerfile, you can use buildah or docker with this file. -
🧪 Testing structure using pytest -
✅ Code linting using flake8 -
📊 Code coverage reports using codecov -
🛳️ Automatic release to PyPI using twine and github actions. -
🎯 Entry points to execute your program usingpython -mor$ fastapi_project_templatewith basic CLI argument parsing. -
🔄 Continuous integration using Github Actions with jobs to lint, test and release your project on Linux, Mac and Windows environments.
Curious about architectural decisions on this template? read ABOUT_THIS_TEMPLATE.md
If you want to contribute to this template please open an issue or fork and send a PULL REQUEST.
fastapi_project_template
Awesome fastapi_project_template created by zxenonx
Install
from source
git clone https://github.com/zxenonx/fastapi-project-template fastapi_project_template
cd fastapi_project_template
make install
from pypi
pip install fastapi_project_template
Executing
$ fastapi_project_template run --port 8080
or
python -m fastapi_project_template run --port 8080
or
$ uvicorn fastapi_project_template:app
CLI
❯ fastapi_project_template --help
Usage: fastapi_project_template [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion [bash|zsh|fish|powershell|pwsh]
Install completion for the specified shell.
--show-completion [bash|zsh|fish|powershell|pwsh]
Show completion for the specified shell, to
copy it or customize the installation.
--help Show this message and exit.
Commands:
create-user Create user
run Run the API server.
shell Opens an interactive shell with objects auto imported
Creating a user
❯ fastapi_project_template create-user --help
Usage: fastapi_project_template create-user [OPTIONS] USERNAME PASSWORD
Create user
Arguments:
USERNAME [required]
PASSWORD [required]
Options:
--superuser / --no-superuser [default: no-superuser]
--help
IMPORTANT To create an admin user on the first run:
fastapi_project_template create-user admin admin --superuser
The Shell
You can enter an interactive shell with all the objects imported.
❯ fastapi_project_template shell
Auto imports: ['app', 'settings', 'User', 'engine', 'cli', 'create_user', 'select', 'session', 'Content']
In [1]: session.query(Content).all()
Out[1]: [Content(text='string', title='string', created_time='2021-09-14T19:25:00.050441', user_id=1, slug='string', id=1, published=False, tags='string')]
In [2]: user = session.get(User, 1)
In [3]: user.contents
Out[3]: [Content(text='string', title='string', created_time='2021-09-14T19:25:00.050441', user_id=1, slug='string', id=1, published=False, tags='string')]
API
Run with fastapi_project_template run and access http://127.0.0.1:8000/docs
For some api calls you must authenticate using the user created with fastapi_project_template create-user.
Testing
❯ make test
Black All done! ✨ 🍰 ✨
13 files would be left unchanged.
Isort All done! ✨ 🍰 ✨
6 files would be left unchanged.
Success: no issues found in 13 source files
================================ test session starts ===========================
platform linux -- Python 3.9.6, pytest-6.2.5, py-1.10.0, pluggy-1.0.0 --
/fastapi-project-template/.venv/bin/python3
cachedir: .pytest_cache
rootdir: /fastapi-project-template
plugins: cov-2.12.1
collected 10 items
tests/test_app.py::test_using_testing_db PASSED [ 10%]
tests/test_app.py::test_index PASSED [ 20%]
tests/test_cli.py::test_help PASSED [ 30%]
tests/test_cli.py::test_cmds_help[run-args0---port] PASSED [ 40%]
tests/test_cli.py::test_cmds_help[create-user-args1-create-user] PASSED [ 50%]
tests/test_cli.py::test_cmds[create-user-args0-created admin2 user] PASSED[ 60%]
tests/test_content_api.py::test_content_create PASSED [ 70%]
tests/test_content_api.py::test_content_list PASSED [ 80%]
tests/test_user_api.py::test_user_list PASSED [ 90%]
tests/test_user_api.py::test_user_create PASSED [100%]
----------- coverage: platform linux, python 3.9.6-final-0 -----------
Name Stmts Miss Cover
-----------------------------------------------------
fastapi_project_template/__init__.py 4 0 100%
fastapi_project_template/app.py 16 1 94%
fastapi_project_template/cli.py 21 0 100%
fastapi_project_template/config.py 5 0 100%
fastapi_project_template/db.py 10 0 100%
fastapi_project_template/models/__init__.py 0 0 100%
fastapi_project_template/models/content.py 47 1 98%
fastapi_project_template/routes/__init__.py 11 0 100%
fastapi_project_template/routes/content.py 52 25 52%
fastapi_project_template/routes/security.py 15 1 93%
fastapi_project_template/routes/user.py 52 26 50%
fastapi_project_template/security.py 103 12 88%
-----------------------------------------------------
TOTAL 336 66 80%
========================== 10 passed in 2.34s ==================================
Linting and Formatting
make lint # checks for linting errors
make fmt # formats the code
Configuration
This project uses Dynaconf to manage configuration.
from fastapi_project_template.config import settings
Acessing variables
settings.get("SECRET_KEY", default="sdnfjbnfsdf")
settings["SECRET_KEY"]
settings.SECRET_KEY
settings.db.uri
settings["db"]["uri"]
settings["db.uri"]
settings.DB__uri
Defining variables
On files
settings.toml
[development]
dynaconf_merge = true
[development.db]
echo = true
dynaconf_mergeis a boolean that tells if the settings should be merged with the default settings defined in fastapi_project_template/default.toml.
As environment variables
export fastapi_project_template_KEY=value
export fastapi_project_template_KEY="@int 42"
export fastapi_project_template_KEY="@jinja {{ this.db.uri }}"
export fastapi_project_template_DB__uri="@jinja {{ this.db.uri | replace('db', 'data') }}"
Secrets
There is a file .secrets.toml where your sensitive variables are stored, that file must be ignored by git. (add that to .gitignore)
Or store your secrets in environment variables or a vault service, Dynaconf can read those variables.
Switching environments
fastapi_project_template_ENV=production fastapi_project_template run
Read more on https://dynaconf.com
Development
Read the CONTRIBUTING.md file.
4 Mar 16, 2022
1 Jan 04, 2022
273 Dec 01, 2022
27 Oct 16, 2022
2 Aug 31, 2022
283 Jan 04, 2023
18 Jan 02, 2023
200 Jan 08, 2023
74 Dec 30, 2022
543 Jan 05, 2023
23 Nov 20, 2022
768 Dec 22, 2022
1 Oct 14, 2021
59 Nov 29, 2022
16 Aug 30, 2022
1 Nov 27, 2021
31 Jan 10, 2023
135 Dec 19, 2022
225 Dec 28, 2022
238 Jan 07, 2023