cleanup and docs

Author: joeblackwaslike

examples/eager_loading.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import sqlalchemy
+import sqlalchemy.orm
+import sqlalchemy.sql.selectable
+from sqlalchemy.orm import Mapped, mapped_column
+
+sa = sqlalchemy
+
+engine = sa.create_engine("sqlite://", echo=False)
+Base = sa.orm.declarative_base()
+Session = sa.orm.sessionmaker(bind=engine, expire_on_commit=False)
+
+
+class User(Base):
+    __tablename__ = "user"
+
+    id: Mapped[int] = mapped_column(sa.Identity(), primary_key=True)
+    name: Mapped[str] = mapped_column(sa.String(255), nullable=True)
+    time_created: Mapped[datetime] = mapped_column(
+        default=sa.func.now(),
+        server_default=sa.FetchedValue(),
+    )
+    time_updated: Mapped[datetime] = mapped_column(
+        default=sa.func.now(),
+        onupdate=sa.func.now(),
+        server_default=sa.FetchedValue(),
+        server_onupdate=sa.FetchedValue(),
+    )
+
+    posts = sa.orm.relationship("Post", back_populates="user")
+
+
+class Post(Base):
+    __tablename__ = "post"
+
+    id: Mapped[int] = mapped_column(sa.Identity(), primary_key=True)
+    user_id: Mapped[int] = mapped_column(sa.ForeignKey("user.id"), nullable=True)
+
+    user = sa.orm.relationship("User", back_populates="posts", uselist=False)
+
+
+Base.metadata.create_all(bind=engine)
+
+with Session() as session:
+    with session.begin():
+        user = User(name="joe", posts=[Post(), Post()])
+        session.add(user)
+        session.flush()
+        session.refresh(user)
+
+
+with Session() as session:
+    statement = sa.select(User).where(User.id == user.id)
+    eager_statement = statement.options(sa.orm.joinedload(User.posts))
+
+print(user.id, user.time_created, user.time_updated)
+
+with Session() as session:
+    with session.begin():
+        user = session.get(User, user.id)
+        new_user = session.merge(User(id=user.id, name="new"))
+        session.flush()
+        session.refresh(new_user)
+
+# time_updated not fetched, needs to be refreshed
+# print(new_user.name, new_user.time_created)
+
+print(user.id, user.name, user.time_created, user.time_updated)
+
+with Session() as session:
+    user = session.get(User, new_user.id)
+
+print(user.id, user.name, user.time_created, user.time_updated)
+
+>>> print(user.id, user.time_created, user.time_updated)
+'1 2023-03-21 18:02:56 2023-03-21 18:02:56'

src/quart_sqlalchemy/repository/abstract.py renamed to examples/repository/base.py

@@ -9,13 +9,13 @@
 import sqlalchemy.exc
 import sqlalchemy.orm
 import sqlalchemy.sql
+from builder import StatementBuilder
 
-from ..types import ColumnExpr
-from ..types import EntityIdT
-from ..types import EntityT
-from ..types import ORMOption
-from ..types import Selectable
-from .statement import StatementBuilder
+from quart_sqlalchemy.types import ColumnExpr
+from quart_sqlalchemy.types import EntityIdT
+from quart_sqlalchemy.types import EntityT
+from quart_sqlalchemy.types import ORMOption
+from quart_sqlalchemy.types import Selectable
 
 
 sa = sqlalchemy

src/quart_sqlalchemy/repository/statement.py renamed to examples/repository/builder.py

@@ -9,10 +9,10 @@
 import sqlalchemy.sql
 from sqlalchemy.orm.interfaces import ORMOption
 
-from ..types import ColumnExpr
-from ..types import DMLTable
-from ..types import EntityT
-from ..types import Selectable
+from quart_sqlalchemy.types import ColumnExpr
+from quart_sqlalchemy.types import DMLTable
+from quart_sqlalchemy.types import EntityT
+from quart_sqlalchemy.types import Selectable
 
 
 sa = sqlalchemy

src/quart_sqlalchemy/repository/meta.py renamed to examples/repository/meta.py

@@ -2,9 +2,9 @@
 
 import typing as t
 
-from ..model import SoftDeleteMixin
-from ..types import EntityT
-from ..util import lazy_property
+from quart_sqlalchemy.model import SoftDeleteMixin
+from quart_sqlalchemy.types import EntityT
+from quart_sqlalchemy.util import lazy_property
 
 
 class TableMetadataMixin(t.Generic[EntityT]):

src/quart_sqlalchemy/repository/sqla.py renamed to examples/repository/sqla.py

@@ -7,17 +7,17 @@
 import sqlalchemy.exc
 import sqlalchemy.orm
 import sqlalchemy.sql
-
-from ..types import ColumnExpr
-from ..types import EntityIdT
-from ..types import EntityT
-from ..types import ORMOption
-from ..types import Selectable
-from ..types import SessionT
-from .abstract import AbstractBulkRepository
-from .abstract import AbstractRepository
-from .meta import TableMetadataMixin
-from .statement import StatementBuilder
+from builder import StatementBuilder
+from meta import TableMetadataMixin
+
+from base import AbstractBulkRepository
+from base import AbstractRepository
+from quart_sqlalchemy.types import ColumnExpr
+from quart_sqlalchemy.types import EntityIdT
+from quart_sqlalchemy.types import EntityT
+from quart_sqlalchemy.types import ORMOption
+from quart_sqlalchemy.types import Selectable
+from quart_sqlalchemy.types import SessionT
 
 
 sa = sqlalchemy

examples/testing/conftest.py

@@ -0,0 +1,146 @@
+"""Pytest plugin for quart-sqlalchemy.
+
+The lifecycle of the database during testing should look something like this.
+
+1. The QuartSQLAlchemy object is instantiated by the application in a well known location such as the top level package.  Usually named `db`.  The database should be a fresh, in-memory, sqlite instance.
+2. The Quart object is instantiated in a pytest fixture `app` using the application factory pattern, inside this factory, db.init_app(app) is called.
+3. The database schema or DDL is executed using something like `db.create_all()`.
+4. The necessary database test fixtures are loaded into the database.
+5. A test transaction is created with savepoint, this transaction should be scoped at the `function` level.
+6. Any calls to Session() should be patched to return a session bound to the test transaction savepoint.
+    a. Bind.Session: sessionmaker
+    b. BindContext.Session
+    c. TestTransaction.Session (already patched)
+7. Engine should be patched to return connections bound to the savepoint transaction but this is too complex to be in scope.
+8. The test is run.
+9. The test transaction goes out of function scope and rolls back the database.
+10. The test transaction is recreated for the next test and so on until the pytest session is closed.
+"""
+
+import typing as t
+
+import pytest
+import sqlalchemy
+import sqlalchemy.orm
+from quart import Quart
+
+
+sa = sqlalchemy
+
+from quart_sqlalchemy import AsyncBind
+from quart_sqlalchemy import Base
+from quart_sqlalchemy import SQLAlchemyConfig
+from quart_sqlalchemy.framework import QuartSQLAlchemy
+from quart_sqlalchemy.testing import AsyncTestTransaction
+from quart_sqlalchemy.testing import TestTransaction
+
+
+default_app = Quart(__name__)
+
+
+@pytest.fixture(scope="session")
+def app() -> Quart:
+    """
+    This pytest fixture should return the Quart object
+    """
+    return default_app
+
+
+@pytest.fixture(scope="session")
+def db_config() -> SQLAlchemyConfig:
+    """
+    This pytest fixture should return the SQLAlchemyConfig object
+    """
+    return SQLAlchemyConfig(
+        model_class=Base,
+        binds={  # type: ignore
+            "default": {
+                "engine": {"url": "sqlite:///file:mem.db?mode=memory&cache=shared&uri=true"},
+                "session": {"expire_on_commit": False},
+            },
+            "read-replica": {
+                "engine": {"url": "sqlite:///file:mem.db?mode=memory&cache=shared&uri=true"},
+                "session": {"expire_on_commit": False},
+                "read_only": True,
+            },
+            "async": {
+                "engine": {
+                    "url": "sqlite+aiosqlite:///file:mem.db?mode=memory&cache=shared&uri=true"
+                },
+                "session": {"expire_on_commit": False},
+            },
+        },
+    )
+
+
+@pytest.fixture(scope="session")
+@pytest.fixture
+def _db(db_config: SQLAlchemyConfig, app: Quart) -> QuartSQLAlchemy:
+    """
+    This pytest fixture should return the QuartSQLAlchemy object
+    """
+    return QuartSQLAlchemy(db_config, app)
+
+
+@pytest.fixture(scope="session", autouse=True)
+@pytest.fixture
+def database_test_fixtures(_db: QuartSQLAlchemy) -> t.Generator[None, None, None]:
+    """
+    This pytest fixture should use the injected session to load any necessary testing fixtures.
+    """
+    _db.create_all()
+
+    with _db.bind.Session() as s:
+        with s.begin():
+            # add test fixtures to this session
+            pass
+
+    yield
+
+    _db.drop_all()
+
+
+@pytest.fixture(autouse=True)
+def db_test_transaction(
+    _db: QuartSQLAlchemy, database_test_fixtures: None
+) -> t.Generator[TestTransaction, None, None]:
+    """
+    This pytest fixture should yield a synchronous TestTransaction
+    """
+    with _db.bind.test_transaction(savepoint=True) as test_transaction:
+        yield test_transaction
+
+
+@pytest.fixture(autouse=True)
+async def async_db_test_transaction(
+    _db: QuartSQLAlchemy, database_test_fixtures: None
+) -> t.AsyncGenerator[TestTransaction, None]:
+    """
+    This pytest fixture should yield an asynchronous TestTransaction
+    """
+    async_bind: AsyncBind = _db.get_bind("async")  # type: ignore
+    async with async_bind.test_transaction(savepoint=True) as async_test_transaction:
+        yield async_test_transaction
+
+
+@pytest.fixture(autouse=True)
+def patch_sessionmakers(
+    _db: QuartSQLAlchemy,
+    db_test_transaction: TestTransaction,
+    async_db_test_transaction: AsyncTestTransaction,
+    monkeypatch,
+) -> t.Generator[None, None, None]:
+    for bind in _db.binds.values():
+        if isinstance(bind, AsyncBind):
+            savepoint_bound_session = async_db_test_transaction.Session
+        else:
+            savepoint_bound_session = db_test_transaction.Session
+
+        monkeypatch.setattr(bind, "Session", savepoint_bound_session)
+
+    yield
+
+
+@pytest.fixture(name="db", autouse=True)
+def patched_db(_db, patch_sessionmakers):
+    return _db

src/quart_sqlalchemy/bind.py

@@ -201,6 +201,12 @@ def register_soft_delete_support_for_session(
     options: t.Dict[str, t.Any],
     session_factory: t.Union[sa.orm.sessionmaker, sa.ext.asyncio.async_sessionmaker],
 ) -> None:
+    """Register the event handlers that enable soft-delete logic to be applied automatically.
+
+    This functionality is opt-in by nature.  Opt-in involves adding the SoftDeleteMixin to the
+    ORM models that should support soft-delete.  You can learn more by checking out the
+    model.mixins module.
+    """
     if all(
         [
             isinstance(session_factory, sa.ext.asyncio.async_sessionmaker),
@@ -212,6 +218,13 @@ def register_soft_delete_support_for_session(
     setup_soft_delete_for_session(session_factory)  # type: ignore
 
 
+# Beware of Dragons!
+#
+# The following handlers aren't at all crucial to understanding how this package works, they are
+# mostly based on well known sqlalchemy recipes and their impact can be fully understood from
+# their docstrings alone.
+
+
 @signals.after_bind_engine_created.connect
 def register_engine_connection_cross_process_safety_handlers(
     sender: Bind,
@@ -265,3 +278,57 @@ def checkout(dbapi_connection, connection_record, connection_proxy):
 
     if not sa.event.contains(engine, "checkout", checkout):
         sa.event.listen(engine, "checkout", checkout)
+
+
+@signals.after_bind_engine_created.connect
+def register_engine_connection_sqlite_specific_transaction_fix(
+    sender: Bind,
+    config: t.Dict[str, t.Any],
+    prefix: str,
+    engine: t.Union[sa.Engine, sa.ext.asyncio.AsyncEngine],
+) -> None:
+    """Register event handlers to fix dbapi broken transaction for sqlite dialects.
+
+    The pysqlite DBAPI driver has several long-standing bugs which impact the correctness of its
+    transactional behavior. In its default mode of operation, SQLite features such as
+    SERIALIZABLE isolation, transactional DDL, and SAVEPOINT support are non-functional, and in
+    order to use these features, workarounds must be taken.
+
+    The issue is essentially that the driver attempts to second-guess the user’s intent, failing
+    to start transactions and sometimes ending them prematurely, in an effort to minimize the
+    SQLite databases’s file locking behavior, even though SQLite itself uses “shared” locks for
+    read-only activities.
+
+    SQLAlchemy chooses to not alter this behavior by default, as it is the long-expected behavior
+    of the pysqlite driver; if and when the pysqlite driver attempts to repair these issues, that
+    will be more of a driver towards defaults for SQLAlchemy.
+
+    The good news is that with a few events, we can implement transactional support fully, by
+    disabling pysqlite’s feature entirely and emitting BEGIN ourselves. This is achieved using
+    two event listeners:
+
+    To learn more about this recipe, check out the sqlalchemy docs link below:
+        https://docs.sqlalchemy.org/en/20/dialects/sqlite.html#pysqlite-serializable
+    """
+
+    # Use the sync_engine when AsyncEngine
+    if isinstance(engine, sa.ext.asyncio.AsyncEngine):
+        engine = engine.sync_engine
+
+    if engine.dialect.name != "sqlite":
+        return
+
+    def do_connect(dbapi_connection, connection_record):
+        # disable pysqlite's emitting of the BEGIN statement entirely.
+        # also stops it from emitting COMMIT before any DDL.
+        dbapi_connection.isolation_level = None
+
+    if not sa.event.contains(engine, "connect", do_connect):
+        sa.event.listen(engine, "connect", do_connect)
+
+    def do_begin(conn_):
+        # emit our own BEGIN
+        conn_.exec_driver_sql("BEGIN")
+
+    if not sa.event.contains(engine, "begin", do_begin):
+        sa.event.listen(engine, "begin", do_begin)