BREAKING CHANGE!: Switch to feature rich template

Author: Bit-Maximum

.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: Testing app
+
+on: push
+
+jobs:
+  lint:
+    strategy:
+      matrix:
+        cmd:
+          - black
+          - ruff
+          - mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install poetry
+        run: pipx install poetry
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'poetry'
+      - name: Install deps
+        run: poetry install
+      - name: Run lint check
+        run: poetry run pre-commit run -a ${{ matrix.cmd }}
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create .env
+        run: touch .env
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Update docker-compose
+        uses: KengoTODA/actions-setup-docker-compose@v1
+        with:
+          version: "2.28.0"
+      - name: run tests
+        run: docker-compose run --rm api pytest -vv

.gitignore

@@ -140,4 +140,3 @@ dmypy.json
 
 # Cython debug symbols
 cython_debug/
-/.qodo/

Dockerfile

@@ -1,8 +1,16 @@
 # Start from a slim version of Python 3.13
 FROM python:3.13-slim AS base
+COPY --from=ghcr.io/astral-sh/uv:0.6.4 /uv /uvx /bin/
 
-# Set Python Envs
-ENV APP_HOME=/app/ PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 UV_COMPILE_BYTECODE=1
+# Set Envs
+ENV APP_HOME=/app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_COMPILE_BYTECODE=1 \
+    PATH="$APP_HOME/.venv/bin:$PATH" \
+    UV_LINK_MODE=copy \
+    PYTHONPATH=$APP_HOME
 
 WORKDIR $APP_HOME
 
@@ -15,36 +23,19 @@ RUN apt-get update \
     wget \
     && pip install --prefer-binary --no-cache-dir --upgrade pip \
     && apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false \
-    && rm -rf /var/lib/apt/lists/* \
-
-# Install uv
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#installing-uv
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
-
-# Place executables in the environment at the front of the path
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#using-the-environment
-ENV PATH="/app/.venv/bin:$PATH" UV_LINK_MODE=copy PYTHONPATH=$APP_HOME
+    && rm -rf /var/lib/apt/lists/*
 
 # ===== Prod stage =====
 FROM base AS prod
 
-# Install base dependencies
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
-RUN --mount=type=cache,target=/root/.cache/uv \
-    --mount=type=bind,source=uv.lock,target=uv.lock \
-    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
-    uv sync --locked --no-install-project --no-dev
+COPY pyproject.toml uv.lock ./
 
-COPY ./pyproject.toml ./uv.lock $APP_HOME
-
-COPY ./src $APP_HOME/src
-
-# Sync the project
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync --locked --no-dev
 
-# Run app - exec form (doesn’t start a shell on its own)
-CMD ["/usr/local/bin/python", "-m", "main.py"]
+COPY ./app ./$APP_HOME
+
+CMD ["python", "-m", "app"]
 
 # ===== Dev stage =====
 FROM prod AS dev

README.md

@@ -1,4 +1,4 @@
-# FastAPI_super_template
+# app
 
 This project was generated using fastapi_template.
 
@@ -11,7 +11,7 @@ To run the project use this set of commands:
 
 ```bash
 poetry install
-poetry run python -m src
+poetry run python -m app
 ```
 
 This will start the server on the configured host.
@@ -46,10 +46,13 @@ docker-compose build
 ## Project structure
 
 ```bash
-$ tree "FastAPI_super_template"
-src
+$ tree "app"
+app
 ├── conftest.py  # Fixtures for all tests.
-├── main.py  # Startup script. Starts uvicorn.
+├── db  # module contains db configurations
+│   ├── dao  # Data Access Objects. Contains different classes to interact with database.
+│   └── models  # Package contains different models for ORMs.
+├── __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.
@@ -68,18 +71,18 @@ 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 "FASTAPI_SUPER_TEMPLATE_" prefix.
+All environment variables should start with "APP_" prefix.
 
-For example if you see in your "FastAPI_super_template/settings.py" a variable named like
-`random_parameter`, you should provide the "FASTAPI_SUPER_TEMPLATE_RANDOM_PARAMETER"
+For example if you see in your "app/settings.py" a variable named like
+`random_parameter`, you should provide the "APP_RANDOM_PARAMETER"
 variable to configure the value. This behaviour can be changed by overriding `env_prefix` property
-in `FastAPI_super_template.settings.Settings.Config`.
+in `app.settings.Settings.Config`.
 
 An example of .env file:
 ```bash
-FASTAPI_SUPER_TEMPLATE_RELOAD="True"
-FASTAPI_SUPER_TEMPLATE_PORT="8000"
-FASTAPI_SUPER_TEMPLATE_ENVIRONMENT="dev"
+APP_RELOAD="True"
+APP_PORT="8000"
+APP_ENVIRONMENT="dev"
 ```
 
 You can read more about BaseSettings class here: https://pydantic-docs.helpmanual.io/usage/settings/
@@ -134,7 +137,40 @@ If you haven't pushed to docker registry yet, you can build image locally.
 
 ```bash
 docker-compose build
-docker save --output src.tar src:latest
+docker save --output app.tar app:latest
+```
+
+## Migrations
+
+If you want to migrate your database, you should run following commands:
+```bash
+# To run all migrations until the migration with revision_id.
+alembic upgrade "<revision_id>"
+
+# To perform all pending migrations.
+alembic upgrade "head"
+```
+
+### Reverting migrations
+
+If you want to revert migrations, you should run:
+```bash
+# revert all migrations up to: revision_id.
+alembic downgrade <revision_id>
+
+# Revert everything.
+ alembic downgrade base
+```
+
+### Migration generation
+
+To generate migrations you should run:
+```bash
+# For automatic change detection.
+alembic revision --autogenerate
+
+# For empty file generation.
+alembic revision
 ```
 
 
@@ -148,6 +184,12 @@ docker-compose down
 ```
 
 For running tests on your local machine.
+1. you need to start a database.
+
+I prefer doing it with docker:
+```
+docker run -p "5432:5432" -e "POSTGRES_PASSWORD=app" -e "POSTGRES_USER=app" -e "POSTGRES_DB=app" postgres:16.3-bullseye
+```
 
 
 2. Run the pytest.

alembic.ini

@@ -0,0 +1,52 @@
+[alembic]
+script_location = app/db/migrations
+file_template = %%(year)d-%%(month).2d-%%(day).2d-%%(hour).2d-%%(minute).2d_%%(rev)s
+prepend_sys_path = .
+output_encoding = utf-8
+# truncate_slug_length = 40
+
+
+[post_write_hooks]
+hooks = black,ruff
+
+black.type = console_scripts
+black.entrypoint = black
+
+ruff.type = exec
+ruff.executable = ruff
+ruff.options = check --fix REVISION_SCRIPT_FILENAME --ignore N999
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

app/__init__.py

@@ -0,0 +1 @@
+"""app package."""

src/main.py app/__main__.pysrc/main.py renamed to app/__main__.py

@@ -4,16 +4,15 @@
 
 import uvicorn
 
-from src.gunicorn_runner import GunicornApplication
-from src.settings import settings
+from app.settings import settings
 
 
 def set_multiproc_dir() -> None:
     """
     Sets mutiproc_dir env variable.
 
     This function cleans up the multiprocess directory
-    and recreates it. This actions are required by prometheus-client
+    and recreates it. Thous actions are required by prometheus-client
     to share metrics between processes.
 
     After cleanup, it sets two variables.
@@ -36,30 +35,15 @@ def set_multiproc_dir() -> None:
 def main() -> None:
     """Entrypoint of the application."""
     set_multiproc_dir()
-    if settings.reload:
-        uvicorn.run(
-            "src.web.application:get_app",
-            workers=settings.workers_count,
-            host=settings.host,
-            port=settings.port,
-            reload=settings.reload,
-            log_level=settings.log_level.value.lower(),
-            factory=True,
-        )
-    else:
-        # We choose gunicorn only if reload
-        # option is not used, because reload
-        # feature doesn't work with gunicorn workers.
-        GunicornApplication(
-            "src.web.application:get_app",
-            host=settings.host,
-            port=settings.port,
-            workers=settings.workers_count,
-            factory=True,
-            accesslog="-",
-            loglevel=settings.log_level.value.lower(),
-            access_log_format='%r "-" %s "-" %Tf',
-        ).run()
+    uvicorn.run(
+        "app.web.application:get_app",
+        workers=settings.workers_count,
+        host=settings.host,
+        port=settings.port,
+        reload=settings.reload,
+        log_level=settings.log_level.value.lower(),
+        factory=True,
+    )
 
 
 if __name__ == "__main__":

app/db/__init__.py

@@ -0,0 +1,9 @@
+from sqlalchemy.orm import DeclarativeBase
+
+from app.db.meta import meta
+
+
+class Base(DeclarativeBase):
+    """Base for all models."""
+
+    metadata = meta

app/db/base.py

@@ -0,0 +1 @@
+"""DAO classes."""