ferro-orm 0.12.0__tar.gz → 0.12.2__tar.gz

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/AGENTS.md

@@ -90,7 +90,8 @@ If you add a new schema feature (e.g. partial indexes, exclusion constraints):
    numbered list above.
 2. Implement it in **both** the Alembic and Rust paths in the same PR.
 3. Add a parity test that asserts the names match.
-4. Add a regression entry to `CHANGELOG.md`.
+4. Do not edit `CHANGELOG.md` manually — release tooling records entries at
+   release time (see I-11).
 
 ---
 
@@ -276,3 +277,21 @@ Rules:
   updates are complete before merge.
 - AI agents and human contributors follow the same requirement. If issue status
   closure is missing, the PR is not done.
+
+---
+
+## I-11: Do not edit CHANGELOG.md manually
+
+`CHANGELOG.md` is updated automatically by the release workflow (semantic
+release / release tooling). Agents and contributors must **not** add,
+reorder, or edit changelog entries in feature, bugfix, or docs PRs.
+
+What to do instead:
+
+- Describe user-visible changes in the PR title and body.
+- Rely on conventional commit messages and the release process to populate
+  `CHANGELOG.md` after merge.
+
+If release tooling fails to capture a change, fix the release configuration or
+commit message conventions — do not patch `CHANGELOG.md` by hand in ordinary
+PRs.

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/CHANGELOG.md

@@ -1,6 +1,23 @@
 # CHANGELOG
 
 
+## v0.12.2 (2026-06-23)
+
+### Bug Fixes
+
+- Cross-context session teardown (Fixes #123) ([#127](https://github.com/syn54x/ferro-orm/pull/127),
+  [`6b9ae13`](https://github.com/syn54x/ferro-orm/commit/6b9ae1332becef88f14bdb4beae1d24e3a4104cd))
+
+
+## v0.12.1 (2026-06-23)
+
+### Bug Fixes
+
+- Stop framework predicate warnings and bind unnamed sessions to default
+  ([#124](https://github.com/syn54x/ferro-orm/pull/124),
+  [`66b92d8`](https://github.com/syn54x/ferro-orm/commit/66b92d8b691a1ad806691b9841bcbaf93c78f691))
+
+
 ## v0.12.0 (2026-06-23)
 
 ### Documentation

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/Cargo.lock

@@ -288,7 +288,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.12.0"
+version = "0.12.2"
 dependencies = [
  "dashmap",
  "ferro-migrate",

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/ferro-schema-ir", "crates/ferro-migrate"]
 
 [package]
 name = "ferro"
-version = "0.12.0"
+version = "0.12.2"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.12.0
+Version: 0.12.2
 Requires-Dist: pydantic>=2.0
 Requires-Dist: alembic>=1.18.1 ; extra == 'alembic'
 Requires-Dist: sqlalchemy>=2.0.46 ; extra == 'alembic'

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/docs/pages/api/connection.md

@@ -2,6 +2,8 @@
 
 Functions for managing database connections and the global model registry. `connect()` registers a (optionally named) connection pool; `reset_engine()` tears everything down; the registry helpers control schema creation and the identity map. Sessionized routing is exposed via `ferro.engines.session(name)` / `ferro.Session`. See the [Connections & Databases guide](../guide/connections.md).
 
+::: ferro.Session
+
 ::: ferro.connect
 
 ::: ferro.PoolConfig

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/docs/pages/guide/connections.md

@@ -114,6 +114,37 @@ async with ferro.engines.session("analytics") as s:
 
 Inside an active session context, convenience APIs (`User.all()`, `User.where(...)`, `ferro.execute(...)`) automatically bind to that session's connection.
 
+### Request-scoped sessions
+
+For short units of work (HTTP handlers, scripts, tests), use `async with`:
+
+```python
+async with ferro.engines.session("analytics"):
+    rows = await User.where(lambda t: t.active == True).all()  # noqa: E712
+```
+
+### Long-lived sessions (GUI, app lifecycle)
+
+When startup and shutdown run in different asyncio tasks (for example Textual `on_mount` / `on_unmount`), open a session handle at startup and close it explicitly at shutdown:
+
+```python
+class App:
+    async def on_mount(self) -> None:
+        self.session = ferro.engines.session("default")
+        await self.session.__aenter__()
+
+    async def on_unmount(self) -> None:
+        await self.session.close()
+```
+
+`Session.close()` is safe across asyncio contexts and idempotent. Prefer explicit `session=` routing when ambient context may be unavailable in the closing task.
+
+After a cross-context close, the enter task may still hold a stale ambient session object until a new session is opened; ambient operations then raise `RuntimeError` with a session-closed message (including when `using=` names another connection). If nested sessions are open, close inner sessions from the same task or via cross-context `close()` before closing the outer handle in the original task.
+
+Operations on a closed session handle (ambient or explicit `session=`) raise `RuntimeError` rather than falling back to legacy default routing.
+
+`ferro.reset_engine()` tears down **all** connections and is intended for test isolation — not per-session app lifecycle teardown.
+
 Legacy implicit default-connection routing (calling unqualified operations outside a session) is still temporarily supported for compatibility, but now emits a deprecation warning and is on the `v0.14.0` removal track.
 Follow [Migrating to v0.12.0](../howto/migrating-to-v0-12-0.md) to remove these legacy call sites during the compatibility window.
 

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/docs/pages/howto/migrating-to-v0-12-0.md

@@ -72,6 +72,10 @@ active session relied on implicit default-connection routing. That fallback is
 deprecated. Wrap request- or task-scoped work in a session so routing, the
 identity map, and transactions are explicit and isolated under concurrency.
 
+After a single unnamed `connect(dsn)`, `async with ferro.engines.session()` (no
+argument) binds to that default connection — you do not need to pass
+`"default"` explicitly.
+
 === "Before (deprecated)"
 
     ```python

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ferro-orm"
-version = "0.12.0"
+version = "0.12.2"
 description = "A high-performance, Rust-backed ORM for Python."
 readme = "README.md"
 authors = [

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/src/ferro/_core.pyi

@@ -160,7 +160,7 @@ async def begin_transaction(
 async def commit_transaction(tx_id: str, session_id: Optional[str] = None) -> None: ...
 def transaction_connection_name(tx_id: str, session_id: Optional[str] = None) -> str: ...
 async def rollback_transaction(tx_id: str, session_id: Optional[str] = None) -> None: ...
-def open_session(using: Optional[str] = None) -> str: ...
+def open_session(using: Optional[str] = None) -> tuple[str, str]: ...
 def close_session(session_id: str) -> None: ...
 async def raw_execute(
     sql: str,

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/src/ferro/models.py

@@ -31,7 +31,7 @@ from ._core import (
 from .base import ForeignKey, foreign_key_allows_none
 from .exceptions import ModelDoesNotExist
 from .metaclass import ModelMetaclass
-from .query import Query, QueryNode
+from .query import Predicate, Query, QueryNode
 from .state import (
     _CURRENT_TRANSACTION,
     _CURRENT_TRANSACTION_CONNECTION,
@@ -43,6 +43,11 @@ from .state import (
 _FERRO_CONNECTION_ATTR = "__ferro_connection_name"
 
 
+def _field_eq(field_name: str, value: Any) -> Predicate[Any]:
+    """Build a lambda predicate for dynamic field equality without operator style."""
+    return lambda t, f=field_name, v=value: getattr(t, f) == v
+
+
 def _transaction_or_using(
     using: str | None, session: "Session | None"
 ) -> tuple[str | None, str | None, str | None]:
@@ -289,12 +294,10 @@ class Model(BaseModel, metaclass=ModelMetaclass):
 
         if pk_val is not None:
             name = self.__class__.__name__
-            query = self.__class__.where(
-                getattr(self.__class__, pk_field_name) == pk_val
-            )
+            query = self.__class__.where(_field_eq(pk_field_name, pk_val))
             if operation_using is not None:
                 query = Query(self.__class__, using=operation_using).where(
-                    getattr(self.__class__, pk_field_name) == pk_val
+                    _field_eq(pk_field_name, pk_val)
                 )
             await query.delete()
             evict_instance(
@@ -391,7 +394,9 @@ class Model(BaseModel, metaclass=ModelMetaclass):
         if pk_field_name is None:
             raise RuntimeError(f"Model {cls.__name__} does not define a primary key")
 
-        instance = await cls.where(getattr(cls, pk_field_name) == pk, session=session).first()
+        instance = await cls.where(
+            _field_eq(pk_field_name, pk), session=session
+        ).first()
         if instance:
             cls._fix_types(instance)
         return instance
@@ -423,10 +428,10 @@ class Model(BaseModel, metaclass=ModelMetaclass):
         )
 
         evict_instance(name, str(pk_val), identity_using, session_id=session_id)
-        query = self.__class__.where(getattr(self.__class__, pk_field_name) == pk_val)
+        query = self.__class__.where(_field_eq(pk_field_name, pk_val))
         if operation_using is not None:
             query = Query(self.__class__, using=operation_using).where(
-                getattr(self.__class__, pk_field_name) == pk_val
+                _field_eq(pk_field_name, pk_val)
             )
         fresh_instance = await query.first()
 
@@ -576,7 +581,7 @@ class Model(BaseModel, metaclass=ModelMetaclass):
         """
         query = Query(cls, session=session)
         for key, val in fields.items():
-            query = query.where(getattr(cls, key) == val)
+            query = query.where(_field_eq(key, val))
 
         instance = await query.first()
         if instance:
@@ -604,7 +609,7 @@ class Model(BaseModel, metaclass=ModelMetaclass):
         """
         query = Query(cls, session=session)
         for key, val in fields.items():
-            query = query.where(getattr(cls, key) == val)
+            query = query.where(_field_eq(key, val))
 
         instance = await query.first()
         if instance:
@@ -662,9 +667,7 @@ class ModelConnection[M: Model]:
                 f"Model {self.model_cls.__name__} does not define a primary key"
             )
 
-        instance = await self.where(
-            getattr(self.model_cls, pk_field_name) == pk
-        ).first()
+        instance = await self.where(_field_eq(pk_field_name, pk)).first()
         if instance:
             self.model_cls._fix_types(instance)
         return instance
@@ -677,7 +680,7 @@ class ModelConnection[M: Model]:
     ) -> tuple[M, bool]:
         query = Query(self.model_cls, using=self._connection_name)
         for key, val in fields.items():
-            query = query.where(getattr(self.model_cls, key) == val)
+            query = query.where(_field_eq(key, val))
 
         instance = await query.first()
         if instance:
@@ -691,7 +694,7 @@ class ModelConnection[M: Model]:
     ) -> tuple[M, bool]:
         query = Query(self.model_cls, using=self._connection_name)
         for key, val in fields.items():
-            query = query.where(getattr(self.model_cls, key) == val)
+            query = query.where(_field_eq(key, val))
 
         instance = await query.first()
         if instance:

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/src/ferro/relations/descriptors.py

@@ -69,9 +69,10 @@ class RelationshipDescriptor(BaseModel):
 
         pk_val = getattr(instance, pk_field)
 
+        fk_field = f"{self.field_name}_id"
         if self.is_one_to_one:
             return self._target_model.where(
-                getattr(self._target_model, f"{self.field_name}_id") == pk_val
+                lambda t, f=fk_field, v=pk_val: getattr(t, f) == v
             ).first()
 
         from ..query.builder import Relation
@@ -79,9 +80,7 @@ class RelationshipDescriptor(BaseModel):
         return Relation(
             self._target_model,
             using=_instance_origin_outside_transaction(instance),
-        ).where(
-            getattr(self._target_model, f"{self.field_name}_id") == pk_val
-        )
+        ).where(lambda t, f=fk_field, v=pk_val: getattr(t, f) == v)
 
 
 class ForwardDescriptor(BaseModel):

ferro_orm-0.12.2/src/ferro/session.py

@@ -0,0 +1,122 @@
+"""Session-scoped runtime state for Ferro operations."""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._core import close_session as _core_close_session
+from ._core import open_session as _core_open_session
+from .state import _CURRENT_SESSION
+
+_SESSION_CLOSE_AMBIENT_MISMATCH = (
+    "Session close failed: ambient session does not match the closing session. "
+    "This usually indicates session lifecycle misuse in the current asyncio context."
+)
+
+
+@dataclass(slots=True)
+class Session:
+    connection_name: str | None = None
+    session_id: str | None = None
+    _token: Any = field(default=None, repr=False, compare=False)
+    _enter_context: contextvars.Context | None = field(
+        default=None, repr=False, compare=False
+    )
+    _enter_task: asyncio.Task[Any] | None = field(
+        default=None, repr=False, compare=False
+    )
+
+    async def __aenter__(self) -> "Session":
+        self.session_id, resolved_name = _core_open_session(self.connection_name)
+        if self.connection_name is None:
+            self.connection_name = resolved_name
+        self._token = _CURRENT_SESSION.set(self)
+        self._enter_context = contextvars.copy_context()
+        self._enter_task = asyncio.current_task()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        try:
+            await self.close()
+        except Exception as close_exc:
+            if exc_type is None:
+                raise
+            if exc is not None:
+                raise exc from close_exc
+            raise close_exc
+
+    async def close(self) -> None:
+        """Close this session and release its runtime state.
+
+        Safe to call from a different asyncio context than ``__aenter__``.
+        Repeated calls are no-ops.
+
+        Raises:
+            RuntimeError: If the ambient session in this asyncio context does not
+                match this handle (same-context lifecycle misuse).
+        """
+        if self.session_id is None and self._token is None:
+            return
+
+        self._assert_close_allowed()
+
+        if self.session_id is not None:
+            session_id = self.session_id
+            _core_close_session(session_id)
+            self.session_id = None
+
+        if self._token is None:
+            self._enter_context = None
+            self._enter_task = None
+            return
+
+        token = self._token
+        self._token = None
+        self._enter_context = None
+        self._enter_task = None
+        self._restore_ambient_session(token)
+
+    def _assert_close_allowed(self) -> None:
+        if self._token is None:
+            return
+        if asyncio.current_task() is not self._enter_task:
+            return
+        ambient = _CURRENT_SESSION.get()
+        if ambient is self:
+            return
+        entered_ambient = (
+            self._enter_context.get(_CURRENT_SESSION)
+            if self._enter_context is not None
+            else None
+        )
+        if entered_ambient is self and ambient is not None:
+            raise RuntimeError(_SESSION_CLOSE_AMBIENT_MISMATCH)
+
+    def _restore_ambient_session(self, token: Any) -> None:
+        ambient = _CURRENT_SESSION.get()
+        if ambient is not self:
+            try:
+                _CURRENT_SESSION.reset(token)
+            except ValueError:
+                return
+            raise RuntimeError(_SESSION_CLOSE_AMBIENT_MISMATCH)
+        try:
+            _CURRENT_SESSION.reset(token)
+        except ValueError:
+            return
+
+    def query(self, model_cls):
+        from .query import Query
+
+        return Query(model_cls, session=self)
+
+
+class EngineManager:
+    def session(self, name: str | None = None) -> Session:
+        return Session(connection_name=name)
+
+
+engines = EngineManager()

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/src/ferro/state.py

@@ -34,6 +34,16 @@ _LEGACY_DEFAULT_CONNECTION_REASON = (
     "ORM/raw operations."
 )
 
+_SESSION_CLOSED_MESSAGE = (
+    "Session is closed. Open a new session with "
+    "`async with ferro.engines.session(...)` or pass an active session handle."
+)
+
+
+def _ensure_active_session(session: SessionLike | None) -> None:
+    if session is not None and session.session_id is None:
+        raise RuntimeError(_SESSION_CLOSED_MESSAGE)
+
 # Global registry for models (Python side)
 _MODEL_REGISTRY_PY = {}
 
@@ -76,6 +86,11 @@ def resolve_operation_scope(
         if explicit_session is None and using != effective_session.connection_name:
             effective_session = None
 
+    if explicit_session is None and ambient_session is not None:
+        _ensure_active_session(ambient_session)
+
+    _ensure_active_session(effective_session)
+
     session_id = effective_session.session_id if effective_session is not None else None
 
     if tx_id is not None:
@@ -124,6 +139,11 @@ def resolve_transaction_scope(
         if explicit_session is None and using != effective_session.connection_name:
             effective_session = None
 
+    if explicit_session is None and ambient_session is not None:
+        _ensure_active_session(ambient_session)
+
+    _ensure_active_session(effective_session)
+
     if parent_tx_id is not None:
         # Nested tx route is always inherited from parent.
         return parent_tx_id, None, (

{ferro_orm-0.12.0 → ferro_orm-0.12.2}/src/operations.rs

@@ -825,9 +825,10 @@ pub fn rollback_transaction(
 
 #[pyfunction]
 #[pyo3(signature = (using=None))]
-pub fn open_session(using: Option<String>) -> PyResult<String> {
+pub fn open_session(using: Option<String>) -> PyResult<(String, String)> {
     let (connection_name, _) = active_connection_for_route(using)?;
-    Ok(register_session(connection_name))
+    let session_id = register_session(connection_name.clone());
+    Ok((session_id, connection_name))
 }
 
 #[pyfunction]

ferro_orm-0.12.2/tests/test_framework_predicates.py

@@ -0,0 +1,72 @@
+"""Regression tests for framework-internal predicate style (issue #121)."""
+
+import warnings
+from typing import Annotated
+
+import pytest
+
+import ferro
+
+
+pytestmark = pytest.mark.sqlite_only
+
+
+class FrameworkPredicateMarker(ferro.Model):
+    id: Annotated[int | None, ferro.FerroField(primary_key=True)] = None
+    name: str
+
+
+@pytest.fixture(autouse=True)
+def _ensure_models_registered():
+    from ferro.state import _MODEL_REGISTRY_PY
+
+    FrameworkPredicateMarker._reregister_ferro()
+    _MODEL_REGISTRY_PY[FrameworkPredicateMarker.__name__] = FrameworkPredicateMarker
+    yield
+
+
+def _operator_predicate_warnings(caught: list[warnings.WarningMessage]) -> list[str]:
+    return [
+        str(w.message)
+        for w in caught
+        if issubclass(w.category, DeprecationWarning)
+        and "Operator predicate style" in str(w.message)
+    ]
+
+
+@pytest.mark.asyncio
+async def test_framework_helpers_do_not_emit_operator_predicate_warnings(tmp_path):
+    db = tmp_path / "framework_predicates.db"
+    await ferro.connect(f"sqlite:{db}?mode=rwc", auto_migrate=True)
+
+    async with ferro.engines.session("default"):
+        widget = FrameworkPredicateMarker(id=1, name="demo")
+        await widget.save()
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", DeprecationWarning)
+            loaded = await FrameworkPredicateMarker.get_or_none(1)
+            assert loaded is not None
+            await loaded.refresh()
+            found, created = await FrameworkPredicateMarker.get_or_create(name="demo")
+            assert found is not None
+            assert created is False
+            await loaded.delete()
+
+        assert _operator_predicate_warnings(caught) == []
+
+
+@pytest.mark.asyncio
+async def test_model_connection_get_or_none_does_not_emit_operator_warnings(tmp_path):
+    db = tmp_path / "framework_predicates_bound.db"
+    await ferro.connect(f"sqlite:{db}?mode=rwc", auto_migrate=True)
+
+    async with ferro.engines.session("default"):
+        await FrameworkPredicateMarker.create(id=2, name="bound")
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", DeprecationWarning)
+            loaded = await FrameworkPredicateMarker.using("default").get_or_none(2)
+
+        assert loaded is not None
+        assert _operator_predicate_warnings(caught) == []