python-general-be-lib 0.7.2__tar.gz → 0.8.1__tar.gz

python_general_be_lib-0.8.1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: python-general-be-lib
+Version: 0.8.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
+Keywords: backend,sqlalchemy,fastapi,pydantic,repository,crud,geoalchemy2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: geoalchemy2>=0.14.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-benchmark>=5; extra == "dev"
+Requires-Dist: testcontainers[postgres]>=4; extra == "dev"
+Requires-Dist: psycopg[binary]>=3; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+Dynamic: requires-python
+
+# python-general-be-lib
+
+Libreria backend general purpose per progetti Python: repository CRUD e spaziali
+su **SQLAlchemy** / **GeoAlchemy2**, eccezioni **FastAPI**, modelli base
+**Pydantic** e utility di logging.
+
+- Distribuzione PyPI: `python-general-be-lib`
+- Pacchetto importabile: `general`
+- Python richiesto: **3.12+**
+
+```bash
+pip install python-general-be-lib
+```
+
+```python
+from sqlalchemy import create_engine
+
+from general.interface.repository.crud_repository import CrudRepository
+
+engine = create_engine("postgresql://user:pass@localhost/db")
+repo = CrudRepository(entity=User, model=UserModel, engine=engine)
+
+repo.insert(models=[UserModel(name="Mario", email="mario@example.com")])
+repo.find(active=True, order_by="name", asc=True)
+```
+
+---
+
+## Cosa contiene
+
+| Area | Componenti |
+|---|---|
+| Repository ORM | `CrudRepository`, `GeometryRepository`, `ManyToManyRepository`, `ViewRepository` |
+| Layer Core (senza ORM) | `CrudMetadata`, `GeomMetadata` — CRUD e query spaziali su `Table` riflesse |
+| Motore di filtraggio | `StatementManager` + `BaseHandler`, `JsonHandler`, `ILikeHandler`, `JsonILikeHandler`, `OrHandler`, `IntervalHandler` |
+| Basi | `Base` (declarative base estesa), `ExtBaseModel`, `CamelExtBaseModel` |
+| Paginazione | `PaginatorRequestModel`, `PaginatorResponseModel` |
+| Eccezioni | `ExceptionInterface` e sottoclassi HTTP (400/401/403/404/422/500/503) |
+| Logging | `init_logger`, decorator `@log` |

python_general_be_lib-0.8.1/README.md

@@ -0,0 +1,39 @@
+# python-general-be-lib
+
+Libreria backend general purpose per progetti Python: repository CRUD e spaziali
+su **SQLAlchemy** / **GeoAlchemy2**, eccezioni **FastAPI**, modelli base
+**Pydantic** e utility di logging.
+
+- Distribuzione PyPI: `python-general-be-lib`
+- Pacchetto importabile: `general`
+- Python richiesto: **3.12+**
+
+```bash
+pip install python-general-be-lib
+```
+
+```python
+from sqlalchemy import create_engine
+
+from general.interface.repository.crud_repository import CrudRepository
+
+engine = create_engine("postgresql://user:pass@localhost/db")
+repo = CrudRepository(entity=User, model=UserModel, engine=engine)
+
+repo.insert(models=[UserModel(name="Mario", email="mario@example.com")])
+repo.find(active=True, order_by="name", asc=True)
+```
+
+---
+
+## Cosa contiene
+
+| Area | Componenti |
+|---|---|
+| Repository ORM | `CrudRepository`, `GeometryRepository`, `ManyToManyRepository`, `ViewRepository` |
+| Layer Core (senza ORM) | `CrudMetadata`, `GeomMetadata` — CRUD e query spaziali su `Table` riflesse |
+| Motore di filtraggio | `StatementManager` + `BaseHandler`, `JsonHandler`, `ILikeHandler`, `JsonILikeHandler`, `OrHandler`, `IntervalHandler` |
+| Basi | `Base` (declarative base estesa), `ExtBaseModel`, `CamelExtBaseModel` |
+| Paginazione | `PaginatorRequestModel`, `PaginatorResponseModel` |
+| Eccezioni | `ExceptionInterface` e sottoclassi HTTP (400/401/403/404/422/500/503) |
+| Logging | `init_logger`, decorator `@log` |

python_general_be_lib-0.8.1/general/exception/access_exceptions.py

@@ -0,0 +1,23 @@
+"""Eccezioni HTTP per autenticazione e autorizzazione.
+
+A differenza di ``crud_exceptions``, queste eccezioni non sono sollevate
+automaticamente dalla libreria: sono a disposizione dei layer di autenticazione
+e autorizzazione dei progetti che la usano.
+
+Il package ``general.exception`` non re-esporta questi simboli: vanno importati
+dal modulo, ``from general.exception.access_exceptions import ForbiddenException``.
+"""
+
+from .exception_interface import ExceptionInterface
+
+
+class ForbiddenException(ExceptionInterface):
+    """403 — Utente autenticato ma senza i permessi per la risorsa richiesta."""
+    status_code = 403
+    default_message = "Risorsa non accessibile da questo utente"
+
+
+class UnauthorizedException(ExceptionInterface):
+    """401 — Richiesta priva di credenziali valide."""
+    status_code = 401
+    default_message = "Non autorizzato"

python_general_be_lib-0.8.1/general/exception/crud_exceptions.py

@@ -0,0 +1,90 @@
+"""Eccezioni HTTP per le operazioni di persistenza.
+
+Sono le eccezioni su cui ``CrudRepository._handle_exception`` mappa gli errori
+SQLAlchemy:
+
+- ``OperationalError`` → ``ServiceUnavailableException`` (503)
+- ``NoResultFound`` → ``EntityNotFoundException`` (404)
+- ``DataError`` | ``IntegrityError`` → ``BadRequestException`` (400)
+
+Il package ``general.exception`` non re-esporta questi simboli: vanno importati
+dal modulo, ``from general.exception.crud_exceptions import BadRequestException``.
+"""
+
+from .exception_interface import ExceptionInterface
+
+
+class BadRequestException(ExceptionInterface):
+    """400 — Dati della richiesta non validi o vincolo di integrità violato.
+
+    Sollevata al posto di ``DataError`` e ``IntegrityError`` (es. violazione di
+    una foreign key, di un unique o di un NOT NULL).
+    """
+    status_code = 400
+    default_message = "Richiesta non corretta"
+
+
+class EntityNotFoundException(ExceptionInterface):
+    """404 — Nessun record corrisponde ai criteri richiesti.
+
+    Sollevata al posto di ``NoResultFound``.
+    """
+    status_code = 404
+    default_message = "Dato non trovato"
+
+
+class ServiceUnavailableException(ExceptionInterface):
+    """503 — Database non raggiungibile.
+
+    Sollevata al posto di ``OperationalError`` (connessione caduta, pool esaurito,
+    server non in ascolto).
+    """
+    status_code = 503
+    default_message = "Servizio momentaneamente non disponibile, riprovare più tardi"
+
+
+class UnprocessableEntityException(ExceptionInterface):
+    """422 — Entità sintatticamente valida ma non processabile.
+
+    Non è sollevata automaticamente dai repository: è a disposizione dei service
+    per gli errori di validazione applicativa.
+    """
+    status_code = 422
+    default_message = "Entità non processabile"
+
+
+class HasNoAttributeException(ExceptionInterface):
+    """400 — Colonna o attributo non presente sull'entità.
+
+    Sollevata quando un nome di colonna passato a ``columns``, ``exclude_columns``
+    o ``order_by`` non esiste sull'entità.
+
+    Example:
+        >>> raise HasNoAttributeException("cognome")
+        # detail: "Richiesta non corretta - Attributo cognome non presente"
+    """
+    status_code = 400
+    default_message = "Richiesta non corretta"
+
+    def __init__(self, attr: str = ""):
+        """Compone il dettaglio in base alla presenza del nome dell'attributo.
+
+        Args:
+            attr (str): Nome dell'attributo mancante. Se omesso, viene usato un
+                messaggio generico che non identifica la colonna.
+        """
+        if attr:
+            super().__init__(custom_message=f"Attributo {attr} non presente", )
+        else:
+            super().__init__(custom_message="Alcuni attributi non sono presenti per questa entità", )
+
+
+class InternalServerException(ExceptionInterface):
+    """500 — Errore interno non previsto.
+
+    Usata come fallback dal decorator ``@log`` per ogni eccezione che non sia già
+    una ``HTTPException``, e da ``CrudMetadata.get_table`` per una tabella
+    inesistente.
+    """
+    status_code = 500
+    default_message = "Impossibile gestire la richiesta al momento"

python_general_be_lib-0.8.1/general/exception/exception_interface.py

@@ -0,0 +1,38 @@
+from fastapi import HTTPException
+
+
+class ExceptionInterface(HTTPException):
+    """Interfaccia base per tutte le eccezioni della libreria.
+
+    Estende ``fastapi.HTTPException`` spostando status code e messaggio su
+    **attributi di classe**: ogni sottoclasse dichiara il proprio ``status_code``
+    e ``default_message`` e può quindi essere sollevata senza argomenti.
+
+    Sollevata dentro un endpoint FastAPI, viene serializzata automaticamente nella
+    risposta di errore con lo status code dichiarato.
+
+    Attributes:
+        status_code (int): Status code HTTP della risposta.
+        default_message (str): Messaggio di default usato come ``detail``.
+
+    Example:
+        >>> class TeapotException(ExceptionInterface):
+        ...     status_code = 418
+        ...     default_message = "Sono una teiera"
+        >>> raise TeapotException("niente caffè")
+        # detail: "Sono una teiera - niente caffè"
+    """
+    status_code: int
+    default_message: str
+
+    def __init__(self, custom_message: str = None):
+        """Compone il ``detail`` a partire dal messaggio di default e da quello custom.
+
+        Args:
+            custom_message (str, optional): Dettaglio aggiuntivo, accodato al
+                ``default_message`` nella forma
+                ``"{default_message} - {custom_message}"``. Se omesso, il ``detail``
+                è il solo ``default_message``.
+        """
+        detail = f"{self.default_message} - {custom_message}" if custom_message else self.default_message
+        super().__init__(status_code=self.status_code, detail=detail)

{python_general_be_lib-0.7.2 → python_general_be_lib-0.8.1}/general/interface/base/declarative_base.py

@@ -1,6 +1,6 @@
 __all__ = ["Base", "retrieve_mapper_entity", "retrieve_mapper_from_table"]
 
-from typing import Optional, Any
+from typing import Optional, Any, Sequence
 
 from geoalchemy2 import Geometry, WKBElement
 from pydantic import create_model
@@ -17,7 +17,7 @@ class Base:
     """
 
     @classmethod
-    def to_pydantic(cls, model_name: str = None, full_optional: bool = False, default_values: dict[str, Any] = None, **create_model_kwargs):
+    def to_pydantic(cls, model_name: str = None, full_optional: bool = False, default_values: dict[str, Any] = None, include_only: Sequence[str] = None, **create_model_kwargs):
         """Genera dinamicamente un modello Pydantic a partire dalle colonne dell'entità.
 
         Itera sulle colonne mappate dall'ORM e costruisce i campi del modello
@@ -44,12 +44,16 @@ class Base:
         if not default_values:
             default_values = dict()
         mapper: Mapper = inspect(cls)
+
+        column_properties = [prop for prop in mapper.column_attrs if include_only is None or prop.key in include_only]
+
         model_name = f"{cls.__name__}Model" if not model_name else model_name
         fields = dict()
-        field_values = {col.name: None if full_optional else ... for col in mapper.columns}
+        field_values = {prop.key: None if full_optional else ... for prop in column_properties}
         field_values.update(default_values)
-        for col in mapper.columns:
-            field_name = col.name
+        for prop in column_properties:
+            col = prop.columns[0]
+            field_name = prop.key
             if isinstance(col.type, Geometry):
                 field_type = Optional[WKBElement] if col.nullable or full_optional else WKBElement
             else:
@@ -111,6 +115,9 @@ class Base:
 def retrieve_mapper_entity(entity_name: str):
     """Cerca e restituisce una sottoclasse di ``Base`` per nome della classe.
 
+    Itera su ``Base.__subclasses__()``: trova quindi solo le sottoclassi **dirette**
+    di ``Base``, non quelle annidate in ulteriori livelli di ereditarietà.
+
     Args:
         entity_name (str): Nome della classe ORM da cercare (es. ``"User"``).
 
@@ -129,6 +136,9 @@ def retrieve_mapper_entity(entity_name: str):
 def retrieve_mapper_from_table(table_name: str):
     """Cerca e restituisce una sottoclasse di ``Base`` per nome della tabella.
 
+    Itera su ``Base.__subclasses__()``: trova quindi solo le sottoclassi **dirette**
+    di ``Base``, non quelle annidate in ulteriori livelli di ereditarietà.
+
     Args:
         table_name (str): Nome della tabella nel database (es. ``"users"``).
 

{python_general_be_lib-0.7.2 → python_general_be_lib-0.8.1}/general/interface/metadata/crud_metadata.py

@@ -23,6 +23,14 @@ class CrudMetadata:
     chiusura; altrimenti la connessione viene aperta, committata e chiusa
     internamente.
 
+    Differenze rispetto a ``CrudRepository``:
+    - **non** usa la pipeline degli handler: i filtri passano direttamente da
+      ``_eq_where``, quindi non c'è supporto per JSON, ILIKE, intervalli o alias;
+    - le eccezioni SQLAlchemy **non** vengono mappate su eccezioni HTTP: vengono
+      loggate e rilanciate tal quali (vedi ``_handle_exception``);
+    - la serializzazione avviene con ``parsing_model(**row)`` sui mapping delle
+      righe, non con ``model_validate`` su entità ORM.
+
     Attributes:
         schema (str | None): Nome dello schema di default per le tabelle.
         metadata (MetaData): Contenitore SQLAlchemy delle tabelle riflesse/definite.
@@ -483,9 +491,10 @@ class CrudMetadata:
     def _eq_where(self, col: Column, condition, neq: bool = False):
         """Costruisce la singola condizione WHERE per una colonna.
 
-        Logica applicata:
+        Logica applicata (stessa di ``BaseHandler._handle``):
+        - Colonna ``ARRAY`` + ``list`` → ``col && ARRAY[values]`` (overlap)
+        - Colonna ``ARRAY`` + scalare → ``value = ANY(col)``
         - ``list`` → ``col IN (values)``
-        - Tipo ``ARRAY`` → ``value = ANY(col)``
         - Scalare → ``col == value``
 
         Args:

{python_general_be_lib-0.7.2 → python_general_be_lib-0.8.1}/general/interface/metadata/geom_metadata.py

@@ -19,7 +19,10 @@ class GeomMetadata(CrudMetadata):
     della tabella.
 
     Gestisce la riproiezione automatica tra SRID diversi e il buffering opzionale
-    della geometria di input.
+    della geometria di input. Il parametro ``tolerance`` è sempre un **buffer**
+    (``ST_Buffer``) applicato alla geometria di input: a differenza di
+    ``GeometryRepository.intersects``, che con ``tolerance > 0`` passa a
+    ``ST_DWithin``, qui il predicato resta ``ST_Intersects``.
 
     Example:
         >>> meta = GeomMetadata(engine=engine, schema_name="public")

{python_general_be_lib-0.7.2 → python_general_be_lib-0.8.1}/general/interface/repository/crud_repository.py

@@ -1,5 +1,6 @@
 __all__ = ["CrudRepository"]
 
+import hashlib
 import logging
 import math
 from functools import lru_cache
@@ -31,6 +32,23 @@ def _list_adapter(model: Type[BaseModel]) -> TypeAdapter:
     """
     return TypeAdapter(list[model])
 
+@lru_cache(maxsize=None)
+def _reduced_model(entity: Type[Base], columns: frozenset[str]) -> Type[BaseModel]:
+    """Modello ridotto alle colonne indicate, costruito una volta per combinazione.
+
+    Cachato per (entità, colonne) perché `create_model` produce una classe nuova a
+    ogni chiamata: senza memoizzazione `_list_adapter` — che esiste per non
+    ricostruire il TypeAdapter — mancherebbe il bersaglio a ogni richiesta, e il suo
+    `maxsize=None` tratterebbe una voce per classe generata.
+    """
+    ordinate = [prop.key for prop in inspect(entity).column_attrs if prop.key in columns]
+    digest = hashlib.sha1("|".join(ordinate).encode()).hexdigest()[:8]
+    return entity.to_pydantic(
+        model_name=f"{entity.__name__}_{digest}",
+        full_optional=True,
+        include_only=ordinate,
+    )
+
 
 class CrudRepository[Entity: Base | Type[Base]]:
     """Repository ORM generico con operazioni CRUD complete su una singola entità SQLAlchemy.
@@ -109,6 +127,17 @@ class CrudRepository[Entity: Base | Type[Base]]:
 
     # -------------------------
 
+
+
+
+    def _retrieve_parsing_model(self, columns=None, exclude_columns=None):
+        selected_columns = set(columns) if columns else set(self.entity.__mapper__.attrs.keys())  # o columns_names corretto
+        if exclude_columns:
+            selected_columns -= set(exclude_columns)
+        if columns is None and not exclude_columns:
+            return self.model
+        return _reduced_model(self.entity, frozenset(selected_columns))
+
     def _handle_exception(self, session: Session, e: Exception):
         """Chiude la sessione, logga l'errore e rilancia un'eccezione HTTP-friendly.
 
@@ -179,8 +208,9 @@ class CrudRepository[Entity: Base | Type[Base]]:
 
         Args:
             *columns (str): Nomi delle colonne da verificare.
-            entity (Type[Base], optional): Entità su cui verificare. Se ``None``,
-                usa ``self.entity``.
+            entity (Type[Base]): Entità su cui verificare. Obbligatoria nei fatti:
+                pur avendo default ``None``, il metodo non applica nessun fallback
+                a ``self.entity`` e con ``None`` solleva ``AttributeError``.
 
         Returns:
             bool: ``True`` se tutte le colonne sono presenti, ``False`` altrimenti.
@@ -210,9 +240,9 @@ class CrudRepository[Entity: Base | Type[Base]]:
             stmt = select(entity)
             if columns:
                 entity_columns = {column for column in columns if column not in self.relationship_attributes}
-                stmt = stmt.options(load_only(*[getattr(self.entity, column) for column in entity_columns]))
+                stmt = stmt.options(load_only(*[getattr(entity, column) for column in entity_columns]))
             if exclude_columns:
-                stmt = stmt.options(defer(*[getattr(self.entity, column) for column in exclude_columns]))
+                stmt = stmt.options(*[defer(getattr(entity, column)) for column in exclude_columns])
         except AttributeError:
             raise HasNoAttributeException()
         return stmt
@@ -301,6 +331,13 @@ class CrudRepository[Entity: Base | Type[Base]]:
             list[Entity]: Lista di modelli serializzati (o entità grezze se
                 sessione esterna).
 
+        Raises:
+            HasNoAttributeException: Se una colonna in ``columns``,
+                ``exclude_columns`` o ``order_by`` non esiste sull'entità.
+
+        Note:
+            Essendo una lettura pura non esegue nessun commit (``commit=False``).
+
         Example:
             >>> repo.find(active=True, limit=10)
             >>> repo.find(where={"role": ["admin", "editor"]})
@@ -310,6 +347,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
         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)
+        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,
@@ -575,47 +613,67 @@ class CrudRepository[Entity: Base | Type[Base]]:
         return count_
 
     def _count(self, session: Session, where: dict[str, Any] = None, **kwhere):
-        pk = self.entity.primary_key()[0]
         if where is None:
             where = kwhere if kwhere else {}
-        stmt = select(count(pk))
+        stmt = select(count()).select_from(self.entity)
         stmt = self.stmt_manager.prepare_statement(stmt=stmt, **where)
         return session.execute(stmt).scalar()
 
-    def _preconf_count(self, session: Session, where: Optional[ColumnElement[Any]]):
-        """Conta i record usando una clausola WHERE già costruita (ColumnElement).
+    def _preconf_count(self, session: Session, where: Optional[list[ColumnElement[Any]]]):
+        """Conta i record a partire da condizioni WHERE già costruite.
 
-        Usato internamente da ``_paging_find`` per riusare la clausola WHERE
-        già applicata allo statement di selezione.
+        Usato da ``_paging_find`` quando il totale non è ricavabile dalla pagina
+        appena letta: riusa la lista di condizioni prodotta dalla pipeline degli
+        handler, così i filtri vengono tradotti una sola volta per chiamata.
+
+        Conta con ``COUNT(*)`` e non ``COUNT(pk)``: evita il controllo NOT NULL per
+        riga a parità di piano di esecuzione. Il ``select_from`` è indispensabile —
+        ``select(count())`` da solo compilerebbe in un ``SELECT count(*)`` **senza
+        FROM**, che restituisce sempre 1.
 
         Args:
             session (Session): Sessione corrente.
-            where (ColumnElement): Clausola WHERE precostruita dallo statement.
+            where (list[ColumnElement] | None): Condizioni già costruite, come le
+                restituisce ``StatementManager.conditions``. Una lista vuota o
+                ``None`` conta tutte le righe della tabella.
 
         Returns:
             int: Numero totale di record corrispondenti.
         """
-        pk = self.entity.primary_key()[0]
-        stmt = select(count(pk))
+        stmt = select(count()).select_from(self.entity)
         if where is not None:
-            stmt = stmt.where(where)
+            stmt = stmt.where(*where)
         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]:
         """Esegue una ricerca paginata con supporto a ordinamento e offset.
 
-        Calcola il numero totale di pagine in base al count reale dei record
-        filtrati, e restituisce solo la pagina richiesta.
+        Calcola il numero totale di pagine e restituisce solo la pagina richiesta.
+
+        La query dei dati viene eseguita **per prima**, così il totale può essere
+        ricavato dalle righe ottenute ed evitare del tutto la ``COUNT``:
+
+        - ``limit=0`` (nessuna paginazione) → il totale è il numero di righe;
+        - pagina non piena in prima pagina → il totale è il numero di righe;
+        - pagina non piena oltre la prima → il totale è ``(page-1)*limit + righe``;
+        - pagina **piena**, oppure vuota oltre la prima → il totale non è
+          ricavabile e viene eseguita la ``COUNT`` (``_preconf_count``), che riusa le
+          condizioni già costruite dalla pipeline degli handler.
+
+        Il valore derivato è esatto, non stimato: il ``tot_pages`` restituito è
+        identico a quello che darebbe la ``COUNT`` in tutti i casi.
 
         Args:
             session (Session, optional): Sessione esterna.
             where (dict[str, Any], optional): Filtri come dizionario.
             columns (list[str], optional): Colonne da includere.
             exclude_columns (list[str], optional): Colonne da escludere.
-            limit (int): Numero di elementi per pagina. Default: 0 (nessun limite).
+            limit (int): Numero di elementi per pagina. Default: 0 (nessun limite,
+                quindi una sola pagina).
             page (int): Numero di pagina richiesta (1-based). Default: 1.
-            order_by (str, optional): Colonna per l'ordinamento.
+            order_by (str, optional): Colonna per l'ordinamento. Se ``None``, viene
+                usata la prima colonna della chiave primaria.
             asc (bool): Ordinamento crescente se ``True``. Default: ``True``.
             parsing_model (Type[BaseModel], optional): Modello alternativo per
                 la serializzazione.
@@ -633,25 +691,34 @@ class CrudRepository[Entity: Base | Type[Base]]:
         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)
+        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 or self.model).validate_python(paginated.data, from_attributes=True)
+            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):
         if where is None:
             where = kwhere if kwhere else {}
-        stmt = self._select(entity=self.entity, columns=columns, exclude_columns=exclude_columns)
-        stmt = self.stmt_manager.prepare_statement(stmt=stmt, **where)
-
-        row_numbers = self._preconf_count(session=session, where=stmt.whereclause)
 
+        stmt = self._select(entity=self.entity, columns=columns, exclude_columns=exclude_columns)
+        conditions = self.stmt_manager.conditions(where=where)
         order_by = order_by or self.entity.primary_key()[0].name
+        if conditions:
+            stmt = stmt.where(*conditions)
         stmt = self.stmt_manager.limit_offset_condition(stmt=stmt, limit=limit, page=page)
         stmt = self.stmt_manager.order_by_condition(stmt=stmt, order_by=order_by, asc=asc)
-
         entities = self.execute(session, stmt)
-        return self.parse_pagination(limit=limit, page=page, order_by=order_by, count=row_numbers, asc=asc, data=entities)
+
+        len_entities = len(entities)
+        if limit == 0 or (len_entities < limit and page == 1):
+            count_ = len_entities
+        elif limit > len_entities > 0 and page > 1:
+            count_ = (page - 1) * limit + len_entities
+        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)
 
     def parse_pagination(self, limit: int, page: int, order_by: str, asc: bool, count: int, data: Sequence[Row] | Sequence[Row | RowMapping] | Sequence[RowMapping]) -> PaginatorResponseModel:
         """Costruisce il ``PaginatorResponseModel`` dai dati di paginazione.
@@ -681,8 +748,8 @@ class CrudRepository[Entity: Base | Type[Base]]:
         """Coppie distinte ``(key, value)`` per i record che soddisfano ``where``.
 
         Calcola i valori distinti lato DB con ``SELECT DISTINCT`` invece di caricare
-        tutte le righe e dedupplicare in Python (usato da ``BaseService.company_filters``
-        per popolare le opzioni dei filtri). Per le colonne ``ARRAY`` srotola in
+        tutte le righe e dedupplicare in Python. Tipicamente usato per popolare le
+        opzioni di un filtro lato client. Per le colonne ``ARRAY`` srotola in
         parallelo chiave ed etichetta con ``unnest`` (lateral implicito).
 
         Args:
@@ -694,6 +761,14 @@ class CrudRepository[Entity: Base | Type[Base]]:
 
         Returns:
             list[Row]: Coppie ``(key, value)`` distinte.
+
+        Note:
+            A differenza degli altri metodi restituisce ``Row`` (tuple) e non modelli
+            Pydantic: non passa da ``_return`` e non accetta un ``parsing_model``.
+
+        Example:
+            >>> repo.distinct_pairs("id_operatore", "operatore", where={"id_azienda": 3})
+            [(1, 'Rossi'), (2, 'Bianchi')]
         """
         if where is None:
             where = kwhere if kwhere else {}
@@ -723,6 +798,11 @@ class CrudRepository[Entity: Base | Type[Base]]:
 
         In caso di errore, delega la gestione a ``_handle_exception``.
 
+        Poiché usa ``.scalars()``, di ogni riga viene restituita solo la **prima**
+        colonna: statement arricchiti con ``add_columns`` perdono le colonne
+        aggiuntive. Per leggerle serve eseguire lo statement direttamente sulla
+        sessione (vedi ``distinct_pairs``, che usa ``session.execute(...).all()``).
+
         Args:
             session (Session): Sessione su cui eseguire lo statement.
             stmt (Select | Insert | Update | Delete): Statement da eseguire.