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

{python_general_be_lib-0.8.0 → python_general_be_lib-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.8.0
+Version: 0.8.2
 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
@@ -25,6 +25,9 @@ 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
@@ -69,40 +72,3 @@ repo.find(active=True, order_by="name", asc=True)
 | 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 → python_general_be_lib-0.8.2}/README.md

@@ -36,41 +36,4 @@ repo.find(active=True, order_by="name", asc=True)
 | 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).
+| Logging | `init_logger`, decorator `@log` |

{python_general_be_lib-0.8.0 → python_general_be_lib-0.8.2}/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,20 @@ class Base:
         if not default_values:
             default_values = dict()
         mapper: Mapper = inspect(cls)
+
+        # ``mapper.columns`` è indicizzato per **nome di attributo** e non forza la
+        # configurazione dei mapper: ``column_attrs``/``attrs``/``relationships`` la
+        # forzerebbero, e chiamare ``to_pydantic`` a import-time — il pattern
+        # documentato — romperebbe le relationship con forward-ref non ancora
+        # risolvibili (stessa ragione per cui ``relationship_attributes`` è lazy).
+        selected = [(name, column) for name, column in mapper.columns.items()
+                    if include_only is None or name 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 = {name: None if full_optional else ... for name, _ in selected}
         field_values.update(default_values)
-        for col in mapper.columns:
-            field_name = col.name
+        for field_name, col in selected:
             if isinstance(col.type, Geometry):
                 field_type = Optional[WKBElement] if col.nullable or full_optional else WKBElement
             else:

{python_general_be_lib-0.8.0 → python_general_be_lib-0.8.2}/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,25 @@ 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.
+    """
+    # ``mapper.columns`` è indicizzato per nome di attributo e non forza la
+    # configurazione dei mapper (a differenza di ``column_attrs``/``attrs``).
+    ordinate = [name for name in inspect(entity).columns.keys() if name 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 +129,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(inspect(self.entity).columns.keys())
+        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.
 
@@ -211,9 +242,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
@@ -318,6 +349,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,
@@ -583,40 +615,56 @@ 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. Il count riusa la
-        ``whereclause`` già costruita sullo statement di selezione
-        (``_preconf_count``), così i filtri vengono tradotti una sola volta.
+        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.
@@ -645,25 +693,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.

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

@@ -76,6 +76,7 @@ class GeometryRepository[Entity: Base | Type[Base]](CrudRepository[Entity]):
         keep_open = False if session is None else True
         session = self.open_session if session is None else session
         entities = self._intersects(session=session, geom=geom, tolerance=tolerance, where=where, not_where=not_where, columns=columns, exclude_columns=exclude_columns, limit=limit, geom_srid=geom_srid)
+        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 _intersects(self, session: Session, geom: WKBElement, tolerance: float = 0.0, columns: list[str] = None, exclude_columns: list[str] = None, where: dict[str, Any] = None, not_where: dict[str, Any] = None,
@@ -88,12 +89,9 @@ class GeometryRepository[Entity: Base | Type[Base]](CrudRepository[Entity]):
         stmt = self._select(entity=self.entity, columns=columns, exclude_columns=exclude_columns)
 
         intersecting_geom = self._geom_condition(geom=geom, geom_srid=geom_srid)
-
-        stmt = self.stmt_manager.prepare_statement(stmt=stmt, **where)
-        stmt = self.stmt_manager.prepare_statement(stmt=stmt, neq=True, **not_where)
-
         geom_condition = self.geom_column.ST_DWithin(intersecting_geom, tolerance) if tolerance else self.geom_column.ST_Intersects(intersecting_geom)
-        stmt = stmt.where(geom_condition)
+
+        stmt = stmt.where(*self.stmt_manager.conditions(where=where), *self.stmt_manager.conditions(neq=True, where=not_where), geom_condition)
         stmt = self.stmt_manager.limit_offset_condition(stmt=stmt, limit=limit)
 
         return self.execute(session, stmt)
@@ -131,6 +129,7 @@ class GeometryRepository[Entity: Base | Type[Base]](CrudRepository[Entity]):
         keep_open = False if session is None else True
         session = self.open_session if session is None else session
         entities = self._contains(session=session, geom=geom, tolerance=tolerance, where=where, contained=contained, columns=columns, exclude_columns=exclude_columns, limit=limit, geom_srid=geom_srid)
+        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 _contains(self, session: Session, geom: WKBElement, tolerance: float = 0.0, columns: list[str] = None, exclude_columns: list[str] = None, where: dict[str, Any] = None, limit: int = 0, contained: bool = False,
@@ -139,12 +138,11 @@ class GeometryRepository[Entity: Base | Type[Base]](CrudRepository[Entity]):
             where = {}
 
         stmt = self._select(entity=self.entity, columns=columns, exclude_columns=exclude_columns)
-        stmt = self.stmt_manager.prepare_statement(stmt=stmt, **where)
 
         geom_condition = self._geom_condition(geom=geom, geom_srid=geom_srid, buffer=tolerance)
         geom_condition = self.geom_column.ST_Contains(geom_condition) if not contained else geom_condition.ST_Contains(self.geom_column)
 
-        stmt = stmt.where(geom_condition)
+        stmt = stmt.where(*self.stmt_manager.conditions(where=where), geom_condition)
 
         stmt = self.stmt_manager.limit_offset_condition(stmt=stmt, limit=limit)
         return self.execute(session, stmt)
@@ -183,6 +181,7 @@ class GeometryRepository[Entity: Base | Type[Base]](CrudRepository[Entity]):
         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)
+        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 _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):

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

@@ -2,7 +2,7 @@ __all__ = ["BaseHandler"]
 
 from typing import Any
 
-from sqlalchemy import Select, Update, Delete, Column, not_, ARRAY, type_coerce
+from sqlalchemy import Select, Update, Delete, Column, ColumnElement, not_, ARRAY, type_coerce
 from sqlalchemy.sql.base import ReadOnlyColumnCollection
 
 
@@ -40,10 +40,13 @@ class BaseHandler:
         self.array_columns = {column.name for column in columns if isinstance(column.type, ARRAY)}
 
     def handle(self, stmt: Select | Update | Delete, neq: bool = False, where: dict[str, Any] = None):
-        """Applica i filtri WHERE allo statement per tutte le coppie chiave-valore in ``where``.
+        """Applica allo statement le condizioni prodotte da ``conditions``.
 
-        Per ogni coppia ``{colonna: valore}`` delega la costruzione della condizione
-        a ``_handle`` e la aggiunge allo statement con ``.where()``.
+        Adattatore fra il protocollo degli handler (che costruisce condizioni) e uno
+        statement: raccoglie tutte le condizioni e le aggiunge con **una sola**
+        chiamata a ``.where()``. Nella pipeline normale è ``StatementManager`` a
+        occuparsene, accorpando anche le condizioni degli altri handler; questo
+        metodo serve a usare un handler in isolamento.
 
         Args:
             stmt (Select | Update | Delete): Statement SQLAlchemy su cui applicare i filtri.
@@ -59,9 +62,33 @@ class BaseHandler:
             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()])
+        conditions = self.conditions(neq=neq, where=where)
+        stmt = stmt.where(*conditions)
         return stmt
 
+    def conditions(self, neq: bool = False, where: dict[str, Any] = None) -> list[ColumnElement[Any]]:
+        """Costruisce una condizione per ogni coppia ``{colonna: valore}`` rimasta in ``where``.
+
+        Essendo l'ultimo handler della pipeline, ``BaseHandler`` non ha successori e
+        quindi — a differenza degli handler specializzati — **non rimuove** le chiavi
+        dal dizionario: le consuma tutte trattandole come colonne reali. Ogni chiave
+        che nessun handler precedente ha rivendicato e che non è una colonna provoca
+        perciò un ``KeyError``.
+
+        Args:
+            neq (bool): Se ``True``, ogni condizione viene negata con ``NOT``.
+                Default: ``False``.
+            where (dict[str, Any]): Filtri ``{nome_colonna: valore}``.
+
+        Returns:
+            list[ColumnElement]: Una condizione per ogni chiave, nell'ordine del
+                dizionario.
+
+        Raises:
+            KeyError: Se una chiave non corrisponde a nessuna colonna della tabella.
+        """
+        return [self._handle(column=self.columns[column], condition=condition, neq=neq) for column, condition in where.items()]
+
     def _handle(self, column: Column, condition: Any, neq: bool = False):
         """Costruisce la singola condizione WHERE per una colonna.
 

python_general_be_lib-0.8.2/general/interface/repository/handler/ilike_handler.py

@@ -0,0 +1,105 @@
+__all__ = ["ILikeHandler"]
+
+from typing import Any
+
+from sqlalchemy import Column, ColumnElement, or_
+from sqlalchemy.sql.base import ReadOnlyColumnCollection
+
+from .base_handler import BaseHandler
+
+
+class ILikeHandler(BaseHandler):
+    """Handler per ricerche case-insensitive (ILIKE) su più colonne tramite un alias.
+
+    Permette di esporre un singolo parametro di ricerca testuale (es. ``"search"``)
+    che viene applicato come ``ILIKE '%value%'`` su un insieme di colonne con ``OR``.
+
+    Attributes:
+        ilike_aliases (list[str]): Chiavi nel dizionario ``where`` che attivano
+            la ricerca ILIKE (es. ``["search", "q"]``).
+        ilike_attributes (list[Column]): Colonne su cui applicare ILIKE, già
+            risolte in fase di inizializzazione dai nomi passati al costruttore.
+
+    Example:
+        >>> handler = ILikeHandler(
+        ...     columns=User.columns(),
+        ...     ilike_aliases=["search"],
+        ...     ilike_attributes=["name", "surname"]
+        ... )
+        >>> repo.find(where={"search": "mario"})
+        # WHERE name ILIKE '%mario%' OR surname ILIKE '%mario%'
+    """
+    __slots__ = "ilike_aliases", "ilike_attributes"
+    ilike_aliases: list[str]
+    ilike_attributes: list[Column]
+
+    def __init__(self, columns: ReadOnlyColumnCollection[str, Column[Any]], ilike_aliases: list[str] = None, ilike_attributes: list[str] = None):
+        """Inizializza l'handler risolvendo subito gli ``ilike_attributes`` in colonne.
+
+        Gli attributi vengono tradotti una volta sola in oggetti ``Column``, così a
+        ogni richiesta non si paga la risoluzione per nome: è la parte di
+        precalcolo dell'handler.
+
+        Args:
+            columns (ReadOnlyColumnCollection): Colonne della tabella.
+            ilike_aliases (list[str], optional): Chiavi alias che attivano la ricerca.
+                Default: lista vuota.
+            ilike_attributes (list[str], optional): Colonne su cui applicare ILIKE.
+                Default: lista vuota.
+
+        Raises:
+            KeyError: Se uno degli ``ilike_attributes`` non è una colonna della tabella.
+                La risoluzione avviene qui, quindi l'errore è immediato e non alla
+                prima query.
+        """
+        super().__init__(columns)
+        self.ilike_aliases = ilike_aliases if ilike_aliases is not None else []
+        self.ilike_attributes = [self.columns[ilike_attribute] for ilike_attribute in ilike_attributes] if ilike_attributes is not None else []
+
+    def conditions(self, neq: bool = False, where: dict[str, Any] = None) -> list[ColumnElement[Any]]:
+        """Costruisce una condizione ``OR`` di ``ILIKE`` per ogni alias valorizzato in ``where``.
+
+        Per ogni alias in ``ilike_aliases`` estrae il valore dal ``where``
+        **rimuovendolo** (anche quando non produce nessuna condizione, vedi sotto) e
+        genera un ``ILIKE '%valore%'`` su tutte le colonne di ``ilike_attributes``,
+        unite da ``OR``. Ogni alias produce una condizione a sé, quindi più alias
+        valorizzati si combinano in ``AND``.
+
+        Args:
+            neq (bool): Ignorato. La negazione non è implementata: con ``neq=True``
+                viene generata comunque la condizione **positiva**. Riguarda il
+                ``not_where`` di ``GeometryRepository``.
+            where (dict[str, Any]): Filtri. Gli alias gestiti vengono rimossi in-place.
+
+        Returns:
+            list[ColumnElement]: Una condizione per ogni alias valorizzato.
+
+        Note:
+            I valori falsy (``None``, ``""``, ``0``) non producono nessuna condizione,
+            ma la chiave viene **comunque rimossa** dal ``where``: una ricerca con la
+            stringa vuota equivale a nessun filtro.
+        """
+        conditions = []
+        for alias in self.ilike_aliases:
+            condition = where.pop(alias, None)
+            if condition:
+                or_conditions = [self._handle(column=ilike_column, condition=condition, neq=neq) for ilike_column in self.ilike_attributes]
+                conditions.append(or_(*or_conditions))
+        return conditions
+
+    def _handle(self, column: Column, condition: Any, neq: bool = False):
+        """Costruisce l'``ILIKE`` su una singola colonna, con il valore fra due ``%``.
+
+        Sovrascrive la logica di ``BaseHandler._handle`` (uguaglianza / ``IN`` /
+        ``ARRAY``): qui il confronto è sempre una ricerca testuale parziale.
+
+        Args:
+            column (Column): Colonna (o espressione, es. una chiave JSON già estratta
+                da ``JsonILikeHandler``) su cui applicare l'``ILIKE``.
+            condition (Any): Valore da cercare; viene interpolato in ``%valore%``.
+            neq (bool): Ignorato, vedi ``conditions``.
+
+        Returns:
+            ColumnElement: Espressione ``column ILIKE '%valore%'``.
+        """
+        return column.ilike(f'%{condition}%')