ferro-orm 0.12.1__tar.gz → 0.12.3__tar.gz

{ferro_orm-0.12.1 → ferro_orm-0.12.3}/CHANGELOG.md

@@ -1,6 +1,27 @@
 # CHANGELOG
 
 
+## v0.12.3 (2026-06-24)
+
+### Bug Fixes
+
+- **session**: Reject close while transactions are active
+  ([#128](https://github.com/syn54x/ferro-orm/pull/128),
+  [`e46f183`](https://github.com/syn54x/ferro-orm/commit/e46f183fba7a3bcbc635f7e66502a77aeb56861d))
+
+- **session**: Serialize concurrent close teardown
+  ([#129](https://github.com/syn54x/ferro-orm/pull/129),
+  [`7afa616`](https://github.com/syn54x/ferro-orm/commit/7afa6168abd2eb19b564fc1c2ab9956e03a20fe9))
+
+
+## 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

{ferro_orm-0.12.1 → ferro_orm-0.12.3}/Cargo.lock

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

{ferro_orm-0.12.1 → ferro_orm-0.12.3}/Cargo.toml

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

{ferro_orm-0.12.1 → ferro_orm-0.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.12.1
+Version: 0.12.3
 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.1 → ferro_orm-0.12.3}/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.1 → ferro_orm-0.12.3}/docs/pages/guide/connections.md

@@ -114,6 +114,39 @@ 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.
+
+Close raises `RuntimeError` if session-scoped transactions are still open — exit all `transaction()` blocks before closing the session.
+
+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.1 → ferro_orm-0.12.3}/docs/pages/guide/transactions.md

@@ -40,6 +40,8 @@ async with ferro.engines.session("analytics"):
 
 You can also pass an explicit session handle (`transaction(session=my_session)`) when ambient context is different and you need a deterministic override.
 
+`Session.close()` raises `RuntimeError` while session-scoped transactions are still open. Exit all `transaction()` blocks before closing the session.
+
 ## Raw SQL Inside a Transaction
 
 `transaction()` yields a `Transaction` handle exposing `execute` / `fetch_all` / `fetch_one` for raw SQL on the transaction's own connection — useful for Postgres GUCs (`set_config`, `SET LOCAL`), advisory locks, or any one-off statement that doesn't fit a model:

{ferro_orm-0.12.1 → ferro_orm-0.12.3}/pyproject.toml

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

ferro_orm-0.12.3/src/ferro/session.py

@@ -0,0 +1,128 @@
+"""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
+    )
+    _close_lock: asyncio.Lock | 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), or if
+                session-scoped transactions are still open.
+        """
+        if self._close_lock is None:
+            self._close_lock = asyncio.Lock()
+
+        async with self._close_lock:
+            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.1 → ferro_orm-0.12.3}/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.1 → ferro_orm-0.12.3}/src/operations.rs

@@ -9,8 +9,8 @@ use crate::backend::{
 use crate::query::{QueryDef, query_def_from_ir_payload};
 use crate::state::{
     IDENTITY_MAP, MODEL_REGISTRY, SqlDialect, TRANSACTION_REGISTRY,
-    TransactionConnection, TransactionHandle, connection_for_route, engine_for_connection,
-    register_session, session_state, unregister_session,
+    TransactionConnection, TransactionHandle, connection_for_route, ensure_session_idle_for_close,
+    engine_for_connection, register_session, session_state, unregister_session,
 };
 use ferro_schema_ir::{IrEnvelope, QueryIrPayload};
 use pyo3::prelude::*;
@@ -833,6 +833,7 @@ pub fn open_session(using: Option<String>) -> PyResult<(String, String)> {
 
 #[pyfunction]
 pub fn close_session(session_id: String) -> PyResult<()> {
+    ensure_session_idle_for_close(&session_id)?;
     if !unregister_session(&session_id) {
         return Err(pyo3::exceptions::PyRuntimeError::new_err(format!(
             "Session '{}' is not active",

{ferro_orm-0.12.1 → ferro_orm-0.12.3}/src/state.rs

@@ -199,6 +199,20 @@ pub fn session_state(session_id: &str) -> PyResult<Arc<SessionState>> {
         })
 }
 
+pub(crate) const SESSION_CLOSE_ACTIVE_TRANSACTIONS_MSG: &str =
+    "Cannot close session while transactions are active. \
+     Exit all transaction() blocks before closing the session.";
+
+pub fn ensure_session_idle_for_close(session_id: &str) -> PyResult<()> {
+    let session = session_state(session_id)?;
+    if !session.transaction_registry.is_empty() {
+        return Err(pyo3::exceptions::PyRuntimeError::new_err(
+            SESSION_CLOSE_ACTIVE_TRANSACTIONS_MSG,
+        ));
+    }
+    Ok(())
+}
+
 /// A Rust-native representation of database values.
 ///
 /// Used during the GIL-free parsing phase to move data from the database
@@ -262,3 +276,53 @@ impl RustValue {
         }
     }
 }
+
+#[cfg(test)]
+mod session_close_tests {
+    use super::{TransactionHandle, register_session, unregister_session, SESSION_REGISTRY};
+    use crate::backend::EngineHandle;
+    use sqlx::sqlite::SqlitePoolOptions;
+
+    #[tokio::test]
+    async fn close_guard_uses_transaction_registry_emptiness() {
+        let session_id = register_session("default".to_string());
+
+        let pool = SqlitePoolOptions::new()
+            .max_connections(1)
+            .connect("sqlite::memory:")
+            .await
+            .expect("sqlite memory pool");
+        let engine = EngineHandle::new_sqlite(pool);
+        let conn = engine
+            .begin_transaction_connection()
+            .await
+            .expect("begin transaction connection");
+
+        {
+            let session = SESSION_REGISTRY
+                .get(&session_id)
+                .expect("session registered")
+                .value()
+                .clone();
+            session.transaction_registry.insert(
+                "tx-test".to_string(),
+                TransactionHandle::root(conn, "default".to_string()),
+            );
+            assert!(!session.transaction_registry.is_empty());
+        }
+
+        SESSION_REGISTRY
+            .get(&session_id)
+            .expect("session registered")
+            .transaction_registry
+            .clear();
+        assert!(
+            SESSION_REGISTRY
+                .get(&session_id)
+                .expect("session registered")
+                .transaction_registry
+                .is_empty()
+        );
+        assert!(unregister_session(&session_id));
+    }
+}