python-general-be-lib 0.8.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

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:

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.
 
@@ -211,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
@@ -318,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,
@@ -583,40 +613,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 +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.

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):

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.
 

general/interface/repository/handler/ilike_handler.py

@@ -2,7 +2,7 @@ __all__ = ["ILikeHandler"]
 
 from typing import Any
 
-from sqlalchemy import Column, Select, Update, Delete, or_
+from sqlalchemy import Column, ColumnElement, or_
 from sqlalchemy.sql.base import ReadOnlyColumnCollection
 
 from .base_handler import BaseHandler
@@ -17,8 +17,8 @@ class ILikeHandler(BaseHandler):
     Attributes:
         ilike_aliases (list[str]): Chiavi nel dizionario ``where`` che attivano
             la ricerca ILIKE (es. ``["search", "q"]``).
-        ilike_attributes (list[str]): Nomi delle colonne su cui applicare ILIKE
-            (es. ``["name", "surname", "email"]``).
+        ilike_attributes (list[Column]): Colonne su cui applicare ILIKE, già
+            risolte in fase di inizializzazione dai nomi passati al costruttore.
 
     Example:
         >>> handler = ILikeHandler(
@@ -31,10 +31,14 @@ class ILikeHandler(BaseHandler):
     """
     __slots__ = "ilike_aliases", "ilike_attributes"
     ilike_aliases: list[str]
-    ilike_attributes: 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 validando che le colonne ILIKE esistano sull'entità.
+        """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.
@@ -44,47 +48,58 @@ class ILikeHandler(BaseHandler):
                 Default: lista vuota.
 
         Raises:
-            ValueError: Se uno degli ``ilike_attributes`` non è presente tra le colonne.
+            KeyError: Se uno degli ``ilike_attributes`` non è una colonna della tabella.
+                La risoluzione avviene qui, quindi l'errore è immediato e non alla
+                prima query.
         """
-        self.columns = columns
+        super().__init__(columns)
         self.ilike_aliases = ilike_aliases if ilike_aliases is not None else []
-        self.ilike_attributes = ilike_attributes if ilike_attributes is not None else []
-
-        for ilike_attribute in self.ilike_attributes:
-            if ilike_attribute not in self.columns:
-                raise ValueError(f"{ilike_attribute} not in columns")
+        self.ilike_attributes = [self.columns[ilike_attribute] for ilike_attribute in ilike_attributes] if ilike_attributes is not None else []
 
-    def handle(self, stmt: Select | Update | Delete, where: dict[str, Any] = None, **kwargs):
-        """Applica i filtri ILIKE allo statement per ogni alias trovato in ``where``.
+    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 presente in ``ilike_aliases`` e trovato in ``where``,
-        estrae il valore, lo rimuove dal dizionario e aggiunge la condizione ILIKE
-        su tutte le colonne in ``ilike_attributes`` con ``OR``.
+        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:
-            stmt (Select | Update | Delete): Statement su cui applicare i filtri.
-            where (dict[str, Any]): Dizionario dei filtri. Gli alias ILIKE vengono
-                estratti e rimossi in-place.
-            **kwargs: Ignorati (compatibilità con l'interfaccia base).
+            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:
-            Select | Update | Delete: Statement con le condizioni ILIKE aggiunte.
+            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:
-                stmt = stmt.where(self._handle(alias, condition))
-        return stmt
+                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 ``%``.
 
-    def _handle(self, alias: str, condition: str, neq: bool = False):
-        """Costruisce la condizione ILIKE con OR su tutte le colonne configurate.
+        Sovrascrive la logica di ``BaseHandler._handle`` (uguaglianza / ``IN`` /
+        ``ARRAY``): qui il confronto è sempre una ricerca testuale parziale.
 
         Args:
-            alias (str): Alias attivato (usato per identificare la ricerca, non la colonna).
-            condition (str): Stringa da cercare (viene wrappata con ``%``).
-            neq (bool): Non utilizzato in questa implementazione.
+            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 ``OR(col1 ILIKE '%val%', col2 ILIKE '%val%', ...)``.
+            ColumnElement: Espressione ``column ILIKE '%valore%'``.
         """
-        return or_(*[self.columns[col].ilike(f'%{condition}%') for col in self.ilike_attributes])
+        return column.ilike(f'%{condition}%')

general/interface/repository/handler/interval_handler.py

@@ -2,7 +2,7 @@ __all__ = ["IntervalHandler"]
 
 from typing import Any
 
-from sqlalchemy import Column, Select, Update, Delete, or_
+from sqlalchemy import Column, ColumnElement, or_
 from sqlalchemy.sql.base import ReadOnlyColumnCollection
 
 from .base_handler import BaseHandler
@@ -21,11 +21,14 @@ class IntervalHandler(BaseHandler):
     Se non forniti, gli alias coincidono col nome della colonna.
 
     Quando i due alias coincidono l'handler entra in modalità ``between``: una
-    singola chiave nel ``where`` valorizza entrambi i limiti (vedi ``handle``).
+    singola chiave nel ``where`` valorizza entrambi i limiti (vedi ``conditions``).
 
     Attributes:
-        from\\_ (Any): Nome della colonna su cui applicare il limite inferiore (``>=``).
-        to\\_ (Any): Nome della colonna su cui applicare il limite superiore (``<=``).
+        from\\_ (Column | None): Colonna su cui applicare il limite inferiore (``>=``),
+            risolta in fase di inizializzazione dal nome passato al costruttore.
+            ``None`` se il limite inferiore non è configurato.
+        to\\_ (Column | None): Colonna su cui applicare il limite superiore (``<=``),
+            risolta come sopra. ``None`` se il limite superiore non è configurato.
         from_alias (str): Chiave del ``where`` che valorizza il limite inferiore.
         to_alias (str): Chiave del ``where`` che valorizza il limite superiore.
         inf_is_none (bool): Se ``True``, un valore ``NULL`` nella colonna ``to_``
@@ -43,23 +46,28 @@ class IntervalHandler(BaseHandler):
         # WHERE data_inizio >= '2024-01-01' AND (data_fine <= '2024-12-31' OR data_fine IS NULL)
     """
     __slots__ = "from_", "to_", "inf_is_none", "from_alias", "to_alias", "between"
-    from_: Any
-    to_: Any
+    from_: Column | None
+    to_: Column | None
     from_alias: str
     to_alias: str
     inf_is_none: bool
     between: bool
 
     def __init__(self, columns: ReadOnlyColumnCollection[str, Column[Any]], from_: Any = None, from_alias: str = None, to_: Any = None, to_alias: str = None, inf_is_none: bool = False):
-        """Inizializza l'handler con le colonne dei limiti e i relativi alias.
+        """Inizializza l'handler risolvendo subito le colonne dei limiti.
+
+        I nomi di colonna passati in ``from_``/``to_`` vengono tradotti una volta sola
+        in oggetti ``Column``, così a ogni richiesta non si paga la risoluzione per
+        nome. Gli alias restano invece stringhe: sono chiavi del dizionario ``where``,
+        non colonne.
 
         Args:
             columns (ReadOnlyColumnCollection): Colonne della tabella.
-            from\\_ (Any, optional): Nome della colonna per il limite inferiore
+            from\\_ (str, optional): Nome della colonna per il limite inferiore
                 (condizione ``>=``). Default: ``None`` (disabilitato).
             from_alias (str, optional): Chiave del ``where`` da cui leggere il limite
                 inferiore. Se omessa, vale ``str(from_)``.
-            to\\_ (Any, optional): Nome della colonna per il limite superiore
+            to\\_ (str, optional): Nome della colonna per il limite superiore
                 (condizione ``<=``). Default: ``None`` (disabilitato).
             to_alias (str, optional): Chiave del ``where`` da cui leggere il limite
                 superiore. Se omessa, vale ``str(to_)``.
@@ -67,56 +75,69 @@ class IntervalHandler(BaseHandler):
                 condizione sul limite superiore per trattare NULL come infinito.
                 Default: ``False``.
 
+        Raises:
+            KeyError: Se ``from_`` o ``to_`` non sono colonne della tabella. La
+                risoluzione avviene qui, quindi l'errore è immediato e non alla prima
+                query.
+
         Note:
             Se gli alias risultanti sono uguali viene attivata la modalità
-            ``between`` (attributo ``between``).
+            ``between`` (attributo ``between``). Con entrambi i nomi di colonna a
+            ``None`` e nessun alias esplicito i due alias valgono entrambi
+            ``"None"``, quindi la modalità ``between`` risulta attiva su un handler
+            che non ha nulla da filtrare.
         """
-        self.columns = columns
-        self.from_ = from_
-        self.to_ = to_
+        super().__init__(columns)
+        self.from_ = self.columns[from_] if from_ else None
+        self.to_ = self.columns[to_] if to_ else None
         self.from_alias = from_alias if from_alias else str(from_)
         self.to_alias = to_alias if to_alias else str(to_)
         self.inf_is_none = inf_is_none
         self.between = True if self.from_alias == self.to_alias else False
 
-    def handle(self, stmt: Select | Update | Delete, where: dict[str, Any] = None, **kwargs):
-        """Applica le condizioni di range allo statement estraendo i valori da ``where``.
+    def conditions(self, neq: bool = False, where: dict[str, Any] = None) -> list[ColumnElement[Any]]:
+        """Costruisce le condizioni di limite inferiore e superiore leggendole dal ``where``.
+
+        Estrae e **rimuove** in-place le chiavi ``from_alias`` e ``to_alias``. In
+        modalità ``between`` viene letta solo ``from_alias`` e il suo valore alimenta
+        entrambi i limiti.
 
-        Estrae e rimuove in-place le chiavi ``from_alias`` e ``to_alias`` dal
-        dizionario ``where``, quindi aggiunge le relative condizioni allo statement.
-        In modalità ``between`` viene letta solo ``from_alias`` e il suo valore è
-        usato per entrambi i limiti.
+        Condizioni generate:
 
-        I valori falsy (``None``, ``0``, ``""``) vengono ignorati: la condizione non
-        viene aggiunta, ma la chiave è comunque rimossa dal ``where``. Un limite
-        inferiore pari a ``0`` non produce quindi nessun filtro.
+        - limite inferiore: ``from_ >= valore``;
+        - limite superiore: ``to_ <= valore``, oppure
+          ``(to_ <= valore OR to_ IS NULL)`` se ``inf_is_none=True``.
 
         Args:
-            stmt (Select | Update | Delete): Statement su cui applicare le condizioni.
-            where (dict[str, Any]): Dizionario dei filtri. Le chiavi di intervallo
-                vengono estratte e rimosse in-place.
-            **kwargs: Ignorati (compatibilità con l'interfaccia base).
+            neq (bool): Ignorato. La negazione non è implementata: con ``neq=True``
+                vengono generate comunque le condizioni **positive**.
+            where (dict[str, Any]): Filtri. Le chiavi di intervallo vengono rimosse
+                in-place.
 
         Returns:
-            Select | Update | Delete: Statement con le condizioni di range aggiunte.
+            list[ColumnElement]: Da zero a due condizioni, in ordine (inferiore,
+                superiore). Un estremo non configurato al costruttore
+                (``from_``/``to_`` a ``None``) non produce nulla anche se il ``where``
+                contiene il suo alias.
 
         Note:
-            - Limite inferiore: ``from_ >= value``
-            - Limite superiore: ``to_ <= value`` oppure ``(to_ <= value OR to_ IS NULL)``
-              se ``inf_is_none=True``.
-            - In modalità ``between`` le condizioni generate restano ``from_ >= value``
-              e ``to_ <= value``. Per ottenere la semantica "la riga è valida al valore
-              indicato" le colonne vanno mappate invertite, ad es. ``from_="data_fine"``
-              e ``to_="data_inizio"`` con lo stesso alias ``"data"``, che produce
-              ``data_fine >= value AND data_inizio <= value``.
+            I valori falsy (``None``, ``0``, ``""``) non producono nessuna condizione,
+            ma la chiave viene **comunque rimossa** dal ``where``: un limite inferiore
+            pari a ``0`` non genera quindi alcun filtro.
+
+            In modalità ``between`` le condizioni restano ``from_ >= valore`` e
+            ``to_ <= valore``: per ottenere la semantica "la riga è valida al valore
+            indicato" le colonne vanno mappate invertite (vedi il docstring della
+            classe).
         """
+        conditions = []
         from_condition = where.pop(self.from_alias, None)
         to_condition = where.pop(self.to_alias, None) if not self.between else from_condition
-        if from_condition:
-            stmt = stmt.where(self.columns[self.from_] >= from_condition)
-        if to_condition:
-            condition = self.columns[self.to_] <= to_condition
+        if from_condition and self.from_ is not None:
+            conditions.append(self.from_ >= from_condition)
+        if to_condition and self.to_ is not None:
+            condition = self.to_ <= to_condition
             if self.inf_is_none:
-                condition = or_(condition, self.columns[self.to_] == None)
-            stmt = stmt.where(condition)
-        return stmt
+                condition = or_(condition, self.to_ == None)
+            conditions.append(condition)
+        return conditions