python-general-be-lib 0.12.0__tar.gz → 0.12.2__tar.gz

{python_general_be_lib-0.12.0 → python_general_be_lib-0.12.2}/PKG-INFO

@@ -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 → python_general_be_lib-0.12.2}/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)

{python_general_be_lib-0.12.0 → python_general_be_lib-0.12.2}/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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-general-be-lib"
-version = "0.12.0"
+version = "0.12.2"
 description = "General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, Keycloak JWT auth, logger utilities."
 readme = "README.md"
 license = { text = "MIT" }

{python_general_be_lib-0.12.0 → python_general_be_lib-0.12.2}/python_general_be_lib.egg-info/PKG-INFO

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

@@ -75,6 +75,7 @@ tests/test_ordinamento.py
 tests/test_pipeline_handler.py
 tests/test_query_count.py
 tests/test_retrieve_mapper.py
+tests/test_rollback.py
 tests/test_smoke_crud.py
 tests/test_softdelete.py
 tests/test_sql_snapshot.py

{python_general_be_lib-0.12.0 → python_general_be_lib-0.12.2}/tests/test_metadata_paginazione.py

@@ -24,6 +24,7 @@ from general.interface.base.base_model import ExtBaseModel
 from general.interface.metadata.crud_metadata import CrudMetadata
 from general.interface.repository.handler import ILikeHandler
 from support import assert_query_count
+from support.queries import count_queries
 
 RIGHE = 25
 
@@ -200,3 +201,76 @@ def test_i_filtri_del_chiamante_non_vengono_consumati(meta: CrudMetadata) -> Non
     assert filtri == atteso
     assert prima.tot_pages == seconda.tot_pages
     assert [r["id"] for r in prima.data] == [r["id"] for r in seconda.data]
+
+
+# --------------------------------------------- ordine totale (0.12.2, PERF-13)
+
+
+def ordine_della_pagina(meta: CrudMetadata, engine: Engine, **kwargs) -> str:
+    """``ORDER BY`` della query dei dati emessa da ``paging_find``, o ``-- NIENTE --``."""
+    meta.get_table(kwargs.get("from_table", "riga"))  # riflessione fuori dalla misura
+    with count_queries(engine) as log:
+        meta.paging_find(**{"from_table": "riga", **kwargs})
+    sql = log.sql[0]
+    if "ORDER BY" not in sql:
+        return "-- NIENTE --"
+    return sql.split("ORDER BY")[1].split("LIMIT")[0].strip()
+
+
+@pytest.mark.parametrize(
+    "orders_by, atteso",
+    [
+        ({"ruolo": True}, "riga.ruolo ASC, riga.id ASC"),
+        ({"ruolo": False, "id": False}, "riga.ruolo DESC, riga.id DESC"),
+        ({"id": False, "ruolo": True}, "riga.id DESC, riga.ruolo ASC"),
+    ],
+    ids=["appesa", "pk_in_coda_desc", "pk_in_testa_desc"],
+)
+def test_paging_find_appende_la_pk_come_discriminante(meta: CrudMetadata, sqlite_engine: Engine, orders_by: dict, atteso: str) -> None:
+    """Stessa regola del layer ORM: PK in coda e ascendente, mai duplicata."""
+    assert ordine_della_pagina(meta, sqlite_engine, orders_by=orders_by, limit=5, page=2) == atteso
+
+
+def test_senza_orders_by_la_paginazione_non_ordina(meta: CrudMetadata, sqlite_engine: Engine) -> None:
+    """Il default del layer resta: nessun ordinamento chiesto, nessun ``ORDER BY`` e nessun criterio dichiarato.
+
+    Diverso dal layer ORM, che senza ordinamento pagina per PK: qui il default non
+    promette alcun ordine, e cambiarlo cambierebbe ``campoOrdinamento`` nella risposta.
+    """
+    assert ordine_della_pagina(meta, sqlite_engine, limit=5, page=2) == "-- NIENTE --"
+    assert meta.paging_find(from_table="riga", limit=5, page=1).order_by is None
+
+
+def test_la_risposta_non_dichiara_la_discriminante(meta: CrudMetadata) -> None:
+    risposta = meta.paging_find(from_table="riga", limit=5, page=1, orders_by={"ruolo": False})
+    assert risposta.orders_by == {"ruolo": False}
+    assert (risposta.order_by, risposta.asc) == ("ruolo", False)
+
+
+def test_le_pagine_su_una_colonna_ripetuta_coprono_tutte_le_righe(meta: CrudMetadata) -> None:
+    """``ruolo`` ha due valori su 25 righe: a pari merito decide l'id."""
+    viste = []
+    for page in range(1, 6):
+        viste.extend(riga["id"] for riga in meta.paging_find(from_table="riga", limit=5, page=page, orders_by={"ruolo": True}).data)
+
+    admin = [i for i in range(1, RIGHE + 1) if i % 5 == 0]
+    assert viste == admin + [i for i in range(1, RIGHE + 1) if i not in admin]
+
+
+def test_una_vista_senza_pk_resta_con_l_ordinamento_chiesto(meta: CrudMetadata, sqlite_engine: Engine) -> None:
+    """Una vista riflessa non ha PK: niente da appendere, e nessun errore.
+
+    L'ordinamento resta quello chiesto, e con lui l'instabilità delle pagine a pari
+    merito: per una vista l'ordine totale lo deve dare il chiamante.
+    """
+    with sqlite_engine.begin() as connessione:
+        connessione.execute(text("drop view if exists vista_riga"))
+        connessione.execute(text("create view vista_riga as select id, ruolo from riga"))
+    try:
+        assert meta.get_table("vista_riga").primary_key.columns.keys() == []
+        assert ordine_della_pagina(meta, sqlite_engine, from_table="vista_riga", orders_by={"ruolo": True}, limit=5, page=1) == (
+            "vista_riga.ruolo ASC"
+        )
+    finally:
+        with sqlite_engine.begin() as connessione:
+            connessione.execute(text("drop view if exists vista_riga"))

{python_general_be_lib-0.12.0 → python_general_be_lib-0.12.2}/tests/test_ordinamento.py

@@ -10,8 +10,10 @@ 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.
+3. l'**ordine totale** di ``paging_find`` (0.12.2, PERF-13): la PK viene appesa in
+   coda come discriminante, così ``LIMIT/OFFSET`` non ripete né perde righe;
+4. un **limite noto** che resta aperto (i ``NULL``), fissato come caratterizzazione
+   perché correggerlo cambia i risultati e non deve avvenire per caso.
 """
 
 from __future__ import annotations
@@ -19,13 +21,13 @@ from __future__ import annotations
 from typing import Optional
 
 import pytest
-from sqlalchemy import Column, Engine, Integer, String, insert
+from sqlalchemy import Column, Engine, Integer, String, insert, select, text
 
 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 models import Assegnazione, AssegnazioneModel, Utente, UtenteModel, utente_repository
 from support.sql import captured_sql
 
 
@@ -48,6 +50,27 @@ class UtenteChiaveEsplicitaModel(ExtBaseModel):
     nome: Optional[str] = None
 
 
+class VistaRuoli(Base):
+    """Entità mappata su una **vista**: la PK esiste solo nella dichiarazione ORM.
+
+    Il database non sa che ``id`` è una chiave; la libreria la legge da
+    ``__table__.primary_key`` come per qualunque tabella, ed è il caso delle entità su
+    vista dei backend che la usano.
+    """
+
+    __tablename__ = "vista_ruoli"
+
+    id = Column(Integer, primary_key=True)
+    nome = Column(String(50))
+    ruolo = Column(String(20))
+
+
+class VistaRuoliModel(ExtBaseModel):
+    id: Optional[int] = None
+    nome: Optional[str] = None
+    ruolo: Optional[str] = None
+
+
 @pytest.fixture
 def repo(sqlite_engine: Engine) -> CrudRepository:
     """Repository su ``Utente`` con qualche riga, per gli ordinamenti sui dati."""
@@ -107,7 +130,7 @@ def test_paging_find_conserva_il_suo_default_ascendente(repo) -> None:
     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"
+    assert clausola(repo.paging_find, limit=5, page=1, order_by="nome") == "utente.nome ASC, utente.id ASC"
 
 
 # ---------------------------------------------------------------- orders_by
@@ -241,19 +264,139 @@ def test_parse_pagination_senza_ordinamento_non_ne_dichiara_uno(repo) -> 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.
+def test_la_risposta_non_dichiara_la_discriminante(repo) -> None:
+    """La PK appesa è un dettaglio della query, non dell'ordinamento chiesto.
+
+    I client leggono ``campoOrdinamento``/``crescente`` e rimandano
+    ``campiOrdinamento`` alla pagina successiva: devono ritrovare ciò che hanno
+    chiesto, come prima della 0.12.2.
+    """
+    risposta = repo.paging_find(orders_by={"ruolo": False}, limit=2, page=1)
+    assert risposta.orders_by == {"ruolo": False}
+    assert (risposta.order_by, risposta.asc) == ("ruolo", False)
+
+
+# ------------------------------------------- ordine totale nella paginazione
+
+
+@pytest.mark.parametrize(
+    "orders_by, atteso",
+    [
+        ({"ruolo": True}, "utente.ruolo ASC, utente.id ASC"),
+        ({"ruolo": False, "eta": False}, "utente.ruolo DESC, utente.eta DESC, utente.id ASC"),
+        ({"id": False}, "utente.id DESC"),
+        ({"ruolo": True, "id": False}, "utente.ruolo ASC, utente.id DESC"),
+        ({"id": False, "ruolo": True}, "utente.id DESC, utente.ruolo ASC"),
+    ],
+    ids=["appesa", "appesa_dopo_due", "pk_sola_desc", "pk_in_coda_desc", "pk_in_testa_desc"],
+)
+def test_la_paginazione_appende_la_pk_come_discriminante(repo, orders_by: dict, atteso: str) -> None:
+    """La PK va in coda, ascendente, solo se il chiamante non l'ha già messa.
+
+    Una colonna della PK già presente resta dov'è e con la sua direzione: da lì in
+    poi l'ordinamento è già totale, e duplicarla cambierebbe solo l'SQL.
+    """
+    assert clausola(repo.paging_find, orders_by=orders_by, limit=20, page=2) == atteso
+
+
+def test_find_non_appende_la_pk(repo) -> None:
+    """``find`` con ``limit`` resta com'era: senza ``page`` non ci sono pagine da tenere coerenti."""
+    assert clausola(repo.find, orders_by={"ruolo": True}, limit=20) == "utente.ruolo ASC"
+
+
+def test_pk_composta_appende_tutte_le_colonne(sqlite_engine: Engine) -> None:
+    """Con una PK composta servono tutte le colonne, e nel default anche le altre."""
+    repository = CrudRepository(entity=Assegnazione, model=AssegnazioneModel, engine=sqlite_engine)
+
+    assert clausola(repository.paging_find, limit=5, page=1) == (
+        "assegnazione.id_utente ASC, assegnazione.id_ruolo ASC"
+    )
+    assert clausola(repository.paging_find, orders_by={"note": False}, limit=5, page=1) == (
+        "assegnazione.note DESC, assegnazione.id_utente ASC, assegnazione.id_ruolo ASC"
+    )
+    assert clausola(repository.paging_find, orders_by={"id_ruolo": False}, limit=5, page=1) == (
+        "assegnazione.id_ruolo DESC, assegnazione.id_utente ASC"
+    )
+
+
+def test_pk_composta_le_pagine_coprono_tutte_le_righe(sqlite_engine: Engine) -> None:
+    """Sui dati: ``note`` ha due soli valori, le coppie della PK decidono il resto."""
+    with sqlite_engine.begin() as connessione:
+        connessione.execute(
+            insert(Assegnazione.__table__),
+            [{"id_utente": u, "id_ruolo": r, "note": "x" if (u + r) % 2 else "y"} for u in range(1, 6) for r in range(1, 5)],
+        )
+    repository = CrudRepository(entity=Assegnazione, model=AssegnazioneModel, engine=sqlite_engine)
+
+    viste = []
+    for page in range(1, 5):
+        viste.extend((a.id_utente, a.id_ruolo, a.note) for a in repository.paging_find(orders_by={"note": True}, limit=6, page=page).data)
+
+    attese = sorted(((u, r, "x" if (u + r) % 2 else "y") for u in range(1, 6) for r in range(1, 5)), key=lambda t: (t[2], t[0], t[1]))
+    assert viste == attese
+
+
+def test_entita_con_pk_key_diverso_da_name_riceve_la_discriminante(sqlite_engine: Engine) -> None:
+    """La PK si appende per ``key``, il nome con cui ``Table.c`` la risolve, non per ``name``."""
+    UtenteChiaveEsplicita.__table__.create(sqlite_engine, checkfirst=True)
+    repository = CrudRepository(entity=UtenteChiaveEsplicita, model=UtenteChiaveEsplicitaModel, engine=sqlite_engine)
+
+    assert clausola(repository.paging_find, orders_by={"nome": True}, limit=5, page=1) == (
+        'utente_chiave_esplicita.nome ASC, utente_chiave_esplicita."ID_LEGACY" ASC'
+    )
+    assert repository.paging_find(orders_by={"nome": True}, limit=5, page=1).orders_by == {"nome": True}
+
+
+@pytest.fixture
+def vista_ruoli(sqlite_engine: Engine):
+    """Vista SQLite su ``utente`` con 30 righe e due soli ruoli; viene rimossa alla fine."""
+    with sqlite_engine.begin() as connessione:
+        connessione.execute(text("drop view if exists vista_ruoli"))
+        connessione.execute(text("create view vista_ruoli as select id, nome, ruolo from utente"))
+        connessione.execute(
+            insert(Utente.__table__),
+            [{"id": i, "nome": f"n{i}", "ruolo": "admin" if i % 3 == 0 else "user", "attivo": True} for i in range(1, 31)],
+        )
+    yield CrudRepository(entity=VistaRuoli, model=VistaRuoliModel, engine=sqlite_engine)
+    with sqlite_engine.begin() as connessione:
+        connessione.execute(text("drop view if exists vista_ruoli"))
+
+
+def test_entita_su_vista_riceve_la_discriminante(vista_ruoli: CrudRepository) -> None:
+    """La PK dichiarata nell'ORM basta: il database non deve sapere che è una chiave."""
+    assert clausola(vista_ruoli.paging_find, orders_by={"ruolo": True}, limit=7, page=2) == (
+        "vista_ruoli.ruolo ASC, vista_ruoli.id ASC"
+    )
+
+    viste = []
+    for page in range(1, 6):
+        viste.extend(v.id for v in vista_ruoli.paging_find(orders_by={"ruolo": True}, limit=7, page=page).data)
+
+    admin = [i for i in range(1, 31) if i % 3 == 0]
+    assert viste == admin + [i for i in range(1, 31) if i not in admin]
+
 
-    ``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.
+def test_le_pagine_su_una_colonna_ripetuta_non_ripetono_ne_perdono_righe(engine: Engine) -> None:
+    """Il difetto di PERF-13, misurato sui dati: unione delle pagine = tutte le righe, una volta.
 
-    Il giorno in cui si deciderà di appendere la PK automaticamente, questo test
-    **deve** fallire: è il segnale che il comportamento è cambiato di proposito.
+    2.000 righe con lo stesso ``ruolo``, sfogliate a pagine da 20. Senza discriminante
+    PostgreSQL restituisce le righe a pari merito in un ordine che cambia con
+    l'``OFFSET`` (il top-N heapsort non è stabile). Con la 0.12.1 questo test falliva
+    su PostgreSQL: 48 righe ripetute, e altrettante mai mostrate. SQLite non
+    riproduce il difetto, e lì il test passa comunque.
     """
-    assert clausola(repo.paging_find, orders_by={"ruolo": True}, limit=20, page=2) == "utente.ruolo ASC"
+    with engine.begin() as connessione:
+        connessione.execute(insert(Utente.__table__), [{"nome": f"n{i}", "ruolo": "user", "attivo": True} for i in range(2000)])
+        tutti = connessione.execute(select(Utente.__table__.c.id)).scalars().all()
+    repository = CrudRepository(entity=Utente, model=UtenteModel, engine=engine)
+
+    viste = []
+    with repository.open_session as sessione:
+        for page in range(1, 101):
+            viste.extend(u.id for u in repository.paging_find(session=sessione, orders_by={"ruolo": False}, limit=20, page=page).data)
+
+    assert len(viste) == len(set(viste)), f"{len(viste) - len(set(viste))} righe ripetute"
+    assert sorted(viste) == sorted(tutti)
 
 
 @pytest.mark.pg

python_general_be_lib-0.12.2/tests/test_rollback.py

@@ -0,0 +1,85 @@
+"""Rollback di ``CrudRepository._handle_exception``.
+
+``Session.close()`` annulla già la transazione sul database: quello che il
+``rollback()`` esplicito aggiunge è la scadenza delle istanze ORM. Senza, un'entità
+rimasta in mano al chiamante resta leggibile con i valori del ``flush`` mai
+confermati; con, la lettura alza ``DetachedInstanceError``. Il rollback gira su ogni
+errore, SELECT compresa, e un suo fallimento non deve coprire l'errore originale.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+from sqlalchemy import select, text
+from sqlalchemy.engine import Engine
+from sqlalchemy.exc import IntegrityError, ProgrammingError
+from sqlalchemy.orm import Session
+from sqlalchemy.orm.exc import DetachedInstanceError
+
+from general.exception.crud_exceptions import BadRequestException, ServiceUnavailableException
+from general.interface.repository.crud_repository import CrudRepository
+from models import Prodotto, ProdottoModel, prodotto_repository
+
+
+@pytest.fixture
+def repo(engine: Engine) -> CrudRepository:
+    repository = prodotto_repository(engine)
+    repository.insert(models=[ProdottoModel(id=1, codice="pulito")])
+    return repository
+
+
+def test_errore_di_scrittura_fa_scadere_le_entita_della_sessione_esterna(engine: Engine, repo: CrudRepository) -> None:
+    """Dopo un ``IntegrityError`` l'entità modificata non espone più il valore mai confermato."""
+    sessione = Session(engine)
+    entita = sessione.get(Prodotto, 1)
+    entita.codice = "sporco"
+
+    with pytest.raises(BadRequestException):
+        repo.insert(session=sessione, models=[ProdottoModel(id=1, codice="duplicato")])
+
+    with pytest.raises(DetachedInstanceError):
+        _ = entita.codice
+    assert repo.get(1).codice == "pulito"
+
+
+def test_anche_una_select_fallita_fa_scadere_le_entita(engine: Engine, repo: CrudRepository) -> None:
+    """Su PostgreSQL una SELECT fallita blocca la transazione: il rollback vale anche lì."""
+    sessione = Session(engine)
+    entita = sessione.get(Prodotto, 1)
+    entita.codice = "sporco"
+    sessione.flush()
+
+    # SQLite la segnala come OperationalError (503), PostgreSQL come ProgrammingError (non mappato)
+    with pytest.raises((ServiceUnavailableException, ProgrammingError)):
+        repo.execute(sessione, select(Prodotto).where(text("colonna_inesistente = 1")))
+
+    with pytest.raises(DetachedInstanceError):
+        _ = entita.codice
+    assert repo.get(1).codice == "pulito"
+
+
+class _SessioneConRollbackRotto:
+    """Sessione finta il cui ``rollback`` fallisce, per verificare cosa succede dopo."""
+
+    def __init__(self) -> None:
+        self.chiusa = False
+
+    def rollback(self) -> None:
+        raise RuntimeError("rollback rotto")
+
+    def close(self) -> None:
+        self.chiusa = True
+
+
+def test_un_rollback_fallito_non_copre_l_errore_originale(sqlite_engine: Engine, caplog) -> None:
+    """L'errore originale resta quello mappato, la sessione viene chiusa e il guasto registrato."""
+    repository = prodotto_repository(sqlite_engine)
+    sessione = _SessioneConRollbackRotto()
+
+    with caplog.at_level(logging.ERROR), pytest.raises(BadRequestException):
+        repository._handle_exception(session=sessione, e=IntegrityError("s", None, Exception()))
+
+    assert sessione.chiusa is True
+    assert any(record.exc_info and isinstance(record.exc_info[1], RuntimeError) for record in caplog.records)

{python_general_be_lib-0.12.0 → python_general_be_lib-0.12.2}/tests/test_sql_snapshot.py

@@ -237,10 +237,12 @@ def test_paging_find_emette_dati_poi_count(ut) -> None:
     L'ordine è invertito rispetto a prima dell'intervento 1.4: serve avere le righe
     per sapere se il totale è ricavabile dalla pagina. Qui la pagina è vuota oltre la
     prima (la sessione finta non restituisce righe), quindi la COUNT viene eseguita.
+    Dalla 0.12.2 l'``ORDER BY`` finisce con la PK (discriminante, PERF-13); la COUNT
+    non ha ordinamento e resta identica.
     """
     data_sql, count_sql = captured_sql(ut.paging_find, where={"attivo": True}, limit=20, page=3, order_by="nome")
     assert data_sql == (
-        f"{SELECT_UT} WHERE utente.attivo = true ORDER BY utente.nome ASC "
+        f"{SELECT_UT} WHERE utente.attivo = true ORDER BY utente.nome ASC, utente.id ASC "
         f"LIMIT %(param_1)s OFFSET %(param_2)s"
     )
     assert count_sql == "SELECT count(*) AS count_1 FROM utente WHERE utente.attivo = true"