document setup, session & pagination

Author: hadrien

README.md

@@ -8,7 +8,11 @@ _Async SQLAlchemy 2 for FastAPI — boilerplate, pagination, and seamless sessio
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-brightgreen.svg)](https://conventionalcommits.org)
 [![GitHub License](https://img.shields.io/github/license/hadrien/fastsqla)](https://github.com/hadrien/FastSQLA/blob/main/LICENSE)
 
-**Documentation**: https://hadrien.github.io/FastSQLA/
+**Documentation**: [https://hadrien.github.io/FastSQLA/](https://hadrien.github.io/FastSQLA/)
+
+**Github Repo:** [https://github.com/hadrien/fastsqla](https://github.com/hadrien/fastsqla)
+
+-----------------------------------------------------------------------------------------
 
 `FastSQLA` is an [`SQLAlchemy 2`](https://docs.sqlalchemy.org/en/20/) extension for
 [`FastAPI`](https://fastapi.tiangolo.com/).
@@ -147,11 +151,13 @@ class Hero(Base):
     id: Mapped[int] = mapped_column(primary_key=True)
     name: Mapped[str] = mapped_column(unique=True)
     secret_identity: Mapped[str]
+    age: Mapped[int]
 
 
 class HeroBase(BaseModel):
     name: str
     secret_identity: str
+    age: int
 
 
 class HeroModel(HeroBase):
@@ -160,21 +166,21 @@ class HeroModel(HeroBase):
 
 
 @app.get("/heros", response_model=Page[HeroModel])
-async def list_users(paginate: Paginate):
+async def list_heros(paginate: Paginate):
     stmt = select(Hero)
     return await paginate(stmt)
 
 
 @app.get("/heros/{hero_id}", response_model=Item[HeroModel])
-async def get_user(hero_id: int, session: Session):
+async def get_hero(hero_id: int, session: Session):
     hero = await session.get(Hero, hero_id)
     if hero is None:
         raise HTTPException(HTTPStatus.NOT_FOUND, "Hero not found")
     return {"data": hero}
 
 
 @app.post("/heros", response_model=Item[HeroModel])
-async def create_user(new_hero: HeroBase, session: Session):
+async def create_hero(new_hero: HeroBase, session: Session):
     hero = Hero(**new_hero.model_dump())
     session.add(hero)
     try:
@@ -197,22 +203,23 @@ sqlite3 db.sqlite <<EOF
 CREATE TABLE hero (
     id              INTEGER PRIMARY KEY AUTOINCREMENT,
     name            TEXT NOT NULL UNIQUE, -- Unique hero name (e.g., Superman)
-    secret_identity TEXT NOT NULL         -- Secret identity (e.g., Clark Kent)
+    secret_identity TEXT NOT NULL,        -- Secret identity (e.g., Clark Kent)
+    age             INTEGER NOT NULL      -- Age of the hero (e.g., 30)
 );
 
--- Insert heroes with their name and secret identity
-INSERT INTO hero (name, secret_identity) VALUES ('Superman',        'Clark Kent');
-INSERT INTO hero (name, secret_identity) VALUES ('Batman',          'Bruce Wayne');
-INSERT INTO hero (name, secret_identity) VALUES ('Wonder Woman',    'Diana Prince');
-INSERT INTO hero (name, secret_identity) VALUES ('Iron Man',        'Tony Stark');
-INSERT INTO hero (name, secret_identity) VALUES ('Spider-Man',      'Peter Parker');
-INSERT INTO hero (name, secret_identity) VALUES ('Captain America', 'Steve Rogers');
-INSERT INTO hero (name, secret_identity) VALUES ('Black Widow',     'Natasha Romanoff');
-INSERT INTO hero (name, secret_identity) VALUES ('Thor',            'Thor Odinson');
-INSERT INTO hero (name, secret_identity) VALUES ('Scarlet Witch',   'Wanda Maximoff');
-INSERT INTO hero (name, secret_identity) VALUES ('Doctor Strange',  'Stephen Strange');
-INSERT INTO hero (name, secret_identity) VALUES ('The Flash',       'Barry Allen');
-INSERT INTO hero (name, secret_identity) VALUES ('Green Lantern',   'Hal Jordan');
+-- Insert heroes with their name, secret identity, and age
+INSERT INTO hero (name, secret_identity, age) VALUES ('Superman',        'Clark Kent',       30);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Batman',          'Bruce Wayne',      35);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Wonder Woman',    'Diana Prince',     30);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Iron Man',        'Tony Stark',       45);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Spider-Man',      'Peter Parker',     25);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Captain America', 'Steve Rogers',     100);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Black Widow',     'Natasha Romanoff', 35);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Thor',            'Thor Odinson',     1500);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Scarlet Witch',   'Wanda Maximoff',   30);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Doctor Strange',  'Stephen Strange',  40);
+INSERT INTO hero (name, secret_identity, age) VALUES ('The Flash',       'Barry Allen',      28);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Green Lantern',   'Hal Jordan',       35);
 EOF
 ```
 

docs/pagination.md

@@ -0,0 +1,8 @@
+# Pagination
+
+## `fastsqla.Paginate[T]`
+
+::: fastsqla.Paginate
+    options:
+        heading_level: false
+        show_source: false

docs/session.md

@@ -0,0 +1,39 @@
+# `SQLAlchemy` Session
+
+## Lifecycle
+
+[`SQLAlchemy` documentation](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it)
+recommends the following:
+
+*  Keep the lifecycle of the session **separate and external** from functions and
+    objects that access and/or manipulate database data.
+*  Make sure you have a clear notion of where transactions begin and end, and keep
+    transactions **short**, meaning, they end at the series of a sequence of operations,
+    instead of being held open indefinitely.
+
+`FastSQLA` automatically manages the session lifecycle:
+
+* If the request is successful, the session is committed.
+* If the request fails, the session is rolled back.
+* In all cases, at the end of the request, the session is closed and the associated
+  connection is returned to the connection pool.
+
+
+To learn more about `SQLAlchemy` sessions:
+
+* [Session Basics](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#)
+
+
+## Session dependency
+
+::: fastsqla.Session
+    options:
+        heading_level: false
+        show_source: false
+
+## Session context manager
+
+::: fastsqla.open_session
+    options:
+        heading_level: false
+        show_source: false

docs/configuration.md renamed to docs/setup.md

@@ -1,10 +1,22 @@
-# Configuration
+# Setup
 
-Configuration is exclusively done via environment variables to follow the
+## `fastsqla.lifespan`
+
+::: fastsqla.lifespan
+    options:
+        heading_level: false
+        show_source: false
+
+## Configuration
+
+Configuration is done exclusively via environment variables, adhering to the
 [**Twelve-Factor App methodology**](https://12factor.net/config).
 
-The only required key is **`SQLALCHEMY_URL`**, which specifies the database URL and
-supports embedding specific database driver parameters in the query string.
+The only required key is **`SQLALCHEMY_URL`**, which defines the database URL. It
+specifies the database driver in the URL's scheme and allows embedding driver parameters
+in the query string. Example:
+
+    sqlite+aiosqlite:////tmp/test.db?check_same_thread=false
 
 All parameters of [`sqlalchemy.create_engine`][] can be configured by setting environment
 variables, with each parameter name prefixed by **`SQLALCHEMY_`**.
@@ -14,14 +26,14 @@ variables, with each parameter name prefixed by **`SQLALCHEMY_`**.
     FastSQLA is **case-insensitive** when reading environment variables, so parameter
     names prefixed with **`SQLALCHEMY_`** can be provided in any letter case.
 
-## Examples
+### Examples
 
 1.  :simple-postgresql: PostgreSQL url using
     [`asyncpg`][sqlalchemy.dialects.postgresql.asyncpg] driver with a
     [`pool_recycle`][sqlalchemy.create_engine.params.pool_recycle] of 30 minutes:
 
     ```bash
-    export SQLALCHEMY_URL=postgresql+asyncpg://postgres@localhost
+    export SQLALCHEMY_URL=postgresql+asyncpg://postgres@localhost/postgres
     export SQLALCHEMY_POOL_RECYCLE=1800
     ```
 
@@ -30,7 +42,7 @@ variables, with each parameter name prefixed by **`SQLALCHEMY_`**.
     [`pool_size`][sqlalchemy.create_engine.params.pool_size] of 50:
 
     ```bash
-    export sqlalchemy_url=sqlite+aiosqlite:////tmp/test.db?check_same_thread=false
+    export sqlalchemy_url=sqlite+aiosqlite:///tmp/test.db?check_same_thread=false
     export sqlalchemy_pool_size=10
     ```
 
@@ -40,4 +52,4 @@ variables, with each parameter name prefixed by **`SQLALCHEMY_`**.
     ```bash
     export sqlalchemy_url=mysql+aiomysql://bob:password!@db.example.com/app
     export sqlalchemy_echo=true
-    ```
+    ```

mkdocs.yml

@@ -7,16 +7,18 @@ edit_uri: edit/main/docs/
 nav:
 - Get Started:
   - Welcome to FastSQLA: index.md
-  - Configuration: configuration.md
-  - Changelog: changelog.md
+- Usage:
+  - Setup: setup.md
+  - SQLAlchemy Session: session.md
+  - Pagination: pagination.md
+- Changelog: changelog.md
 
 theme:
   favicon: images/favicon.png
   icon:
     logo: material/database
   name: material
   features:
-    - admonition
     - announce.dismiss
     - content.code.annotate
     - content.code.copy
@@ -63,6 +65,7 @@ plugins:
   - search
 
 markdown_extensions:
+  - abbr
   - admonition
   - attr_list
   - md_in_html
@@ -71,7 +74,16 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
   - pymdownx.superfences
+
   - toc:
       permalink: true
-
+watch:
+  - docs
+  - src