python-general-be-lib 0.12.0__py3-none-any.whl → 0.12.2__py3-none-any.whl

general/interface/metadata/crud_metadata.py

@@ -11,7 +11,7 @@ from sqlalchemy.sql.functions import count
 from ...exception.crud_exceptions import BadRequestException, EntityNotFoundException, HasNoAttributeException, InternalServerException, raise_http_exception
 from ...interface.repository.handler.base_handler import BaseHandler
 from ...interface.repository.handler.statement_manager import StatementManager
-from ...paginator_dto import PaginatorResponseModel, parse_pagination
+from ...paginator_dto import PaginatorResponseModel, parse_pagination, _with_tiebreaker
 
 
 class CrudMetadata:
@@ -865,14 +865,17 @@ class CrudMetadata:
             page (int): Requested page number, 1-based. Default: 1.
             parsing_model (Type[BaseModel], optional): Model each row is serialized with.
             orders_by (dict[str, bool], optional): Ordering, as ``{column: ascending}``,
-                with the clauses following the insertion order of the dictionary. When
-                omitted no ordering is applied, and without a total order two pages can
-                overlap.
+                with the clauses following the insertion order of the dictionary. The
+                primary key columns missing from it are appended, ascending, as a
+                tie-breaker, so that two pages cannot overlap; a key column already
+                passed keeps its position and direction. A table without a primary key,
+                such as a reflected view, gets no tie-breaker. When omitted no ordering
+                is applied at all, and the pages are not stable.
             **kwhere: Additional filters as keyword arguments.
 
         Returns:
             PaginatorResponseModel: Object carrying ``data``, ``tot_pages``, ``page``,
-                ``limit`` and the ordering.
+                ``limit`` and the ordering requested, without the tie-breaker.
 
         Raises:
             HasNoAttributeException: If the table or one of the columns does not exist.
@@ -891,6 +894,9 @@ class CrudMetadata:
                      orders_by: dict[str, bool] = None, **kwhere) -> PaginatorResponseModel:
         """Read the page and derive the total, running the ``COUNT`` only when needed.
 
+        A non-empty ordering gets the missing primary key columns appended, ascending, so
+        that it is total; the response reports it as requested, without them.
+
         Args:
             table (Table): Table to search on.
             connection (Connection): Connection to run the statements on.
@@ -898,7 +904,8 @@ class CrudMetadata:
             columns (list[str], optional): Columns to select.
             limit (int): Rows per page. 0 means no limit.
             page (int): Page number, 1-based.
-            orders_by (dict[str, bool], optional): Ordering to apply.
+            orders_by (dict[str, bool], optional): Ordering requested. When empty,
+                nothing is ordered.
             **kwhere: Additional filters as keyword arguments.
 
         Returns:
@@ -911,8 +918,9 @@ class CrudMetadata:
 
         manager = self._statement_manager(table)
         stmt = self._select(table=table, columns=columns)
-        stmt = self._add_orders_by_condition(stmt, table, orders_by)
-        stmt = manager.limit_offset_condition(stmt=stmt, limit=limit,page=page)
+        if orders_by:
+            stmt = self._add_orders_by_condition(stmt, table, _with_tiebreaker(orders_by, table.primary_key.columns.keys()))
+        stmt = manager.limit_offset_condition(stmt=stmt, limit=limit, page=page)
         conditions = manager.conditions(where=dict(where))
         if conditions:
             stmt = stmt.where(*conditions)

general/interface/repository/crud_repository.py

@@ -16,7 +16,7 @@ from .handler.base_handler import BaseHandler
 from .handler.statement_manager import StatementManager
 from ...exception.crud_exceptions import BadRequestException, EntityNotFoundException, HasNoAttributeException, raise_http_exception
 from ...interface.base.declarative_base import Base
-from ...paginator_dto import PaginatorResponseModel, parse_pagination
+from ...paginator_dto import PaginatorResponseModel, parse_pagination, _with_tiebreaker
 
 
 @lru_cache(maxsize=None)
@@ -169,14 +169,23 @@ class CrudRepository[Entity: Base | Type[Base]]:
         return _reduced_model(self.entity, frozenset(selected_columns))
 
     def _handle_exception(self, session: Session, e: Exception):
-        """Close the session, log the error and raise an HTTP-friendly exception.
+        """Roll back and close the session, log the error and raise an HTTP-friendly exception.
 
         An ``OperationalError`` becomes a ``ServiceUnavailableException``, a
         ``NoResultFound`` an ``EntityNotFoundException``, a ``DataError`` or an
         ``IntegrityError`` a ``BadRequestException``; any other exception is re-raised as is.
 
+        ``close`` alone already rolls back the database transaction. What the explicit
+        ``rollback`` adds is the expiry of the ORM instances: an entity still held by the
+        caller raises ``DetachedInstanceError`` on access instead of exposing values that
+        were flushed but never committed. It runs on every error, a failed SELECT included,
+        since on PostgreSQL that aborts the transaction as well. An external session is
+        rolled back and closed too, so the caller's transaction is lost. A failure of the
+        rollback itself is logged and does not replace ``e``, and the session is closed
+        anyway.
+
         Args:
-            session (Session): Session to close.
+            session (Session): Session to roll back and close.
             e (Exception): Caught exception to handle.
 
         Raises:
@@ -184,6 +193,11 @@ class CrudRepository[Entity: Base | Type[Base]]:
             EntityNotFoundException: If no record matches.
             BadRequestException: If the data is malformed or violates a constraint.
         """
+        try:
+            session.rollback()
+        except Exception:
+            # un rollback fallito non deve sostituire l'errore originale, né saltare la close
+            logging.exception("Rollback failed")
         session.close()
         logging.error(e)
         raise_http_exception(e)
@@ -195,12 +209,13 @@ class CrudRepository[Entity: Base | Type[Base]]:
             session (Session): Session to commit.
 
         Raises:
-            ServiceUnavailableException | BadRequestException: On error during the commit.
+            ServiceUnavailableException | BadRequestException: On error during the commit,
+                after rolling back and closing the session.
         """
         try:
             session.commit()
         except Exception as e:
-            self._handle_exception(session, e)
+            self._handle_exception(session=session, e=e)
 
     def _flush(self, session: Session):
         """Flush the session, handling the possible exceptions.
@@ -214,12 +229,13 @@ class CrudRepository[Entity: Base | Type[Base]]:
             session (Session): Session to flush.
 
         Raises:
-            ServiceUnavailableException | BadRequestException: On error during the flush.
+            ServiceUnavailableException | BadRequestException: On error during the flush,
+                after rolling back and closing the session.
         """
         try:
             session.flush()
         except Exception as e:
-            self._handle_exception(session, e)
+            self._handle_exception(session=session, e=e)
 
     def _entity_has_columns(self, *columns: str, entity: Type[Base] | Base = None) -> bool:
         """Check that every given name is a column of the entity.
@@ -441,7 +457,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
             try:
                 entity = session.get(self.entity, values)
             except Exception as e:
-                self._handle_exception(session, e)
+                self._handle_exception(session=session, e=e)
             else:
                 return [entity] if entity is not None else []
 
@@ -607,7 +623,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
         try:
             session.add_all(entities)
         except Exception as e:
-            self._handle_exception(session, e)
+            self._handle_exception(session=session, e=e)
         return self._return(session=session, entities=entities, keep_open=keep_open, commit=True, parsing_model=parsing_model)
 
     def update(self, session: Session = None, where: dict[str, Any] = None, returning: bool = True, parsing_model: Type[BaseModel] | BaseModel = None, **kwargs) -> list[Entity] | list[BaseModel]:
@@ -869,22 +885,25 @@ class CrudRepository[Entity: Base | Type[Base]]:
                 therefore a single page.
             page (int): Requested page number, 1-based. Default: 1.
             order_by (str, optional): Column to order by. When ``None``, the first column of
-                the primary key is used.
+                the primary key is used, followed by the other ones if the key is
+                composite.
             asc (bool): Ascending order if ``True``. Default: ``True``.
             parsing_model (Type[BaseModel], optional): Alternative model for the
                 serialization.
             orders_by (dict[str, bool], optional): Ordering on several columns, as
                 ``{column: ascending}``, with the clauses following the insertion order of
                 the dictionary. Takes precedence over ``order_by``/``asc``. The primary key
-                is **not** appended as a tie-breaker, so an ordering on a non-unique column
-                does not give a total order and two pages can overlap: pass the key
-                explicitly as the last entry when the ordering must be stable.
+                columns missing from the ordering are appended, ascending, as a
+                tie-breaker: an ordering on a non-unique column is not total, and with
+                ``LIMIT/OFFSET`` two pages could overlap and some rows never show up. A
+                key column the caller already passed keeps its position and direction.
             **kwhere: Filters as keyword arguments.
 
         Returns:
             PaginatorResponseModel[Entity]: Object carrying ``data``, ``tot_pages``,
                 ``page``, ``limit``, ``orders_by``, plus ``order_by`` and ``asc`` holding
-                the first pair of the ordering.
+                the first pair of the ordering. ``orders_by`` is the ordering requested,
+                without the appended tie-breaker.
         """
         keep_open = False if session is None else True
         session = self.open_session if session is None else session
@@ -897,15 +916,36 @@ class CrudRepository[Entity: Base | Type[Base]]:
         return paginated
 
     def _paging_find(self, session: Session, where: dict[str, Any] = None, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 0, page: int = 1, orders_by: dict[str, bool] = None, **kwhere):
+        """Read the page with a total ordering and derive the total, counting only when needed.
+
+        The primary key columns missing from ``orders_by`` are appended to the ``ORDER BY``,
+        ascending, so that ``LIMIT/OFFSET`` cuts every page from the same sequence of rows.
+        The response reports ``orders_by`` as requested, without them.
+
+        Args:
+            session (Session): Session to run the statements on.
+            where (dict[str, Any], optional): Filters. When ``None``, ``**kwhere`` is used.
+            columns (list[str], optional): Columns to include.
+            exclude_columns (list[str], optional): Columns to exclude.
+            limit (int): Rows per page. 0 means no limit.
+            page (int): Page number, 1-based.
+            orders_by (dict[str, bool], optional): Ordering requested, as
+                ``{column: ascending}``. When empty, the primary key ascending.
+            **kwhere: Filters as keyword arguments.
+
+        Returns:
+            PaginatorResponseModel: Page and total, with the raw entities as ``data``.
+        """
         if where is None:
             where = kwhere if kwhere else {}
+        primary_key = [column.key for column in self.entity.primary_key()]
         if not orders_by:
-            orders_by = {self.entity.primary_key()[0].key: True}
+            orders_by = {primary_key[0]: True}
 
         stmt = self._select(entity=self.entity, columns=columns, exclude_columns=exclude_columns)
         stmt = self.stmt_manager.limit_offset_condition(stmt=stmt, limit=limit, page=page)
 
-        for order_by, asc in orders_by.items():
+        for order_by, asc in _with_tiebreaker(orders_by, primary_key).items():
             stmt = self.stmt_manager.order_by_condition(stmt=stmt, order_by=order_by, asc=asc)
 
         conditions = self.stmt_manager.conditions(where=where)
@@ -1049,9 +1089,9 @@ class CrudRepository[Entity: Base | Type[Base]]:
         """Execute a SQLAlchemy statement and return the result as it is.
 
         The method owns the error handling and nothing else: every exception goes to
-        ``_handle_exception``, which closes the session and maps the error to an HTTP
-        status. Reading the result is left to the caller, which is the only one knowing the
-        shape it needs — ``.scalars().all()`` for entities, ``.scalar()`` for an aggregate,
+        ``_handle_exception``, which rolls back and closes the session and maps the error
+        to an HTTP status. Reading the result is left to the caller, which is the only one
+        knowing the shape it needs — ``.scalars().all()`` for entities, ``.scalar()`` for an aggregate,
         ``.all()`` for the multi-column rows of a statement built with ``add_columns``,
         ``.rowcount`` for a DML without ``RETURNING``. The result is bound to the session,
         so it has to be consumed before the session is closed. ``Session.execute`` returns
@@ -1076,6 +1116,6 @@ class CrudRepository[Entity: Base | Type[Base]]:
         try:
             result = session.execute(statement=stmt, params=values)
         except Exception as e:
-            self._handle_exception(session, e)
+            self._handle_exception(session=session, e=e)
         else:
             return result

general/paginator_dto.py

@@ -1,7 +1,7 @@
 __all__ = ["PaginatorRequestModel", "PaginatorResponseModel", "parse_pagination"]
 
 import math
-from typing import Any, Optional, Sequence
+from typing import Any, Iterable, Optional, Sequence
 
 from pydantic import Field
 
@@ -46,9 +46,11 @@ class PaginatorResponseModel[ResponseType](PaginatorBaseModel):
     Attributes:
         tot_pages (int): Total number of pages, computed by the repository.
             Alias: ``pagineTotali``.
-        orders_by (dict[str, bool] | None): Whole ordering applied, as
+        orders_by (dict[str, bool] | None): Whole ordering requested, as
             ``{column: ascending}``. The inherited ``order_by``/``asc`` carry its first
-            pair, which is the main criterion. Alias: ``campiOrdinamento``.
+            pair, which is the main criterion. The primary key columns that
+            ``paging_find`` appends as a tie-breaker are not listed: they are an
+            internal detail of the query. Alias: ``campiOrdinamento``.
         data (list[ResponseType]): Items of the current page.
     """
 
@@ -70,7 +72,7 @@ def parse_pagination(limit: int, page: int, orders_by: dict[str, bool], count: i
     Args:
         limit (int): Number of items per page.
         page (int): Current page.
-        orders_by (dict[str, bool]): Ordering applied, as ``{column: ascending}``.
+        orders_by (dict[str, bool]): Ordering requested, as ``{column: ascending}``.
         count (int): Total number of filtered records.
         data (Sequence): Rows of the current page.
 
@@ -83,3 +85,27 @@ def parse_pagination(limit: int, page: int, orders_by: dict[str, bool], count: i
     tot_pages = math.ceil(count / limit) if count and limit > 0 else 1
 
     return PaginatorResponseModel(limit=limit, page=page, order_by=order_by, asc=asc, tot_pages=tot_pages, orders_by=orders_by, data=data)
+
+
+def _with_tiebreaker(orders_by: dict[str, bool], keys: Iterable[str]) -> dict[str, bool]:
+    """Append to an ordering the key columns it does not contain yet, ascending.
+
+    ``LIMIT/OFFSET`` over an ordering that is not total is unstable: the database may
+    return the rows tied on the ordering columns in a different order from one query to
+    the next, so consecutive pages overlap and some rows are never shown. Appending the
+    primary key makes the ordering total. A key column the caller already ordered by is
+    left where it is and with its direction, since the ordering is total from that point
+    on anyway. Shared by the ORM and the metadata layer.
+
+    Args:
+        orders_by (dict[str, bool]): Ordering as ``{column: ascending}``. Never mutated.
+        keys (Iterable[str]): Names of the primary key columns, as the statement
+            manager resolves them. Empty when the table has no primary key, in which case
+            the ordering is returned as it is.
+
+    Returns:
+        dict[str, bool]: ``orders_by`` itself when nothing is missing, otherwise a new
+            dictionary with the missing key columns appended as ``True``.
+    """
+    missing = [key for key in keys if key not in orders_by]
+    return {**orders_by, **dict.fromkeys(missing, True)} if missing else orders_by

{python_general_be_lib-0.12.0.dist-info → python_general_be_lib-0.12.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.12.0
+Version: 0.12.2
 Summary: General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, Keycloak JWT auth, logger utilities.
 Author-email: Andrea Di Placido <a.diplacido@arpes.it>, "Arpes S.r.l." <it.admin@arpes.it>
 License: MIT

{python_general_be_lib-0.12.0.dist-info → python_general_be_lib-0.12.2.dist-info}/RECORD

@@ -1,7 +1,7 @@
 general/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 general/context.py,sha256=AbASV-jPnDM-M-Nih5c9vKHFlIS0kjp8Q1yuHC34FeA,1925
 general/logger.py,sha256=MnK8ZDA9x4xhX0KcpOxTieosnFIhFVwSa8b52Q4T9tA,5039
-general/paginator_dto.py,sha256=DB2hfcrckuEiHEIORLT4EgCcnX4AYYKGlHRr-l-Q1Cw,3741
+general/paginator_dto.py,sha256=0aIdJIOXJlwoQ3d7w8A6tOZ1An6AWBjoHMhIqtZJhic,5221
 general/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 general/auth/__init__.py,sha256=6cYCA6Ir-nnBK9z_bUfh_io3wEYjJUwHAN8mdhjtKeI,2239
 general/auth/jwt_model.py,sha256=KcopeNUPRSQOLvreoIuSo6kJybRtrmhzLoJ5oHFngGw,3447
@@ -17,14 +17,14 @@ general/interface/base/__init__.py,sha256=wRKbvb8lF33_2iG100mEQXz1tEkh9BF5bPcIi7
 general/interface/base/base_model.py,sha256=aIzrRZVUytmbgmEH1bya29rVFOm-Njinn_JXkgkBrr8,2575
 general/interface/base/declarative_base.py,sha256=J-q6nJIdYixFk9tgWjmGVII2cHeOazf0e4snaO_rHhI,9302
 general/interface/metadata/__init__.py,sha256=CawnfGK7WcJmtqi9CjEjBqCyX_vuHFK-Td1orXTH__U,1849
-general/interface/metadata/crud_metadata.py,sha256=SfV2__zgkTTeX1opLHDMRIeyB1DKiObr7pGOHkGVFlo,48120
+general/interface/metadata/crud_metadata.py,sha256=4pK4ptX5w0HYv2DK8sj4cJeVfnGJRz9lAjiWgGvYyhs,48763
 general/interface/metadata/geom_metadata.py,sha256=xWNZnWhN_Om91pcqSsURKi5EUYNZh444zDqMwoOpq84,15508
 general/interface/mixin/__init__.py,sha256=M5-e6T_R63Utwh3_WcmoE3wanwIZjNjbgLYrrFlSpTA,659
 general/interface/mixin/audit_mixin.py,sha256=N2JDD9JxXDMeBqu0yAlhVWFOK3EeUA2b215hPvXytUU,1421
 general/interface/mixin/softdelete_mixin.py,sha256=526luzM4DBCorcq99kZ6BYqtQKKJCpnxX9rSEigfyIU,2148
 general/interface/mixin/timestamp_mixin.py,sha256=wmcIx2Y8jgVqg9A-1E61BvkcKCo52ZjKNHeKfXJmUl0,2220
 general/interface/repository/__init__.py,sha256=QQD6okLfRozC0uOZPGrwOUDKJyZTgpObvwJ3OOSJdbM,1813
-general/interface/repository/crud_repository.py,sha256=Hr7APBsN1uFqEfM78ZSIcgheg4ilvND4OMc7TBNOlcw,55962
+general/interface/repository/crud_repository.py,sha256=W1kZyMw1VCOhbDYS5YpDBgXez0-0pzy6xFgcbR1Scb0,58469
 general/interface/repository/geometry_repository.py,sha256=Fmv0qhfqumnU5fiETMMAmiB0UyG43b19jlPXQ8cJ9CU,11289
 general/interface/repository/many_to_many_repository.py,sha256=KRJ2SMUGDYNoGV-ea541wlWg0FW4NQ_Ry85aJBarmC8,11183
 general/interface/repository/view_repository.py,sha256=wxDGw7kenuVrDd9nfh7-omw2m9Jex5WzF_lhEiqPoA0,7902
@@ -40,8 +40,8 @@ general/interface/repository/handler/soft_delete_handler.py,sha256=1WD1n6q5plyJ0
 general/interface/repository/handler/statement_manager.py,sha256=JSj6K-iQJ06kLdsMTOqK62cIvR87ioOA1LmLTGpqrB0,8205
 general/utils/__init__.py,sha256=_SPe88reIZ0JxwK7mp-u_p-9c4hCcZ-daUihi0gymNk,103
 general/utils/consts.py,sha256=nE75Ud7sVuDw9K_xmIJNjL_5f_BVJmwGNPGFYc26H3Y,264
-python_general_be_lib-0.12.0.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
-python_general_be_lib-0.12.0.dist-info/METADATA,sha256=5RrV-gffYJqAwx09wHOCqK-xN7GDSqK7dKgeP7Rfcyk,3995
-python_general_be_lib-0.12.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_general_be_lib-0.12.0.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
-python_general_be_lib-0.12.0.dist-info/RECORD,,
+python_general_be_lib-0.12.2.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
+python_general_be_lib-0.12.2.dist-info/METADATA,sha256=y3oeQsu0X1IYTfpOIE4pblBBEvMr9KQu8psiK4TIeiQ,3995
+python_general_be_lib-0.12.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_general_be_lib-0.12.2.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
+python_general_be_lib-0.12.2.dist-info/RECORD,,

{python_general_be_lib-0.12.0.dist-info → python_general_be_lib-0.12.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any