python-general-be-lib 0.5.5__tar.gz → 0.6.0__tar.gz

{python_general_be_lib-0.5.5 → python_general_be_lib-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.5.5
+Version: 0.6.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

python_general_be_lib-0.6.0/general/interface/metadata/crud_metadata.py

@@ -0,0 +1,502 @@
+__all__ = ["CrudMetadata"]
+
+import logging
+from typing import Optional, Any, Type, Iterable, Sequence
+
+from pydantic import BaseModel
+from sqlalchemy import MetaData, Engine, Column, Table, inspect, Connection, select, RowMapping, CursorResult, not_
+from sqlalchemy.exc import NoSuchTableError
+
+from ...exception.crud_exceptions import HasNoAttributeException, InternalServerException
+
+
+class CrudMetadata:
+    """Repository CRUD basato su SQLAlchemy Core e ``MetaData``, senza ORM.
+
+    Alternativa a ``CrudRepository`` che opera su tabelle riflesse (``Table``)
+    e ``Connection`` invece che su entità mappate e ``Session``. Utile per
+    lavorare con tabelle prive di un modello ORM: lo schema viene riflesso a
+    runtime e le tabelle sono risolte per nome.
+
+    Le operazioni accettano una connessione esterna opzionale: se fornita
+    (``keep_open=True``) i risultati grezzi vengono restituiti senza commit né
+    chiusura; altrimenti la connessione viene aperta, committata e chiusa
+    internamente.
+
+    Attributes:
+        schema (str | None): Nome dello schema di default per le tabelle.
+        metadata (MetaData): Contenitore SQLAlchemy delle tabelle riflesse/definite.
+        engine (Engine): Istanza SQLAlchemy Engine connessa al database.
+        engine_inspection (Inspector): Inspector usato per le introspezioni
+            (es. presenza tabelle).
+
+    Example:
+        >>> meta = CrudMetadata(engine=engine, schema_name="public")
+        >>> rows = meta.find(from_table="users", where={"active": True}, limit=10)
+    """
+    __slots__ = "schema", "metadata", "engine", "engine_inspection"
+
+    @property
+    def open_connection(self):
+        """Apre e restituisce una nuova connessione all'engine.
+
+        Returns:
+            Connection: Nuova connessione associata all'engine configurato.
+        """
+        return self.engine.connect()
+
+    def __init__(self, engine: Engine, schema_name: str = None, reflect: bool = True):
+        """Inizializza il repository con l'engine e (opzionalmente) riflette lo schema.
+
+        Args:
+            engine (Engine): Istanza SQLAlchemy Engine connessa al database.
+            schema_name (str, optional): Nome dello schema di default a cui
+                appartengono le tabelle. Se ``None``, viene usato lo schema di
+                default della connessione.
+            reflect (bool): Se ``True``, riflette tutte le tabelle dello schema
+                indicato alla costruzione (operazione potenzialmente costosa su
+                schemi grandi). Default: ``True``.
+        """
+        self.schema = schema_name
+        self.metadata = MetaData(schema_name) if schema_name else MetaData()
+        self.engine = engine
+        self.engine_inspection = inspect(self.engine)
+        if reflect:
+            self.metadata.reflect(bind=self.engine, schema=schema_name)
+
+    # ---------------------------
+
+    def _handle_exception(self, connection: Connection, e: Exception, to_raise: bool = True):
+        """Chiude la connessione, logga l'errore ed eventualmente lo rilancia.
+
+        Args:
+            connection (Connection): Connessione da chiudere.
+            e (Exception): Eccezione catturata.
+            to_raise (bool): Se ``True``, rilancia l'eccezione dopo il logging.
+                Default: ``True``.
+
+        Raises:
+            Exception: L'eccezione originale, se ``to_raise=True``.
+        """
+        connection.close()
+        logging.error(e)
+        if to_raise:
+            raise e
+
+    def commit(self, connection: Connection):
+        """Esegue il commit sulla connessione, gestendo eventuali eccezioni.
+
+        Args:
+            connection (Connection): Connessione su cui eseguire il commit.
+
+        Raises:
+            Exception: In caso di errore durante il commit (via ``_handle_exception``).
+        """
+        try:
+            connection.commit()
+        except Exception as e:
+            self._handle_exception(connection, e)
+
+    def has_columns(self, *columns: Iterable[str], table: Table):
+        """Verifica che tutte le colonne specificate esistano sulla tabella.
+
+        Args:
+            *columns (str): Nomi delle colonne da verificare.
+            table (Table): Tabella su cui effettuare la verifica.
+
+        Returns:
+            bool: ``True`` se tutte le colonne sono presenti, ``False`` altrimenti.
+        """
+        return all([column in [c.key for c in table.c] for column in columns])
+
+    def _select(self, table: Table, columns: list[str] = None):
+        """Costruisce lo statement SELECT sulla tabella.
+
+        Args:
+            table (Table): Tabella su cui costruire il SELECT.
+            columns (list[str], optional): Colonne da selezionare. Se ``None``,
+                seleziona tutte le colonne della tabella.
+
+        Returns:
+            Select: Statement SELECT configurato.
+
+        Raises:
+            HasNoAttributeException: Se una colonna specificata non esiste sulla tabella.
+        """
+        try:
+            stmt = table.select() if not columns else select(*[table.c[column] for column in columns])
+        except:
+            raise HasNoAttributeException()
+        return stmt
+
+    def _return(self, connection: Connection, result: CursorResult | RowMapping | Sequence[RowMapping] | Sequence[dict] = None, keep_open: bool = False, commit: bool = True,
+                parsing_model: Type[BaseModel] | BaseModel = None):
+        """Serializza il risultato e chiude la connessione se necessario.
+
+        Se ``keep_open=True`` (connessione esterna), restituisce il risultato
+        grezzo senza chiudere la connessione. Altrimenti esegue il commit (se
+        richiesto), serializza con il ``parsing_model`` e chiude la connessione.
+
+        Args:
+            connection (Connection): Connessione corrente.
+            result (CursorResult | RowMapping | Sequence): Righe risultanti
+                (tipicamente mapping ``{colonna: valore}``).
+            keep_open (bool): Se ``True``, non chiude la connessione e non serializza.
+            commit (bool): Se ``True`` e ``keep_open=False``, esegue il commit.
+            parsing_model (Type[BaseModel], optional): Modello Pydantic con cui
+                istanziare ogni riga (``parsing_model(**row)``). Se ``None``,
+                restituisce le righe grezze.
+
+        Returns:
+            list[BaseModel] | Sequence: Modelli serializzati o righe grezze.
+        """
+        if keep_open:
+            return result
+        else:
+            if commit:
+                self.commit(connection=connection)
+            result = result if parsing_model is None else [parsing_model(**r) for r in result]
+            connection.close()
+        return result
+
+    def create_table(self, name: str, columns: Iterable[Column], **kwargs):
+        """Crea una nuova tabella sul database.
+
+        Args:
+            name (str): Nome della tabella da creare.
+            columns (Iterable[Column]): Colonne che compongono la tabella.
+            **kwargs: Argomenti aggiuntivi passati al costruttore ``Table``
+                (es. ``schema``, vincoli, ``Index``).
+        """
+        table = Table(name=name, metadata=self.metadata, *columns, **kwargs)
+        table.create(self.engine)
+
+    def drop_table(self, name: str):
+        """Elimina una tabella dal database e dal ``MetaData`` locale.
+
+        Args:
+            name (str): Nome della tabella da eliminare.
+        """
+        table = self.get_table(name=name)
+        table.drop(self.engine)
+        self.metadata.remove(table=table)
+
+    def find(self, from_table: str, connection: Connection = None, where: dict[str, Any] = None, columns: list[str] = None, limit: int = 0, parsing_model: Type[BaseModel] = None, **kwhere):
+        """Cerca le righe della tabella che corrispondono ai criteri specificati.
+
+        Args:
+            from_table (str): Nome della tabella su cui eseguire la ricerca.
+            connection (Connection, optional): Connessione esterna. Se ``None``,
+                ne viene aperta una nuova che viene chiusa al termine.
+            where (dict[str, Any], optional): Filtri come dizionario
+                ``{colonna: valore}``. Ha precedenza su ``**kwhere``.
+            columns (list[str], optional): Colonne da includere nel risultato.
+            limit (int): Numero massimo di righe. 0 = nessun limite. Default: 0.
+            parsing_model (Type[BaseModel], optional): Modello Pydantic per la
+                serializzazione delle righe.
+            **kwhere: Filtri aggiuntivi come keyword arguments.
+
+        Returns:
+            list[BaseModel] | Sequence[RowMapping]: Righe serializzate o mapping grezzi.
+
+        Example:
+            >>> meta.find(from_table="users", name="Mario", limit=10)
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        result = self._find(table=table, connection=connection, where=where, columns=columns, limit=limit, **kwhere)
+        return self._return(connection=connection, result=result, keep_open=keep_open, commit=False, parsing_model=parsing_model)
+
+    def _find(self, table: Table, connection: Connection, where: dict[str, Any] = None, columns: list[str] = None, limit: int = 0, **kwhere):
+        """Costruisce ed esegue lo statement SELECT con filtri e limit.
+
+        Args:
+            table (Table): Tabella su cui eseguire la SELECT.
+            connection (Connection): Connessione corrente.
+            where (dict[str, Any], optional): Filtri ``{colonna: valore}``.
+                Se ``None``, usa ``**kwhere``.
+            columns (list[str], optional): Colonne da selezionare.
+            limit (int): Numero massimo di righe. Default: 0 (nessun limite).
+            **kwhere: Filtri aggiuntivi come keyword arguments.
+
+        Returns:
+            Sequence[RowMapping]: Righe risultanti come mapping.
+        """
+        if where is None:
+            where = kwhere if kwhere else {}
+        stmt = self._select(table=table, columns=columns)
+        stmt = stmt.where(*[self._eq_where(table.c[column], condition) for column, condition in where.items()])
+        stmt = self._add_limit_offset_condition(stmt, limit)
+        return self.execute(connection=connection, stmt=stmt, mapping=True)
+
+    def insert(self, from_table: str, connection: Connection = None, models: list[Type[BaseModel] | BaseModel] = None, values: list[dict[str, Any]] = None, returning: bool = True,
+               parsing_model: Type[BaseModel] | BaseModel = None):
+        """Inserisce righe nella tabella a partire da modelli e/o dizionari di valori.
+
+        Le righe possono essere fornite come modelli Pydantic (``models``, da cui
+        si estraggono i valori con ``model_dump(exclude_none=True)``) e/o come
+        dizionari grezzi (``values``). Le due fonti vengono unite.
+
+        Args:
+            from_table (str): Nome della tabella su cui inserire.
+            connection (Connection, optional): Connessione esterna. Se ``None``,
+                ne viene aperta una nuova con commit automatico.
+            models (list[BaseModel], optional): Modelli Pydantic da inserire.
+            values (list[dict[str, Any]], optional): Righe come dizionari grezzi.
+            returning (bool): Se ``True``, usa ``RETURNING`` per recuperare le righe
+                inserite. Default: ``True``.
+            parsing_model (Type[BaseModel], optional): Modello per la serializzazione
+                del risultato.
+
+        Returns:
+            list[BaseModel] | Sequence[RowMapping]: Righe inserite (serializzate o grezze).
+
+        Note:
+            Se ``values`` è fornito, viene esteso in-place con i valori derivati
+            da ``models``.
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        values_condition = values if values else []
+        values_condition.extend([model.model_dump(exclude_none=True) for model in models]) if models else values_condition
+        result = self._insert(table=table, connection=connection, values=values_condition, returning=returning)
+        return self._return(connection=connection, result=result, keep_open=keep_open, commit=True, parsing_model=parsing_model)
+
+    def _insert(self, table: Table, connection: Connection, values: list[dict[str, Any]] = None, returning: bool = True):
+        """Costruisce ed esegue lo statement INSERT con i valori forniti.
+
+        Args:
+            table (Table): Tabella su cui inserire.
+            connection (Connection): Connessione corrente.
+            values (list[dict[str, Any]], optional): Righe da inserire. Se vuoto,
+                non esegue nessuna operazione.
+            returning (bool): Se ``True``, usa ``RETURNING``. Default: ``True``.
+
+        Returns:
+            Sequence[RowMapping] | list: Righe inserite come mapping, o lista vuota
+                se non ci sono valori.
+        """
+        if values:
+            stmt = table.insert().values(values)
+            stmt = stmt if not returning else stmt.returning()
+            return self.execute(connection=connection, stmt=stmt, mapping=True)
+        else:
+            return []
+
+    def update(self, from_table: str, connection: Connection = None, where: dict[str, Any] = None, returning: bool = True, parsing_model: Type[BaseModel] | BaseModel = None, **kwargs):
+        """Aggiorna le righe che soddisfano i criteri ``where`` con i valori in ``**kwargs``.
+
+        Args:
+            from_table (str): Nome della tabella da aggiornare.
+            connection (Connection, optional): Connessione esterna. Se ``None``,
+                ne viene aperta una nuova con commit automatico.
+            where (dict[str, Any], optional): Filtri per selezionare le righe da
+                aggiornare. Se ``None``, aggiorna tutte le righe (usare con cautela).
+            returning (bool): Se ``True``, usa ``RETURNING``. Default: ``True``.
+            parsing_model (Type[BaseModel], optional): Modello per la serializzazione
+                del risultato.
+            **kwargs: Valori da impostare sulle righe trovate.
+
+        Returns:
+            list[BaseModel] | Sequence[RowMapping]: Righe aggiornate (serializzate o grezze).
+
+        Example:
+            >>> meta.update(from_table="users", where={"id": 1}, name="Luigi")
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        result = self._update(table=table, connection=connection, where=where, returning=returning, **kwargs)
+        return self._return(connection=connection, result=result, keep_open=keep_open, commit=True, parsing_model=parsing_model)
+
+    def _update(self, table: Table, connection: Connection, where: dict[str, Any] = None, returning: bool = True, **kwargs):
+        """Costruisce ed esegue lo statement UPDATE con filtri e valori.
+
+        Args:
+            table (Table): Tabella da aggiornare.
+            connection (Connection): Connessione corrente.
+            where (dict[str, Any], optional): Filtri per le righe da aggiornare.
+            returning (bool): Se ``True``, usa ``RETURNING``. Default: ``True``.
+            **kwargs: Valori da impostare sulle righe.
+
+        Returns:
+            Sequence[RowMapping]: Righe aggiornate come mapping.
+        """
+        if where is None:
+            where = {}
+        stmt = table.update()
+        stmt = stmt.where(*[self._eq_where(table.c[column], condition) for column, condition in where.items()])
+        stmt = stmt.values(**kwargs)
+        stmt = stmt if not returning else stmt.returning()
+        return self.execute(connection=connection, stmt=stmt, mapping=True)
+
+    def delete(self, from_table: str, connection: Connection = None, where: dict[str, Any] = None, **kwhere):
+        """Elimina le righe che soddisfano i criteri specificati.
+
+        Args:
+            from_table (str): Nome della tabella da cui eliminare.
+            connection (Connection, optional): Connessione esterna. Se fornita, il
+                commit non viene eseguito automaticamente.
+            where (dict[str, Any], optional): Filtri come dizionario.
+                Ha precedenza su ``**kwhere``.
+            **kwhere: Filtri come keyword arguments.
+
+        Returns:
+            int: Numero di righe eliminate.
+
+        Example:
+            >>> meta.delete(from_table="users", id=5)
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        num_rows = self._delete(table=table, connection=connection, where=where, **kwhere)
+        if not num_rows or keep_open:
+            return num_rows
+        else:
+            self.commit(connection)
+        connection.close()
+        return num_rows
+
+    def _delete(self, table: Table, connection: Connection, where: dict[str, Any] = None, **kwhere):
+        """Costruisce ed esegue lo statement DELETE con i filtri forniti.
+
+        Args:
+            table (Table): Tabella da cui eliminare.
+            connection (Connection): Connessione corrente.
+            where (dict[str, Any], optional): Filtri ``{colonna: valore}``.
+                Se ``None``, usa ``**kwhere``.
+            **kwhere: Filtri come keyword arguments.
+
+        Returns:
+            int: Numero di righe eliminate (``rowcount``).
+        """
+        if where is None:
+            where = kwhere if kwhere else {}
+        stmt = table.delete()
+        stmt = stmt.where(*[self._eq_where(table.c[column], condition) for column, condition in where.items()])
+        return self.execute(connection=connection, stmt=stmt).rowcount
+
+    # --------------
+
+    def execute(self, connection: Connection, stmt, mapping: bool = False):
+        """Esegue uno statement sulla connessione, gestendo le eccezioni.
+
+        Args:
+            connection (Connection): Connessione su cui eseguire lo statement.
+            stmt: Statement SQLAlchemy Core da eseguire.
+            mapping (bool): Se ``True``, restituisce le righe come mapping
+                (``result.mappings().all()``); altrimenti restituisce il
+                ``CursorResult`` grezzo. Default: ``False``.
+
+        Returns:
+            Sequence[RowMapping] | CursorResult: Righe come mapping se ``mapping=True``,
+                altrimenti il result grezzo.
+
+        Raises:
+            Exception: In caso di errore durante l'esecuzione (via ``_handle_exception``).
+        """
+        try:
+            result = connection.execute(stmt)
+        except Exception as e:
+            self._handle_exception(connection, e)
+        else:
+            if mapping:
+                result = result.mappings().all()
+            return result
+
+    def _get_table(self, name: str):
+        """Recupera una tabella dal ``MetaData`` locale per nome.
+
+        Normalizza il nome anteponendo lo schema configurato, se necessario.
+
+        Args:
+            name (str): Nome della tabella (con o senza prefisso di schema).
+
+        Returns:
+            Table | None: La tabella se già presente nel ``MetaData``, altrimenti ``None``.
+        """
+        if self.schema is not None:
+            table_name = name if name.startswith(f"{self.schema}.") else f"{self.schema}.{name}"
+        else:
+            table_name = name
+        return self.metadata.tables.get(table_name)
+
+    def get_table(self, name: str) -> Optional[Table]:
+        """Restituisce una tabella, riflettendola dal database se non già nota.
+
+        Cerca prima nel ``MetaData`` locale; se assente, tenta il caricamento
+        automatico (``autoload_with``) dal database.
+
+        Args:
+            name (str): Nome della tabella da recuperare.
+
+        Returns:
+            Optional[Table]: La tabella richiesta.
+
+        Raises:
+            InternalServerException: Se la tabella non esiste nel database.
+        """
+        table = self._get_table(name=name)
+        if table is None:
+            try:
+                table = Table(name, self.metadata, schema=self.schema, autoload_with=self.engine)
+            except NoSuchTableError:
+                raise InternalServerException(f"No such table {name}")
+        return table
+
+    def has_table(self, name: str):
+        """Verifica se una tabella esiste nel database.
+
+        Args:
+            name (str): Nome della tabella da verificare.
+
+        Returns:
+            bool: ``True`` se la tabella esiste nello schema configurato.
+        """
+        return self.engine_inspection.has_table(name, self.schema)
+
+    def _add_limit_offset_condition(self, stmt, limit: int, page: int = None):
+        """Aggiunge le clausole LIMIT e OFFSET allo statement per la paginazione.
+
+        Non applica nessuna modifica se ``limit`` è 0 o negativo.
+        L'offset viene calcolato come ``(page - 1) * limit``.
+
+        Args:
+            stmt: Statement su cui applicare LIMIT/OFFSET.
+            limit (int): Numero massimo di righe. 0 = nessun limite.
+            page (int, optional): Numero di pagina (1-based). Se ``None`` o <= 0,
+                non viene applicato nessun offset.
+
+        Returns:
+            Statement con LIMIT e/o OFFSET applicati.
+        """
+        if limit and limit > 0:
+            stmt = stmt.limit(limit)
+            if page and page > 0:
+                offset = (page - 1) * limit
+                stmt = stmt.offset(offset)
+        return stmt
+
+    def _eq_where(self, col: Column, condition, neq: bool = False):
+        """Costruisce la singola condizione WHERE per una colonna.
+
+        Logica applicata:
+        - ``list`` → ``col IN (values)``
+        - Tipo ``ARRAY`` → ``value = ANY(col)``
+        - Scalare → ``col == value``
+
+        Args:
+            col (Column): Colonna su cui applicare la condizione.
+            condition: Valore o lista di valori da confrontare.
+            neq (bool): Se ``True``, nega la condizione (``NOT``). Default: ``False``.
+
+        Returns:
+            ColumnElement: Espressione booleana SQLAlchemy.
+        """
+        eq_where = col.in_(condition) if isinstance(condition, list) else col == condition if str(col.type) != "ARRAY" else condition == col.any_()
+        if neq:
+            eq_where = not_(eq_where)
+        return eq_where