python-general-be-lib 0.7.1__tar.gz → 0.8.0__tar.gz

python_general_be_lib-0.8.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: python-general-be-lib
+Version: 0.8.0
+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: 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` |
+
+---
+
+## Documentazione
+
+Il codice della libreria vive nella directory `general/`, che è un **git
+submodule** ([novatellus/shared-be-libs](https://github.com/novatellus/shared-be-libs)).
+Questo repository esterno è il wrapper di packaging e pubblicazione.
+
+- **[general/README.md](general/README.md)** — panoramica, quickstart, contratto
+  di sessione, handler, operazioni spaziali
+- **[general/DOCS.md](general/DOCS.md)** — riferimento completo di ogni metodo
+
+Dopo il clone, inizializza il submodule:
+
+```bash
+git submodule update --init --recursive
+```
+
+---
+
+## Build e pubblicazione
+
+La versione è definita in **entrambi** `setup.py` e `pyproject.toml`: vanno
+aggiornati insieme. I messaggi di commit sono prefissati con la nuova versione
+(es. `0.7.2 OrHandler e distinct_pairs`).
+
+```bash
+python3 setup.py sdist bdist_wheel   # build di sdist + wheel in dist/
+python3 -m twine upload dist/*       # pubblicazione su PyPI
+```
+
+---
+
+## Licenza
+
+MIT — vedi [LICENSE](LICENSE).

python_general_be_lib-0.8.0/README.md

@@ -0,0 +1,76 @@
+# 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` |
+
+---
+
+## Documentazione
+
+Il codice della libreria vive nella directory `general/`, che è un **git
+submodule** ([novatellus/shared-be-libs](https://github.com/novatellus/shared-be-libs)).
+Questo repository esterno è il wrapper di packaging e pubblicazione.
+
+- **[general/README.md](general/README.md)** — panoramica, quickstart, contratto
+  di sessione, handler, operazioni spaziali
+- **[general/DOCS.md](general/DOCS.md)** — riferimento completo di ogni metodo
+
+Dopo il clone, inizializza il submodule:
+
+```bash
+git submodule update --init --recursive
+```
+
+---
+
+## Build e pubblicazione
+
+La versione è definita in **entrambi** `setup.py` e `pyproject.toml`: vanno
+aggiornati insieme. I messaggi di commit sono prefissati con la nuova versione
+(es. `0.7.2 OrHandler e distinct_pairs`).
+
+```bash
+python3 setup.py sdist bdist_wheel   # build di sdist + wheel in dist/
+python3 -m twine upload dist/*       # pubblicazione su PyPI
+```
+
+---
+
+## Licenza
+
+MIT — vedi [LICENSE](LICENSE).

python_general_be_lib-0.8.0/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.0/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.0/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.1 → python_general_be_lib-0.8.0}/general/interface/base/declarative_base.py

@@ -111,6 +111,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 +132,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.1 → python_general_be_lib-0.8.0}/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.1 → python_general_be_lib-0.8.0}/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.1 → python_general_be_lib-0.8.0}/general/interface/repository/crud_repository.py

@@ -179,8 +179,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.
@@ -301,6 +302,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"]})
@@ -606,16 +614,20 @@ class CrudRepository[Entity: Base | Type[Base]]:
         """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.
+        filtrati, e restituisce solo la pagina richiesta. Il count riusa la
+        ``whereclause`` già costruita sullo statement di selezione
+        (``_preconf_count``), così i filtri vengono tradotti una sola volta.
 
         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.
@@ -681,8 +693,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 +706,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 +743,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.

{python_general_be_lib-0.7.1 → python_general_be_lib-0.8.0}/general/interface/repository/geometry_repository.py

@@ -150,50 +150,48 @@ class GeometryRepository[Entity: Base | Type[Base]](CrudRepository[Entity]):
         return self.execute(session, stmt)
 
     def nearest(self, geom: WKBElement, session: Session = None, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 1, where: dict[str, Any] = None, geom_srid: int = 4326,
-                distance: bool = True, parsing_model: Type[BaseModel] | BaseModel = None) -> list[Entity]:
+                parsing_model: Type[BaseModel] | BaseModel = None) -> list[Entity]:
         """Restituisce le entità più vicine alla geometria fornita, ordinate per distanza.
 
-        Aggiunge una colonna ``distance`` ai risultati con la distanza calcolata
-        tramite ``ST_Distance``. L'ordinamento usa l'operatore KNN ``<->``
-        (``distance_centroid``) anziché ``ST_Distance``: con ``LIMIT`` impostato,
-        PostGIS può servire la ricerca dei più vicini tramite l'indice spaziale
-        GiST, evitando il calcolo della distanza su tutte le righe.
+        L'ordinamento usa l'operatore KNN ``<->`` (``distance_centroid``) anziché
+        ``ST_Distance``: con ``LIMIT`` impostato, PostGIS può servire la ricerca dei
+        più vicini tramite l'indice spaziale GiST, evitando il calcolo della
+        distanza su tutte le righe.
 
         Args:
-            geom (WKBElement): Geometria di riferimento per il calcolo della distanza.
+            geom (WKBElement): Geometria di riferimento per il calcolo della prossimità.
             session (Session, optional): Sessione esterna.
             columns (list[str], optional): Colonne da includere.
             exclude_columns (list[str], optional): Colonne da escludere.
             limit (int): Numero di entità più vicine da restituire. Default: 1.
             where (dict[str, Any], optional): Filtri aggiuntivi.
             geom_srid (int): SRID della geometria fornita. Default: 4326.
-            distance (bool): Se ``True``, aggiunge ai risultati la colonna ``distance``
-                con la distanza calcolata via ``ST_Distance``. Default: ``True``.
-                L'ordinamento per prossimità (operatore KNN ``<->``) viene applicato
-                in ogni caso, indipendentemente da questo flag.
             parsing_model (Type[BaseModel], optional): Modello alternativo.
 
         Returns:
             list[Entity]: Entità ordinate dalla più vicina alla più lontana.
 
+        Note:
+            Restituisce solo le entità, senza il valore della distanza: la distanza
+            è usata unicamente per l'ordinamento lato database. Per ottenerla come
+            colonna serve uno statement custom, dato che ``execute`` restituisce
+            ``result.scalars().all()`` e terrebbe solo la prima colonna di ogni riga.
+
         Example:
             >>> nearest = repo.nearest(geom=my_point, limit=5)
         """
         keep_open = False if session is None else True
         session = self.open_session if session is None else session
-        entities = self._nearest(session=session, geom=geom, where=where, columns=columns, exclude_columns=exclude_columns, limit=limit, geom_srid=geom_srid, distance=distance)
+        entities = self._nearest(session=session, geom=geom, where=where, columns=columns, exclude_columns=exclude_columns, limit=limit, geom_srid=geom_srid)
         return self._return(session=session, entities=entities, keep_open=keep_open, commit=False, parsing_model=parsing_model)
 
-    def _nearest(self, session: Session, geom: WKBElement, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 1, where: dict[str, Any] = None, geom_srid: int = 4326, distance: bool = True):
+    def _nearest(self, session: Session, geom: WKBElement, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 1, where: dict[str, Any] = None, geom_srid: int = 4326):
         if where is None:
             where = {}
         stmt = self._select(entity=self.entity, columns=columns, exclude_columns=exclude_columns)
 
         geom_condition = self._geom_condition(geom=geom, geom_srid=geom_srid)
 
-        if distance:
-            stmt = stmt.add_columns(self.geom_column.ST_Distance(geom_condition).label("distance"))
-
         stmt = self.stmt_manager.prepare_statement(stmt=stmt, **where)
         stmt = stmt.order_by(self.geom_column.distance_centroid(geom_condition))
         stmt = self.stmt_manager.limit_offset_condition(stmt=stmt, limit=limit)

{python_general_be_lib-0.7.1 → python_general_be_lib-0.8.0}/general/interface/repository/handler/base_handler.py

@@ -10,7 +10,14 @@ class BaseHandler:
     """Handler base per la costruzione di filtri WHERE su statement SQLAlchemy.
 
     Gestisce i casi standard di uguaglianza, liste (``IN``) e colonne di tipo
-    ``ARRAY``. Può essere esteso per supportare logiche di filtraggio personalizzate.
+    ``ARRAY``. È anche la classe base di tutti gli handler specializzati, che
+    possono estenderla per logiche di filtraggio personalizzate.
+
+    Nella pipeline dello ``StatementManager`` è sempre l'**ultimo** handler
+    eseguito: riceve le chiavi del ``where`` non consumate dagli handler
+    precedenti e le tratta come filtri su colonne reali. A differenza degli
+    handler specializzati non rimuove nulla dal dizionario, perché non ha
+    successori.
 
     Attributes:
         columns (ReadOnlyColumnCollection): Colonne della tabella su cui operare.
@@ -43,9 +50,14 @@ class BaseHandler:
             neq (bool): Se ``True``, applica la negazione (``NOT``) a ogni condizione.
                 Default: ``False``.
             where (dict[str, Any]): Dizionario ``{nome_colonna: valore}`` con i filtri.
+                Tutte le chiavi devono corrispondere a colonne reali della tabella.
 
         Returns:
             Select | Update | Delete: Statement arricchito con le clausole WHERE.
+
+        Raises:
+            KeyError: Se una chiave del ``where`` non corrisponde a nessuna colonna,
+                ovvero se nessun handler precedente l'ha consumata.
         """
         stmt = stmt.where(*[self._handle(column=self.columns[column], condition=condition, neq=neq) for column, condition in where.items()])
         return stmt