python-general-be-lib 0.12.1__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)
@@ -885,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
@@ -913,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)

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.1.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.1
+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.1.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=Z7IgLz7dtfIyzZMJO7T_IDunHH1qTDYRApdWlbMkE2A,57031
+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.1.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
-python_general_be_lib-0.12.1.dist-info/METADATA,sha256=8T5p8u9J9MUHT1xZjRf_Ss29Y97hEeJX5wZD71aVTyI,3995
-python_general_be_lib-0.12.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
-python_general_be_lib-0.12.1.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
-python_general_be_lib-0.12.1.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,,