hajimi-sqlalchemy 0.0.3__tar.gz → 0.2.0__tar.gz

{hajimi_sqlalchemy-0.0.3 → hajimi_sqlalchemy-0.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: hajimi-sqlalchemy
-Version: 0.0.3
-Requires-Python: >=3.14
+Version: 0.2.0
+Requires-Python: >=3.12
 License-File: LICENSE
-Requires-Dist: hajimi-core>=0.1.0
+Requires-Dist: hajimi-core>=0.4.0
 Requires-Dist: sqlalchemy[asyncio,postgresql-psycopg]>=2.0.49
 Dynamic: license-file

{hajimi_sqlalchemy-0.0.3 → hajimi_sqlalchemy-0.2.0}/README.md

@@ -1,4 +1,4 @@
-# hajimi-core
+# hajimi-sqlalchemy
 
 ## Install
 

{hajimi_sqlalchemy-0.0.3 → hajimi_sqlalchemy-0.2.0}/hajimi_sqlalchemy/__init__.py

@@ -1,4 +1,5 @@
 from .base import BaseModel
 from .config import HajimiSQLAlchemyConfig
 from .dependencies import SessionDep
+from .models import collect_plugin_models
 from .plugin import HajimiSQLAlchemyPlugin

hajimi_sqlalchemy-0.2.0/hajimi_sqlalchemy/columns.py

@@ -0,0 +1,26 @@
+import secrets
+from typing import Any
+
+from sqlalchemy import DateTime, func
+from sqlalchemy.orm import MappedColumn, mapped_column
+
+
+def id_column() -> MappedColumn[Any]:
+    return mapped_column(primary_key=True, autoincrement=True, nullable=False)
+
+
+def external_id_column() -> MappedColumn[Any]:
+    return mapped_column(
+        default=lambda: secrets.token_urlsafe(9),
+        unique=True,
+        nullable=False,
+        index=True,
+    )
+
+
+def created_at_column() -> MappedColumn[Any]:
+    return mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+
+def updated_at_column() -> MappedColumn[Any]:
+    return mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)

hajimi_sqlalchemy-0.2.0/hajimi_sqlalchemy/dependencies.py

@@ -0,0 +1,16 @@
+from typing import Annotated, AsyncGenerator
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from hajimi_core import AppStateDep
+from .plugin import HajimiSQLAlchemyPlugin
+
+
+async def get_session(app_state: AppStateDep) -> AsyncGenerator[AsyncSession, None]:
+    plugin: HajimiSQLAlchemyPlugin = app_state[HajimiSQLAlchemyPlugin.__name__]
+    async with plugin.session_maker.begin() as session:
+        yield session
+
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]

hajimi_sqlalchemy-0.2.0/hajimi_sqlalchemy/models.py

@@ -0,0 +1,91 @@
+"""SQLAlchemy 模型注册相关的工具:让 plugin 显式声明自己拥有的 models。
+
+背景:
+- SQLAlchemy 的 DeclarativeBase 只在 model 类**被定义**时,把 Table 挂到
+  ``BaseModel.metadata`` 上。如果 ``env.py`` / 任何消费方没 import 该类,
+  autogenerate 就看不到这张表。
+- 历史上靠 plugin 模块顶部的 ``from .models import X`` 副作用顺带触发注册,
+  这种隐式契约很容易被重构(lazy import、TYPE_CHECKING 分支)静默打破。
+
+契约:
+- 任何持有 SQLAlchemy 模型的 plugin 在类上声明
+  ``models: tuple[type[BaseModel], ...] = ()``。
+- alembic / lifespan / 任何需要让 SQLAlchemy 看到这些表的入口,统一调用
+  ``collect_plugin_models(plugins_or_classes)`` 来触发注册并拿到类列表。
+
+接口:
+- ``collect_plugin_models`` 接受 plugin **类**或**实例**(duck-typing),
+  提取 ``models`` 属性、对每个类做 ``import_module(__module__)`` 触发
+  SQLAlchemy 注册、按首次出现顺序去重,返回 ``tuple[type[BaseModel], ...]``。
+"""
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, Iterable
+
+from .base import BaseModel
+
+
+def collect_plugin_models(
+        plugins_or_classes: Iterable[Any],
+) -> tuple[type[BaseModel], ...]:
+    """收集所有 plugin 声明的 models,并触发它们注册到 ``BaseModel.metadata``。
+
+    参数:
+        plugins_or_classes:plugin **类**或**实例**的可迭代对象。空集合返回空 tuple。
+
+    返回:
+        按首次出现顺序去重的 ``BaseModel`` 子类 tuple。同一 plugin 重复出现
+        只计一次;同一 model 被多个 plugin 声明也只计一次。
+
+    抛出:
+        TypeError:任一 plugin 的 ``models`` 不是 tuple,或其中的元素不是
+            ``BaseModel`` 子类。契约违反必须显式失败,而不是静默跳过。
+
+    实现说明:
+        SQLAlchemy 在 model 类**定义时**就把 Table 挂到 ``BaseModel.metadata``。
+        本函数对每个返回的 model 做一次 ``import_module(model.__module__)``,
+        以防调用方在拿到类引用之前还没触达模块(典型场景:alembic env.py 不
+        通过 plugin 模块的 import 副作用注册)。已加载模块的 import 是幂等的。
+    """
+    seen: dict[type, BaseModel] = {}  # 借用 dict 保持插入顺序去重
+    for plugin in plugins_or_classes:
+        for model in _extract_models(plugin):
+            if model in seen:
+                continue
+            _ensure_registered(model)
+            seen[model] = model
+    return tuple(seen)
+
+
+def _extract_models(plugin: Any) -> tuple[type[BaseModel], ...]:
+    """读取单个 plugin(类或实例)上的 ``models`` 字段并校验元素类型。"""
+    name = _plugin_name(plugin)
+    raw = getattr(plugin, 'models', ())
+    if raw is None:
+        return ()
+    if not isinstance(raw, tuple):
+        raise TypeError(
+            f'{name}.models must be a tuple, got {type(raw).__name__}'
+        )
+    result: list[type[BaseModel]] = []
+    for m in raw:
+        if not (isinstance(m, type) and issubclass(m, BaseModel)):
+            raise TypeError(
+                f'{name}.models contains {m!r}, '
+                f'which is not a BaseModel subclass'
+            )
+        result.append(m)
+    return tuple(result)
+
+
+def _plugin_name(plugin: Any) -> str:
+    """取 plugin 的可读名字:类取 ``__name__``,实例取 ``type(self).__name__``。"""
+    if isinstance(plugin, type):
+        return plugin.__name__
+    return type(plugin).__name__
+
+
+def _ensure_registered(model: type[BaseModel]) -> None:
+    """import 模型所在模块,确保 SQLAlchemy 把 Table 注册到 ``BaseModel.metadata``。"""
+    import_module(model.__module__)

hajimi_sqlalchemy-0.2.0/hajimi_sqlalchemy/plugin.py

@@ -0,0 +1,88 @@
+from contextlib import AbstractAsyncContextManager
+
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+from hajimi_core.state import APP_STATE_KEY
+from .config import HajimiSQLAlchemyConfig
+
+
+class HajimiSQLAlchemyPlugin:
+    dependencies = ()
+
+    def __init__(self, config: HajimiSQLAlchemyConfig) -> None:
+        self._config = config
+        self._engine: AsyncEngine | None = None
+        self._session_maker: async_sessionmaker[AsyncSession] | None = None
+        # 启动阶段共享 session:在 startup() 中开启、在 finalize_startup() 中 commit
+        self._startup_session_cm: AbstractAsyncContextManager[AsyncSession] | None = None
+        self._startup_session: AsyncSession | None = None
+
+    @property
+    def session_maker(self) -> async_sessionmaker[AsyncSession]:
+        if not isinstance(self._session_maker, async_sessionmaker):
+            raise RuntimeError(
+                'HajimiSQLAlchemyPlugin.session_maker is unavailable: '
+                'startup() has not been called or shutdown() has already run.'
+            )
+
+        return self._session_maker
+
+    @property
+    def startup_session(self) -> AsyncSession:
+        """启动阶段共享的 ``AsyncSession``,供依赖本插件的 plugin 在自己的 ``startup`` 中使用。
+
+        仅在所有 plugin 的 ``startup`` 都成功跑完之前可用;
+        一旦 ``finalize_startup()`` 被调用、session 已被 commit/close,该属性即抛错。
+        """
+        if self._startup_session is None:
+            raise RuntimeError(
+                'HajimiSQLAlchemyPlugin.startup_session is unavailable: '
+                'startup() has not been called or finalize_startup() has already run.'
+            )
+
+        return self._startup_session
+
+    async def startup(self, app: FastAPI) -> None:
+        self._engine = create_async_engine(
+            url=self._config.url,
+            echo=self._config.echo,
+            pool_size=self._config.pool_size,
+            max_overflow=self._config.max_overflow,
+            pool_timeout=self._config.pool_timeout,
+            pool_recycle=self._config.pool_recycle,
+            pool_pre_ping=True,
+            connect_args={'connect_timeout': 6},
+        )
+        # 局部变量:让 PyCharm 从右侧赋值正确推断类型,绕过 self 字段的 Optional 标注
+        session_maker = async_sessionmaker(self._engine)
+        self._session_maker = session_maker
+
+        # 启动阶段事务:手动 enter begin(),所有依赖方共享同一个 AsyncSession;
+        # finalize_startup() 时 __aexit__(None, None, None) 触发 commit。
+        startup_cm = session_maker.begin()
+        self._startup_session_cm = startup_cm
+        self._startup_session = await startup_cm.__aenter__()
+
+        app.state[APP_STATE_KEY][type(self).__name__] = self
+
+    async def finalize_startup(self, app: FastAPI) -> None:
+        # 没开过事务就直接返回(例如未经过 startup() 直接调用)
+        if self._startup_session_cm is None:
+            return
+        # 正常退出 -> commit
+        await self._startup_session_cm.__aexit__(None, None, None)
+        self._startup_session_cm = None
+        self._startup_session = None
+
+    async def shutdown(self, app: FastAPI) -> None:
+        # 清空启动阶段 session 引用(若仍持有 cm,engine dispose 会兜底回滚事务)
+        self._startup_session = None
+        self._startup_session_cm = None
+        if self._session_maker is not None:
+            self._session_maker = None
+        if self._engine is not None:
+            await self._engine.dispose()
+            self._engine = None
+
+        app.state[APP_STATE_KEY].pop(type(self).__name__, None)

hajimi_sqlalchemy-0.2.0/hajimi_sqlalchemy/utils.py

@@ -0,0 +1,12 @@
+from typing import TypeVar
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+T = TypeVar('T')
+
+
+async def add_and_flush(session: AsyncSession, model: T) -> T:
+    session.add(model)
+    await session.flush([model])
+
+    return model

{hajimi_sqlalchemy-0.0.3 → hajimi_sqlalchemy-0.2.0}/hajimi_sqlalchemy.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: hajimi-sqlalchemy
-Version: 0.0.3
-Requires-Python: >=3.14
+Version: 0.2.0
+Requires-Python: >=3.12
 License-File: LICENSE
-Requires-Dist: hajimi-core>=0.1.0
+Requires-Dist: hajimi-core>=0.4.0
 Requires-Dist: sqlalchemy[asyncio,postgresql-psycopg]>=2.0.49
 Dynamic: license-file

{hajimi_sqlalchemy-0.0.3 → hajimi_sqlalchemy-0.2.0}/hajimi_sqlalchemy.egg-info/SOURCES.txt

@@ -3,16 +3,24 @@ README.md
 pyproject.toml
 hajimi_sqlalchemy/__init__.py
 hajimi_sqlalchemy/base.py
+hajimi_sqlalchemy/columns.py
 hajimi_sqlalchemy/config.py
 hajimi_sqlalchemy/dependencies.py
+hajimi_sqlalchemy/models.py
 hajimi_sqlalchemy/plugin.py
+hajimi_sqlalchemy/utils.py
 hajimi_sqlalchemy.egg-info/PKG-INFO
 hajimi_sqlalchemy.egg-info/SOURCES.txt
 hajimi_sqlalchemy.egg-info/dependency_links.txt
 hajimi_sqlalchemy.egg-info/requires.txt
 hajimi_sqlalchemy.egg-info/top_level.txt
 tests/test_base.py
+tests/test_columns.py
 tests/test_config.py
 tests/test_dependencies.py
+tests/test_dependencies_extras.py
 tests/test_init.py
-tests/test_plugin.py
+tests/test_models.py
+tests/test_plugin.py
+tests/test_plugin_extras.py
+tests/test_utils.py

{hajimi_sqlalchemy-0.0.3 → hajimi_sqlalchemy-0.2.0}/hajimi_sqlalchemy.egg-info/requires.txt

@@ -1,2 +1,2 @@
-hajimi-core>=0.1.0
+hajimi-core>=0.4.0
 sqlalchemy[asyncio,postgresql-psycopg]>=2.0.49

{hajimi_sqlalchemy-0.0.3 → hajimi_sqlalchemy-0.2.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hajimi-sqlalchemy"
-version = "0.0.3"
-requires-python = ">=3.14"
+version = "0.2.0"
+requires-python = ">=3.12"
 dependencies = [
-    "hajimi-core>=0.1.0",
+    "hajimi-core>=0.4.0",
     "sqlalchemy[asyncio,postgresql-psycopg]>=2.0.49",
 ]
 
@@ -22,3 +22,6 @@ dev = [
 asyncio_mode = "auto"
 pythonpath = ["."]
 testpaths = ["tests"]
+
+[tool.uv.sources]
+hajimi-core = { workspace = true }

hajimi_sqlalchemy-0.2.0/tests/test_columns.py

@@ -0,0 +1,308 @@
+"""Tests for hajimi_sqlalchemy.columns helpers.
+
+覆盖四个工厂:
+* ``id_column`` —— 主键 + 自增 + 非空 + Integer;
+* ``external_id_column`` —— 默认生成 URL-safe token + unique + index + 非空;
+* ``created_at_column`` —— tz-aware DateTime + server_default=now() + 非空;
+* ``updated_at_column`` —— tz-aware DateTime + server_default=now() + onupdate=now() + 非空。
+
+按公开 API 表达:不直接读私有属性,通过 ``__table__.c.<col>`` 观察落到
+SQLAlchemy ``Column`` 上的契约(nullable / default / type / index)。
+"""
+from sqlalchemy import DateTime, Integer
+from sqlalchemy.orm import Mapped, MappedColumn
+
+from hajimi_sqlalchemy.base import BaseModel
+from hajimi_sqlalchemy.columns import (
+    created_at_column,
+    external_id_column,
+    id_column,
+    updated_at_column,
+)
+
+
+# ---------------------------------------------------------------------------
+# id_column
+# ---------------------------------------------------------------------------
+
+
+def test_id_column_returns_mapped_column_instance():
+    """``id_column()`` must hand back a SQLAlchemy ``MappedColumn`` descriptor."""
+
+    result = id_column()
+
+    assert isinstance(result, MappedColumn)
+
+
+def test_id_column_is_marked_as_primary_key():
+    """When attached to a model, the column produced by ``id_column()`` is the primary key."""
+
+    class _PkItem(BaseModel):
+        __tablename__ = 'items_for_id_column_pk'
+        id: Mapped[int] = id_column()
+
+    assert _PkItem.__table__.c.id.primary_key is True
+
+
+def test_id_column_is_not_nullable():
+    """``nullable=False`` must reach the generated table column."""
+
+    class _NullableItem(BaseModel):
+        __tablename__ = 'items_for_id_column_nullable'
+        id: Mapped[int] = id_column()
+
+    assert _NullableItem.__table__.c.id.nullable is False
+
+
+def test_id_column_is_autoincrement():
+    """``autoincrement=True`` must be preserved on the generated table column."""
+
+    class _AutoincItem(BaseModel):
+        __tablename__ = 'items_for_id_column_autoincrement'
+        id: Mapped[int] = id_column()
+
+    assert _AutoincItem.__table__.c.id.autoincrement is True
+
+
+def test_id_column_defaults_to_integer_type():
+    """No explicit type is given, so the column must default to SQLAlchemy ``Integer``."""
+
+    class _TypedItem(BaseModel):
+        __tablename__ = 'items_for_id_column_type'
+        id: Mapped[int] = id_column()
+
+    assert isinstance(_TypedItem.__table__.c.id.type, Integer)
+
+
+def test_id_column_is_the_only_column_on_the_model():
+    """Attaching ``id_column()`` to a model produces exactly one column named ``id``."""
+
+    class _SingleColItem(BaseModel):
+        __tablename__ = 'items_for_id_column_only'
+        id: Mapped[int] = id_column()
+
+    assert list(_SingleColItem.__table__.c.keys()) == ['id']
+
+
+def test_id_column_callable_produces_independent_instances():
+    """Each call to ``id_column()`` must return a fresh ``MappedColumn`` instance.
+
+    Reusing a single ``MappedColumn`` across multiple models would cause
+    SQLAlchemy's declarative scan to complain about an attribute being
+    assigned to more than one class.
+    """
+
+    first = id_column()
+    second = id_column()
+
+    assert first is not second
+
+
+# ---------------------------------------------------------------------------
+# external_id_column
+# ---------------------------------------------------------------------------
+
+
+def test_external_id_column_returns_mapped_column_instance():
+    """``external_id_column()`` 必须返回 SQLAlchemy ``MappedColumn`` 描述符。"""
+
+    result = external_id_column()
+
+    assert isinstance(result, MappedColumn)
+
+
+def test_external_id_column_is_unique():
+    """生成的列必须 ``unique=True``,用作对外暴露的标识时不容许重复。"""
+
+    class _ExternalIdUnique(BaseModel):
+        __tablename__ = 'items_for_external_id_unique'
+        id: Mapped[int] = id_column()
+        external_id: Mapped[str] = external_id_column()
+
+    assert _ExternalIdUnique.__table__.c.external_id.unique is True
+
+
+def test_external_id_column_is_not_nullable():
+    """``external_id`` 必须 ``nullable=False``,确保每行都有对外 ID。"""
+
+    class _ExternalIdNullable(BaseModel):
+        __tablename__ = 'items_for_external_id_nullable'
+        id: Mapped[int] = id_column()
+        external_id: Mapped[str] = external_id_column()
+
+    assert _ExternalIdNullable.__table__.c.external_id.nullable is False
+
+
+def test_external_id_column_is_indexed():
+    """``external_id`` 必须 ``index=True``,外部查询通常按它查找,需要索引支撑。"""
+
+    class _ExternalIdIndexed(BaseModel):
+        __tablename__ = 'items_for_external_id_indexed'
+        id: Mapped[int] = id_column()
+        external_id: Mapped[str] = external_id_column()
+
+    assert _ExternalIdIndexed.__table__.c.external_id.index is True
+
+
+def test_external_id_column_default_attaches_a_callable_default():
+    """``default`` 必须落到 Column 上为一个可调用 default,触发时产出 token。
+
+    通过 ``__table__.c.external_id.default`` 观察:是 ``CallableColumnDefault``
+    类型,并且 ``is_callable`` 标记为 True,确保 ORM 端会在 INSERT 时调用它。
+    """
+
+    class _ExternalIdDefault(BaseModel):
+        __tablename__ = 'items_for_external_id_default'
+        id: Mapped[int] = id_column()
+        external_id: Mapped[str] = external_id_column()
+
+    col_default = _ExternalIdDefault.__table__.c.external_id.default
+    # ``CallableColumnDefault.is_callable`` 是公开属性,直接断言即可
+    assert col_default is not None
+    assert col_default.is_callable is True
+
+
+def test_external_id_column_default_callable_produces_non_empty_urlsafe_string():
+    """``default`` 触发后必须产出非空 URL-safe 字符串。
+
+    通过 ``col.default.arg(ctx)`` 调用 —— SQLAlchemy 把原始 lambda 包装成
+    接受 ``ctx`` 参数的可调用对象,这就是 ORM 端 INSERT 时实际调用的契约。
+    """
+
+    mc = external_id_column()
+    col_default = mc.column.default
+
+    assert col_default.is_callable is True
+    value = col_default.arg(None)
+    assert isinstance(value, str)
+    assert value != ''
+
+
+def test_external_id_column_default_values_are_highly_unique():
+    """连续触发默认生成器应当产出几乎不重复的 token,避免外部 ID 撞车。
+
+    抽 50 次,``secrets.token_urlsafe(9)`` 输出长度约 12 字符,
+    碰撞概率 ≈ 50² / 2^72 ≈ 6.8e-19,实际不可能撞码。
+    """
+
+    mc = external_id_column()
+    col_default = mc.column.default
+
+    samples = {col_default.arg(None) for _ in range(50)}
+
+    assert len(samples) == 50
+
+
+def test_external_id_column_callable_produces_independent_instances():
+    """Each call to ``external_id_column()`` must return a fresh ``MappedColumn`` instance.
+
+    Reusing a single ``MappedColumn`` across multiple models would cause
+    SQLAlchemy's declarative scan to complain about an attribute being
+    assigned to more than one class.
+    """
+
+    first = external_id_column()
+    second = external_id_column()
+
+    assert first is not second
+
+
+# ---------------------------------------------------------------------------
+# created_at_column
+# ---------------------------------------------------------------------------
+
+
+def test_created_at_column_returns_mapped_column_instance():
+    """``created_at_column()`` 必须返回 SQLAlchemy ``MappedColumn`` 描述符。"""
+
+    result = created_at_column()
+
+    assert isinstance(result, MappedColumn)
+
+
+def test_created_at_column_is_timezone_aware_datetime():
+    """生成的列类型必须是 ``DateTime(timezone=True)``(避开 naive datetime 隐式转换坑)。"""
+
+    class _CreatedAtItem(BaseModel):
+        __tablename__ = 'items_for_created_at_type'
+        id: Mapped[int] = id_column()
+        created_at = created_at_column()
+
+    assert isinstance(_CreatedAtItem.__table__.c.created_at.type, DateTime)
+    assert _CreatedAtItem.__table__.c.created_at.type.timezone is True
+
+
+def test_created_at_column_has_server_default_now():
+    """``created_at`` 必须有 ``server_default=func.now()``,由 DB 端兜底写入。"""
+
+    class _CreatedAtDefault(BaseModel):
+        __tablename__ = 'items_for_created_at_default'
+        id: Mapped[int] = id_column()
+        created_at = created_at_column()
+
+    # server_default 在 ORM 层映射为 ``FetchedValue`` / ``ClauseElement``,断言非 None 即可。
+    assert _CreatedAtDefault.__table__.c.created_at.server_default is not None
+
+
+def test_created_at_column_is_not_nullable():
+    """``created_at`` 必须 ``nullable=False``,确保每行有创建时间戳。"""
+
+    class _CreatedAtNullable(BaseModel):
+        __tablename__ = 'items_for_created_at_nullable'
+        id: Mapped[int] = id_column()
+        created_at = created_at_column()
+
+    assert _CreatedAtNullable.__table__.c.created_at.nullable is False
+
+
+# ---------------------------------------------------------------------------
+# updated_at_column
+# ---------------------------------------------------------------------------
+
+
+def test_updated_at_column_returns_mapped_column_instance():
+    """``updated_at_column()`` 必须返回 SQLAlchemy ``MappedColumn`` 描述符。"""
+
+    result = updated_at_column()
+
+    assert isinstance(result, MappedColumn)
+
+
+def test_updated_at_column_is_timezone_aware_datetime():
+    """``updated_at`` 必须 tz-aware,与 ``created_at`` 对齐,避免时区漂移。"""
+
+    class _UpdatedAtItem(BaseModel):
+        __tablename__ = 'items_for_updated_at_type'
+        id: Mapped[int] = id_column()
+        updated_at = updated_at_column()
+
+    assert isinstance(_UpdatedAtItem.__table__.c.updated_at.type, DateTime)
+    assert _UpdatedAtItem.__table__.c.updated_at.type.timezone is True
+
+
+def test_updated_at_column_has_server_default_and_onupdate():
+    """``updated_at`` 必须同时有 ``server_default=func.now()`` + ``onupdate=func.now()``:
+
+    * server_default:新建行时 DB 端兜底写入;
+    * onupdate:任何 UPDATE 语句触发时由 ORM 端写新值(无论是否在 SET 列表里)。
+    """
+
+    class _UpdatedAtHooks(BaseModel):
+        __tablename__ = 'items_for_updated_at_hooks'
+        id: Mapped[int] = id_column()
+        updated_at = updated_at_column()
+
+    col = _UpdatedAtHooks.__table__.c.updated_at
+    assert col.server_default is not None
+    assert col.onupdate is not None
+
+
+def test_updated_at_column_is_not_nullable():
+    """``updated_at`` 必须 ``nullable=False``,确保每行有更新时间戳。"""
+
+    class _UpdatedAtNullable(BaseModel):
+        __tablename__ = 'items_for_updated_at_nullable'
+        id: Mapped[int] = id_column()
+        updated_at = updated_at_column()
+
+    assert _UpdatedAtNullable.__table__.c.updated_at.nullable is False

hajimi_sqlalchemy-0.2.0/tests/test_dependencies.py

@@ -0,0 +1,35 @@
+"""Tests for hajimi_sqlalchemy.dependencies."""
+
+import typing
+from types import SimpleNamespace
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from hajimi_sqlalchemy.dependencies import SessionDep, get_session
+from hajimi_sqlalchemy.plugin import HajimiSQLAlchemyPlugin
+
+
+async def test_get_session_yields_session_and_finishes(fake_session, fake_session_factory):
+    """``get_session`` yields the session from the registered plugin's session maker."""
+    app_state = {
+        HajimiSQLAlchemyPlugin.__name__: SimpleNamespace(
+            session_maker=fake_session_factory,
+        ),
+    }
+    gen = get_session(app_state)
+
+    session = await gen.__anext__()
+    assert session is fake_session
+
+    with pytest.raises(StopAsyncIteration):
+        await gen.__anext__()
+
+
+def test_session_dep_is_annotated_async_session():
+    """``SessionDep`` is an ``Annotated`` alias whose first type-arg is ``AsyncSession``."""
+    origin = typing.get_origin(SessionDep)
+    args = typing.get_args(SessionDep)
+
+    assert origin is not None
+    assert args[0] is AsyncSession