python-general-be-lib 0.9.0__py3-none-any.whl → 0.9.1__py3-none-any.whl

general/interface/repository/crud_repository.py

@@ -317,7 +317,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
         return True
 
     def find(self, session: Session = None, where: dict[str, Any] = None, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 0, parsing_model: Type[BaseModel] = None, order_by: str = None,
-             asc: bool = None, **kwhere) -> list[Entity]:
+             asc: bool = None, orders_by: dict[str, bool] = None, **kwhere) -> list[Entity]:
         """Find the records matching the given criteria.
 
         The filters can be passed as a ``where`` dictionary or as keyword arguments. Being a
@@ -337,6 +337,11 @@ class CrudRepository[Entity: Base | Type[Base]]:
                 ``None``, no ordering is applied.
             asc (bool, optional): Ordering direction, ``True`` for ASC and ``False`` for
                 DESC. When ``None``, the default ordering is DESC.
+            orders_by (dict[str, bool], optional): Ordering on several columns, as
+                ``{column: ascending}``. The clauses follow the insertion order of the
+                dictionary. Takes precedence over ``order_by``/``asc``. The keys are
+                database column names, unlike ``columns``, which takes Python attribute
+                names.
             **kwhere: Additional filters as keyword arguments.
 
         Returns:
@@ -344,22 +349,26 @@ class CrudRepository[Entity: Base | Type[Base]]:
                 given.
 
         Raises:
-            HasNoAttributeException: If a column in ``columns``, ``exclude_columns`` or
-                ``order_by`` does not exist on the entity.
+            HasNoAttributeException: If a column in ``columns``, ``exclude_columns``,
+                ``order_by`` or ``orders_by`` does not exist on the entity.
         """
 
         keep_open = False if session is None else True
         session = self.open_session if session is None else session
-        entities = self._find(session=session, where=where, columns=columns, exclude_columns=exclude_columns, limit=limit, order_by=order_by, asc=asc, **kwhere)
+        if order_by is not None and orders_by is None:
+            orders_by = {order_by: asc if asc is not None else False}
+        entities = self._find(session=session, where=where, columns=columns, exclude_columns=exclude_columns, limit=limit, orders_by=orders_by, **kwhere)
         parsing_model = parsing_model if parsing_model is not None else self._retrieve_parsing_model(columns=columns, exclude_columns=exclude_columns)
         return self._return(session=session, entities=entities, keep_open=keep_open, commit=False, parsing_model=parsing_model)
 
-    def _find(self, session: Session, where: dict[str, Any] = None, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 0, order_by: str = None,
-              asc: bool = None, **kwhere):
+    def _find(self, session: Session, where: dict[str, Any] = None, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 0, orders_by: dict[str, bool] = None, **kwhere):
         if where is None:
             where = kwhere if kwhere else {}
+        if orders_by is None:
+            orders_by = {}
         stmt = self._select(entity=self.entity, columns=columns, exclude_columns=exclude_columns)
-        stmt = self.stmt_manager.order_by_condition(stmt=stmt, order_by=order_by, asc=asc)
+        for order_by, asc in orders_by.items():
+            stmt = self.stmt_manager.order_by_condition(stmt=stmt, order_by=order_by, asc=asc)
         stmt = self.stmt_manager.limit_offset_condition(stmt=stmt, limit=limit)
 
         stmt = self.stmt_manager.prepare_statement(stmt=stmt, **where)
@@ -626,7 +635,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
         return session.execute(stmt).scalar()
 
     def paging_find(self, session: Session = None, where: dict[str, Any] = None, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 0, page: int = 1, order_by: str = None, asc: bool = True,
-                    parsing_model: Type[BaseModel] = None, **kwhere) -> PaginatorResponseModel[Entity]:
+                    parsing_model: Type[BaseModel] = None, orders_by: dict[str, bool] = None, **kwhere) -> PaginatorResponseModel[Entity]:
         """Run a paginated search with ordering and offset support.
 
         Computes the total number of pages and returns the requested page only. The data
@@ -650,30 +659,40 @@ class CrudRepository[Entity: Base | Type[Base]]:
             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.
             **kwhere: Filters as keyword arguments.
 
         Returns:
             PaginatorResponseModel[Entity]: Object carrying ``data``, ``tot_pages``,
-                ``page``, ``limit``, ``order_by`` and ``asc``.
+                ``page``, ``limit``, ``orders_by``, plus ``order_by`` and ``asc`` holding
+                the first pair of the ordering.
         """
         keep_open = False if session is None else True
         session = self.open_session if session is None else session
-        paginated = self._paging_find(session=session, where=where, columns=columns, exclude_columns=exclude_columns, limit=limit, page=page, order_by=order_by, asc=asc, **kwhere)
+        orders_by = orders_by if orders_by else {order_by or self.entity.primary_key()[0].key: asc if asc is not None else False}
+        paginated = self._paging_find(session=session, where=where, columns=columns, exclude_columns=exclude_columns, limit=limit, page=page, orders_by=orders_by, **kwhere)
         parsing_model = parsing_model if parsing_model is not None else self._retrieve_parsing_model(columns=columns, exclude_columns=exclude_columns)
         if not keep_open:
             paginated.data = _list_adapter(parsing_model).validate_python(paginated.data, from_attributes=True)
             session.close()
         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, order_by: str = None, asc: bool = True, **kwhere):
+    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):
         if where is None:
             where = kwhere if kwhere else {}
+        if not orders_by:
+            orders_by = {self.entity.primary_key()[0].key: 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)
 
-        order_by = order_by or self.entity.primary_key()[0].name
-        stmt = self.stmt_manager.order_by_condition(stmt=stmt, order_by=order_by, asc=asc)
+        for order_by, asc in orders_by.items():
+            stmt = self.stmt_manager.order_by_condition(stmt=stmt, order_by=order_by, asc=asc)
 
         conditions = self.stmt_manager.conditions(where=where)
         if conditions:
@@ -690,20 +709,22 @@ class CrudRepository[Entity: Base | Type[Base]]:
         else:
             count_ = self._preconf_count(session=session, where=conditions)
 
-        return self.parse_pagination(limit=limit, page=page, order_by=order_by, count=count_, asc=asc, data=entities)
+        return self.parse_pagination(limit=limit, page=page, orders_by=orders_by, count=count_, data=entities)
 
-    def parse_pagination(self, limit: int, page: int, order_by: str, asc: bool, count: int, data: Sequence[Row] | Sequence[Row | RowMapping] | Sequence[RowMapping]) -> PaginatorResponseModel:
+    def parse_pagination(self, limit: int, page: int, orders_by: dict[str, bool], count: int, data: Sequence[Row] | Sequence[Row | RowMapping] | Sequence[RowMapping]) -> PaginatorResponseModel:
         """Build the ``PaginatorResponseModel`` from the pagination data.
 
         Computes the total number of pages. When ``limit`` is 0, meaning no limit, the
-        length of the data is used as the effective limit; when ``order_by`` is not given,
-        the primary key is used as the default ordering field.
+        length of the data is used as the effective limit. The response carries the whole
+        ``orders_by`` plus its first pair as ``order_by``/``asc``, which are the fields the
+        clients read as the main ordering criterion.
 
         Args:
             limit (int): Number of items per page.
             page (int): Current page.
-            order_by (str): Ordering field used.
-            asc (bool): Ordering direction.
+            orders_by (dict[str, bool]): Ordering applied, as ``{column: ascending}``. Its
+                first pair fills ``order_by``/``asc``; when empty both stay ``None``,
+                because no ordering was applied.
             count (int): Total number of filtered records.
             data (Sequence): Entities of the current page.
 
@@ -711,10 +732,11 @@ class CrudRepository[Entity: Base | Type[Base]]:
             PaginatorResponseModel: Complete paginated response.
         """
         limit = limit if limit else len(data)
-        order_by = order_by if order_by else self.entity.primary_key()[0].name
+        order_by = next(iter(orders_by), None) if orders_by else None
+        asc = orders_by.get(order_by) if order_by is not None else None
         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, data=data)
+        return PaginatorResponseModel(limit=limit, page=page, order_by=order_by, asc=asc, tot_pages=tot_pages, orders_by=orders_by, data=data)
 
     def distinct_pairs(self, key: str, value: str, session: Session = None, where: dict[str, Any] = None, **kwhere) -> list[Row] | None:
         """Return the distinct ``(key, value)`` pairs of the records matching ``where``.

general/interface/repository/handler/statement_manager.py

@@ -113,12 +113,19 @@ class StatementManager:
         return stmt
 
     def order_by_condition(self, stmt: Select, order_by: str, asc: bool):
-        """Add the ORDER BY clause to the statement.
+        """Add one ORDER BY clause to the statement.
+
+        Adds a single criterion and can be called repeatedly to build an ordering on
+        several columns: ``Select.order_by`` appends, so the clauses keep the order of the
+        calls. The column name is resolved against the table columns, so a name that is
+        not a column cannot reach the SQL.
 
         Args:
             stmt (Select): Select statement to add the ordering to.
-            order_by (str): Name of the column to order by.
-            asc (bool): If ``True``, ascending order (ASC); if ``False``, descending (DESC).
+            order_by (str): Database name of the column to order by. Falsy values leave the
+                statement untouched.
+            asc (bool): If ``True``, ascending order (ASC); if ``False`` or ``None``,
+                descending (DESC).
 
         Returns:
             Select: Statement with the ORDER BY clause added.

general/paginator_dto.py

@@ -18,12 +18,12 @@ class PaginatorBaseModel(ExtBaseModel):
         page (int): Current page number, 1-based. Alias: ``numeroPagina``.
         limit (int | None): Number of items per page. Alias: ``numeroElementi``.
         order_by (str | None): Field used for the ordering. Alias: ``campoOrdinamento``.
-        asc (bool): Ascending order if ``True``. Alias: ``crescente``.
+        asc (bool | None): Ascending order if ``True``. Alias: ``crescente``.
     """
     page: int = Field(alias="numeroPagina")
     limit: Optional[int] = Field(default=None, alias="numeroElementi")
     order_by: Optional[str] = Field(default=None, alias="campoOrdinamento")
-    asc: bool = Field(alias="crescente")
+    asc: Optional[bool] = Field(default=None, alias="crescente")
 
 
 class PaginatorRequestModel(PaginatorBaseModel):
@@ -45,8 +45,12 @@ 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
+            ``{column: ascending}``. The inherited ``order_by``/``asc`` carry its first
+            pair, which is the main criterion. Alias: ``campiOrdinamento``.
         data (list[ResponseType]): Items of the current page.
     """
 
     tot_pages: int = Field(alias="pagineTotali")
+    orders_by: Optional[dict[str, bool]] = Field(default=None, alias="campiOrdinamento")
     data: list[ResponseType]

{python_general_be_lib-0.9.0.dist-info → python_general_be_lib-0.9.1.dist-info}/METADATA

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.9.0
+Version: 0.9.1
 Summary: General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, logger utilities.
 Author-email: Andrea Di Placido <a.diplacido@arpes.it>, "Arpes S.r.l." <it.admin@arpes.it>
 License: MIT
 Project-URL: Homepage, https://github.com/Arpes-IS/python-general-be-lib
 Project-URL: Repository, https://github.com/Arpes-IS/python-general-be-lib
+Project-URL: Changelog, https://github.com/Arpes-IS/python-general-be-lib/blob/main/CHANGELOG.md
 Keywords: backend,sqlalchemy,fastapi,pydantic,repository,crud,geoalchemy2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers

{python_general_be_lib-0.9.0.dist-info → python_general_be_lib-0.9.1.dist-info}/RECORD

@@ -1,6 +1,6 @@
 general/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 general/logger.py,sha256=P-7-BLtO1XC2m43wXrnJcTakr2iZBE0gUkMVppJ9exE,4506
-general/paginator_dto.py,sha256=uHMC5fEPZL9It8xY3g4JdGzoH4DXNmrff00DOOgtsgc,1912
+general/paginator_dto.py,sha256=ug2KJMPQRgxcwTu8-MvuLi7MwvmkHDG9cHwfp6EzqIg,2267
 general/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 general/exception/__init__.py,sha256=3o5KaoCwA020aG0GIR0jOA4t_ibOBiji0xMxZx4uNug,745
 general/exception/access_exceptions.py,sha256=tNIBjxM0-5iSOXDc7Il01eb36mEk-POQGVaHhCpG278,744
@@ -14,7 +14,7 @@ general/interface/metadata/__init__.py,sha256=pXKYY4uO92eQI3gtuG4FKZbBi76gu-VJLx
 general/interface/metadata/crud_metadata.py,sha256=i6ldkyUqjHPerninf--sQlGyUm18FgzIBmDq55UYz0g,22819
 general/interface/metadata/geom_metadata.py,sha256=thfVc0hyKgkTFIQrRaX6khf_NbEHyEkc-zUA7nO8bI8,11918
 general/interface/repository/__init__.py,sha256=eWoNy35LVu6sDrK5ju7VAeoclknKO0-yTgjVckJpi8s,321
-general/interface/repository/crud_repository.py,sha256=r9xq8YTS_GKKhnVPLPdajzo04ID2v0L9ajSb3bNknvI,38288
+general/interface/repository/crud_repository.py,sha256=CH05WG6ZKkDpS5DEB_718AoRqJUS47CMXM65bI-1nCE,40032
 general/interface/repository/geometry_repository.py,sha256=dB1AmZyyi5cWEzl-_4-2eOXXex-rQsa_cu6bl85wtNE,11252
 general/interface/repository/many_to_many_repository.py,sha256=wl-K0n-rwPvIDpa_LfoBq1iHUnC6QvSLm-uwyKA4taw,8574
 general/interface/repository/view_repository.py,sha256=wxDGw7kenuVrDd9nfh7-omw2m9Jex5WzF_lhEiqPoA0,7902
@@ -26,9 +26,9 @@ general/interface/repository/handler/interval_handler.py,sha256=4TtEcpzUFZeyB-yi
 general/interface/repository/handler/json_handler.py,sha256=f_nGemsxTPJ3W0xkU99sCFA0EVo1xa8p803NyjcGJT4,4414
 general/interface/repository/handler/json_ilike_handler.py,sha256=icfA4dO8E_W_KUEG5HB1nLVI1jfjxzkG8ZJ-IaCd4kY,3530
 general/interface/repository/handler/or_handler.py,sha256=UOjIh77H4y-x434YGLYRfVIXKnod1M5XPiMf71V2JTg,3137
-general/interface/repository/handler/statement_manager.py,sha256=U0jQNAV33ihwHwotIUa3kgqsV9Kofi_t2Te4TDFb0WM,6928
-python_general_be_lib-0.9.0.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
-python_general_be_lib-0.9.0.dist-info/METADATA,sha256=RgbrOLnOUhFXi95YVLFVZvDUxxu8dSfittwi8AjB5NA,3312
-python_general_be_lib-0.9.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_general_be_lib-0.9.0.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
-python_general_be_lib-0.9.0.dist-info/RECORD,,
+general/interface/repository/handler/statement_manager.py,sha256=dPG-HZy0jVM3Y4ZnCp2QPY4gLgt-rWSzOvY1_UmotcI,7333
+python_general_be_lib-0.9.1.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
+python_general_be_lib-0.9.1.dist-info/METADATA,sha256=J4CIjmhDsD6SN26tAfFUvtbd2eQOggjhucncPn6Sn6c,3409
+python_general_be_lib-0.9.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_general_be_lib-0.9.1.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
+python_general_be_lib-0.9.1.dist-info/RECORD,,