FastAPI Cookiecutter Template
=============================
Introduction
------------
This projects consist of a `cookiecutter`_ template that generates a full structure
for creating a RESTful API service project based on FastAPI following the MVC
(Model-View-Controller) structure in the same way Django projects does.
While using this project, you will be asked to provide some inputs such the authors, the name of the project, etc. As result you will obtain the
complete file and folder structure to quickly start to code your project.
Prerequisites
-------------
It uses ``Python`` (>=3.7) behind the scenes. Please install the Python package `cookiecutter`_ before using it.
Project Generation Options
--------------------------
project_name:
Your project's human-readable name, capitals and spaces allowed.
project_slug:
Your project's slug without dashes or spaces. Used to name your repo
and in other places where a Python-importable version of your project name
is needed.
project_url:
The url of your project hosted in gitlab or github.
author:
This is you! The value goes into places like ``README.md`` and such.
email:
The email address you want to identify yourself in the project.
short_description:
Describes your project briefly and gets used in places like ``README.md`` and ``setup.py``.
version:
The version of the project at its inception.
use_oauth:
Indicates whether the project should be configured for using OAuth2 authentication. The choices are:
1. No
2. Yes
use_database:
Indicates whether the project should be configured for using database. The choices are:
1. No
2. Yes
ci_tool:
Select a CI tool. The choices are:
1. GitHub
2. GitLab
3. Bitbucket
4. None
ci_tool:
Select the python version for configuring the created project's CI/CD pipeline. The choices are:
1. 3.10
2. 3.11
3. 3.9
4. 3.8
5. 3.7
Tutorial
--------
Let's pretend you want to create a FastAPI project called "redditclone".
By using this template based on `cookiecutter`_,
you will be able to quickly setup a runnable FastAPI project.
First, get Cookiecutter. Trust me, it's awesome::
$ pip install "cookiecutter>=1.7.0"
Now run it against this repo::
$ cookiecutter https://github.com/zhiwei2017/FastAPI-Cookiecutter.git
You'll be prompted for some values. Provide them, then a FastAPI project will be created for you.
**Warning**: After this point, change 'My Awesome Project', 'John Doe', etc to your own information.
Answer the prompts with your own desired `Project Generation Options <./docs/source/02_prompts.rst>`_. For example::
Cloning into 'fastapi-cookiecutter'...
remote: Enumerating objects: 219, done.
remote: Counting objects: 100% (219/219), done.
remote: Compressing objects: 100% (123/123), done.
remote: Total 219 (delta 83), reused 181 (delta 69), pack-reused 0
Receiving objects: 100% (219/219), 41.09 KiB | 1.71 MiB/s, done.
Resolving deltas: 100% (83/83), done.
project_name [My Awesome Project]: Reddit Clone
project_slug [reddit_clone]: reddit_clone
project_url [https://github.com/example_project]: https://github.com/redditclone
author [John Doe]: John Doe
email [john-doe@example.com]: john.doe@example.com
short_description [Behold My Awesome Project!]: A reddit clone.
version [0.0.1]: 0.1.0
Select use_oauth:
1 - No
2 - Yes
Choose from 1, 2 [1]: 1
Select use_database:
1 - Yes
2 - No
Choose from 1, 2 [1]: 1
Select ci_tool:
1. GitHub
2. GitLab
3. Bitbucket
4. None
Choose from 1, 2 [1]: 1
Select python_version:
1. 3.10
2. 3.11
3. 3.9
4. 3.8
5. 3.7
Choose from 1, 2 [1]: 1
Enter the project and take a look around::
$ cd reddit_clone/
$ ls
Now take a look at your repo. Don't forget to carefully look at the generated **README**.
Project Structure
-----------------
Files related to application are in the ``src`` or ``tests`` directories.
Application components are::
{{cookiecutter.project_slug}}
├── docs - sphinx documentastion
├── scripts - scripts
│ └── prestart.sh
├── {{cookiecutter.project_slug}}
│ ├── app
│ │ ├── api - api endpoints
│ │ │ └── base.py - basic endpoints
│ │ ├── application.py - function for FastAPI application creation and configuration
│ │ ├── configs - application configuration
│ │ │ └── base.py - basic configuration class
│ │ ├── constants.py - constants used inside the application
│ │ ├── db - database related stuff
│ │ │ ├── base.py - base sqlalchemy DB model class
│ │ │ ├── models - folder for defining sqlalchemy DB model classes
│ │ │ ├── queries - folder for predefined sqlalchemy queries
│ │ │ └── session.py - a local session instance used inside application
│ │ ├── events - events for startup, shutdown
│ │ │ └── base.py - dummy startup event and shudown event
│ │ ├── globals.py - global variables
│ │ ├── middlewares - middleware stuff
│ │ │ └── logging.py - middleware function related to logging
│ │ ├── schemas - pydantic models for this application
│ │ │ └── base.py - pydantic models for the basic endpoints
│ │ ├── services - logic that is not included in the other folders
│ │ ├── utils - utility stuff
│ │ │ ├── errors.py - customized exception classes
│ │ │ ├── logging.py - logging related utility functions, classes
│ │ │ └── security.py - security related functions, classes
│ │ └── version.py - version information
│ ├── data - data used for this application
│ └── main.py - main function to run the application
├── tests - unit tests
│ ├── conftest.py - fixtures in tests
│ ├── resources - resources used in tests
│ └── ...
├── Dockerfile - docker file for building docker image
├── Makefile - predefined commands
├── README.md - package information
├── requirements - package dependencies
│ ├── base.txt - documentation dependecies
│ ├── doc.txt - documentation dependecies
│ ├── dev.txt - tests dependencies
├── setup.cfg - configurations for mypy, bandit, pytest etc. Centralizing all the configurations to one place.
└── setup.py - package installation configuration
Advanced Usage
--------------
``Gunicorn`` Configuration
**************************
A default ``gunicorn-conf.py`` file is included in the docker image and will be
executed before your service is up. It supports configuration through environment
variables. Please check the section `Environment variables <https://github.com/tiangolo/uvicorn-gunicorn-docker#environment-variables>`_
from `uvicorn-gunicorn-docker`_ project
for more detailed information. The suggested approach for defining environment variables
is to use the ``scrtips/prestart.sh`` file.
In case you need to customize the ``Gunicorn`` configuration file, please check the
default `gunicorn-conf.py <https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/master/docker-images/gunicorn_conf.py>`_ file
and read the section `Custom Gunicorn configuration file <https://github.com/tiangolo/uvicorn-gunicorn-docker#custom-gunicorn-configuration-file>`_
from `uvicorn-gunicorn-docker`_ project firstly.
Customize ``prestart`` Hook
***************************
If you need to run anything before starting the app, you can add a file ``prestart.sh`` to the directory ``scripts``.
Please check the section `Custom /app/prestart.sh <https://github.com/tiangolo/uvicorn-gunicorn-docker#custom-appprestartsh>`_
from `uvicorn-gunicorn-docker`_ project for more details.
Access Token
************
An access token creation function is provided. However, it's not used by fault.
To use it, please check the `example <the https://github.com/tiangolo/full-stack-fastapi-postgresql/blob/master/%7B%7Bcookiecutter.project_slug%7D%7D/backend/app/app/api/api_v1/endpoints/login.py>`_.
Contributing Guide
------------------
Please check the `Contributing Guide <docs/source/07_contributing.rst>`_ for details.
Core Team
---------
* `Zhiwei Zhang <https://github.com/zhiwei2017>`_ - *Author* / *Maintainer* - `zhiwei2017@gmail.com <mailto:zhiwei2017@gmail.com?subject=[GitHub]FastAPI%20Cookiecutter>`_
Literature
----------
+ `cookiecutter`_
+ `FastAPI <https://fastapi.tiangolo.com>`_
+ `Pydantic <https://pydantic-docs.helpmanual.io>`_
+ `SQLAlchemy <https://www.sqlalchemy.org>`_
+ `Alembic <https://alembic.sqlalchemy.org/en/latest/>`_
+ `PyJWT <https://github.com/jpadilla/pyjwt>`_
+ `python-jose <https://github.com/mpdavis/python-jose>`_
.. _`cookiecutter`: https://github.com/cookiecutter/cookiecutter
.. _uvicorn-gunicorn-docker: https://github.com/tiangolo/uvicorn-gunicorn-docker
Raw data
{
"_id": null,
"home_page": "https://github.com/zhiwei2017/fastapi-cookiecutter",
"name": "FastAPI-Cookiecutter",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "cookiecutter template,python37,python38,python39,python310,python311,github-actions,gitlab-ci,bitbucket-pipelines,fastapi,RESTful API",
"author": "Zhiwei Zhang",
"author_email": "zhiwei2017@gmail.com",
"download_url": "",
"platform": null,
"description": "FastAPI Cookiecutter Template\n=============================\n\nIntroduction\n------------\nThis projects consist of a `cookiecutter`_ template that generates a full structure\nfor creating a RESTful API service project based on FastAPI following the MVC\n(Model-View-Controller) structure in the same way Django projects does.\n\nWhile using this project, you will be asked to provide some inputs such the authors, the name of the project, etc. As result you will obtain the\ncomplete file and folder structure to quickly start to code your project.\n\nPrerequisites\n-------------\nIt uses ``Python`` (>=3.7) behind the scenes. Please install the Python package `cookiecutter`_ before using it.\n\n\n\nProject Generation Options\n--------------------------\n\nproject_name:\n Your project's human-readable name, capitals and spaces allowed.\n\nproject_slug:\n Your project's slug without dashes or spaces. Used to name your repo\n and in other places where a Python-importable version of your project name\n is needed.\n\nproject_url:\n The url of your project hosted in gitlab or github.\n\nauthor:\n This is you! The value goes into places like ``README.md`` and such.\n\nemail:\n The email address you want to identify yourself in the project.\n\nshort_description:\n Describes your project briefly and gets used in places like ``README.md`` and ``setup.py``.\n\nversion:\n The version of the project at its inception.\n\nuse_oauth:\n Indicates whether the project should be configured for using OAuth2 authentication. The choices are:\n\n 1. No\n 2. Yes\n\nuse_database:\n Indicates whether the project should be configured for using database. The choices are:\n\n 1. No\n 2. Yes\n\nci_tool:\n Select a CI tool. The choices are:\n\n 1. GitHub\n 2. GitLab\n 3. Bitbucket\n 4. None\n\nci_tool:\n Select the python version for configuring the created project's CI/CD pipeline. The choices are:\n\n 1. 3.10\n 2. 3.11\n 3. 3.9\n 4. 3.8\n 5. 3.7\n\nTutorial\n--------\nLet's pretend you want to create a FastAPI project called \"redditclone\".\nBy using this template based on `cookiecutter`_,\nyou will be able to quickly setup a runnable FastAPI project.\n\nFirst, get Cookiecutter. Trust me, it's awesome::\n\n $ pip install \"cookiecutter>=1.7.0\"\n\nNow run it against this repo::\n\n $ cookiecutter https://github.com/zhiwei2017/FastAPI-Cookiecutter.git\n\nYou'll be prompted for some values. Provide them, then a FastAPI project will be created for you.\n\n**Warning**: After this point, change 'My Awesome Project', 'John Doe', etc to your own information.\n\nAnswer the prompts with your own desired `Project Generation Options <./docs/source/02_prompts.rst>`_. For example::\n\n Cloning into 'fastapi-cookiecutter'...\n remote: Enumerating objects: 219, done.\n remote: Counting objects: 100% (219/219), done.\n remote: Compressing objects: 100% (123/123), done.\n remote: Total 219 (delta 83), reused 181 (delta 69), pack-reused 0\n Receiving objects: 100% (219/219), 41.09 KiB | 1.71 MiB/s, done.\n Resolving deltas: 100% (83/83), done.\n project_name [My Awesome Project]: Reddit Clone\n project_slug [reddit_clone]: reddit_clone\n project_url [https://github.com/example_project]: https://github.com/redditclone\n author [John Doe]: John Doe\n email [john-doe@example.com]: john.doe@example.com\n short_description [Behold My Awesome Project!]: A reddit clone.\n version [0.0.1]: 0.1.0\n Select use_oauth:\n 1 - No\n 2 - Yes\n Choose from 1, 2 [1]: 1\n Select use_database:\n 1 - Yes\n 2 - No\n Choose from 1, 2 [1]: 1\n Select ci_tool:\n 1. GitHub\n 2. GitLab\n 3. Bitbucket\n 4. None\n Choose from 1, 2 [1]: 1\n Select python_version:\n 1. 3.10\n 2. 3.11\n 3. 3.9\n 4. 3.8\n 5. 3.7\n Choose from 1, 2 [1]: 1\n\nEnter the project and take a look around::\n\n $ cd reddit_clone/\n $ ls\n\nNow take a look at your repo. Don't forget to carefully look at the generated **README**.\n\nProject Structure\n-----------------\n\nFiles related to application are in the ``src`` or ``tests`` directories.\nApplication components are::\n\n {{cookiecutter.project_slug}}\n \u251c\u2500\u2500 docs - sphinx documentastion\n \u251c\u2500\u2500 scripts - scripts\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 prestart.sh\n \u251c\u2500\u2500 {{cookiecutter.project_slug}}\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 app\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 api - api endpoints\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 base.py - basic endpoints\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 application.py - function for FastAPI application creation and configuration\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 configs - application configuration\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 base.py - basic configuration class\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 constants.py - constants used inside the application\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 db - database related stuff\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 base.py - base sqlalchemy DB model class\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 models - folder for defining sqlalchemy DB model classes\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 queries - folder for predefined sqlalchemy queries\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 session.py - a local session instance used inside application\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 events - events for startup, shutdown\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 base.py - dummy startup event and shudown event\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 globals.py - global variables\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 middlewares - middleware stuff\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 logging.py - middleware function related to logging\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 schemas - pydantic models for this application\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 base.py - pydantic models for the basic endpoints\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 services - logic that is not included in the other folders\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 utils - utility stuff\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 errors.py - customized exception classes\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 logging.py - logging related utility functions, classes\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 security.py - security related functions, classes\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 version.py - version information\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 data - data used for this application\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.py - main function to run the application\n \u251c\u2500\u2500 tests - unit tests\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 conftest.py - fixtures in tests\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 resources - resources used in tests\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 ...\n \u251c\u2500\u2500 Dockerfile - docker file for building docker image\n \u251c\u2500\u2500 Makefile - predefined commands\n \u251c\u2500\u2500 README.md - package information\n \u251c\u2500\u2500 requirements - package dependencies\n \u2502 \u251c\u2500\u2500 base.txt - documentation dependecies\n \u2502 \u251c\u2500\u2500 doc.txt - documentation dependecies\n \u2502 \u251c\u2500\u2500 dev.txt - tests dependencies\n \u251c\u2500\u2500 setup.cfg - configurations for mypy, bandit, pytest etc. Centralizing all the configurations to one place.\n \u2514\u2500\u2500 setup.py - package installation configuration\n\nAdvanced Usage\n--------------\n``Gunicorn`` Configuration\n**************************\nA default ``gunicorn-conf.py`` file is included in the docker image and will be\nexecuted before your service is up. It supports configuration through environment\nvariables. Please check the section `Environment variables <https://github.com/tiangolo/uvicorn-gunicorn-docker#environment-variables>`_\nfrom `uvicorn-gunicorn-docker`_ project\nfor more detailed information. The suggested approach for defining environment variables\nis to use the ``scrtips/prestart.sh`` file.\n\nIn case you need to customize the ``Gunicorn`` configuration file, please check the\ndefault `gunicorn-conf.py <https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/master/docker-images/gunicorn_conf.py>`_ file\nand read the section `Custom Gunicorn configuration file <https://github.com/tiangolo/uvicorn-gunicorn-docker#custom-gunicorn-configuration-file>`_\nfrom `uvicorn-gunicorn-docker`_ project firstly.\n\nCustomize ``prestart`` Hook\n***************************\nIf you need to run anything before starting the app, you can add a file ``prestart.sh`` to the directory ``scripts``.\nPlease check the section `Custom /app/prestart.sh <https://github.com/tiangolo/uvicorn-gunicorn-docker#custom-appprestartsh>`_\nfrom `uvicorn-gunicorn-docker`_ project for more details.\n\nAccess Token\n************\nAn access token creation function is provided. However, it's not used by fault.\nTo use it, please check the `example <the https://github.com/tiangolo/full-stack-fastapi-postgresql/blob/master/%7B%7Bcookiecutter.project_slug%7D%7D/backend/app/app/api/api_v1/endpoints/login.py>`_.\n\nContributing Guide\n------------------\n\nPlease check the `Contributing Guide <docs/source/07_contributing.rst>`_ for details.\n\nCore Team\n---------\n\n* `Zhiwei Zhang <https://github.com/zhiwei2017>`_ - *Author* / *Maintainer* - `zhiwei2017@gmail.com <mailto:zhiwei2017@gmail.com?subject=[GitHub]FastAPI%20Cookiecutter>`_\n\nLiterature\n----------\n\n+ `cookiecutter`_\n+ `FastAPI <https://fastapi.tiangolo.com>`_\n+ `Pydantic <https://pydantic-docs.helpmanual.io>`_\n+ `SQLAlchemy <https://www.sqlalchemy.org>`_\n+ `Alembic <https://alembic.sqlalchemy.org/en/latest/>`_\n+ `PyJWT <https://github.com/jpadilla/pyjwt>`_\n+ `python-jose <https://github.com/mpdavis/python-jose>`_\n\n.. _`cookiecutter`: https://github.com/cookiecutter/cookiecutter\n.. _uvicorn-gunicorn-docker: https://github.com/tiangolo/uvicorn-gunicorn-docker\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This projects consist of a cookiecutter template that generates a full structure for a creating a PyPi standard package.",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://zhiwei2017.github.io/fastapi-cookiecutter/",
"Homepage": "https://github.com/zhiwei2017/fastapi-cookiecutter",
"Repository": "https://github.com/zhiwei2017/fastapi-cookiecutter"
},
"split_keywords": [
"cookiecutter template",
"python37",
"python38",
"python39",
"python310",
"python311",
"github-actions",
"gitlab-ci",
"bitbucket-pipelines",
"fastapi",
"restful api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4aef3647513ae24b1c04d4cabe14426887c6aafb5830e1cb0463c560776c3217",
"md5": "5ed4ef266755bd242cb60e68a9771392",
"sha256": "18503c1dbf908f7b509549fdc8858e30ca026705f7decd399739ab165f85a744"
},
"downloads": -1,
"filename": "fastapi_cookiecutter-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ed4ef266755bd242cb60e68a9771392",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 77908,
"upload_time": "2024-02-03T21:30:15",
"upload_time_iso_8601": "2024-02-03T21:30:15.210718Z",
"url": "https://files.pythonhosted.org/packages/4a/ef/3647513ae24b1c04d4cabe14426887c6aafb5830e1cb0463c560776c3217/fastapi_cookiecutter-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-03 21:30:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zhiwei2017",
"github_project": "fastapi-cookiecutter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fastapi-cookiecutter"
}
JSON
