fastapi-boilerplate

A well structured codebase written with FastAPI trying to follow the Clean Architecture principles.

For more information about Clean Architecture, you can check the documentation

P.D: This is a modified version of the FastAPI Clean Architecture project, but with some changes to fit the needs of every developer

Table of Content 📑

---

• Project Folder Structure
• How to run the code
  • Installation
• Installing project's dependencies
• How to run locally
• How to run migrations
  • Alembic
• Development Configuration
  • Pre-commit
  • Convetional Commits (Commitizen)
• Built with

Project Folder Structure

.
├── alembic             # Migration tool.
│   └── versions        # Migrations made (Like `make migrations` in Django).
├── app                 # Main app folder.
│   ├── api             # Api related folder (routes, deps, versioning, etc.).
│   │   └── v1
│   │       └── routes  # Route folder where are all routes located for current version.
│   ├── core            # Core where locate all app configs,
│   │   └── settings    # like app settings, logging, etc.
│   │
│   ├── infrastructure  # Infrastructure related configs like databases, external resources, etc.
│   ├── entities        # Database models representation as python classes.
│   ├── repositories    # Collection of classes responsible of databases operations (CRUD).
│   ├── schemas         # Pydantic schemas for validating data input/output (like `serializers` in Django).
│   ├── services        # Classes with the business logic, like use cases.
│   └── utils           # Utils used in the app.
├── tests               # Test cases for the app.
└── main.py             # Entry point where uvicorn runs to start application.

How to run the code

Installation

You will need to install Poetry to install project's dependencies

$ curl -sSL https://install.python-poetry.org | python3 -

Note: On some systems, python may still refer to Python 2 instead of Python 3. We always suggest the python3 binary to avoid ambiguity.

Locate where Poetry is installed

$ whereis poetry

Copy and replace poetry's path to this line and added it at the end of the .bashrc file

$ export PATH="$HOME/.poetry/bin:$PATH"

Installing project's dependencies

Clone the repository

$ git clone https://github.com/Arkemix30/fastapi-boilerplate

Enter into project's root folder and run:

$ poetry install

It should create a .venv folder, generating a virtual enviroment with all project's dependencies

How to run locally

• To run the project, you need to activate the virtual environment. For that, you can run this command:

  $ poetry shell

• And finally, to run the server:

  $ uvicorn main:app --reload

How to run migrations

Alembic

• To create a new migration, run:

  $ alembic revision --autogenerate -m "Migration name"

  This will create a new migration file in alembic/versions folder.

• To apply the migrations made, run:

  $ alembic upgrade head

  This will apply all migrations to the database.

• To downgrade the migrations, run:

  $ alembic downgrade -1

  This will downgrade the last migration applied to the database.

• To downgrade all migrations, run:

  $ alembic downgrade base

  This will downgrade all migrations applied to the database.

• To check the history of migrations applied, run:

  $ alembic history

  This will show the history of migrations applied to the database.

For more information about Alembic, you can check the documentation

Development Configuration

Pre-commit

This project uses pre-commit to run some checks before commiting the code.

To install it, run:

$ pre-commit install

This will install the hooks in the .git/hooks folder.

To run the checks manually, run:

$ pre-commit run --all-files

In case you want to skip the checks, you can use the --no-verify flag:

$ git commit -m "Commit message" --no-verify

In every commit, the following checks will be run:

• black - The uncompromising code formatter.
• flake8 - The tool for style guide enforcement.
• isort - A Python utility / library to sort imports.
• bandit - Security linter from OpenStack Security.
• pre-commit-hooks - Some useful hooks for pre-commit.

Conventional Commits (Commitizen)

This project uses commitizen to standardize the commit messages.

To install it, run:

$ pip install commitizen

To run it, run:

$ cz commit

or the short version:

$ cz c

This will open a prompt to write the commit message.

Built with

• FastAPI - The framework used.
• Uvicorn - The light-fast ASGI server.
• Pydantic - Data Validator using Python type annotations.
• SQLModel - Database ORM based in SQLAlchemy and Pydantic.
• GeoAlchemy2 - Provides extensions to SQLAlchemy for working with spatial databases.
• Alembic - Database migration tool to manage changes to the database schema over time.
• SqlAdmin - Admin interface for SQLAlchemy/SQLModel models.

---

README ⌨️ with ❤️ by Enmanuel Silva 😊