fix(tests,docs): green CI — table fixtures, runnable doc examples, topmost imports

- Replace per-test create_all(tables=[...]) + drop_all in the encrypted-type
  integration tests with a shared fixture doing metadata.create_all(engine)
  (mirrors the password-hash tests). The old pattern did not create the
  BigIntBase PK sequence on a fresh database, causing
  "relation <table>_id_seq does not exist" on PostgreSQL/Oracle/MSSQL CI.
- Make the new docs code examples self-contained and runnable under Sybil:
  build HashedPassword/TOTPProvider directly instead of referencing undefined
  model instances, and import HashedPassword/StoredObject from the topmost
  advanced_alchemy.types path.
- Add TOTP secret, one-time-code, and rehash-on-verify to the README feature
  list.

The crypto type imports remain safe when their optional libraries are absent:
importing advanced_alchemy.types pulls in none of cryptography/pyotp/argon2/
passlib/pwdlib (guards fire at construction time, not import time).

Author: cofin

README.md

@@ -47,7 +47,9 @@ offering:
 - Integrated support for UUID6 and UUID7 ([`uuid-utils`](https://github.com/aminalaee/uuid-utils) when installed, otherwise native in Python 3.14+, with UUID4 fallback on older versions).
 - Integrated support for Nano ID using [`fastnanoid`](https://github.com/oliverlambson/fastnanoid) (install with the `nanoid` extra)
 - Custom encrypted text type with multiple backend support including [`pgcrypto`](https://www.postgresql.org/docs/current/pgcrypto.html) for PostgreSQL and the Fernet implementation from [`cryptography`](https://cryptography.io/en/latest/) for other databases
-- Custom password hashing type with multiple backend support including [`Argon2`](https://github.com/P-H-C/phc-winner-argon2), [`Passlib`](https://passlib.readthedocs.io/en/stable/), and [`Pwdlib`](https://pwdlib.readthedocs.io/en/stable/) with automatic salt generation
+- Custom password hashing type with multiple backend support including [`Argon2`](https://github.com/P-H-C/phc-winner-argon2), [`Passlib`](https://passlib.readthedocs.io/en/stable/), and [`Pwdlib`](https://pwdlib.readthedocs.io/en/stable/) with automatic salt generation and rehash-on-verify for transparent hash upgrades on login
+- Custom TOTP shared-secret type that stores an authenticator seed encrypted at rest and verifies time-based one-time passwords via [`pyotp`](https://github.com/pyauth/pyotp) (install with the `pyotp` extra)
+- Custom one-time-code type for hashed, single-use email/SMS verification codes, reusing the password-hash backends
 - Pre-configured base classes with audit columns UUID or Big Integer primary keys and
   a [sentinel column](https://docs.sqlalchemy.org/en/20/core/connections.html#configuring-sentinel-columns).
 - Synchronous and asynchronous repositories featuring:

docs/usage/frameworks/fastapi.rst

@@ -255,9 +255,8 @@ Start by registering a backend and mapping the file column:
     from sqlalchemy.orm import Mapped, mapped_column
 
     from advanced_alchemy.extensions.fastapi import base, repository, service
-    from advanced_alchemy.types import FileObject, storages
+    from advanced_alchemy.types import FileObject, storages, StoredObject
     from advanced_alchemy.types.file_object.backends.obstore import ObstoreBackend
-    from advanced_alchemy.types.file_object.data_type import StoredObject
 
     documents_backend = ObstoreBackend(
         key="documents",

docs/usage/frameworks/litestar.rst

@@ -996,9 +996,8 @@ The pattern below mirrors ``examples/litestar/litestar_fileobject.py``:
         repository,
         service,
     )
-    from advanced_alchemy.types import FileObject, storages
+    from advanced_alchemy.types import FileObject, storages, StoredObject
     from advanced_alchemy.types.file_object.backends.obstore import ObstoreBackend
-    from advanced_alchemy.types.file_object.data_type import StoredObject
 
     # Configure file storage backend
     documents_backend = ObstoreBackend(

docs/usage/modeling/types.rst

@@ -165,15 +165,21 @@ explicitly — each pulls a different optional dependency:
 
         password: Mapped[str] = mapped_column(PasswordHash(backend=Argon2Hasher()))
 
-On read, ``account.password`` is a ``HashedPassword``. Verify with ``verify``, or use
-``verify_and_update`` to transparently upgrade a hash that was created with weaker
-parameters after a successful login:
+On read, ``account.password`` is a :class:`HashedPassword <advanced_alchemy.types.HashedPassword>`.
+Verify with ``verify``, or use ``verify_and_update`` to transparently upgrade a hash created
+with weaker parameters after a successful login. The same wrapper can be built standalone:
 
 .. code-block:: python
 
-    ok, new_hash = account.password.verify_and_update(submitted_password)
+    from advanced_alchemy.types import HashedPassword
+    from advanced_alchemy.types.password_hash.argon2 import Argon2Hasher
+
+    backend = Argon2Hasher()
+    stored = HashedPassword(backend.hash("s3cret"), backend)
+
+    ok, new_hash = stored.verify_and_update("s3cret")
     if ok and new_hash is not None:
-        account.password = new_hash  # re-hashed with current parameters; persist it
+        ...  # persist new_hash back to the row
 
 The default column ``length`` is 255 to accommodate stacked passlib schemes.
 
@@ -197,12 +203,17 @@ extra (``pip install advanced_alchemy[pyotp]``); a ``key`` is mandatory.
 
         seed: Mapped[str] = mapped_column(TOTPSecret(key="my-secret-key", issuer="ACME"))
 
-    # enrollment
-    enrollment = MfaEnrollment(seed=generate_totp_secret())
-    uri = enrollment.seed.provisioning_uri(name="alice@example.com")  # render as a QR code
+After loading a row, ``enrollment.seed`` is a
+:class:`TOTPProvider <advanced_alchemy.types.TOTPProvider>`. Build one directly to generate a
+provisioning URI (render it as a QR code) and verify submitted codes:
+
+.. code-block:: python
+
+    from advanced_alchemy.types import TOTPProvider, generate_totp_secret
 
-    # verification (tolerates one tick of clock drift by default)
-    is_valid = enrollment.seed.verify(submitted_code)
+    provider = TOTPProvider(generate_totp_secret(), issuer="ACME")
+    uri = provider.provisioning_uri(name="alice@example.com")
+    is_valid = provider.verify("123456")  # tolerates one tick of clock drift by default
 
 One-Time Codes
 --------------

tests/integration/test_encrypted_string.py

@@ -1,9 +1,9 @@
 """Integration round-trip tests for the encrypted column types."""
 
-from typing import Optional, cast
+from typing import Any, Optional, cast
 
 import pytest
-from sqlalchemy import Engine, String, Table, text
+from sqlalchemy import Engine, String, text
 from sqlalchemy.orm import Mapped, Session, mapped_column, sessionmaker
 
 from advanced_alchemy.base import BigIntBase
@@ -50,6 +50,14 @@ class TOTPModel(BigIntBase):
         __table_args__ = {"info": {"allow_eager": True}}
 
 
+@pytest.fixture()
+def encrypted_test_tables(engine: Engine) -> None:
+    """Create the encrypted-type test tables for sync engines."""
+    name = getattr(engine.dialect, "name", "")
+    if name != "mock" and not name.startswith("spanner"):
+        FernetModel.metadata.create_all(engine)
+
+
 def _should_skip(engine: Engine) -> Optional[str]:
     name = engine.dialect.name
     if name == "mock":
@@ -61,51 +69,43 @@ def _should_skip(engine: Engine) -> Optional[str]:
     return None
 
 
-def test_fernet_round_trip(engine: Engine) -> None:
+def test_fernet_round_trip(engine: Engine, encrypted_test_tables: None) -> None:
     skip_reason = _should_skip(engine)
     if skip_reason is not None:
         pytest.skip(skip_reason)
 
-    FernetModel.metadata.create_all(engine, tables=[cast("Table", FernetModel.__table__)])
     session_factory: sessionmaker[Session] = sessionmaker(engine, expire_on_commit=False)
-    try:
-        with session_factory() as db_session:
-            obj = FernetModel(name="fernet", secret="top-secret-value")
-            db_session.add(obj)
-            db_session.commit()
-            db_session.refresh(obj)
-            assert obj.secret == "top-secret-value"
+    with session_factory() as db_session:
+        obj = FernetModel(name="fernet", secret="top-secret-value")
+        db_session.add(obj)
+        db_session.commit()
+        db_session.refresh(obj)
+        assert obj.secret == "top-secret-value"
 
-            obj.secret = None
-            db_session.commit()
-            db_session.refresh(obj)
-            assert obj.secret is None
-    finally:
-        FernetModel.metadata.drop_all(engine, tables=[cast("Table", FernetModel.__table__)])
+        obj.secret = None
+        db_session.commit()
+        db_session.refresh(obj)
+        assert obj.secret is None
 
 
-def test_pgcrypto_round_trip(engine: Engine) -> None:
+def test_pgcrypto_round_trip(engine: Engine, encrypted_test_tables: None) -> None:
     if engine.dialect.name != "postgresql":
         pytest.skip("pgcrypto requires a real PostgreSQL backend")
 
     with engine.begin() as conn:
         conn.execute(text("CREATE EXTENSION IF NOT EXISTS pgcrypto"))
 
-    PGCryptoModel.metadata.create_all(engine, tables=[cast("Table", PGCryptoModel.__table__)])
     session_factory: sessionmaker[Session] = sessionmaker(engine, expire_on_commit=False)
-    try:
-        with session_factory() as db_session:
-            obj = PGCryptoModel(name="pgcrypto", secret="pg-secret-value")
-            db_session.add(obj)
-            db_session.commit()
-            db_session.refresh(obj)
-            assert obj.secret == "pg-secret-value"
-    finally:
-        PGCryptoModel.metadata.drop_all(engine, tables=[cast("Table", PGCryptoModel.__table__)])
+    with session_factory() as db_session:
+        obj = PGCryptoModel(name="pgcrypto", secret="pg-secret-value")
+        db_session.add(obj)
+        db_session.commit()
+        db_session.refresh(obj)
+        assert obj.secret == "pg-secret-value"
 
 
 @pytest.mark.parametrize("model", [FernetModel, PGCryptoModel])
-def test_backends_are_interchangeable(engine: Engine, model: "type[BigIntBase]") -> None:
+def test_backends_are_interchangeable(engine: Engine, model: "type[BigIntBase]", encrypted_test_tables: None) -> None:
     """Fernet and PGCrypto must be drop-in interchangeable: same API, same external behavior.
 
     Run on PostgreSQL where both backends work (pgcrypto is PostgreSQL-only) so the two are
@@ -117,32 +117,27 @@ def test_backends_are_interchangeable(engine: Engine, model: "type[BigIntBase]")
     with engine.begin() as conn:
         conn.execute(text("CREATE EXTENSION IF NOT EXISTS pgcrypto"))
 
-    table = cast("Table", model.__table__)
-    model.metadata.create_all(engine, tables=[table])
     session_factory: sessionmaker[Session] = sessionmaker(engine, expire_on_commit=False)
-    try:
-        with session_factory() as db_session:
-            for value in ["plain-value", "ünîcödé 🔐 secret", "", None]:
-                obj = model(name="x", secret=value)
-                db_session.add(obj)
-                db_session.commit()
-                db_session.refresh(obj)
-                assert obj.secret == value
-
-                raw = db_session.execute(
-                    text(f"SELECT secret FROM {model.__tablename__} WHERE id = :id"),
-                    {"id": obj.id},
-                ).scalar_one()
-                if value is None:
-                    assert raw is None
-                else:
-                    assert raw != value
-    finally:
-        model.metadata.drop_all(engine, tables=[table])
+    with session_factory() as db_session:
+        for value in ["plain-value", "ünîcödé 🔐 secret", "", None]:
+            obj = cast("Any", model(name="x", secret=value))
+            db_session.add(obj)
+            db_session.commit()
+            db_session.refresh(obj)
+            assert obj.secret == value
+
+            raw = db_session.execute(
+                text(f"SELECT secret FROM {model.__tablename__} WHERE id = :id"),
+                {"id": obj.id},
+            ).scalar_one()
+            if value is None:
+                assert raw is None
+            else:
+                assert raw != value
 
 
 @pytest.mark.skipif(not PYOTP_INSTALLED, reason="pyotp not installed")
-def test_totp_secret_round_trip(engine: Engine) -> None:
+def test_totp_secret_round_trip(engine: Engine, encrypted_test_tables: None) -> None:
     import pyotp
 
     from advanced_alchemy.types.totp import TOTPProvider
@@ -152,24 +147,20 @@ def test_totp_secret_round_trip(engine: Engine) -> None:
         pytest.skip(skip_reason)
 
     secret = pyotp.random_base32()
-    TOTPModel.metadata.create_all(engine, tables=[cast("Table", TOTPModel.__table__)])
     session_factory: sessionmaker[Session] = sessionmaker(engine, expire_on_commit=False)
-    try:
-        with session_factory() as db_session:
-            obj = TOTPModel(name="totp", seed=secret)
-            db_session.add(obj)
-            db_session.commit()
-            row_id = obj.id
-            db_session.refresh(obj)
-
-            provider = cast("object", obj.seed)
-            assert isinstance(provider, TOTPProvider)
-            assert provider.secret == secret
-            assert provider.verify(pyotp.TOTP(secret).now()) is True
-
-            stored = db_session.execute(
-                text("SELECT seed FROM test_encrypted_totp WHERE id = :id"), {"id": row_id}
-            ).scalar_one()
-            assert stored != secret
-    finally:
-        TOTPModel.metadata.drop_all(engine, tables=[cast("Table", TOTPModel.__table__)])
+    with session_factory() as db_session:
+        obj = TOTPModel(name="totp", seed=secret)
+        db_session.add(obj)
+        db_session.commit()
+        row_id = obj.id
+        db_session.refresh(obj)
+
+        provider = cast("object", obj.seed)
+        assert isinstance(provider, TOTPProvider)
+        assert provider.secret == secret
+        assert provider.verify(pyotp.TOTP(secret).now()) is True
+
+        stored = db_session.execute(
+            text("SELECT seed FROM test_encrypted_totp WHERE id = :id"), {"id": row_id}
+        ).scalar_one()
+        assert stored != secret