readme - update about and step by step section

Signed-off-by: Rafał Safin <rafal.safin@rafsaf.pl>

Author: Rafał Safin

README.md

@@ -64,7 +64,7 @@ cd your_project_name
 poetry install
 ```
 
-Note, be sure to use `python3.12` with this template with either poetry or standard venv & pip, if you need to stick to some earlier python version, you should adapt it yourself (remove new versions specific syntax for example `str | int` for python < 3.10 or `tomllib` for python < 3.11)
+Note, be sure to use `python3.12` with this template with either poetry or standard venv & pip, if you need to stick to some earlier python version, you should adapt it yourself (remove new versions specific syntax for example `str | int` for python < 3.10)
 
 ### 3. Setup database and migrations
 
@@ -84,11 +84,11 @@ uvicorn app.main:app --reload
 
 ```
 
-You should then use `git init` to initialize git repository and access OpenAPI spec at http://localhost:8000/ by default. To customize docs url, cors and allowed hosts settings, read section about it.
+You should then use `git init` (if needed) to initialize git repository and access OpenAPI spec at http://localhost:8000/ by default. To customize docs url, cors and allowed hosts settings, read [section about it](#docs-url-cors-and-allowed-hosts).
 
 ### 5. Activate pre-commit
 
-[pre-commit](https://pre-commit.com/) is de facto standard now for pre push activities like isort or black or its replacement ruff.
+[pre-commit](https://pre-commit.com/) is de facto standard now for pre push activities like isort or black or its nowadays replacement ruff.
 
 Refer to `.pre-commit-config.yaml` file to see my current opinionated choices.
 
@@ -119,6 +119,14 @@ This project is heavily based on the official template https://github.com/tiango
 
 `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, with just `id` (uuid), `email` and `password_hash`, because it will be adapted to the project anyway.
 
+2024 update:
+
+The template was adpoted to my current style and knowledge, the test based expanded to cover more, added mypy, ruff and test setup was completly rewritten to have three things:
+
+- run test in paraller in many processes for speed 
+- transactions rollback after every test
+- create test databases instead of having another in docker-compose.yml
+
 <br>
 
 ## Step by step example - POST and GET endpoints
@@ -132,48 +140,25 @@ I always enjoy to have some kind of an example in templates (even if I don't lik
 
 ### 1. Create SQLAlchemy model
 
-We will add Pet model to `app/models.py`. To keep things clear, below is full result of models.py file.
+We will add `Pet` model to `app/models.py`.
 
 ```python
 # app/models.py
 
-import uuid
-
-from sqlalchemy import ForeignKey, Integer, String
-from sqlalchemy.dialects.postgresql import UUID
-from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
-
-
-class Base(DeclarativeBase):
-    pass
-
-
-class User(Base):
-    __tablename__ = "user_model"
-
-    id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=lambda _: str(uuid.uuid4())
-    )
-    email: Mapped[str] = mapped_column(
-        String(254), nullable=False, unique=True, index=True
-    )
-    hashed_password: Mapped[str] = mapped_column(String(128), nullable=False)
-
+...
 
 class Pet(Base):
     __tablename__ = "pet"
 
-    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
     user_id: Mapped[str] = mapped_column(
-        ForeignKey("user_model.id", ondelete="CASCADE"),
+        ForeignKey("user_account.user_id", ondelete="CASCADE"),
     )
     pet_name: Mapped[str] = mapped_column(String(50), nullable=False)
 
-
-
 ```
 
-Note, we are using super powerful SQLAlchemy feature here - Mapped and mapped_column were first introduced in SQLAlchemy 2.0 on Feb 26, if this syntax is new for you, read carefully "what's new" part of documentation https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html.
+Note, we are using super powerful SQLAlchemy feature here - Mapped and mapped_column were first introduced in SQLAlchemy 2.0, if this syntax is new for you, read carefully "what's new" part of documentation https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html.
 
 <br>
 
@@ -199,15 +184,13 @@ alembic upgrade head
 # INFO  [alembic.runtime.migration] Running upgrade d1252175c146 -> 44b7b689ea5f, create_pet_model
 ```
 
-PS. Note, alembic is configured in a way that it work with async setup and also detects specific column changes.
+PS. Note, alembic is configured in a way that it work with async setup and also detects specific column changes if using `--autogenerate` flag.
 
 <br>
 
 ### 3. Create request and response schemas
 
-I personally lately (after seeing clear benefits at work in Samsung) prefer less files than a lot of them for things like schemas.
-
-Thats why there are only 2 files: `requests.py` and `responses.py` in `schemas` folder and I would keep it that way even for few dozen of endpoints. Not to mention this is opinionated.
+There are only 2 files: `requests.py` and `responses.py` in `schemas` folder and I would keep it that way even for few dozen of endpoints. Not to mention this is opinionated.
 
 ```python
 # app/schemas/requests.py
@@ -238,9 +221,9 @@ class PetResponse(BaseResponse):
 ### 4. Create endpoints
 
 ```python
-# /app/api/endpoints/pets.py
+# app/api/endpoints/pets.py
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, status
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -252,46 +235,54 @@ from app.schemas.responses import PetResponse
 router = APIRouter()
 
 
-@router.post("/create", response_model=PetResponse, status_code=201)
+@router.post(
+    "/create",
+    response_model=PetResponse,
+    status_code=status.HTTP_201_CREATED,
+    description="Creates new pet. Only for logged users.",
+)
 async def create_new_pet(
-    new_pet: PetCreateRequest,
+    data: PetCreateRequest,
     session: AsyncSession = Depends(deps.get_session),
     current_user: User = Depends(deps.get_current_user),
-):
-    """Creates new pet. Only for logged users."""
+) -> Pet:
+    new_pet = Pet(user_id=current_user.user_id, pet_name=data.pet_name)
 
-    pet = Pet(user_id=current_user.id, pet_name=new_pet.pet_name)
-
-    session.add(pet)
+    session.add(new_pet)
     await session.commit()
-    return pet
+
+    return new_pet
 
 
-@router.get("/me", response_model=list[PetResponse], status_code=200)
+@router.get(
+    "/me",
+    response_model=list[PetResponse],
+    status_code=status.HTTP_200_OK,
+    description="Get list of pets for currently logged user.",
+)
 async def get_all_my_pets(
     session: AsyncSession = Depends(deps.get_session),
     current_user: User = Depends(deps.get_current_user),
-):
-    """Get list of pets for currently logged user."""
+) -> list[Pet]:
+    pets = await session.scalars(
+        select(Pet).where(Pet.user_id == current_user.user_id).order_by(Pet.pet_name)
+    )
 
-    stmt = select(Pet).where(Pet.user_id == current_user.id).order_by(Pet.pet_name)
-    pets = await session.execute(stmt)
-    return pets.scalars().all()
+    return list(pets.all())
 
 ```
 
 Also, we need to add newly created endpoints to router.
 
 ```python
-# /app/api/api.py
+# app/api/api.py
 
-from fastapi import APIRouter
+...
 
 from app.api.endpoints import auth, pets, users
 
-api_router = APIRouter()
-api_router.include_router(auth.router, prefix="/auth", tags=["auth"])
-api_router.include_router(users.router, prefix="/users", tags=["users"])
+...
+
 api_router.include_router(pets.router, prefix="/pets", tags=["pets"])
 
 ```
@@ -300,9 +291,12 @@ api_router.include_router(pets.router, prefix="/pets", tags=["pets"])
 
 ### 5. Write tests
 
+We will write two really simple tests in combined file inside newly created `app/tests/test_pets` folder.
+
 ```python
-# /app/tests/test_pets.py
+# app/tests/test_pets/test_pets.py
 
+from fastapi import status
 from httpx import AsyncClient
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -311,24 +305,29 @@ from app.models import Pet, User
 
 
 async def test_create_new_pet(
-    client: AsyncClient, default_user_headers, default_user: User
-):
+    client: AsyncClient, default_user_headers: dict[str, str], default_user: User
+) -> None:
     response = await client.post(
         app.url_path_for("create_new_pet"),
         headers=default_user_headers,
         json={"pet_name": "Tadeusz"},
     )
-    assert response.status_code == 201
+    assert response.status_code == status.HTTP_201_CREATED
+
     result = response.json()
-    assert result["user_id"] == default_user.id
+    assert result["user_id"] == default_user.user_id
     assert result["pet_name"] == "Tadeusz"
 
 
 async def test_get_all_my_pets(
-    client: AsyncClient, default_user_headers, default_user: User, session: AsyncSession
-):
-    pet1 = Pet(user_id=default_user.id, pet_name="Pet_1")
-    pet2 = Pet(user_id=default_user.id, pet_name="Pet_2")
+    client: AsyncClient,
+    default_user_headers: dict[str, str],
+    default_user: User,
+    session: AsyncSession,
+) -> None:
+    pet1 = Pet(user_id=default_user.user_id, pet_name="Pet_1")
+    pet2 = Pet(user_id=default_user.user_id, pet_name="Pet_2")
+
     session.add(pet1)
     session.add(pet2)
     await session.commit()
@@ -337,7 +336,7 @@ async def test_get_all_my_pets(
         app.url_path_for("get_all_my_pets"),
         headers=default_user_headers,
     )
-    assert response.status_code == 200
+    assert response.status_code == status.HTTP_200_OK
 
     assert response.json() == [
         {
@@ -352,6 +351,7 @@ async def test_get_all_my_pets(
         },
     ]
 
+
 ```
 
 ## Design
@@ -368,29 +368,29 @@ There are some **opinionated** default settings in `/app/main.py` for documentat
 
 1. Docs
 
-   ```python
-   app = FastAPI(
-       title=config.settings.PROJECT_NAME,
-       version=config.settings.VERSION,
-       description=config.settings.DESCRIPTION,
-       openapi_url="/openapi.json",
-       docs_url="/",
-   )
-   ```
+    ```python
+    app = FastAPI(
+        title="minimal fastapi postgres template",
+        version="6.0.0",
+        description="https://github.com/rafsaf/minimal-fastapi-postgres-template",
+        openapi_url="/openapi.json",
+        docs_url="/",
+    )
+    ```
 
-   Docs page is simpy `/` (by default in FastAPI it is `/docs`). Title, version and description are taken directly from `config` and then directly from `pyproject.toml` file. You can change it completely for the project, remove or use environment variables `PROJECT_NAME`, `VERSION`, `DESCRIPTION`.
+   Docs page is simpy `/` (by default in FastAPI it is `/docs`). You can change it completely for the project, just as title, version, etc.
 
 2. CORS
 
-   ```python
-   app.add_middleware(
-       CORSMiddleware,
-       allow_origins=[str(origin) for origin in config.settings.BACKEND_CORS_ORIGINS],
-       allow_credentials=True,
-       allow_methods=["*"],
-       allow_headers=["*"],
-   )
-   ```
+    ```python
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=[str(origin) for origin in config.settings.BACKEND_CORS_ORIGINS],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    ```
 
    If you are not sure what are CORS for, follow https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS. React and most frontend frameworks nowadays operate on `http://localhost:3000` thats why it's included in `BACKEND_CORS_ORIGINS` in .env file, before going production be sure to include your frontend domain here, like `https://my-fontend-app.example.com`.