tigrbl-tests 0.3.0__py3-none-any.whl

tests/unit/test_base_facade_initialize.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import pytest
+from sqlalchemy import Column, Integer
+
+from tigrbl.app._app import App as _App
+from tigrbl.api._api import Api as _Api
+from tigrbl.engine import resolver as _resolver
+from tigrbl.engine.shortcuts import mem
+from tigrbl.table import Base
+
+
+class Widget(Base):
+    __tablename__ = "widgets"
+
+    id = Column(Integer, primary_key=True)
+
+
+class SimpleApp(_App):
+    TITLE = "TestApp"
+    VERSION = "0.0"
+    LIFESPAN = None
+    APIS: tuple = ()
+    MODELS: tuple = ()
+    MIDDLEWARES: tuple = ()
+
+
+class SimpleApi(_Api):
+    PREFIX = ""
+    TAGS: list[str] = []
+
+
+def test_base_app_supports_initialize():
+    app = SimpleApp(engine=mem(async_=False))
+    app.models["Widget"] = Widget
+
+    try:
+        app.initialize()
+    finally:
+        _resolver.set_default(None)
+
+    assert getattr(app, "_ddl_executed", False) is True
+    tables = getattr(app, "tables", None)
+    assert tables is not None
+    assert getattr(tables, "Widget", None) is Widget.__table__
+
+
+def test_base_api_supports_initialize_sync():
+    api = SimpleApi(engine=mem(async_=False))
+    api.models["Widget"] = Widget
+
+    api.initialize()
+
+    assert getattr(api, "_ddl_executed", False) is True
+    assert api.tables["Widget"] is Widget.__table__
+
+
+@pytest.mark.asyncio
+async def test_base_api_supports_initialize_async():
+    class Gadget(Base):
+        __tablename__ = "gadgets"
+
+        id = Column(Integer, primary_key=True)
+
+    api = SimpleApi(engine=mem())
+    api.models["Gadget"] = Gadget
+
+    await api.initialize()
+
+    assert getattr(api, "_ddl_executed", False) is True
+    assert api.tables["Gadget"] is Gadget.__table__

tests/unit/test_build_list_params_spec_model.py

@@ -0,0 +1,33 @@
+from tigrbl.orm.tables._base import _materialize_colspecs_to_sqla
+from tigrbl.specs import acol, S, F, IO
+from tigrbl.types import Integer, String
+from tigrbl.schema import _build_list_params
+from sqlalchemy.orm import Mapped, DeclarativeBase
+
+
+class LocalBase(DeclarativeBase):
+    def __init_subclass__(cls, **kw):  # pragma: no cover - simple mapper hook
+        _materialize_colspecs_to_sqla(cls)
+        super().__init_subclass__(**kw)
+
+
+class Thing(LocalBase):
+    __tablename__ = "spec_things"
+
+    id: Mapped[int] = acol(
+        storage=S(type_=Integer, primary_key=True),
+        field=F(py_type=int),
+        io=IO(out_verbs=("read", "list")),
+    )
+    name: Mapped[str] = acol(
+        storage=S(type_=String),
+        field=F(py_type=str),
+        io=IO(out_verbs=("read", "list"), filter_ops=("eq", "like")),
+    )
+
+
+def test_build_list_params_with_spec_only_model():
+    params = _build_list_params(Thing)
+    fields = set(params.model_fields.keys())
+    assert "name" in fields
+    assert "name__like" in fields

tests/unit/test_bulk_body_annotation.py

@@ -0,0 +1,23 @@
+from typing import get_args, get_origin
+
+from tigrbl.bindings.rest.collection import _make_collection_endpoint
+from tigrbl.orm.mixins import BulkCapable, GUIDPk
+from tigrbl.op import OpSpec
+from tigrbl.orm.tables import Base
+from tigrbl.types import Column, String
+
+
+def test_bulk_create_body_annotation_is_list() -> None:
+    Base.metadata.clear()
+
+    class Widget(Base, GUIDPk, BulkCapable):
+        __tablename__ = "widgets_anno"
+        name = Column(String, nullable=False)
+
+    sp = OpSpec(alias="bulk_create", target="bulk_create")
+    endpoint = _make_collection_endpoint(
+        Widget, sp, resource="widget", db_dep=lambda: None
+    )
+    body_ann = endpoint.__annotations__["body"]
+    assert get_origin(body_ann) is list
+    assert get_args(body_ann)[0] is getattr(Widget.schemas.bulk_create, "in_item")

tests/unit/test_bulk_response_schema.py

@@ -0,0 +1,153 @@
+from tigrbl.bindings.rest.router import _build_router
+from tigrbl.op import OpSpec
+from tigrbl.orm.tables import Base
+from tigrbl.orm.mixins import GUIDPk, BulkCapable, Replaceable
+from tigrbl.types import Column, String, App
+
+
+class Widget(Base, GUIDPk, BulkCapable, Replaceable):
+    __tablename__ = "widgets_bulk_schema"
+    name = Column(String, nullable=False)
+
+
+def _openapi_for(ops):
+    router = _build_router(Widget, [OpSpec(alias=a, target=t) for a, t in ops])
+    app = App()
+    app.include_router(router)
+    return app.openapi()
+
+
+def test_create_request_schema_is_object():
+    spec = _openapi_for([("create", "create")])
+    path = f"/{Widget.__name__.lower()}"
+    schema = spec["paths"][path]["post"]["requestBody"]["content"]["application/json"][
+        "schema"
+    ]
+    # The create handler for bulk-capable tables accepts either a single object
+    # or an array of objects. Inspect the first variant to ensure it is an
+    # object schema.
+    if "anyOf" in schema:
+        schema = schema["anyOf"][0]
+    if "$ref" in schema:
+        ref = schema["$ref"].split("/")[-1]
+        schema = spec["components"]["schemas"][ref]
+    assert schema.get("type") == "object"
+
+
+def test_bulk_create_response_schema():
+    spec = _openapi_for([("bulk_create", "bulk_create")])
+    path = f"/{Widget.__name__.lower()}"
+    ref = spec["paths"][path]["post"]["responses"]["200"]["content"][
+        "application/json"
+    ]["schema"]["$ref"]
+    assert ref.endswith("WidgetBulkCreateResponse")
+    comp = spec["components"]["schemas"]["WidgetBulkCreateResponse"]
+    assert comp["type"] == "array"
+    items_ref = comp["items"]["$ref"]
+    assert items_ref.endswith("WidgetRead")
+
+
+def test_bulk_create_request_schema_has_item_ref():
+    spec = _openapi_for([("bulk_create", "bulk_create")])
+    path = f"/{Widget.__name__.lower()}"
+    schema = spec["paths"][path]["post"]["requestBody"]["content"]["application/json"][
+        "schema"
+    ]
+    assert schema["type"] == "array"
+    items_ref = schema["items"]["$ref"]
+    assert items_ref.endswith("WidgetBulkCreateItem")
+
+
+def test_create_and_bulk_create_handlers_and_schemas_bound():
+    _ = _openapi_for(
+        [
+            ("create", "create"),
+            ("bulk_create", "bulk_create"),
+        ]
+    )
+    assert hasattr(Widget.schemas, "create")
+    assert hasattr(Widget.schemas, "bulk_create")
+    assert hasattr(Widget.handlers, "create")
+    assert hasattr(Widget.handlers, "bulk_create")
+    assert hasattr(Widget.handlers.create, "core")
+    assert hasattr(Widget.handlers.bulk_create, "core")
+
+
+def test_bulk_delete_response_schema():
+    spec = _openapi_for([("bulk_delete", "bulk_delete")])
+    path = f"/{Widget.__name__.lower()}"
+    ref = spec["paths"][path]["delete"]["responses"]["200"]["content"][
+        "application/json"
+    ]["schema"]["$ref"]
+    assert ref.endswith("WidgetBulkDeleteResponse")
+    comp = spec["components"]["schemas"]["WidgetBulkDeleteResponse"]
+    props = comp.get("properties", {})
+    assert "deleted" in props
+    assert props["deleted"]["type"] == "integer"
+
+
+def test_bulk_update_request_and_response_schemas():
+    spec = _openapi_for([("bulk_update", "bulk_update")])
+    path = f"/{Widget.__name__.lower()}"
+    # request schema
+    req_schema = spec["paths"][path]["patch"]["requestBody"]["content"][
+        "application/json"
+    ]["schema"]
+    assert req_schema["type"] == "array"
+    assert req_schema["items"]["$ref"].endswith("WidgetBulkUpdateItem")
+    # response schema
+    resp_ref = spec["paths"][path]["patch"]["responses"]["200"]["content"][
+        "application/json"
+    ]["schema"]["$ref"]
+    assert resp_ref.endswith("WidgetBulkUpdateResponse")
+    resp_comp = spec["components"]["schemas"]["WidgetBulkUpdateResponse"]
+    assert resp_comp["items"]["$ref"].endswith("WidgetRead")
+    assert "WidgetRead" in spec["components"]["schemas"]
+
+
+def test_bulk_replace_request_and_response_schemas():
+    spec = _openapi_for([("bulk_replace", "bulk_replace")])
+    path = f"/{Widget.__name__.lower()}"
+    # request schema
+    req_schema = spec["paths"][path]["put"]["requestBody"]["content"][
+        "application/json"
+    ]["schema"]
+    assert req_schema["type"] == "array"
+    assert req_schema["items"]["$ref"].endswith("WidgetBulkReplaceItem")
+    # response schema
+    resp_ref = spec["paths"][path]["put"]["responses"]["200"]["content"][
+        "application/json"
+    ]["schema"]["$ref"]
+    assert resp_ref.endswith("WidgetBulkReplaceResponse")
+    resp_comp = spec["components"]["schemas"]["WidgetBulkReplaceResponse"]
+    assert resp_comp["items"]["$ref"].endswith("WidgetRead")
+
+
+def test_bulk_merge_request_and_response_schemas():
+    spec = _openapi_for([("bulk_merge", "bulk_merge")])
+    path = f"/{Widget.__name__.lower()}"
+    # request schema
+    req_schema = spec["paths"][path]["patch"]["requestBody"]["content"][
+        "application/json"
+    ]["schema"]
+    assert req_schema["type"] == "array"
+    assert req_schema["items"]["type"] == "object"
+    # bulk merge currently returns no content in the response
+    assert "content" not in spec["paths"][path]["patch"]["responses"]["200"]
+
+
+def test_update_and_bulk_update_schema_names_do_not_collide():
+    spec = _openapi_for([("update", "update"), ("bulk_update", "bulk_update")])
+    base = f"/{Widget.__name__.lower()}"
+    update_path = f"{base}/{{item_id}}"
+    # single update schema
+    upd_ref = spec["paths"][update_path]["patch"]["requestBody"]["content"][
+        "application/json"
+    ]["schema"]["$ref"]
+    assert upd_ref.endswith("WidgetUpdateRequest")
+    # bulk update schema
+    bulk_schema = spec["paths"][base]["patch"]["requestBody"]["content"][
+        "application/json"
+    ]["schema"]
+    assert bulk_schema["type"] == "array"
+    assert bulk_schema["items"]["$ref"].endswith("WidgetBulkUpdateItem")

tests/unit/test_colspec_map_isolation.py

@@ -0,0 +1,19 @@
+from tigrbl.column import makeVirtualColumn
+
+
+class Base:
+    base = makeVirtualColumn()
+
+
+class One(Base):
+    one = makeVirtualColumn()
+
+
+class Two(Base):
+    two = makeVirtualColumn()
+
+
+def test_colspec_maps_are_isolated() -> None:
+    assert set(Base.__tigrbl_colspecs__) == {"base"}
+    assert set(One.__tigrbl_colspecs__) == {"base", "one"}
+    assert set(Two.__tigrbl_colspecs__) == {"base", "two"}

tests/unit/test_column_collect_mixins.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from tigrbl.column.mro_collect import mro_collect_columns
+from tigrbl.orm.mixins import GUIDPk
+from tigrbl.orm.tables._base import Base
+from tigrbl.specs import S, acol
+from tigrbl.types import Mapped, String
+
+
+class NameMixin:
+    name: Mapped[str] = acol(storage=S(String, nullable=False))
+
+
+class Thing(Base, GUIDPk, NameMixin):
+    __tablename__ = "thing_collect_mixins"
+
+
+def test_collect_columns_includes_mixin_fields():
+    specs = mro_collect_columns(Thing)
+    assert "id" in specs
+    assert "name" in specs

tests/unit/test_column_rest_rpc_results.py

@@ -0,0 +1,298 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from tigrbl import TigrblApi, alias_ctx
+from tigrbl.column import F, IO, S, makeColumn, makeVirtualColumn
+from tigrbl.engine.shortcuts import engine as build_engine, mem
+from tigrbl.orm.tables import Base
+from tigrbl.types import App, Integer, Mapped, String
+
+
+# Helper to bootstrap API and test client for a model
+
+
+def _setup_api(model):
+    eng = build_engine(mem(async_=False))
+    api = TigrblApi(engine=eng)
+    api.include_model(model)
+    api.initialize()
+
+    app = App()
+    app.include_router(api)
+    client = TestClient(app)
+    return api, client, eng
+
+
+@pytest.mark.parametrize("use_mapped", [True, False])
+@pytest.mark.asyncio
+async def test_make_column_only_rest_rpc(use_mapped):
+    Base.metadata.clear()
+
+    class Thing(Base):
+        __tablename__ = f"mc_only_{'m' if use_mapped else 'u'}"
+        if not use_mapped:
+            __allow_unmapped__ = True
+        if use_mapped:
+            id: Mapped[int] = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            name: Mapped[str] = makeColumn(storage=S(type_=String, nullable=False))
+        else:
+            id = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            name = makeColumn(storage=S(type_=String, nullable=False))
+
+    api, client, eng = _setup_api(Thing)
+    try:
+        with eng.session() as db:
+            created = await api.rpc_call(Thing, "create", {"name": "x"}, db=db)
+            db_read = await api.core.Thing.read({"id": created["id"]}, db=db)
+            rpc_read = await api.rpc_call(Thing, "read", {"id": created["id"]}, db=db)
+        resp = client.get(f"/{Thing.__name__.lower()}/{created['id']}")
+        assert resp.status_code == 200
+        rest_data = resp.json()
+        assert db_read == rpc_read == rest_data == {"id": created["id"], "name": "x"}
+    finally:
+        raw_eng, _ = eng.raw()
+        raw_eng.dispose()
+
+
+@pytest.mark.parametrize("use_mapped", [True, False])
+@pytest.mark.asyncio
+async def test_make_virtual_column_only_rest_rpc(use_mapped):
+    Base.metadata.clear()
+
+    class Thing(Base):
+        __tablename__ = f"mv_only_{'m' if use_mapped else 'u'}"
+        if not use_mapped:
+            __allow_unmapped__ = True
+        if use_mapped:
+            id: Mapped[int] = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            code: str = makeVirtualColumn(
+                field=F(py_type=str),
+                io=IO(out_verbs=("read",)),
+                read_producer=lambda obj, ctx: f"v-{obj.id}",
+                nullable=True,
+            )
+        else:
+            id = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            code: str = makeVirtualColumn(
+                field=F(py_type=str),
+                io=IO(out_verbs=("read",)),
+                read_producer=lambda obj, ctx: f"v-{obj.id}",
+                nullable=True,
+            )
+
+    api, client, eng = _setup_api(Thing)
+    try:
+        with eng.session() as db:
+            created = await api.rpc_call(Thing, "create", {}, db=db)
+            db_read = await api.core.Thing.read({"id": created["id"]}, db=db)
+            rpc_read = await api.rpc_call(Thing, "read", {"id": created["id"]}, db=db)
+        resp = client.get(f"/{Thing.__name__.lower()}/{created['id']}")
+        assert resp.status_code == 200
+        rest_data = resp.json()
+        assert db_read == rpc_read == rest_data == {"id": created["id"], "code": None}
+    finally:
+        raw_eng, _ = eng.raw()
+        raw_eng.dispose()
+
+
+@pytest.mark.parametrize("use_mapped", [True, False])
+@pytest.mark.asyncio
+async def test_make_column_with_alias_rest_rpc(use_mapped):
+    Base.metadata.clear()
+
+    @alias_ctx(read="fetch")
+    class Thing(Base):
+        __tablename__ = f"mc_alias_{'m' if use_mapped else 'u'}"
+        if not use_mapped:
+            __allow_unmapped__ = True
+        if use_mapped:
+            id: Mapped[int] = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            name: Mapped[str] = makeColumn(storage=S(type_=String, nullable=False))
+        else:
+            id = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            name = makeColumn(storage=S(type_=String, nullable=False))
+
+    api, client, eng = _setup_api(Thing)
+    try:
+        with eng.session() as db:
+            created = await api.rpc_call(Thing, "create", {"name": "y"}, db=db)
+            db_read = await api.core.Thing.fetch({"id": created["id"]}, db=db)
+            rpc_read = await api.rpc_call(Thing, "fetch", {"id": created["id"]}, db=db)
+        resp = client.get(f"/{Thing.__name__.lower()}/{created['id']}")
+        assert resp.status_code == 200
+        rest_data = resp.json()
+        assert db_read == rpc_read == rest_data == {"id": created["id"], "name": "y"}
+    finally:
+        raw_eng, _ = eng.raw()
+        raw_eng.dispose()
+
+
+@pytest.mark.parametrize("use_mapped", [True, False])
+@pytest.mark.asyncio
+async def test_make_virtual_column_with_aliases_rest_rpc(use_mapped):
+    Base.metadata.clear()
+
+    @alias_ctx(create="register", read="fetch")
+    class Thing(Base):
+        __tablename__ = f"mv_alias_{'m' if use_mapped else 'u'}"
+        if not use_mapped:
+            __allow_unmapped__ = True
+        if use_mapped:
+            id: Mapped[int] = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            code: str = makeVirtualColumn(
+                field=F(py_type=str),
+                io=IO(out_verbs=("read",)),
+                read_producer=lambda obj, ctx: f"v-{obj.id}",
+                nullable=True,
+            )
+        else:
+            id = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            code: str = makeVirtualColumn(
+                field=F(py_type=str),
+                io=IO(out_verbs=("read",)),
+                read_producer=lambda obj, ctx: f"v-{obj.id}",
+                nullable=True,
+            )
+
+    api, client, eng = _setup_api(Thing)
+    try:
+        with eng.session() as db:
+            created = await api.rpc_call(Thing, "register", {}, db=db)
+            db_read = await api.core.Thing.fetch({"id": created["id"]}, db=db)
+            rpc_read = await api.rpc_call(Thing, "fetch", {"id": created["id"]}, db=db)
+        resp = client.get(f"/{Thing.__name__.lower()}/{created['id']}")
+        assert resp.status_code == 200
+        rest_data = resp.json()
+        assert db_read == rpc_read == rest_data == {"id": created["id"], "code": None}
+    finally:
+        raw_eng, _ = eng.raw()
+        raw_eng.dispose()
+
+
+@pytest.mark.parametrize("use_mapped", [True, False])
+@pytest.mark.asyncio
+async def test_make_column_and_virtual_rest_rpc(use_mapped):
+    Base.metadata.clear()
+
+    class Thing(Base):
+        __tablename__ = f"both_{'m' if use_mapped else 'u'}"
+        if not use_mapped:
+            __allow_unmapped__ = True
+        if use_mapped:
+            id: Mapped[int] = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            name: Mapped[str] = makeColumn(storage=S(type_=String, nullable=False))
+            upper: str = makeVirtualColumn(
+                field=F(py_type=str),
+                io=IO(out_verbs=("read",)),
+                read_producer=lambda obj, ctx: obj.name.upper(),
+                nullable=True,
+            )
+        else:
+            id = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            name = makeColumn(storage=S(type_=String, nullable=False))
+            upper: str = makeVirtualColumn(
+                field=F(py_type=str),
+                io=IO(out_verbs=("read",)),
+                read_producer=lambda obj, ctx: obj.name.upper(),
+                nullable=True,
+            )
+
+    api, client, eng = _setup_api(Thing)
+    try:
+        with eng.session() as db:
+            created = await api.rpc_call(Thing, "create", {"name": "Ada"}, db=db)
+            db_read = await api.core.Thing.read({"id": created["id"]}, db=db)
+            rpc_read = await api.rpc_call(Thing, "read", {"id": created["id"]}, db=db)
+        resp = client.get(f"/{Thing.__name__.lower()}/{created['id']}")
+        assert resp.status_code == 200
+        rest_data = resp.json()
+        assert (
+            db_read
+            == rpc_read
+            == rest_data
+            == {
+                "id": created["id"],
+                "name": "Ada",
+                "upper": None,
+            }
+        )
+    finally:
+        raw_eng, _ = eng.raw()
+        raw_eng.dispose()
+
+
+@pytest.mark.parametrize("use_mapped", [True, False])
+@pytest.mark.asyncio
+async def test_make_column_and_virtual_with_alias_rest_rpc(use_mapped):
+    Base.metadata.clear()
+
+    @alias_ctx(create="register", read="fetch")
+    class Thing(Base):
+        __tablename__ = f"both_alias_{'m' if use_mapped else 'u'}"
+        if not use_mapped:
+            __allow_unmapped__ = True
+        if use_mapped:
+            id: Mapped[int] = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            name: Mapped[str] = makeColumn(storage=S(type_=String, nullable=False))
+            upper: str = makeVirtualColumn(
+                field=F(py_type=str),
+                io=IO(out_verbs=("read",)),
+                read_producer=lambda obj, ctx: obj.name.upper(),
+                nullable=True,
+            )
+        else:
+            id = makeColumn(
+                storage=S(type_=Integer, primary_key=True, autoincrement=True)
+            )
+            name = makeColumn(storage=S(type_=String, nullable=False))
+            upper: str = makeVirtualColumn(
+                field=F(py_type=str),
+                io=IO(out_verbs=("read",)),
+                read_producer=lambda obj, ctx: obj.name.upper(),
+                nullable=True,
+            )
+
+    api, client, eng = _setup_api(Thing)
+    try:
+        with eng.session() as db:
+            created = await api.rpc_call(Thing, "register", {"name": "Bob"}, db=db)
+            db_read = await api.core.Thing.fetch({"id": created["id"]}, db=db)
+            rpc_read = await api.rpc_call(Thing, "fetch", {"id": created["id"]}, db=db)
+        resp = client.get(f"/{Thing.__name__.lower()}/{created['id']}")
+        assert resp.status_code == 200
+        rest_data = resp.json()
+        assert (
+            db_read
+            == rpc_read
+            == rest_data
+            == {
+                "id": created["id"],
+                "name": "Bob",
+                "upper": None,
+            }
+        )
+    finally:
+        raw_eng, _ = eng.raw()
+        raw_eng.dispose()

tests/unit/test_column_table_orm_binding.py

@@ -0,0 +1,51 @@
+from tigrbl.column import F, S, acol, vcol
+from tigrbl.orm.tables import Base
+from tigrbl.types import Integer, Mapped, String
+from sqlalchemy import create_engine, select
+from sqlalchemy.orm import Session
+
+
+def test_acol_vcol_bind_to_table_and_orm() -> None:
+    """`acol`/`vcol` integrate with table metadata and ORM instances."""
+
+    Base.metadata.clear()
+    engine = create_engine("sqlite:///:memory:")
+
+    class User(Base):
+        __tablename__ = "users"
+        id: Mapped[int] = acol(
+            storage=S(type_=Integer, primary_key=True, autoincrement=True)
+        )
+        name: Mapped[str] = acol(storage=S(type_=String, nullable=False))
+        upper: str = vcol(
+            field=F(py_type=str),
+            read_producer=lambda obj, ctx: obj.name.upper(),
+            nullable=True,
+        )
+
+    Base.metadata.create_all(engine)
+
+    # Table contains columns for both persisted and virtual specs
+    assert set(User.__table__.c.keys()) == {"id", "name", "upper"}
+
+    # Spec map tracks both persisted and virtual columns
+    assert set(User.__tigrbl_cols__.keys()) == {"id", "name", "upper"}
+    assert User.__tigrbl_cols__["upper"].storage is None
+
+    with Session(engine) as session:
+        user = User(name="Alice")
+        session.add(user)
+        session.commit()
+        session.refresh(user)
+
+        # persisted column round-trips through the DB
+        result = session.execute(select(User.name)).scalar_one()
+        assert result == "Alice"
+
+        # DB column for virtual spec defaults to NULL
+        raw = session.execute(select(User.upper)).scalar_one()
+        assert raw is None
+
+        # virtual column value produced dynamically
+        spec = User.__tigrbl_cols__["upper"]
+        assert spec.read_producer(user, {}) == "ALICE"

tests/unit/test_config_dataclass_none.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+from tigrbl.config import resolve_cfg
+
+
+def test_dataclass_none_fields_do_not_override_defaults() -> None:
+    @dataclass
+    class AppSpec:
+        trace: dict | None = None
+
+    cfg = resolve_cfg(appspec=AppSpec())
+    assert cfg.trace == {"enabled": True}