Skip to content

README.md

Latest commit

 

History

History
215 lines (157 loc) · 6.09 KB

README.md

File metadata and controls

215 lines (157 loc) · 6.09 KB
Raw

{{cookiecutter.project_name}}

This project was generated using fastapi_template.

UV

This project uses uv. It's a modern dependency management tool.

To run the project use this set of commands:

uv sync --locked
uv run -m {{cookiecutter.project_name}}

This will start the server on the configured host.

You can find swagger documentation at /api/docs.

You can read more about uv here: https://docs.astral.sh/ruff/

Docker

You can start the project with docker using this command:

docker compose up --build

This command exposes the web application on port 8000, mounts current directory and enables autoreload.

But you have to rebuild image every time you modify uv.lock or pyproject.toml with this command:

docker compose build

Project structure

$ tree "{{cookiecutter.project_name}}"
{{cookiecutter.project_name}}
├── conftest.py  # Fixtures for all tests. 
{%- if cookiecutter.db_info.name != "none" %}
├── db  # module contains db configurations
│   ├── dao  # Data Access Objects. Contains different classes to interact with database.
│   └── models  # Package contains different models for ORMs.
{%- endif %}
├── __main__.py  # Startup script. Starts uvicorn.
├── services  # Package for different external services such as rabbit or redis etc.
├── settings.py  # Main configuration settings for project.
├── static  # Static content.
├── tests  # Tests for project.
└── web  # Package contains web server. Handlers, startup config.
    ├── api  # Package with all handlers.
    │   └── router.py  # Main router.
    ├── application.py  # FastAPI application configuration.
    └── lifespan.py  # Contains actions to perform on startup and shutdown.

Configuration

This application can be configured with environment variables.

You can create .env file in the root directory and place all environment variables here.

All environment variables should start with "{{cookiecutter.project_name | upper}}_" prefix.

For example if you see in your "{{cookiecutter.project_name}}/settings.py" a variable named like random_parameter, you should provide the "{{cookiecutter.project_name | upper}}_RANDOM_PARAMETER" variable to configure the value. This behaviour can be changed by overriding env_prefix property in {{cookiecutter.project_name}}.settings.Settings.Config.

An example of .env file:

{{cookiecutter.project_name | upper}}_RELOAD="True"
{{cookiecutter.project_name | upper}}_PORT="8000"
{{cookiecutter.project_name | upper}}_ENVIRONMENT="dev"

You can read more about BaseSettings class here: https://pydantic-docs.helpmanual.io/usage/settings/

{%- if cookiecutter.otlp_enabled == "True" %}

OpenTelemetry

If you want to start your project with OpenTelemetry collector you can add -f ./deploy/docker-compose.otlp.yml to your docker command.

Like this:

docker compose -f docker-compose.yml -f deploy/docker-compose.otlp.yml --project-directory . up

This command will start grafana with full opentelemetry stack at http://localhost:3000/. After sending a requests you can see traces at explore tab in drilldown.

This docker configuration is not supposed to be used in production. It's only for demo purpose.

You can read more about OpenTelemetry here: https://opentelemetry.io/ {%- endif %}

Pre-commit

To install pre-commit simply run inside the shell:

pre-commit install

pre-commit is very useful to check your code before publishing it. It's configured using .pre-commit-config.yaml file.

By default it runs:

  • mypy (validates types);
  • ruff (spots possible bugs);

You can read more about pre-commit here: https://pre-commit.com/

{%- if cookiecutter.enable_migrations == 'True' %}

Migrations

If you want to migrate your database, you should run following commands:

{%- if cookiecutter.orm in ['sqlalchemy', 'ormar'] %}
# To run all migrations until the migration with revision_id.
alembic upgrade "<revision_id>"

# To perform all pending migrations.
alembic upgrade "head"
{%- elif cookiecutter.orm == 'tortoise' %}
# Upgrade database to the last migration.
aerich upgrade

{%- elif cookiecutter.orm == 'piccolo' %}
# You have to set a PICCOLO_CONF variable
export PICCOLO_CONF="{{cookiecutter.project_name}}.piccolo_conf"
# Now you can easily run migrations using 
piccolo migrations forwards all
{%- endif %}

Reverting migrations

If you want to revert migrations, you should run:

{%- if cookiecutter.orm in ['sqlalchemy', 'ormar'] %}
# revert all migrations up to: revision_id.
alembic downgrade <revision_id>

# Revert everything.
 alembic downgrade base
{%- elif cookiecutter.orm == 'tortoise' %}
aerich downgrade
{%- endif %}

Migration generation

To generate migrations you should run:

{%- if cookiecutter.orm in ['sqlalchemy', 'ormar'] %}
# For automatic change detection.
alembic revision --autogenerate

# For empty file generation.
alembic revision
{%- elif cookiecutter.orm == 'tortoise' %}
aerich migrate
{%- endif %}

{%- endif %}

Running tests

If you want to run it in docker, simply run:

docker compose run --build --rm api pytest -vv .
docker compose down

For running tests on your local machine.

{%- if ((cookiecutter.db_info.name != "none" and cookiecutter.db_info.name != "sqlite") or (cookiecutter.enable_redis == "True") or (cookiecutter.enable_rmq == "True") or (cookiecutter.enable_kafka == "True") or (cookiecutter.enable_nats == "True") ) %}

  1. you need to start all aux services.

We can do so by using our docker-compose.yaml configuration. It already has everything we need.

docker compose up -d --wait{%- if cookiecutter.db_info.name != 'none' %} db{%- endif %}{%- if cookiecutter.enable_redis == "True" %} redis{%- endif %}{%- if cookiecutter.enable_rmq == "True" %} rmq{%- endif %}{%- if cookiecutter.enable_kafka == "True" %} kafka{%- endif %}{%- if cookiecutter.enable_nats == "True" %} nats{%- endif %}
  1. Run tests.
pytest -vv .

{%- else %} Simply run

pytest -vv .

{%- endif %}