sqlmodel-crud-utilities 0.2.0__tar.gz → 0.3.0__tar.gz

{sqlmodel_crud_utilities-0.2.0/sqlmodel_crud_utilities.egg-info → sqlmodel_crud_utilities-0.3.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: sqlmodel_crud_utilities
-Version: 0.2.0
+Version: 0.3.0
 Summary: A set of CRUD utilities to expedite operations with SQLModel
 Author-email: Francis Secada <francis.secada@gmail.com>
 License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
 Project-URL: Homepage, https://fsecada01.github.io/SQLModel-CRUD-Utilities/sqlmodel_crud_utils.html
-Project-URL: Repository, https://github.com/fsecada01/sqlmodel_crud_utils
-Project-URL: Bug Tracker, https://github.com/fsecada01/sqlmodel_crud_utils/issues
+Project-URL: Repository, https://github.com/fsecada01/SQLModel-CRUD-Utilities
+Project-URL: Bug Tracker, https://github.com/fsecada01/SQLModel-CRUD-Utilities/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9

{sqlmodel_crud_utilities-0.2.0 → sqlmodel_crud_utilities-0.3.0}/pyproject.toml

@@ -58,7 +58,7 @@ line_length = 80
 
 [project]
 name = "sqlmodel_crud_utilities"
-version = "0.2.0"
+version = "0.3.0"
 authors = [
     { name="Francis Secada", email = "francis.secada@gmail.com" }
 ]
@@ -80,8 +80,8 @@ dependencies = [
 loguru = ["loguru>=0.7.3"]
 [project.urls]
 "Homepage" = "https://fsecada01.github.io/SQLModel-CRUD-Utilities/sqlmodel_crud_utils.html"
-"Repository" = "https://github.com/fsecada01/sqlmodel_crud_utils"
-"Bug Tracker" = "https://github.com/fsecada01/sqlmodel_crud_utils/issues"
+"Repository" = "https://github.com/fsecada01/SQLModel-CRUD-Utilities"
+"Bug Tracker" = "https://github.com/fsecada01/SQLModel-CRUD-Utilities/issues"
 
 
 [dependency-groups]
@@ -91,6 +91,7 @@ dev = [
     "build>=1.2.2.post1",
     "factory-boy>=3.3.3",
     "isort>=6.0.1",
+    "loguru>=0.7.3",
     "pre-commit>=4.2.0",
     "pytest>=8.3.5",
     "pytest-asyncio>=0.26.0",
@@ -100,7 +101,6 @@ dev = [
     "ruff>=0.11.10",
 ]
 
-
 doc = [
     "pdoc>=15.0.1",
 ]

{sqlmodel_crud_utilities-0.2.0 → sqlmodel_crud_utilities-0.3.0/sqlmodel_crud_utilities.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: sqlmodel_crud_utilities
-Version: 0.2.0
+Version: 0.3.0
 Summary: A set of CRUD utilities to expedite operations with SQLModel
 Author-email: Francis Secada <francis.secada@gmail.com>
 License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
 Project-URL: Homepage, https://fsecada01.github.io/SQLModel-CRUD-Utilities/sqlmodel_crud_utils.html
-Project-URL: Repository, https://github.com/fsecada01/sqlmodel_crud_utils
-Project-URL: Bug Tracker, https://github.com/fsecada01/sqlmodel_crud_utils/issues
+Project-URL: Repository, https://github.com/fsecada01/SQLModel-CRUD-Utilities
+Project-URL: Bug Tracker, https://github.com/fsecada01/SQLModel-CRUD-Utilities/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9

{sqlmodel_crud_utilities-0.2.0 → sqlmodel_crud_utilities-0.3.0}/sqlmodel_crud_utilities.egg-info/SOURCES.txt

@@ -14,5 +14,11 @@ sqlmodel_crud_utils/sync.py
 sqlmodel_crud_utils/transactions.py
 sqlmodel_crud_utils/utils.py
 tests/test_async_utils.py
+tests/test_bulk_id_list_ops.py
+tests/test_bulk_upsert_sqlite.py
+tests/test_get_row_param_order.py
+tests/test_get_rows_custom_stmnt.py
+tests/test_sync_async_parity.py
 tests/test_sync_utils.py
+tests/test_timestamp_mixin.py
 tests/test_v0_2_0_features.py

{sqlmodel_crud_utilities-0.2.0 → sqlmodel_crud_utilities-0.3.0}/sqlmodel_crud_utils/__init__.py

@@ -4,7 +4,7 @@ SQLModel CRUD Utilities
 A set of CRUD utilities to expedite operations with SQLModel, providing both
 synchronous and asynchronous support for common database operations.
 
-New in v0.2.0:
+New in v0.2.0 (see CHANGELOG.md for later releases):
     - Custom exception hierarchy for better error handling
     - Transaction context managers for safe operations
     - Audit trail mixins (created_at, updated_at tracking)
@@ -12,13 +12,17 @@ New in v0.2.0:
     - Public API exports for easier imports
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 # Import asynchronous functions with a_ prefix
+from sqlmodel_crud_utils.a_sync import bulk_update_rows as a_bulk_update_rows
 from sqlmodel_crud_utils.a_sync import (
     bulk_upsert_mappings as a_bulk_upsert_mappings,
 )
 from sqlmodel_crud_utils.a_sync import delete_row as a_delete_row
+from sqlmodel_crud_utils.a_sync import (
+    delete_rows_within_id_list as a_delete_rows_within_id_list,
+)
 from sqlmodel_crud_utils.a_sync import get_one_or_create as a_get_one_or_create
 from sqlmodel_crud_utils.a_sync import (
     get_result_from_query as a_get_result_from_query,
@@ -43,12 +47,18 @@ from sqlmodel_crud_utils.exceptions import (
 )
 
 # Import mixins
-from sqlmodel_crud_utils.mixins import AuditMixin, SoftDeleteMixin
+from sqlmodel_crud_utils.mixins import (
+    AuditMixin,
+    SoftDeleteMixin,
+    TimestampMixin,
+)
 
 # Import synchronous functions
 from sqlmodel_crud_utils.sync import (
+    bulk_update_rows,
     bulk_upsert_mappings,
     delete_row,
+    delete_rows_within_id_list,
     get_one_or_create,
     get_result_from_query,
     get_row,
@@ -66,8 +76,10 @@ __all__ = [
     # Version
     "__version__",
     # Synchronous functions
+    "bulk_update_rows",
     "bulk_upsert_mappings",
     "delete_row",
+    "delete_rows_within_id_list",
     "get_one_or_create",
     "get_result_from_query",
     "get_row",
@@ -77,8 +89,10 @@ __all__ = [
     "update_row",
     "write_row",
     # Asynchronous functions
+    "a_bulk_update_rows",
     "a_bulk_upsert_mappings",
     "a_delete_row",
+    "a_delete_rows_within_id_list",
     "a_get_one_or_create",
     "a_get_result_from_query",
     "a_get_row",
@@ -100,4 +114,5 @@ __all__ = [
     # Mixins
     "AuditMixin",
     "SoftDeleteMixin",
+    "TimestampMixin",
 ]

{sqlmodel_crud_utilities-0.2.0 → sqlmodel_crud_utilities-0.3.0}/sqlmodel_crud_utils/a_sync.py

@@ -4,15 +4,18 @@ from dateutil.parser import parse as date_parse
 from dotenv import load_dotenv
 from sqlalchemy.exc import MultipleResultsFound
 from sqlalchemy.orm import lazyload, selectinload
-from sqlmodel import SQLModel, select
+from sqlmodel import SQLModel, delete, select, update
 from sqlmodel.ext.asyncio.session import AsyncSession
 from sqlmodel.sql.expression import SelectOfScalar
 
 from sqlmodel_crud_utils.utils import (
+    chunked,
     get_sql_dialect_import,
     get_val,
     is_date,
     logger,
+    validate_primary_key_field,
+    validate_update_columns,
 )
 
 load_dotenv()  # take environment variables from .env.
@@ -215,20 +218,34 @@ async def get_rows(
     **kwargs,
 ):
     """
-
-    :param session_inst:
-    :param model:
-    :param selectin:
-    :param select_in_keys:
-    :param lazy:
-    :param lazy_load_keys:
-    :param page_size:
-    :param page:
-    :param text_field:
-    :param stmnt:
-    :param kwargs:
-    :return:
+    Retrieve rows for ``model``, building the query from ``kwargs`` or
+    running a caller-supplied statement.
+
+    Pagination applies only to statements built internally (``stmnt`` is
+    ``None``): ``page`` and ``page_size`` translate to OFFSET and LIMIT. A
+    caller-supplied ``stmnt`` is executed exactly as given; the caller owns
+    its pagination, so ``page``, ``page_size`` and any filter, sort or
+    loading arguments are ignored. Add ``.limit()``/``.offset()`` to the
+    statement yourself when you want a bounded result.
+
+    .. versionchanged:: Unreleased
+        A custom ``stmnt`` is no longer silently capped at ``page_size``
+        rows (issue #11).
+
+    :param session_inst: Active session used to execute the query.
+    :param model: SQLModel table class to query.
+    :param selectin: Enable ``selectinload`` for ``select_in_keys``.
+    :param select_in_keys: Relationship names to eager load via selectin.
+    :param lazy: Enable ``lazyload`` for ``lazy_load_keys``.
+    :param lazy_load_keys: Relationship names to lazy load.
+    :param page_size: Rows per page; ignored when ``stmnt`` is supplied.
+    :param page: 1-based page number; ignored when ``stmnt`` is supplied.
+    :param text_field: Field matched with a text search from ``kwargs``.
+    :param stmnt: Custom statement, executed as-is and never paginated.
+    :param kwargs: Filters and sort options for the built query.
+    :return: ``(success, rows)`` where ``success`` is True if rows exist.
     """
+    paginate = stmnt is None
     # kwargs = {k: v for k, v in kwargs.items() if v}
     # Inside get_rows (sync and async versions)
 
@@ -402,10 +419,8 @@ async def get_rows(
                         f"'{key}' on model {model.__name__}"
                     )
 
-    # Apply pagination
-    stmnt = stmnt.offset((page - 1) * page_size).limit(
-        page_size
-    )  # Corrected offset calculation
+    if paginate:
+        stmnt = stmnt.offset((page - 1) * page_size).limit(page_size)
     _result = await session_inst.exec(stmnt)
     results = _result.all()
     success = True if len(results) > 0 else False
@@ -438,6 +453,109 @@ async def get_rows_within_id_list(
     return success, results
 
 
+async def delete_rows_within_id_list(
+    id_str_list: list[str | int],
+    session_inst: AsyncSession,
+    model: type[SQLModel],
+    pk_field: str = "id",
+    chunk_size: int = 500,
+) -> tuple[bool, int]:
+    """
+    Deletes every row whose primary key is within the provided list and
+    commits once. IDs with no matching row are ignored.
+
+    This is a hard SQL ``DELETE``: it bypasses ``SoftDeleteMixin`` (rows are
+    removed, not marked with ``deleted_at``) and any ORM-level hooks. The ID
+    list is split into ``chunk_size`` batches to stay under backend
+    bind-parameter limits. One ``DELETE ... WHERE pk IN (...)`` statement is
+    sent per batch (never per row), so 1,200 IDs at the default size is 3
+    statements. All batches share one transaction, so the call is
+    all-or-nothing.
+
+    :param id_str_list: List of primary key values to delete.
+    :param session_inst: SQLModel AsyncSession instance.
+    :param model: SQLModel class representing the table.
+    :param pk_field: Primary-key column to match against (default: "id").
+    :param chunk_size: Maximum IDs per DELETE statement (default: 500).
+    :return: Tuple[bool, int]: ``True`` and the number of rows deleted. The
+        count is 0 when nothing matched or the list was empty.
+    :raises ValueError: If ``pk_field`` is not a primary-key column of
+        ``model`` or ``chunk_size`` is not positive.
+    :raises Exception: Any database error, after the transaction has been
+        rolled back and the error logged.
+    """
+    validate_primary_key_field(model, pk_field)
+    deleted = 0
+    try:
+        for chunk in chunked(id_str_list, chunk_size):
+            stmnt = delete(model).where(getattr(model, pk_field).in_(chunk))
+            result = await session_inst.exec(stmnt)
+            deleted += max(result.rowcount, 0)
+        await session_inst.commit()
+    except Exception as e:
+        await session_inst.rollback()
+        logger.error(f"Failed to bulk delete rows: {type(e)}, {e}")
+        raise
+
+    return True, deleted
+
+
+async def bulk_update_rows(
+    id_str_list: list[str | int],
+    data: dict,
+    session_inst: AsyncSession,
+    model: type[SQLModel],
+    pk_field: str = "id",
+    chunk_size: int = 500,
+) -> tuple[bool, int]:
+    """
+    Applies the same column values to every row whose primary key is within
+    the provided list and commits once. IDs with no matching row are ignored.
+
+    This is a Core ``UPDATE``: ORM-level hooks and Python-side defaults do
+    not run, so ``AuditMixin.updated_at``/``updated_by`` are not refreshed
+    unless the caller includes them in ``data`` (column-level ``onupdate``
+    defaults, such as ``TimestampMixin.updated_at``, do fire). The ID list is
+    split into ``chunk_size`` batches. One ``UPDATE ... WHERE pk IN (...)``
+    statement is sent per batch (never per row), and all batches share one
+    transaction.
+
+    :param id_str_list: List of primary key values to update.
+    :param data: Mapping of column name to the new value for every row. Must
+        be non-empty and may not name a primary-key column.
+    :param session_inst: SQLModel AsyncSession instance.
+    :param model: SQLModel class representing the table.
+    :param pk_field: Primary-key column to match against (default: "id").
+    :param chunk_size: Maximum IDs per UPDATE statement (default: 500).
+    :return: Tuple[bool, int]: ``True`` and the number of rows matched by the
+        update. The count is 0 when nothing matched or the list was empty.
+    :raises ValueError: If ``pk_field`` is not a primary-key column,
+        ``data`` is empty or names an unknown or primary-key column, or
+        ``chunk_size`` is not positive.
+    :raises Exception: Any database error, after the transaction has been
+        rolled back and the error logged.
+    """
+    validate_primary_key_field(model, pk_field)
+    validate_update_columns(model, data)
+    updated = 0
+    try:
+        for chunk in chunked(id_str_list, chunk_size):
+            stmnt = (
+                update(model)
+                .where(getattr(model, pk_field).in_(chunk))
+                .values(**data)
+            )
+            result = await session_inst.exec(stmnt)
+            updated += max(result.rowcount, 0)
+        await session_inst.commit()
+    except Exception as e:
+        await session_inst.rollback()
+        logger.error(f"Failed to bulk update rows: {type(e)}, {e}")
+        raise
+
+    return True, updated
+
+
 async def delete_row(
     id_str: str | int,
     session_inst: AsyncSession,
@@ -482,12 +600,25 @@ async def bulk_upsert_mappings(
     pk_fields: list[str] | None = None,
 ):
     """
-
-    :param payload:
-    :param session_inst:
-    :param model:
-    :param pk_fields:
-    :return:
+    Insert or update a batch of rows in a single ``INSERT ... ON CONFLICT DO
+    UPDATE ... RETURNING`` statement.
+
+    The ``RETURNING`` rows are fully read (``.all()``) before ``commit()``.
+    SQLite refuses to commit while a result cursor is still unread
+    ("cannot commit transaction - SQL statements in progress"); Postgres
+    tolerates it. The upsert is also executed exactly once rather than once
+    bare and once more to fetch the rows.
+
+    Returned instances are expired by ``commit()`` when the session uses
+    ``expire_on_commit=True`` (the default), so read their attributes while
+    the session is open or create the session with ``expire_on_commit=False``.
+
+    :param payload: Row mappings to upsert; the first mapping's keys decide
+        which columns are overwritten on conflict.
+    :param session_inst: Active session.
+    :param model: Table model being upserted.
+    :param pk_fields: Conflict-target columns. Defaults to ``["id"]``.
+    :return: ``(True, rows)`` where ``rows`` are the upserted model instances.
     """
     if not pk_fields:
         pk_fields = ["id"]
@@ -496,15 +627,16 @@ async def bulk_upsert_mappings(
         index_elements=[getattr(model, x) for x in pk_fields],
         set_={k: getattr(stmnt.excluded, k) for k in payload[0].keys()},
     )
-    await session_inst.exec(stmnt)
-
-    results = await session_inst.scalars(
-        stmnt.returning(model), execution_options={"populate_existing": True}
-    )
+    results = (
+        await session_inst.scalars(
+            stmnt.returning(model),
+            execution_options={"populate_existing": True},
+        )
+    ).all()
 
     await session_inst.commit()
 
-    return True, results.all()
+    return True, results
 
 
 async def update_row(

{sqlmodel_crud_utilities-0.2.0 → sqlmodel_crud_utilities-0.3.0}/sqlmodel_crud_utils/mixins.py

@@ -7,6 +7,8 @@ functionality like audit trails and soft delete support.
 from datetime import datetime, timezone
 from typing import Optional
 
+from sqlalchemy import Column, DateTime, func
+from sqlalchemy.orm import declared_attr
 from sqlmodel import Field
 
 
@@ -15,6 +17,47 @@ def _utc_now() -> datetime:
     return datetime.now(timezone.utc)
 
 
+class TimestampMixin:
+    """Lightweight mixin adding only ``created_at`` and ``updated_at``.
+
+    Use this instead of ``AuditMixin`` when there is no user context to
+    record. Each column is produced by ``declared_attr``, so SQLAlchemy
+    builds a fresh ``Column`` for every concrete ``table=True`` model and
+    the mixin can safely be applied to any number of models.
+
+    Both columns use ``server_default=func.now()``, so the database fills
+    them even for inserts that bypass Python-side defaults, such as
+    ``bulk_insert_mappings`` or raw ``INSERT`` statements. ``updated_at``
+    additionally refreshes through ``onupdate=func.now()`` on ORM updates.
+
+    The ``declared_attr`` methods intentionally carry no return
+    annotations: SQLAlchemy's annotated-declarative scanner would treat
+    them as bare field annotations and raise ``MappedAnnotationError``.
+
+    Example:
+        >>> class Location(TimestampMixin, SQLModel, table=True):
+        ...     id: Optional[int] = Field(default=None, primary_key=True)
+        ...     name: str
+    """
+
+    @declared_attr
+    def created_at(cls):
+        return Column(
+            DateTime(timezone=True),
+            server_default=func.now(),
+            nullable=False,
+        )
+
+    @declared_attr
+    def updated_at(cls):
+        return Column(
+            DateTime(timezone=True),
+            server_default=func.now(),
+            onupdate=func.now(),
+            nullable=False,
+        )
+
+
 class AuditMixin:
     """Mixin for automatic audit trail tracking.