python-general-be-lib 0.9.0__tar.gz → 0.9.1__tar.gz

{python_general_be_lib-0.9.0 → python_general_be_lib-0.9.1}/PKG-INFO

@@ -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 → python_general_be_lib-0.9.1}/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``.

{python_general_be_lib-0.9.0 → python_general_be_lib-0.9.1}/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.

{python_general_be_lib-0.9.0 → python_general_be_lib-0.9.1}/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 → python_general_be_lib-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-general-be-lib"
-version = "0.9.0"
+version = "0.9.1"
 description = "General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, logger utilities."
 readme = "README.md"
 license = { text = "MIT" }
@@ -45,6 +45,7 @@ dev = [
 [project.urls]
 Homepage = "https://github.com/Arpes-IS/python-general-be-lib"
 Repository = "https://github.com/Arpes-IS/python-general-be-lib"
+Changelog = "https://github.com/Arpes-IS/python-general-be-lib/blob/main/CHANGELOG.md"
 
 # PEP 561: il marker `py.typed` va spedito dentro il pacchetto, altrimenti i type
 # checker ignorano la libreria installata (e mypy segnala un errore di import).

{python_general_be_lib-0.9.0 → python_general_be_lib-0.9.1}/python_general_be_lib.egg-info/PKG-INFO

@@ -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 → python_general_be_lib-0.9.1}/python_general_be_lib.egg-info/SOURCES.txt

@@ -42,6 +42,7 @@ tests/test_has_columns.py
 tests/test_import_pubblici.py
 tests/test_logger.py
 tests/test_negazione.py
+tests/test_ordinamento.py
 tests/test_pipeline_handler.py
 tests/test_query_count.py
 tests/test_smoke_crud.py

python_general_be_lib-0.9.1/tests/test_ordinamento.py

@@ -0,0 +1,285 @@
+"""Ordinamento multiplo con ``orders_by`` (feature 2.3 di ``.claude/piano-feature.md``).
+
+Prima esisteva un solo ``order_by: str`` più un ``asc: bool``, quindi le tabelle
+multi-colonna delle UI non erano servibili. Ora ``orders_by`` è un
+``dict[str, bool]``: la chiave è la colonna, il valore la direzione, e l'ordine delle
+clausole segue l'ordine di inserimento del dizionario — garantito dal linguaggio.
+
+I test coprono tre cose in proporzioni diverse:
+
+1. la **retro-compatibilità** di ``order_by``/``asc``, che è dove un difetto passa
+   inosservato: chi passa solo ``order_by`` non guarda l'SQL generato;
+2. il nuovo ``orders_by``, incluso quale chiave finisce nella risposta paginata;
+3. due **limiti noti** che restano aperti, fissati come caratterizzazione perché
+   correggerli cambia i risultati e non deve avvenire per caso.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import pytest
+from sqlalchemy import Column, Engine, Integer, String, insert
+
+from general.exception.crud_exceptions import HasNoAttributeException
+from general.interface.base.base_model import ExtBaseModel
+from general.interface.base.declarative_base import Base
+from general.interface.repository.crud_repository import CrudRepository
+from models import Utente, utente_repository
+from support.sql import captured_sql
+
+
+class UtenteChiaveEsplicita(Base):
+    """Entità la cui PK ha ``key`` diverso da ``name``.
+
+    ``primary_key()[0].name`` vale ``ID_LEGACY`` mentre ``Table.c`` è indicizzato per
+    ``key``, cioè ``id``: usare il nome invece della chiave fa fallire l'ordinamento
+    di default, e quindi **qualunque** ``find()`` su questa entità.
+    """
+
+    __tablename__ = "utente_chiave_esplicita"
+
+    id = Column("ID_LEGACY", Integer, primary_key=True, key="id")
+    nome = Column(String(50))
+
+
+class UtenteChiaveEsplicitaModel(ExtBaseModel):
+    id: Optional[int] = None
+    nome: Optional[str] = None
+
+
+@pytest.fixture
+def repo(sqlite_engine: Engine) -> CrudRepository:
+    """Repository su ``Utente`` con qualche riga, per gli ordinamenti sui dati."""
+    with sqlite_engine.begin() as connessione:
+        connessione.execute(
+            insert(Utente.__table__),
+            [
+                {"id": 1, "nome": "a", "ruolo": "user", "eta": 30, "attivo": True},
+                {"id": 2, "nome": "b", "ruolo": "admin", "eta": 30, "attivo": True},
+                {"id": 3, "nome": "c", "ruolo": "user", "eta": 10, "attivo": True},
+            ],
+        )
+    return utente_repository(sqlite_engine)
+
+
+def clausola(funzione, **kwargs) -> str:
+    """Ritorna la sola ``ORDER BY`` dello statement generato, senza toccare il database."""
+    sql = captured_sql(funzione, **kwargs)[0]
+    if "ORDER BY" not in sql:
+        return "-- NIENTE --"
+    return sql.split("ORDER BY")[1].split("LIMIT")[0].strip()
+
+
+# ------------------------------------------------------- retro-compatibilità
+
+
+@pytest.mark.parametrize(
+    "kwargs, atteso",
+    [
+        ({}, "-- NIENTE --"),
+        ({"order_by": "nome"}, "utente.nome DESC"),
+        ({"order_by": "nome", "asc": True}, "utente.nome ASC"),
+        ({"order_by": "nome", "asc": False}, "utente.nome DESC"),
+        ({"asc": True}, "-- NIENTE --"),
+    ],
+    ids=["niente", "solo_order_by", "asc_true", "asc_false", "solo_asc"],
+)
+def test_find_conserva_il_comportamento_di_order_by(repo, kwargs: dict, atteso: str) -> None:
+    """``order_by``/``asc`` devono comportarsi esattamente come prima di ``orders_by``.
+
+    Due caselle di questa tabella hanno già fallito durante l'implementazione:
+
+    - ``find()`` senza argomenti ha per un momento emesso ``ORDER BY pk DESC``, dove
+      prima non emetteva nulla — 16 snapshot SQL l'hanno segnalato;
+    - ``find(order_by="nome")`` **senza** ``asc`` ha smesso di ordinare, perché la
+      conversione verso ``orders_by`` richiedeva che entrambi fossero valorizzati.
+      Quello non l'ha segnalato nessun test, ed è il caso peggiore: ``asc=None``
+      significa DESC, quindi l'ordinamento sparisce in silenzio.
+    """
+    assert clausola(repo.find, **kwargs) == atteso
+
+
+def test_paging_find_conserva_il_suo_default_ascendente(repo) -> None:
+    """``paging_find`` ordina per PK ascendente quando non gli si dice altro.
+
+    Diverso da ``find``, che senza argomenti non ordina affatto: la paginazione ha
+    bisogno di un ordine, una lista no.
+    """
+    assert clausola(repo.paging_find, limit=5, page=1) == "utente.id ASC"
+    assert clausola(repo.paging_find, limit=5, page=1, order_by="nome") == "utente.nome ASC"
+
+
+# ---------------------------------------------------------------- orders_by
+
+
+def test_orders_by_genera_le_clausole_nell_ordine_del_dizionario(repo) -> None:
+    """L'ordine di inserimento del dizionario è l'ordine delle clausole.
+
+    È la ragione per cui un ``dict`` è una struttura adeguata: in Python l'ordine di
+    inserimento è garantito dal linguaggio, non un dettaglio di implementazione.
+    """
+    assert clausola(repo.find, orders_by={"ruolo": True, "eta": False, "id": True}) == (
+        "utente.ruolo ASC, utente.eta DESC, utente.id ASC"
+    )
+    assert clausola(repo.find, orders_by={"eta": False, "ruolo": True}) == (
+        "utente.eta DESC, utente.ruolo ASC"
+    )
+
+
+def test_orders_by_ha_la_precedenza_su_order_by(repo) -> None:
+    """Passando entrambi vince ``orders_by``, come il ``where`` vince su ``**kwhere``."""
+    assert clausola(repo.find, order_by="nome", asc=True, orders_by={"eta": False}) == "utente.eta DESC"
+
+
+def test_orders_by_ordina_davvero_le_righe(repo) -> None:
+    """L'ordinamento multiplo sui dati, non solo nell'SQL.
+
+    ``ruolo`` ascendente mette gli ``admin`` prima degli ``user``; a parità di ruolo
+    ``eta`` discendente mette il trentenne prima del decenne.
+    """
+    assert [u.id for u in repo.find(orders_by={"ruolo": True, "eta": False})] == [2, 1, 3]
+    assert [u.id for u in repo.find(orders_by={"ruolo": True, "eta": True})] == [2, 3, 1]
+
+
+def test_una_colonna_inesistente_viene_rifiutata(repo) -> None:
+    """La validazione contro le colonne reali valeva già per ``order_by`` e resta.
+
+    Nessuna interpolazione testuale: il nome passa da ``Table.c[...]``, quindi una
+    stringa arbitraria non può raggiungere l'SQL.
+    """
+    with pytest.raises(HasNoAttributeException):
+        repo.find(orders_by={"colonna_mai_esistita": True})
+    with pytest.raises(HasNoAttributeException):
+        repo.find(orders_by={"id; drop table utente; --": True})
+
+
+# ------------------------------------------------- risposta paginata e effetti
+
+
+def test_la_risposta_riporta_la_prima_chiave_con_il_suo_valore(repo) -> None:
+    """``PaginatorResponseModel`` ha un solo ``order_by``: deve essere il principale.
+
+    Una prima versione usava ``popitem()``, che preleva dalla **coda**: la risposta
+    dichiarava l'ordinamento secondario. Peggio, ``next(iter(orders_by))`` itera le
+    **chiavi**, quindi ``order_by, asc = next(iter(...))`` spacchettava la stringa —
+    con la PK ``id`` restituiva silenziosamente ``order_by='i', asc='d'``, e con
+    qualunque nome più lungo sollevava ``ValueError``.
+    """
+    risposta = repo.paging_find(orders_by={"ruolo": True, "eta": False}, limit=5, page=1)
+    assert risposta.order_by == "ruolo"
+    assert risposta.asc is True
+
+
+def test_il_dizionario_del_chiamante_non_viene_mutato(repo) -> None:
+    """Regressione: la prima versione consumava una chiave per chiamata.
+
+    ``orders_by.popitem()`` rimuoveva l'ultima voce dal dizionario **del chiamante**,
+    quindi riusare lo stesso dizionario per due pagine dava due ordinamenti diversi.
+    """
+    ordinamento = {"ruolo": True, "eta": False}
+    repo.paging_find(orders_by=ordinamento, limit=5, page=1)
+    repo.paging_find(orders_by=ordinamento, limit=5, page=2)
+    assert ordinamento == {"ruolo": True, "eta": False}
+
+
+def test_funziona_su_una_entita_con_pk_key_diverso_da_name(sqlite_engine: Engine) -> None:
+    """Regressione: l'ordinamento di default deve usare ``key``, non ``name``.
+
+    ``Table.c`` è indicizzato per ``key``; usare ``name`` faceva fallire con
+    ``HasNoAttributeException`` **qualunque** chiamata a ``find()`` o
+    ``paging_find()`` su questa entità, anche senza argomenti.
+    """
+    UtenteChiaveEsplicita.__table__.create(sqlite_engine, checkfirst=True)
+    repository = CrudRepository(entity=UtenteChiaveEsplicita, model=UtenteChiaveEsplicitaModel, engine=sqlite_engine)
+
+    assert repository.find() == []
+    assert repository.paging_find(limit=5, page=1).order_by == "id"
+
+
+def test_un_dizionario_vuoto_ricade_sul_default(repo) -> None:
+    """``orders_by={}`` non deve sollevare.
+
+    Il metodo pubblico lo tratta come assente; il privato aveva una guardia
+    ``is None`` che non lo catturava, e la lettura della prima chiave sollevava prima
+    ``KeyError`` e poi ``StopIteration``.
+    """
+    with repo.open_session as sessione:
+        risultato = repo._paging_find(session=sessione, orders_by={}, limit=5, page=1)
+    assert risultato.order_by == "id"
+
+
+# ------------------------------------------------------------- limiti noti
+
+
+def test_la_risposta_riporta_anche_l_ordinamento_completo(repo) -> None:
+    """``PaginatorResponseModel.orders_by`` porta tutte le coppie, con alias italiano.
+
+    ``order_by``/``asc`` restano per i client esistenti e riportano il criterio
+    principale; ``orders_by`` serve a chi deve ricostruire l'ordinamento completo, per
+    esempio per rimandarlo indietro alla pagina successiva.
+    """
+    risposta = repo.paging_find(orders_by={"ruolo": True, "eta": False}, limit=5, page=1)
+    assert risposta.orders_by == {"ruolo": True, "eta": False}
+
+    serializzata = risposta.model_dump(by_alias=True)
+    assert serializzata["campiOrdinamento"] == {"ruolo": True, "eta": False}
+    assert serializzata["campoOrdinamento"] == "ruolo"
+
+
+def test_parse_pagination_senza_ordinamento_non_ne_dichiara_uno(repo) -> None:
+    """Con un ``orders_by`` vuoto la risposta non deve inventare un ordinamento.
+
+    ``parse_pagination`` è pubblico: prima ``next(iter({}))`` sollevava
+    ``StopIteration``, che dentro un generatore verrebbe interpretata come fine
+    dell'iterazione invece di propagarsi. Ora ``order_by``/``asc`` restano ``None``,
+    che è la risposta vera — nessun ordinamento è stato applicato.
+    """
+    risposta = repo.parse_pagination(limit=10, page=1, orders_by={}, count=0, data=[])
+    assert risposta.order_by is None
+    assert risposta.asc is None
+    assert risposta.orders_by == {}
+
+
+def test_la_paginazione_non_appende_la_pk_come_discriminante(repo) -> None:
+    """Caratterizzazione: con un ordinamento esplicito non c'è ordine totale.
+
+    ``LIMIT/OFFSET`` su una chiave non univoca non garantisce la stabilità fra due
+    pagine: il database può restituire le righe a parità di chiave in ordine diverso e
+    l'OFFSET taglia in un punto diverso. Misurato su PostgreSQL con 2.000 righe e una
+    colonna dal valore costante: su 10 pagine da 20, **9 righe su 200 comparivano due
+    volte** e altre nove mai.
+
+    Il giorno in cui si deciderà di appendere la PK automaticamente, questo test
+    **deve** fallire: è il segnale che il comportamento è cambiato di proposito.
+    """
+    assert clausola(repo.paging_find, orders_by={"ruolo": True}, limit=20, page=2) == "utente.ruolo ASC"
+
+
+@pytest.mark.pg
+def test_i_null_finiscono_in_posizioni_opposte_sui_due_backend(pg_engine: Engine) -> None:
+    """Caratterizzazione: manca ``nulls_last``, e i due database non concordano.
+
+    Con ``asc=True`` SQLite mette i ``NULL`` **primi** e PostgreSQL **ultimi**; con
+    ``asc=False`` è l'inverso. Lo stesso codice ordina in modo opposto sui due backend
+    che la libreria supporta. Quando arriverà ``nulls_last`` questo test va aggiornato.
+    """
+    with pg_engine.begin() as connessione:
+        connessione.execute(
+            insert(Utente.__table__),
+            [
+                {"id": 1, "nome": "a", "eta": 30, "attivo": True},
+                {"id": 2, "nome": "b", "eta": None, "attivo": True},
+                {"id": 3, "nome": "c", "eta": 10, "attivo": True},
+            ],
+        )
+    repository = utente_repository(pg_engine)
+    assert [u.id for u in repository.find(orders_by={"eta": True})] == [3, 1, 2], "PostgreSQL: NULL ultimo"
+    assert [u.id for u in repository.find(orders_by={"eta": False})] == [2, 1, 3], "PostgreSQL: NULL primo"
+
+
+def test_i_null_su_sqlite_vanno_dalla_parte_opposta(repo) -> None:
+    """L'altra metà del test precedente, su SQLite: ``asc=True`` mette i ``NULL`` primi."""
+    with repo.engine.begin() as connessione:
+        connessione.execute(insert(Utente.__table__), [{"id": 9, "nome": "z", "eta": None, "attivo": True}])
+    assert [u.id for u in repo.find(orders_by={"eta": True})] == [9, 3, 1, 2], "SQLite: NULL primo"