python-general-be-lib 0.5.0__tar.gz → 0.5.1__tar.gz

{python_general_be_lib-0.5.0/python_general_be_lib.egg-info → python_general_be_lib-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.5.0
+Version: 0.5.1
 Summary: General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, logger utilities.
 Author-email: Andrea Di Placido <a.diplacido@arpes.it>, "Arpes S.r.l." <it.admin@arpes.it>
 License: MIT

python_general_be_lib-0.5.1/general/interface/base/base_model.py

@@ -0,0 +1,64 @@
+__all__ = ["ExtBaseModel", "CamelExtBaseModel"]
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+class ConfigModel(BaseModel):
+    """Modello Pydantic base con configurazione condivisa.
+
+    Abilita:
+    - ``from_attributes=True``: validazione da oggetti ORM SQLAlchemy.
+    - ``populate_by_name=True``: accetta sia il nome Python che l'alias.
+    - ``arbitrary_types_allowed=True``: consente tipi non standard (es. ``WKBElement``).
+    - ``validate_default=True``: valida i valori di default alla creazione.
+    """
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True, arbitrary_types_allowed=True, validate_default=True)
+
+
+class CamelConfigModel(ConfigModel):
+    """Estende ``ConfigModel`` aggiungendo la generazione automatica di alias camelCase."""
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    @classmethod
+    def get_attr_by_alias(cls, alias: str) -> str:
+        """Restituisce il nome del campo Python dato un alias camelCase.
+
+        Utile per risalire al nome interno del campo quando si riceve
+        un payload con chiavi in camelCase.
+
+        Args:
+            alias (str): Alias camelCase del campo (es. ``"myField"``).
+
+        Returns:
+            str: Nome Python del campo (es. ``"my_field"``),
+                oppure l'alias stesso se non trovato.
+
+        Example:
+            >>> class MyModel(CamelExtBaseModel):
+            ...     my_field: str
+            >>> MyModel.get_attr_by_alias("myField")
+            'my_field'
+        """
+        for name, field in cls.model_fields.items():
+            if field.alias == alias:
+                return name
+        return alias
+
+
+class ExtBaseModel(ConfigModel):
+    """Modello Pydantic con configurazione standard per l'integrazione ORM.
+
+    Eredita da ``ConfigModel``. Da usare come base per tutti i modelli
+    che devono essere validati a partire da entità SQLAlchemy.
+    """
+    pass
+
+
+class CamelExtBaseModel(CamelConfigModel):
+    """Modello Pydantic con alias camelCase automatici e integrazione ORM.
+
+    Eredita da ``CamelConfigModel``. Da usare quando l'API espone
+    campi in camelCase ma internamente si lavora con snake_case.
+    """
+    pass

python_general_be_lib-0.5.1/general/interface/base/declarative_base.py

@@ -0,0 +1,144 @@
+__all__ = ["Base", "retrieve_mapper_entity", "retrieve_mapper_from_table"]
+
+from typing import Optional, Any
+
+from geoalchemy2 import Geometry, WKBElement
+from pydantic import create_model
+from sqlalchemy.inspection import inspect
+from sqlalchemy.orm import Mapper, as_declarative
+
+
+@as_declarative()
+class Base:
+    """Classe base dichiarativa SQLAlchemy arricchita con metodi di utilità.
+
+    Tutte le entità ORM del progetto devono estendere questa classe.
+    Fornisce accesso rapido a colonne, chiavi primarie e conversione verso Pydantic.
+    """
+
+    @classmethod
+    def to_pydantic(cls, model_name: str = None, full_optional: bool = False, default_values: dict[str, Any] = 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
+        rispettando la nullabilità e i valori di default forniti.
+        Le colonne di tipo ``Geometry`` vengono mappate su ``WKBElement``.
+
+        Args:
+            model_name (str, optional): Nome del modello generato.
+                Se non fornito, viene usato ``{ClassName}Model``.
+            full_optional (bool): Se ``True``, tutti i campi diventano ``Optional``
+                con default ``None``, indipendentemente dalla nullabilità nel DB.
+                Default: ``False``.
+            default_values (dict[str, Any], optional): Dizionario
+                ``{nome_campo: valore_default}`` per sovrascrivere i default inferiti.
+            **create_model_kwargs: Argomenti aggiuntivi passati a ``pydantic.create_model``.
+
+        Returns:
+            Type[BaseModel]: Classe Pydantic generata dinamicamente.
+
+        Example:
+            >>> UserModel = User.to_pydantic(full_optional=True)
+            >>> PatchModel = User.to_pydantic(model_name="UserPatch", full_optional=True)
+        """
+        if not default_values:
+            default_values = dict()
+        mapper: Mapper = inspect(cls)
+        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.update(default_values)
+        for col in mapper.columns:
+            field_name = col.name
+            if isinstance(col.type, Geometry):
+                field_type = Optional[WKBElement] if col.nullable or full_optional else WKBElement
+            else:
+                field_type = Optional[col.type.python_type] if col.nullable or full_optional else col.type.python_type
+            fields[field_name] = (field_type, field_values[field_name])
+        return create_model(model_name, **create_model_kwargs, **fields)
+
+    @classmethod
+    def columns(cls):
+        """Restituisce la collezione di colonne della tabella associata all'entità.
+
+        Returns:
+            ReadOnlyColumnCollection: Collezione delle colonne SQLAlchemy.
+
+        Example:
+            >>> User.columns()
+        """
+        return cls.__table__.c
+
+    @classmethod
+    def columns_names(cls):
+        """Restituisce i nomi di tutte le colonne della tabella.
+
+        Returns:
+            list[str]: Lista dei nomi delle colonne nell'ordine di definizione.
+
+        Example:
+            >>> User.columns_names()
+            ['id', 'name', 'email']
+        """
+        return [col.name for col in cls.__table__.c]
+
+    @classmethod
+    def primary_key(cls):
+        """Restituisce le colonne che compongono la chiave primaria della tabella.
+
+        Returns:
+            list[Column]: Lista delle colonne che formano la primary key.
+
+        Example:
+            >>> User.primary_key()
+            [Column('id', Integer(), ...)]
+        """
+        return cls.__table__.primary_key.columns.values()
+
+    def to_dict(self):
+        """Converte l'istanza in un dizionario ``{colonna: valore}``.
+
+        Returns:
+            dict[str, Any]: Dizionario con i valori correnti dell'istanza.
+
+        Example:
+            >>> user.to_dict()
+            {'id': 1, 'name': 'Mario', 'email': 'mario@example.com'}
+        """
+        return {key: getattr(self, key) for key in self.__class__.columns_names()}
+
+
+def retrieve_mapper_entity(entity_name: str):
+    """Cerca e restituisce una sottoclasse di ``Base`` per nome della classe.
+
+    Args:
+        entity_name (str): Nome della classe ORM da cercare (es. ``"User"``).
+
+    Returns:
+        Type[Base] | None: La classe ORM corrispondente, o ``None`` se non trovata.
+
+    Example:
+        >>> retrieve_mapper_entity("User").__tablename__
+        'users'
+    """
+    for mapper in Base.__subclasses__():
+        if mapper.__name__ == entity_name:
+            return mapper
+
+
+def retrieve_mapper_from_table(table_name: str):
+    """Cerca e restituisce una sottoclasse di ``Base`` per nome della tabella.
+
+    Args:
+        table_name (str): Nome della tabella nel database (es. ``"users"``).
+
+    Returns:
+        Type[Base] | None: La classe ORM corrispondente, o ``None`` se non trovata.
+
+    Example:
+        >>> retrieve_mapper_from_table("users").__name__
+        'User'
+    """
+    for mapper in Base.__subclasses__():
+        if mapper.__tablename__ == table_name:
+            return mapper