finish this version except readme

rafsaf · rafsaf · commit 4eb1b472739d · 2021-11-09T18:46:39.000+01:00
diff --git a/README.md b/README.md
@@ -7,23 +7,23 @@
 - Alembic migrations
 - Very minimal project structure yet ready for quick start building new api
 - Refresh token endpoint (not only access like in official template)
-- Two databases in docker-compose.yml (second for tests)
+- Two databases in docker-compose.yml (second one for tests)
 - poetry
 - `pre-push.sh` script with poetry export, autoflake, black, isort and flake8
-- Setup for tests, one big test for token flow and very extensible `conftest.py`
+- Setup for async tests, one func test for token flow and very extensible `conftest.py`
 
 ## What this repo is
 
-This is a minimal template for FastAPI backend + postgresql db as of 2021, `async` style for database sessions, endpoints and tests. It provides basic codebase that almost every application has, but nothing more.
+This is a minimal template for FastAPI backend + postgresql db as of 2021.11, `async` style for database sessions, endpoints and tests. It provides basic codebase that almost every application has, but nothing more.
 
 ## What this repo is not
 
-It is not complex, full featured solutions for all human kind problems. It doesn't include any third party that isn't necessary for most of apps (dashboards, queues) or implementation differs so much in every project that it's pointless (complex user model, emails).
+It is not complex, full featured solutions for all human kind problems. It doesn't include any third party that isn't necessary for most of apps (dashboards, queues) or implementation differs so much in every project that it's pointless (complex User model, emails, RBAC, permissions).
 
 ## Quickstart
 
 ```bash
-# You can even install it globally
+# Install cookiecutter globally
 pip install cookiecutter
 
 # And cookiecutter this project :)
@@ -32,20 +32,20 @@ cookiecutter https://github.com/rafsaf/minimal-fastapi-postgres-template
 cd project_name
 # Poetry install (and activate environment!)
 poetry install
-# Databases
+# Setup two databases
 docker-compose up -d
 # Alembic migrations upgrade and initial_data.py script
 bash init.sh
 # And this is it:
-uvicorn app.main:app
+uvicorn app.main:app --reload
 ```
 
 tests:
 
 ```bash
+# Note, it will use second database declared in docker-compose.yml, not default one
 pytest
-# Note, it will use second database declared in docker-compose.yml, not default one like
-# in official template
+
 ```
 
 ## About
@@ -54,6 +54,6 @@ This project is heavily base on official template https://github.com/tiangolo/fu
 
 `2.0` style SQLAlchemy API is good enough so there is no need to write everything in `crud` and waste our time... The `core` folder was also rewritten. There is great base for writting tests in `tests`, but I didn't want to write hundreds of them, I noticed that usually after changes in the structure of the project, auto tests are useless and you have to write them from scratch anyway (delete old ones...), hence less than more. Similarly with the `User` model, it is very modest, because it will be adapted to the project anyway (and there are no tests for these endpoints, you would remove them probably).
 
-## Learn by example
+## Step by step example
 
-Let's imagine we need to create API for a website where users brag about their dogs... or whatever, they just can crud dogs in user panel for some reason. We will add dummy model Dog to our API, with relation to the default table User and crud auth endpoints, then test it shortly.
+I always enjoy to to have some kind of example in templates (even if I don't like it much, _some_ parts may be useful and save my time...), so let's create `POST` endpoint for creating dogs.
diff --git a/{{cookiecutter.project_name}}/Dockerfile b/{{cookiecutter.project_name}}/Dockerfile
@@ -1,9 +1,10 @@
-# See https://hub.docker.com/r/nginx/unit/
+# See https://unit.nginx.org/installation/#docker-images
+
 FROM nginx/unit:1.25.0-python3.9
 
 ENV PYTHONUNBUFFERED 1
 
-# Nginx unit config and init.sh will be used at container startup
+# Nginx unit config and init.sh will be consumed at container startup.
 COPY ./app/init.sh /docker-entrypoint.d/init.sh
 COPY ./nginx-unit-config.json /docker-entrypoint.d/config.json
 RUN chmod +x /docker-entrypoint.d/init.sh
@@ -17,7 +18,7 @@ COPY ./alembic ./alembic
 COPY ./alembic.ini .
 COPY ./requirements.txt .
 
-# Requirements and then cleanup
+# Update, install requirements and then cleanup.
 RUN apt update && apt install -y python3-pip                                  \
     && pip3 install -r requirements.txt                                       \
     && apt remove -y python3-pip                                              \
diff --git a/{{cookiecutter.project_name}}/alembic.ini b/{{cookiecutter.project_name}}/alembic.ini
@@ -5,7 +5,7 @@
 script_location = alembic
 
 # template used to generate migration files
-file_template = %%(year)d%%(month).2d%%(day).2d%%(hour).2d%%(minute).2d%%(second).2d_%%(rev)s_%%(slug)s
+file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d_%%(slug)s__%%(rev)s
 
 # sys.path path, will be prepended to sys.path if present.
 # defaults to the current working directory.
diff --git a/{{cookiecutter.project_name}}/alembic/env.py b/{{cookiecutter.project_name}}/alembic/env.py
@@ -31,8 +31,6 @@
 
 
 def get_database_uri():
-    if settings.ENVIRONMENT == "PYTEST":
-        return settings.TEST_SQLALCHEMY_DATABASE_URI
     return settings.DEFAULT_SQLALCHEMY_DATABASE_URI
 
 
diff --git a/{{cookiecutter.project_name}}/alembic/versions/2021_11_09_1736_init__cefce371682e.py b/{{cookiecutter.project_name}}/alembic/versions/2021_11_09_1736_init__cefce371682e.py
@@ -1,16 +1,16 @@
 """init
 
-Revision ID: e2318cba28d4
+Revision ID: cefce371682e
 Revises: 
-Create Date: 2021-10-23 16:15:04.828924
+Create Date: 2021-11-09 17:36:41.970204
 
 """
 from alembic import op
 import sqlalchemy as sa
 
 
 # revision identifiers, used by Alembic.
-revision = 'e2318cba28d4'
+revision = 'cefce371682e'
 down_revision = None
 branch_labels = None
 depends_on = None
diff --git a/{{cookiecutter.project_name}}/app/api/api.py b/{{cookiecutter.project_name}}/app/api/api.py
@@ -0,0 +1,7 @@
+from fastapi import APIRouter
+
+from app.api.endpoints import auth, users
+
+api_router = APIRouter()
+api_router.include_router(auth.router, prefix="/auth", tags=["auth"])
+api_router.include_router(users.router, prefix="/users", tags=["users"])
diff --git a/{{cookiecutter.project_name}}/app/api/deps.py b/{{cookiecutter.project_name}}/app/api/deps.py
@@ -13,7 +13,7 @@
 from app.models import User
 from app.session import async_session
 
-reusable_oauth2 = OAuth2PasswordBearer(tokenUrl="v1/auth/access-token")
+reusable_oauth2 = OAuth2PasswordBearer(tokenUrl="auth/access-token")
 
 
 async def get_session() -> AsyncGenerator[AsyncSession, None]:
diff --git a/{{cookiecutter.project_name}}/app/api/endpoints/__init__.py b/{{cookiecutter.project_name}}/app/api/endpoints/__init__.py
diff --git a/{{cookiecutter.project_name}}/app/api/endpoints/auth.py b/{{cookiecutter.project_name}}/app/api/endpoints/auth.py
@@ -8,13 +8,11 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app import schemas
-from app.api.routers import api_v1_router
-from app.api.api_v1 import deps
+from app.api import deps
 from app.core import security
 from app.core.config import settings
 from app.models import User
 
-
 router = APIRouter()
 
 
@@ -90,6 +88,3 @@ async def refresh_token(
         "refresh_token": refresh_token,
         "refresh_expire_at": refresh_expire_at,
     }
-
-
-api_v1_router.include_router(router, prefix="", tags=["users"])
diff --git a/{{cookiecutter.project_name}}/app/api/endpoints/users.py b/{{cookiecutter.project_name}}/app/api/endpoints/users.py
@@ -4,7 +4,7 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app import models, schemas
-from app.api.api_v1 import deps
+from app.api import deps
 from app.core.security import get_password_hash
 
 router = APIRouter()
diff --git a/{{cookiecutter.project_name}}/app/api/routers.py b/{{cookiecutter.project_name}}/app/api/routers.py
diff --git a/{{cookiecutter.project_name}}/app/conftest.py b/{{cookiecutter.project_name}}/app/conftest.py
@@ -1,8 +1,10 @@
-import os
+"""
+Used to execute code before running tests, in this case we want to use test database.
+We don't want to mess up dev database.
+
+Put here any Pytest related code (it will be executed before `app/tests/...`)
+"""
 
-# We overwrite variables from .env to hardcoded one to connect with test database
-# We don't want to mess up dev database
-#
-# Put here any pytest-specific code (it will run before app/tests/...)
+import os
 
 os.environ["ENVIRONMENT"] = "PYTEST"
diff --git a/{{cookiecutter.project_name}}/app/core/config.py b/{{cookiecutter.project_name}}/app/core/config.py
@@ -1,3 +1,24 @@
+"""
+File with environment variables and general configuration logic.
+`SECRET_KEY`, `ENVIRONMENT` etc. map to env variables with the same names.
+
+Pydantic priority ordering:
+
+1. (Most important, will overwrite everything) - environment variables
+2. `.env` file in root folder of project
+3. Default values
+
+For project name, version, description we use pyproject.toml
+For the rest, we use file `.env` (gitignored), see `.env.example`
+
+`DEFAULT_SQLALCHEMY_DATABASE_URI` and `TEST_SQLALCHEMY_DATABASE_URI`:
+Both are ment to be validated at the runtime, do not change unless you know
+what are you doing. All the two validators do is to build full URI (TCP protocol)
+to databases to avoid typo bugs.
+
+See https://pydantic-docs.helpmanual.io/usage/settings/
+"""
+
 from pathlib import Path
 from typing import Dict, List, Literal, Union
 
@@ -16,7 +37,7 @@ class Settings(BaseSettings):
     REFRESH_TOKEN_EXPIRE_MINUTES: int
     BACKEND_CORS_ORIGINS: Union[str, List[AnyHttpUrl]]
 
-    # PROJECT NAME, API PREFIX, VERSION AND DESC, CORS ORIGINS
+    # PROJECT NAME, VERSION AND DESCRIPTION
     PROJECT_NAME: str = pyproject_content["name"]
     VERSION: str = pyproject_content["version"]
     DESCRIPTION: str = pyproject_content["description"]
diff --git a/{{cookiecutter.project_name}}/app/core/security.py b/{{cookiecutter.project_name}}/app/core/security.py
@@ -1,3 +1,9 @@
+"""
+Black-box security shortcuts to generate JWT tokens and password hash/verify
+
+`subject` in access/refresh func may be antyhing unique to User account, `id` etc.
+"""
+
 from datetime import datetime, timedelta
 from typing import Any, Union
 
diff --git a/{{cookiecutter.project_name}}/app/initial_data.py b/{{cookiecutter.project_name}}/app/initial_data.py
@@ -1,4 +1,11 @@
-from asyncio import get_event_loop
+"""
+Put here any Python code that must be runned before application startup.
+It is included in `init.sh` script.
+
+By defualt `main` create a superuser if not exists
+"""
+
+import asyncio
 from typing import Optional
 
 from sqlalchemy import select
@@ -36,4 +43,4 @@ async def main() -> None:
 
 
 if __name__ == "__main__":
-    get_event_loop().run_until_complete(main())
+    asyncio.run(main())
diff --git a/{{cookiecutter.project_name}}/app/main.py b/{{cookiecutter.project_name}}/app/main.py
@@ -1,7 +1,11 @@
+"""
+Main FastAPI app instance declaration
+"""
+
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
-from app.api.routers import api_v1_router
+from app.api.api import api_router
 from app.core.config import settings
 
 app = FastAPI(
@@ -22,4 +26,4 @@
         allow_headers=["*"],
     )
 
-app.include_router(api_v1_router)
+app.include_router(api_router)
diff --git a/{{cookiecutter.project_name}}/app/models.py b/{{cookiecutter.project_name}}/app/models.py
@@ -1,3 +1,9 @@
+"""
+SQL Alchemy models declaration.
+
+Note, imported by alembic migrations logic, see `alembic/env.py`
+"""
+
 from typing import Any, cast
 
 from sqlalchemy import Column, Integer, String
diff --git a/{{cookiecutter.project_name}}/app/tests/conftest.py b/{{cookiecutter.project_name}}/app/tests/conftest.py
@@ -5,10 +5,10 @@
 from httpx import AsyncClient
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.core.config import settings
 from app.main import app
 from app.models import Base
 from app.session import async_engine, async_session
-from app.core.config import settings
 
 
 @pytest.fixture(scope="session")
@@ -26,11 +26,13 @@ async def client():
 
 @pytest.fixture(scope="session")
 async def test_db_setup_sessionmaker():
+    # assert if we use TEST_DB URL for 100%
     assert settings.ENVIRONMENT == "PYTEST"
     assert str(async_engine.url) == settings.TEST_SQLALCHEMY_DATABASE_URI
 
+    # always drop and create test db tables between tests session
     async with async_engine.begin() as conn:
-        # awalys drop and create test db tables between tests session
+
         await conn.run_sync(Base.metadata.drop_all)
         await conn.run_sync(Base.metadata.create_all)
     return async_session
diff --git a/{{cookiecutter.project_name}}/app/tests/test_auth.py b/{{cookiecutter.project_name}}/app/tests/test_auth.py
@@ -8,7 +8,7 @@
 from app.core.security import get_password_hash
 from app.models import User
 
-# All test coroutines will be treated as marked.
+# All test coroutines in file will be treated as marked (async allowed).
 pytestmark = pytest.mark.asyncio
 
 
@@ -31,6 +31,7 @@ async def default_user(session: AsyncSession):
 
 async def test_login_endpoints(client: AsyncClient, default_user: User):
 
+    # access-token endpoint
     access_token = await client.post(
         "/auth/access-token",
         data={
@@ -45,13 +46,15 @@ async def test_login_endpoints(client: AsyncClient, default_user: User):
     access_token = token["access_token"]
     refresh_token = token["refresh_token"]
 
+    # test-token endpoint
     test_token = await client.post(
         "/auth/test-token", headers={"Authorization": f"Bearer {access_token}"}
     )
     assert test_token.status_code == 200
     response_user = test_token.json()
     assert response_user["email"] == default_user.email
 
+    # refresh-token endpoint
     get_new_token = await client.post(
         "/auth/refresh-token", json={"refresh_token": refresh_token}
     )
