Initial work on adding docs for FastAPISessionMaker (#6)

* Add docs for FastAPISessionMaker

Author: dmontagu

.github/workflows/build.yml

@@ -40,14 +40,14 @@ jobs:
         with:
           path: .pytest_cache
           key: pytest-${{ matrix.python-version }}
+      - name: Check docs build
+        # only run this for the python version used by netlify:
+        if: matrix.python-version == 3.7
+        run: |
+          make docs-build-ci
       - name: Check that formatting, linting, and tests pass
         run: |
           make ci
       - name: Submit coverage report
         run: |
           codecov --token=${{ secrets.CODECOV_TOKEN }}
-      - name: Check docs build
-        # only run this for the python version used by netlify:
-        if: matrix.python-version == 3.7
-        run: |
-          make docs-build-ci

.github/workflows/pull-request.yml

@@ -38,14 +38,14 @@ jobs:
         with:
           path: .pytest_cache
           key: pytest-${{ matrix.python-version }}
+      - name: Check docs build
+        # only run this for the python version used by netlify:
+        if: matrix.python-version == 3.7
+        run: |
+          make docs-build-ci
       - name: Check that formatting, linting, and tests pass
         run: |
           make ci
       - name: Submit coverage report
         run: |
           codecov --token=${{ secrets.CODECOV_TOKEN }}
-      - name: Check docs build
-        # only run this for the python version used by netlify:
-        if: matrix.python-version == 3.7
-        run: |
-          make docs-build-ci

docs/index.md

@@ -3,7 +3,7 @@
 </p>
 <p align="center">
 <img src="https://img.shields.io/github/last-commit/dmontagu/fastapi-utils.svg">
-<a href="https://github.com/dmontagu/" target="_blank">
+<a href="https://github.com/dmontagu/fastapi-utils" target="_blank">
     <img src="https://github.com/dmontagu/fastapi-utils/workflows/build/badge.svg" alt="Build">
 </a>
 <a href="https://codecov.io/gh/dmontagu/fastapi-utils" target="_blank">

docs/src/session1.py

@@ -0,0 +1,48 @@
+from functools import lru_cache
+from typing import Iterator
+from uuid import UUID
+
+import sqlalchemy as sa
+from fastapi import Depends, FastAPI
+from pydantic import BaseSettings
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import Session
+
+from fastapi_utils.guid_type import GUID, GUID_DEFAULT_SQLITE
+from fastapi_utils.session import FastAPISessionMaker
+
+Base = declarative_base()
+
+
+class User(Base):
+    __tablename__ = "user"
+    id = sa.Column(GUID, primary_key=True, default=GUID_DEFAULT_SQLITE)
+    name = sa.Column(sa.String, nullable=False)
+
+
+class DBSettings(BaseSettings):
+    """ Parses variables from environment on instantiation """
+
+    database_uri: str  # could break up into scheme, username, password, host, db
+
+
+def get_db() -> Iterator[Session]:
+    """ FastAPI dependency that provides a sqlalchemy session """
+    yield from _get_fastapi_sessionmaker().get_db()
+
+
+@lru_cache()
+def _get_fastapi_sessionmaker() -> FastAPISessionMaker:
+    """ This function could be replaced with a global variable if preferred """
+    database_uri = DBSettings().database_uri
+    return FastAPISessionMaker(database_uri)
+
+
+app = FastAPI()
+
+
+@app.get("/{user_id}")
+def get_user_name(db: Session = Depends(get_db), *, user_id: UUID) -> str:
+    user = db.query(User).get(user_id)
+    username = user.name
+    return username

docs/user-guide/repeated-tasks.md

@@ -31,7 +31,7 @@ Here's a hypothetical example that could be used to periodically clean up expire
 {!./src/repeated_tasks1.py!}
 ```
 
-(You may want to reference the [sessions docs](sessions.md){.internal-link target=_blank} for more
+(You may want to reference the [sessions docs](session.md){.internal-link target=_blank} for more
 information about `FastAPISessionMaker`.)
 
 By passing `seconds=60 * 60`, we ensure that the decorated function is called once every hour.

docs/user-guide/session.md

@@ -0,0 +1,96 @@
+#### Source module: [`fastapi_utils.sessions`](https://github.com/dmontagu/fastapi-utils/blob/master/fastapi_utils/session.py){.internal-link target=_blank}
+
+---
+
+One of the most commonly used ways to power database functionality with FastAPI is SQLAlchemy's ORM.
+
+FastAPI has [great documentation](https://fastapi.tiangolo.com/tutorial/sql-databases/) about how to integrate
+ORM into your application.
+
+However, the recommended approach for using SQLAlchemy's ORM with FastAPI has evolved over time to reflect both insights
+from the community and the addition of new features to FastAPI.
+
+The `fastapi_utils.session` module contains an implementation making use of the most up-to-date best practices for
+managing SQLAlchemy sessions with FastAPI.
+
+---
+
+## `FastAPISessionMaker`
+The `fastapi_utils.session.FastAPISessionMaker` class conveniently wraps session-making functionality for use with
+FastAPI. This section contains an example showing how to use this class. 
+
+Let's begin with some infrastructure. The first thing we'll do is make sure we have an ORM
+table to query:  
+
+```python hl_lines="8 9 11 14 17 18 19 20"
+{!./src/session1.py!}
+```
+
+Next, we set up infrastructure for loading the database uri from the environment:
+
+```python hl_lines="23 24 25 26"
+{!./src/session1.py!}
+```
+
+We use the `pydantic.BaseSettings` to load variables from the environment. There is documentation for this class in the
+<a href="https://pydantic-docs.helpmanual.io/usage/settings/" class="external-link" target="_blank">pydantic docs</a>,
+but the basic idea is that if a model inherits from this class, any fields not specified during initialization
+are read from the environment if possible.
+
+!!! info
+    Since `database_uri` is not an optional field, a `ValidationError` will be raised if the `DATABASE_URI` environment
+    variable is not set.
+
+!!! info
+    For finer grained control, you could remove the `database_uri` field, and replace it with
+    separate fields for `scheme`, `username`, `password`, `host`, and `db`. You could then give the model a `@property`
+    called `database_uri` that builds the uri from these components.
+
+Now that we have a way to load the database uri, we can create the FastAPI dependency we'll use
+to obtain the sqlalchemy session:
+
+```python hl_lines="29 30 31 34 35 36 37 38"
+{!./src/session1.py!}
+```
+
+!!! info
+    The `get_db` dependency makes use of a context-manager dependency, rather than a middleware-based approach.
+    This means that any endpoints that don't make use of a sqlalchemy session will not be exposed to any
+    session-related overhead.
+    
+    This is in contrast with middleware-based approaches, where the handling of every request would result in
+    a session being created and closed, even if the endpoint would not make use of it. 
+
+!!! warning
+    The `get_db` dependency **will not finalize your ORM session until *after* a response is returned to the user**.
+    
+    This has minor response-latency benefits, but also means that if you have any uncommitted
+    database writes that will raise errors, you may return a success response to the user (status code 200),
+    but still raise an error afterward during request clean-up.
+
+    To deal with this, for any request where you expect a database write to potentially fail, you should **manually
+    perform a commit inside your endpoint logic and appropriately handle any resulting errors.**
+
+    -----
+    
+    Note that while middleware-based approaches can automatically ensure database errors are visible to users, the
+    result would be a generic 500 internal server error, which you should strive to avoid sending to clients under
+    normal circumstances.
+
+    You can still log any database errors raised during cleanup by appropriately modifying the `get_db` function
+    with a `try: except:` block.
+
+The `get_db` function can be used as a FastAPI dependency that will inject a sqlalchemy ORM session where used:
+
+```python hl_lines="45 46"
+{!./src/session1.py!}
+```
+
+!!! info
+    We make use of `@lru_cache` on `_get_fastapi_sessionmaker` to ensure the same `FastAPISessionMaker` instance is
+    reused across requests. This reduces the per-request overhead while still ensuring the instance is created
+    lazily, making it possible to have the `database_uri` reflect modifications to the environment performed *after*
+    importing the relevant source file.
+    
+    This can be especially useful during testing if you want to override environment variables programmatically using
+    your testing framework.

docs/user-guide/sessions.md

@@ -6,6 +6,16 @@
 
 
 class FastAPISessionMaker:
+    """
+    This class provides a convenient cached interface for accessing sqlalchemy ORM sessions using just a database URI.
+
+    The expected format of database_uri is `"<scheme>://<user>:<password>@<host>:<port>/<database>`, exactly as you'd
+    use with `sqlalchemy.create_engine`.
+
+    For example, if a postgres database named `app` is accessible on a container named `db`,
+    the `database_uri` might look like: "postgresql://db_user:password@db:5432/app"
+    """
+
     def __init__(self, database_uri: str):
         self.database_uri = database_uri
 
@@ -14,6 +24,9 @@ def __init__(self, database_uri: str):
 
     @property
     def cached_engine(self) -> sa.engine.Engine:
+        """
+        Returns the cached engine if present, or a new (cached) engine using the database_uri if not
+        """
         engine = self._cached_engine
         if engine is None:
             engine = self.get_new_engine()
@@ -22,49 +35,99 @@ def cached_engine(self) -> sa.engine.Engine:
 
     @property
     def cached_sessionmaker(self) -> sa.orm.sessionmaker:
+        """
+        Returns the cached sessionmaker if present, or a new (cached) sessionmaker using the cached_engine if not
+        """
         sessionmaker = self._cached_sessionmaker
         if sessionmaker is None:
             sessionmaker = self.get_new_sessionmaker(self.cached_engine)
             self._cached_sessionmaker = sessionmaker
         return sessionmaker
 
-    def get_new_engine(self,) -> sa.engine.Engine:
+    def get_new_engine(self) -> sa.engine.Engine:
+        """
+        Returns a new sqlalchemy engine for the database_uri.
+        """
         return get_engine(self.database_uri)
 
     def get_new_sessionmaker(self, engine: Optional[sa.engine.Engine]) -> sa.orm.sessionmaker:
+        """
+        Returns a new sessionmaker for the (optional) provided engine.
+
+        If `None` is provided, the cached engine is used. (A new engine is created and cached if necessary.)
+        """
         engine = engine or self.cached_engine
         return get_sessionmaker_for_engine(engine)
 
     def get_db(self) -> Iterator[Session]:
         """
-        Intended for use as a FastAPI dependency
+        A FastAPI dependency that yields a sqlalchemy session.
+
+        The session is created by the cached sessionmaker, and closed via contextmanager after the response is returned.
+
+        Note that if you perform any database writes and want to handle errors *prior* to returning a response (and you
+        should!), you'll need to put `session.commit()` or `session.rollback()` as appropriate in your endpoint code.
+        This is generally a best practice for expected errors anyway since otherwise you would generate a 500 response.
         """
         yield from _get_db(self.cached_sessionmaker)
 
     @contextmanager
     def context_session(self) -> Iterator[Session]:
+        """
+        This method directly produces a context-managed session without relying on FastAPI's dependency injection.
+
+        Usage would look like:
+        ```python
+        session_maker = FastAPISessionMaker(db_uri)
+        with session_maker.context_session() as session:
+            instance = session.query(OrmModel).get(instance_id)
+        ```
+        """
         yield from self.get_db()
 
     def reset_cache(self) -> None:
+        """
+        Resets the engine and sessionmaker caches.
+
+        After calling this method, the next time you try to use the cached engine or sessionmaker,
+        new ones will be created.
+        """
         self._cached_engine = None
         self._cached_sessionmaker = None
 
 
 def get_engine(uri: str) -> sa.engine.Engine:
+    """
+    Returns a new sqlalchemy engine that "tests connections for liveness upon each checkout".
+    """
     return sa.create_engine(uri, pool_pre_ping=True)
 
 
 def get_sessionmaker_for_engine(engine: sa.engine.Engine) -> sa.orm.sessionmaker:
+    """
+    Returns a sqlalchemy sessionmaker for the provided engine, using recommended settings for use with FastAPI.
+    """
     return sa.orm.sessionmaker(autocommit=False, autoflush=False, bind=engine)
 
 
 @contextmanager
 def context_session(engine: sa.engine.Engine) -> Iterator[Session]:
+    """
+    This method produces a context-managed session for use with a specified engine.
+
+    Behaves similarly to FastAPISessionMaker.context_session.
+    """
     sessionmaker = get_sessionmaker_for_engine(engine)
     yield from _get_db(sessionmaker)
 
 
 def _get_db(sessionmaker: sa.orm.sessionmaker) -> Iterator[Session]:
+    """
+    The underlying generator function used to create context-managed sqlalchemy sessions for:
+    * context_session
+    * FastAPISessionMaker.context_session
+    * FastAPISessionMaker.get_db
+    """
     session = sessionmaker()
     try:
         yield session

fastapi_utils/session.py

@@ -24,7 +24,7 @@ nav:
       - Inferring Router: 'user-guide/inferring-router.md'
       - Repeated Tasks: 'user-guide/repeated-tasks.md'
       - Timing Middleware: 'user-guide/timing-middleware.md'
-      - SQLAlchemy Sessions: 'user-guide/sessions.md'
+      - SQLAlchemy Sessions: 'user-guide/session.md'
       - OpenAPI Spec Simplification: 'user-guide/openapi.md'
       - Other Utilities:
           - APIModel: 'user-guide/basics/api-model.md'