sqlmodel-object-helpers 0.0.11__tar.gz → 0.0.12__tar.gz

{sqlmodel_object_helpers-0.0.11 → sqlmodel_object_helpers-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlmodel-object-helpers
-Version: 0.0.11
+Version: 0.0.12
 Summary: Generic async query helpers for SQLModel: filtering, eager loading, pagination
 Project-URL: Homepage, https://github.com/itstandart/sqlmodel-object-helpers
 Project-URL: Repository, https://github.com/itstandart/sqlmodel-object-helpers
@@ -28,6 +28,8 @@ Description-Content-Type: text/markdown
 
 # sqlmodel-object-helpers
 
+**Version:** v0.0.12 · 2026-10-29 · Рома
+
 [![PyPI version](https://badge.fury.io/py/sqlmodel-object-helpers.svg)](https://pypi.org/project/sqlmodel-object-helpers/)
 [![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
@@ -264,10 +266,15 @@ user = await soh.get_object(
 # Graceful mode (returns None instead of raising)
 user = await soh.get_object(session, User, pk={"id": 999}, suspend_error=True)
 
-# Row-level locking (SELECT ... FOR UPDATE)
+# Row-level locking (SELECT ... FOR UPDATE), preserving pending changes
 user = await soh.get_object(session, User, pk={"id": 5}, for_update=True)
+
+# Refresh an already loaded object when its pending changes have been flushed
+user = await soh.get_object(session, User, pk={"id": 5}, for_update=True, populate_existing=True)
 ```
 
+Use a caller-managed session for a read-modify-write transaction. The standalone wrapper commits and releases the lock before returning. `for_update=True` preserves pending changes in the session by default, so a previously loaded object may still show stale values. `populate_existing=True` refreshes that object, but discards its unflushed changes; flush first when those changes must be kept.
+
 ### get_objects
 
 Fetch multiple objects with filtering, pagination, sorting, and eager loading.
@@ -961,7 +968,11 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 
 ## Changelog
 
-### 0.0.11 — unreleased
+### 0.0.12 — unreleased
+
+- `get_object` supports explicit `populate_existing=True` for refreshing an already loaded ORM object, including locked reads. The default keeps unflushed changes in sessions with `autoflush=False`. SQL mode is unchanged.
+
+### 0.0.11 — 2026-10-28
 
 - **Performance** — `insert_objects_ignore_conflicts` and `upsert_objects` execute one single-row statement as executemany instead of compiling a multi-row `VALUES` statement per chunk; SQLAlchemy insertmanyvalues renders the rows into multi-row pages. No statement cache is involved: SQLAlchemy does not cache PostgreSQL `INSERT ... ON CONFLICT`. On PostgreSQL 18 with asyncpg, inserting 1000 rows of an 18-column table takes about 27 ms instead of 610 ms (20000 rows: 0.56 s instead of 13 s), on par with a hand-written bulk insert; upserting 1000 rows of a 6-column table takes about 12 ms instead of 165 ms (10000 rows: 0.11 s instead of 1.65 s), SAVEPOINTs included. Server-side execution time is unchanged.
 - `upsert_objects` on PostgreSQL: a key repeated in Python terms starts the next statement, in input order, instead of re-running the batch row by row. Each page of a multi-row call keeps the 0.0.10 SAVEPOINT, also when its rows go one by one: a repeat only the database sees (column type, collation of the column or of the unique index, a `BEFORE INSERT` trigger) is retried row by row in a new SAVEPOINT. Another error, including during that retry, rolls back the page without aborting the caller's transaction. A single-row call goes without a SAVEPOINT.

{sqlmodel_object_helpers-0.0.11 → sqlmodel_object_helpers-0.0.12}/README.md

@@ -1,5 +1,7 @@
 # sqlmodel-object-helpers
 
+**Version:** v0.0.12 · 2026-10-29 · Рома
+
 [![PyPI version](https://badge.fury.io/py/sqlmodel-object-helpers.svg)](https://pypi.org/project/sqlmodel-object-helpers/)
 [![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/downloads/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
@@ -236,10 +238,15 @@ user = await soh.get_object(
 # Graceful mode (returns None instead of raising)
 user = await soh.get_object(session, User, pk={"id": 999}, suspend_error=True)
 
-# Row-level locking (SELECT ... FOR UPDATE)
+# Row-level locking (SELECT ... FOR UPDATE), preserving pending changes
 user = await soh.get_object(session, User, pk={"id": 5}, for_update=True)
+
+# Refresh an already loaded object when its pending changes have been flushed
+user = await soh.get_object(session, User, pk={"id": 5}, for_update=True, populate_existing=True)
 ```
 
+Use a caller-managed session for a read-modify-write transaction. The standalone wrapper commits and releases the lock before returning. `for_update=True` preserves pending changes in the session by default, so a previously loaded object may still show stale values. `populate_existing=True` refreshes that object, but discards its unflushed changes; flush first when those changes must be kept.
+
 ### get_objects
 
 Fetch multiple objects with filtering, pagination, sorting, and eager loading.
@@ -933,7 +940,11 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 
 ## Changelog
 
-### 0.0.11 — unreleased
+### 0.0.12 — unreleased
+
+- `get_object` supports explicit `populate_existing=True` for refreshing an already loaded ORM object, including locked reads. The default keeps unflushed changes in sessions with `autoflush=False`. SQL mode is unchanged.
+
+### 0.0.11 — 2026-10-28
 
 - **Performance** — `insert_objects_ignore_conflicts` and `upsert_objects` execute one single-row statement as executemany instead of compiling a multi-row `VALUES` statement per chunk; SQLAlchemy insertmanyvalues renders the rows into multi-row pages. No statement cache is involved: SQLAlchemy does not cache PostgreSQL `INSERT ... ON CONFLICT`. On PostgreSQL 18 with asyncpg, inserting 1000 rows of an 18-column table takes about 27 ms instead of 610 ms (20000 rows: 0.56 s instead of 13 s), on par with a hand-written bulk insert; upserting 1000 rows of a 6-column table takes about 12 ms instead of 165 ms (10000 rows: 0.11 s instead of 1.65 s), SAVEPOINTs included. Server-side execution time is unchanged.
 - `upsert_objects` on PostgreSQL: a key repeated in Python terms starts the next statement, in input order, instead of re-running the batch row by row. Each page of a multi-row call keeps the 0.0.10 SAVEPOINT, also when its rows go one by one: a repeat only the database sees (column type, collation of the column or of the unique index, a `BEFORE INSERT` trigger) is retried row by row in a new SAVEPOINT. Another error, including during that retry, rolls back the page without aborting the caller's transaction. A single-row call goes without a SAVEPOINT.

{sqlmodel_object_helpers-0.0.11 → sqlmodel_object_helpers-0.0.12}/pyproject.toml

@@ -45,11 +45,11 @@ packages = ["src/sqlmodel_object_helpers"]
 
 [dependency-groups]
 dev = [
-    "ruff==0.17.2",
+    "ruff==0.17.4",
     "pyright==1.1.414",
-    "tzdata==2026.5",
-    "pytest==9.1.1",
-    "pytest-asyncio==1.4.0",
+    "tzdata==2026.6",
+    "pytest==9.2.0",
+    "pytest-asyncio==1.4.1.post1",
     "aiosqlite==0.22.1",
 ]
 postgres = [

{sqlmodel_object_helpers-0.0.11 → sqlmodel_object_helpers-0.0.12}/src/sqlmodel_object_helpers/__init__.py

@@ -1,6 +1,6 @@
 """sqlmodel-object-helpers — reusable query helpers for SQLModel projects."""
 
-__version__ = "0.0.11"
+__version__ = "0.0.12"
 
 from .constants import QueryHelperSettings, settings
 from .dynamic_meta import (

{sqlmodel_object_helpers-0.0.11 → sqlmodel_object_helpers-0.0.12}/src/sqlmodel_object_helpers/query.py

@@ -256,6 +256,10 @@ async def _execute_with_pagination_dicts(
 # ---------------------------------------------------------------------------
 
 
+def _with_populate_existing(stmt: Any, enabled: bool) -> Any:
+    return stmt.execution_options(populate_existing=True) if enabled else stmt
+
+
 @overload
 async def get_object[T: SQLModel](
     session: AsyncSession,
@@ -270,6 +274,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> T: ...
 
 
@@ -287,6 +292,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> T | None: ...
 
 
@@ -304,6 +310,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> list[dict[str, Any]]: ...
 
 
@@ -321,6 +328,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> list[dict[str, Any]] | T | None: ...
 
 
@@ -337,6 +345,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> list[dict[str, Any]] | T | None:
     """
     Fetch a single object by primary key or filters.
@@ -344,6 +353,8 @@ async def get_object[T: SQLModel](
     Supports two modes:
     - ORM mode: returns a model instance with eager-loaded relationships
     - SQL mode (columns + extra_joins): returns flat dicts
+
+    Flush pending changes before setting populate_existing=True.
     """
     start = time.perf_counter()
 
@@ -381,6 +392,7 @@ async def get_object[T: SQLModel](
 
     if for_update:
         stmt = stmt.with_for_update()
+    stmt = _with_populate_existing(stmt, populate_existing)
 
     if limit_one:
         stmt = stmt.limit(1)

{sqlmodel_object_helpers-0.0.11 → sqlmodel_object_helpers-0.0.12}/src/sqlmodel_object_helpers/standalone.py

@@ -64,6 +64,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> T: ...
 
 
@@ -80,6 +81,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> T | None: ...
 
 
@@ -96,6 +98,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> list[dict[str, Any]]: ...
 
 
@@ -112,6 +115,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> list[dict[str, Any]] | T | None: ...
 
 
@@ -127,6 +131,7 @@ async def get_object[T: SQLModel](
     extra_joins: list[tuple[Any, ...]] | None = None,
     limit_one: bool = True,
     for_update: bool = False,
+    populate_existing: bool = False,
 ) -> list[dict[str, Any]] | T | None:
     """Fetch a single object. Auto-creates session and commits."""
     logger.debug("standalone.get_object(%s, pk=%s)", model.__name__, pk)
@@ -143,6 +148,7 @@ async def get_object[T: SQLModel](
             extra_joins=extra_joins,
             limit_one=limit_one,
             for_update=for_update,
+            populate_existing=populate_existing,
         )
 
 

sqlmodel_object_helpers-0.0.12/tests/test_for_update.py

@@ -0,0 +1,72 @@
+"""
+Integration tests for the for_update parameter in get_object().
+
+SQLite does not support SELECT ... FOR UPDATE, so these tests cover:
+1) for_update=False (default) works as before
+2) for_update=True executes without error on SQLite (silently ignored)
+3) for_update=True keeps unflushed changes by default
+4) populate_existing=True refreshes an object already present in the identity map
+"""
+
+import pytest
+from conftest import Applicant
+from sqlalchemy import update
+
+import sqlmodel_object_helpers as soh
+
+pytestmark = pytest.mark.asyncio
+
+
+async def test_get_object_default_no_for_update(session, seed_data):
+    """Default for_update=False returns object normally."""
+    applicant = seed_data["applicants"][0]
+    result = await soh.get_object(session, Applicant, pk={"id": applicant.id})
+
+    assert result is not None
+    assert result.last_name == "Иванов"
+
+
+async def test_get_object_with_for_update(session, seed_data):
+    """for_update=True adds WITH FOR UPDATE clause; SQLite ignores it gracefully."""
+    applicant = seed_data["applicants"][0]
+    result = await soh.get_object(
+        session,
+        Applicant,
+        pk={"id": applicant.id},
+        for_update=True,
+    )
+
+    assert result is not None
+    assert result.id == applicant.id
+    assert result.last_name == "Иванов"
+
+
+async def test_for_update_refreshes_object_in_identity_map(session, seed_data):
+    applicant = seed_data["applicants"][0]
+    await session.execute(
+        update(Applicant)
+        .where(Applicant.id == applicant.id)
+        .values(last_name="Updated")
+        .execution_options(synchronize_session=False)
+    )
+    assert applicant.last_name == "Иванов"
+
+    ordinary = await soh.get_object(session, Applicant, pk={"id": applicant.id})
+    assert ordinary is applicant
+    assert ordinary.last_name == "Иванов"
+
+    locked = await soh.get_object(session, Applicant, pk={"id": applicant.id}, for_update=True, populate_existing=True)
+    assert locked is applicant
+    assert locked.last_name == "Updated"
+
+
+async def test_for_update_preserves_unflushed_changes_by_default(session, seed_data):
+    session.autoflush = False
+    applicant = seed_data["applicants"][0]
+    applicant.last_name = "Pending"
+
+    locked = await soh.get_object(session, Applicant, pk={"id": applicant.id}, for_update=True)
+
+    assert locked is applicant
+    assert locked.last_name == "Pending"
+    assert session.is_modified(applicant)

sqlmodel_object_helpers-0.0.12/tests/test_for_update_postgres.py

@@ -0,0 +1,92 @@
+"""PostgreSQL row lock and identity-map refresh tests."""
+
+import os
+from typing import ClassVar
+from uuid import uuid7
+
+import pytest
+import pytest_asyncio
+from sqlalchemy import MetaData, select, update
+from sqlalchemy.exc import DBAPIError
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.schema import CreateSchema, DropSchema
+from sqlmodel import Field, SQLModel, col
+
+import sqlmodel_object_helpers as soh
+
+pytestmark = pytest.mark.asyncio
+
+_SCHEMA = "soh_lock_test"
+
+
+class _PgBase(SQLModel):
+    metadata: ClassVar[MetaData] = MetaData(schema=_SCHEMA)  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class LockedRow(_PgBase, table=True):
+    __tablename__ = "locked_rows"  # pyright: ignore[reportAssignmentType]  SQLModel declares it via declared_attr
+
+    id: int | None = Field(default=None, primary_key=True)
+    value: str
+
+
+@pytest_asyncio.fixture
+async def engine():
+    url = os.environ.get("SOH_TEST_POSTGRES_URL")
+    if not url:
+        pytest.skip("Set SOH_TEST_POSTGRES_URL to run PostgreSQL tests")
+    schema = f"soh_lock_{uuid7().hex}"
+    eng = create_async_engine(url, execution_options={"schema_translate_map": {_SCHEMA: schema}})
+    try:
+        async with eng.begin() as connection:
+            await connection.execute(CreateSchema(schema))
+            await connection.run_sync(_PgBase.metadata.create_all)
+        yield eng
+    finally:
+        async with eng.begin() as connection:
+            await connection.execute(DropSchema(schema, cascade=True, if_exists=True))
+        await eng.dispose()
+
+
+async def test_locked_read_refreshes_cached_row_and_holds_lock(engine):
+    async with (
+        AsyncSession(engine, expire_on_commit=False) as holder,
+        AsyncSession(engine, expire_on_commit=False) as writer,
+        AsyncSession(engine, expire_on_commit=False) as contender,
+    ):
+        row = LockedRow(value="before")
+        holder.add(row)
+        await holder.commit()
+        assert row.id is not None
+
+        cached = await soh.get_object(holder, LockedRow, pk={"id": row.id})
+        await holder.commit()
+        await writer.execute(update(LockedRow).where(col(LockedRow.id) == row.id).values(value="after"))
+        await writer.commit()
+        assert cached.value == "before"
+
+        locked = await soh.get_object(holder, LockedRow, pk={"id": row.id}, for_update=True, populate_existing=True)
+        assert locked is cached
+        assert locked.value == "after"
+
+        with pytest.raises(DBAPIError):
+            await contender.execute(select(LockedRow).where(col(LockedRow.id) == row.id).with_for_update(nowait=True))
+        await contender.rollback()
+        await holder.commit()
+
+        await contender.execute(select(LockedRow).where(col(LockedRow.id) == row.id).with_for_update(nowait=True))
+
+
+async def test_locked_read_keeps_pending_changes_with_autoflush_disabled(engine):
+    async with AsyncSession(engine, autoflush=False, expire_on_commit=False) as session:
+        row = LockedRow(value="saved")
+        session.add(row)
+        await session.commit()
+
+        row.value = "pending"
+        locked = await soh.get_object(session, LockedRow, pk={"id": row.id}, for_update=True)
+
+        assert locked is row
+        assert locked.value == "pending"
+        assert session.is_modified(row)
+        await session.rollback()