python-general-be-lib 0.8.4__py3-none-any.whl → 0.9.0__py3-none-any.whl

general/exception/__init__.py

@@ -0,0 +1,24 @@
+"""HTTP exceptions of the library.
+
+They all extend ``ExceptionInterface``, which in turn extends
+``fastapi.HTTPException``: raised inside an endpoint they are automatically
+serialized into the response with their own status code. The mapping applied by
+``CrudRepository._handle_exception`` to the SQLAlchemy errors is documented in
+``crud_exceptions``.
+"""
+
+from .access_exceptions import *
+from .crud_exceptions import *
+from .exception_interface import *
+
+__all__ = [
+    "ExceptionInterface",
+    "BadRequestException",
+    "EntityNotFoundException",
+    "ServiceUnavailableException",
+    "UnprocessableEntityException",
+    "HasNoAttributeException",
+    "InternalServerException",
+    "ForbiddenException",
+    "UnauthorizedException",
+]

general/exception/access_exceptions.py

@@ -1,23 +1,22 @@
-"""Eccezioni HTTP per autenticazione e autorizzazione.
+"""HTTP exceptions for authentication and authorization.
 
-A differenza di ``crud_exceptions``, queste eccezioni non sono sollevate
-automaticamente dalla libreria: sono a disposizione dei layer di autenticazione
-e autorizzazione dei progetti che la usano.
-
-Il package ``general.exception`` non re-esporta questi simboli: vanno importati
-dal modulo, ``from general.exception.access_exceptions import ForbiddenException``.
+Unlike ``crud_exceptions``, these exceptions are never raised automatically by the
+library: they are available to the authentication and authorization layers of the
+projects using it.
 """
 
+__all__ = ["ForbiddenException", "UnauthorizedException"]
+
 from .exception_interface import ExceptionInterface
 
 
 class ForbiddenException(ExceptionInterface):
-    """403 — Utente autenticato ma senza i permessi per la risorsa richiesta."""
+    """403 - Authenticated user without the permissions for the requested resource."""
     status_code = 403
     default_message = "Risorsa non accessibile da questo utente"
 
 
 class UnauthorizedException(ExceptionInterface):
-    """401 — Richiesta priva di credenziali valide."""
+    """401 - Request without valid credentials."""
     status_code = 401
     default_message = "Non autorizzato"

general/exception/crud_exceptions.py

@@ -1,77 +1,77 @@
-"""Eccezioni HTTP per le operazioni di persistenza.
+"""HTTP exceptions for the persistence operations.
 
-Sono le eccezioni su cui ``CrudRepository._handle_exception`` mappa gli errori
-SQLAlchemy:
-
-- ``OperationalError`` → ``ServiceUnavailableException`` (503)
-- ``NoResultFound`` → ``EntityNotFoundException`` (404)
-- ``DataError`` | ``IntegrityError`` → ``BadRequestException`` (400)
-
-Il package ``general.exception`` non re-esporta questi simboli: vanno importati
-dal modulo, ``from general.exception.crud_exceptions import BadRequestException``.
+These are the exceptions ``CrudRepository._handle_exception`` maps the SQLAlchemy
+errors onto: ``OperationalError`` to ``ServiceUnavailableException`` (503),
+``NoResultFound`` to ``EntityNotFoundException`` (404), ``DataError`` and
+``IntegrityError`` to ``BadRequestException`` (400).
 """
 
+__all__ = [
+    "BadRequestException",
+    "EntityNotFoundException",
+    "ServiceUnavailableException",
+    "UnprocessableEntityException",
+    "HasNoAttributeException",
+    "InternalServerException",
+]
+
 from .exception_interface import ExceptionInterface
 
 
 class BadRequestException(ExceptionInterface):
-    """400 — Dati della richiesta non validi o vincolo di integrità violato.
+    """400 - Invalid request data or violated integrity constraint.
 
-    Sollevata al posto di ``DataError`` e ``IntegrityError`` (es. violazione di
-    una foreign key, di un unique o di un NOT NULL).
+    Raised in place of ``DataError`` and ``IntegrityError``, such as a foreign key,
+    unique or NOT NULL violation.
     """
     status_code = 400
     default_message = "Richiesta non corretta"
 
 
 class EntityNotFoundException(ExceptionInterface):
-    """404 — Nessun record corrisponde ai criteri richiesti.
+    """404 - No record matches the requested criteria.
 
-    Sollevata al posto di ``NoResultFound``.
+    Raised in place of ``NoResultFound``.
     """
     status_code = 404
     default_message = "Dato non trovato"
 
 
 class ServiceUnavailableException(ExceptionInterface):
-    """503 — Database non raggiungibile.
+    """503 - Database unreachable.
 
-    Sollevata al posto di ``OperationalError`` (connessione caduta, pool esaurito,
-    server non in ascolto).
+    Raised in place of ``OperationalError``: dropped connection, exhausted pool, server
+    not listening.
     """
     status_code = 503
     default_message = "Servizio momentaneamente non disponibile, riprovare più tardi"
 
 
 class UnprocessableEntityException(ExceptionInterface):
-    """422 — Entità sintatticamente valida ma non processabile.
+    """422 - Syntactically valid but unprocessable entity.
 
-    Non è sollevata automaticamente dai repository: è a disposizione dei service
-    per gli errori di validazione applicativa.
+    Never raised automatically by the repositories: it is available to the services for
+    their application validation errors.
     """
     status_code = 422
     default_message = "Entità non processabile"
 
 
 class HasNoAttributeException(ExceptionInterface):
-    """400 — Colonna o attributo non presente sull'entità.
-
-    Sollevata quando un nome di colonna passato a ``columns``, ``exclude_columns``
-    o ``order_by`` non esiste sull'entità.
+    """400 - Column or attribute missing on the entity.
 
-    Example:
-        >>> raise HasNoAttributeException("cognome")
-        # detail: "Richiesta non corretta - Attributo cognome non presente"
+    Raised when a column name passed to ``columns``, ``exclude_columns`` or ``order_by``
+    does not exist on the entity.
     """
     status_code = 400
     default_message = "Richiesta non corretta"
 
     def __init__(self, attr: str = ""):
-        """Compone il dettaglio in base alla presenza del nome dell'attributo.
+        """Compose the detail according to the presence of the attribute name.
 
         Args:
-            attr (str): Nome dell'attributo mancante. Se omesso, viene usato un
-                messaggio generico che non identifica la colonna.
+            attr (str): Name of the missing attribute. When omitted, a generic message not
+                identifying the column is used.
         """
         if attr:
             super().__init__(custom_message=f"Attributo {attr} non presente", )
@@ -80,11 +80,10 @@ class HasNoAttributeException(ExceptionInterface):
 
 
 class InternalServerException(ExceptionInterface):
-    """500 — Errore interno non previsto.
+    """500 - Unexpected internal error.
 
-    Usata come fallback dal decorator ``@log`` per ogni eccezione che non sia già
-    una ``HTTPException``, e da ``CrudMetadata.get_table`` per una tabella
-    inesistente.
+    Used as a fallback by the ``@log`` decorator for every exception that is not already
+    an ``HTTPException``, and by ``CrudMetadata.get_table`` for a missing table.
     """
     status_code = 500
     default_message = "Impossibile gestire la richiesta al momento"

general/exception/exception_interface.py

@@ -1,38 +1,31 @@
+__all__ = ["ExceptionInterface"]
+
 from fastapi import HTTPException
 
 
 class ExceptionInterface(HTTPException):
-    """Interfaccia base per tutte le eccezioni della libreria.
-
-    Estende ``fastapi.HTTPException`` spostando status code e messaggio su
-    **attributi di classe**: ogni sottoclasse dichiara il proprio ``status_code``
-    e ``default_message`` e può quindi essere sollevata senza argomenti.
+    """Base interface for every exception of the library.
 
-    Sollevata dentro un endpoint FastAPI, viene serializzata automaticamente nella
-    risposta di errore con lo status code dichiarato.
+    Extends ``fastapi.HTTPException`` moving status code and message to **class
+    attributes**: every subclass declares its own ``status_code`` and
+    ``default_message`` and can therefore be raised without arguments. Raised inside a
+    FastAPI endpoint, it is automatically serialized into the error response with the
+    declared status code.
 
     Attributes:
-        status_code (int): Status code HTTP della risposta.
-        default_message (str): Messaggio di default usato come ``detail``.
-
-    Example:
-        >>> class TeapotException(ExceptionInterface):
-        ...     status_code = 418
-        ...     default_message = "Sono una teiera"
-        >>> raise TeapotException("niente caffè")
-        # detail: "Sono una teiera - niente caffè"
+        status_code (int): HTTP status code of the response.
+        default_message (str): Default message used as ``detail``.
     """
     status_code: int
     default_message: str
 
     def __init__(self, custom_message: str = None):
-        """Compone il ``detail`` a partire dal messaggio di default e da quello custom.
+        """Compose the ``detail`` from the default message and the custom one.
 
         Args:
-            custom_message (str, optional): Dettaglio aggiuntivo, accodato al
-                ``default_message`` nella forma
-                ``"{default_message} - {custom_message}"``. Se omesso, il ``detail``
-                è il solo ``default_message``.
+            custom_message (str, optional): Additional detail, appended to the
+                ``default_message`` as ``"{default_message} - {custom_message}"``. When
+                omitted, the ``detail`` is the ``default_message`` alone.
         """
         detail = f"{self.default_message} - {custom_message}" if custom_message else self.default_message
         super().__init__(status_code=self.status_code, detail=detail)

general/interface/__init__.py

@@ -0,0 +1,8 @@
+"""ORM repositories, ORM-free metadata layer and shared base classes.
+
+Container package: the symbols are imported from the subpackages
+(``general.interface.base``, ``general.interface.repository``,
+``general.interface.repository.handler``, ``general.interface.metadata``). It is
+declared explicitly, instead of being left as an implicit namespace package, so as
+not to depend on the PEP 420 support of the tools consuming the distribution.
+"""

general/interface/base/__init__.py

@@ -1,2 +1,12 @@
+"""SQLAlchemy declarative base class and preconfigured Pydantic models."""
+
 from .base_model import *
 from .declarative_base import *
+
+__all__ = [
+    "Base",
+    "retrieve_mapper_entity",
+    "retrieve_mapper_from_table",
+    "ExtBaseModel",
+    "CamelExtBaseModel",
+]

general/interface/base/base_model.py

@@ -8,66 +8,66 @@ from pydantic.alias_generators import to_camel
 
 @lru_cache(maxsize=None)
 def _alias_to_name(model: type[BaseModel]) -> dict[str, str]:
-    """Mappa ``{alias: nome_campo}`` di un modello, costruita una volta per classe.
+    """Build the ``{alias: field_name}`` map of a model, once per class.
 
-    Cachata sulla classe (long-lived) per evitare la scansione lineare di
-    ``model_fields`` a ogni ``get_attr_by_alias``.
+    Cached on the class, which is long-lived, to avoid the linear scan of
+    ``model_fields`` on every ``get_attr_by_alias`` call.
+
+    Args:
+        model (type[BaseModel]): Pydantic model to inspect.
+
+    Returns:
+        dict[str, str]: Map from alias to Python field name, limited to the fields
+            declaring an alias.
     """
     return {field.alias: name for name, field in model.model_fields.items() if field.alias}
 
 
 class ConfigModel(BaseModel):
-    """Modello Pydantic base con configurazione condivisa.
+    """Base Pydantic model carrying the shared configuration.
 
-    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.
+    Enables ``from_attributes=True`` for the validation from SQLAlchemy ORM objects,
+    ``populate_by_name=True`` to accept both the Python name and the alias,
+    ``arbitrary_types_allowed=True`` to allow non-standard types such as ``WKBElement``,
+    and ``validate_default=True`` to validate the default values on creation.
     """
     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."""
+    """Extend ``ConfigModel`` adding the automatic generation of camelCase aliases."""
     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.
+        """Return the Python field name given a camelCase alias.
 
-        Utile per risalire al nome interno del campo quando si riceve
-        un payload con chiavi in camelCase.
+        Useful to resolve the internal field name when receiving a payload with camelCase
+        keys.
 
         Args:
-            alias (str): Alias camelCase del campo (es. ``"myField"``).
+            alias (str): camelCase alias of the field, such as ``"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'
+            str: Python name of the field, such as ``"my_field"``, or the alias itself when
+                not found.
         """
         return _alias_to_name(cls).get(alias, alias)
 
 
 class ExtBaseModel(ConfigModel):
-    """Modello Pydantic con configurazione standard per l'integrazione ORM.
+    """Pydantic model with the standard configuration for the ORM integration.
 
-    Eredita da ``ConfigModel``. Da usare come base per tutti i modelli
-    che devono essere validati a partire da entità SQLAlchemy.
+    Inherits from ``ConfigModel``. Meant as the base of every model that has to be
+    validated from a SQLAlchemy entity.
     """
     pass
 
 
 class CamelExtBaseModel(CamelConfigModel):
-    """Modello Pydantic con alias camelCase automatici e integrazione ORM.
+    """Pydantic model with automatic camelCase aliases and ORM integration.
 
-    Eredita da ``CamelConfigModel``. Da usare quando l'API espone
-    campi in camelCase ma internamente si lavora con snake_case.
+    Inherits from ``CamelConfigModel``. Meant for the cases where the API exposes
+    camelCase fields while the code works in snake_case.
     """
     pass

general/interface/base/declarative_base.py

@@ -1,46 +1,51 @@
 __all__ = ["Base", "retrieve_mapper_entity", "retrieve_mapper_from_table"]
 
+from functools import lru_cache
 from typing import Optional, Any, Sequence
 
 from geoalchemy2 import Geometry, WKBElement
-from pydantic import create_model
+from pydantic import create_model, ConfigDict
 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à.
+    """SQLAlchemy declarative base class enriched with utility methods.
 
-    Tutte le entità ORM del progetto devono estendere questa classe.
-    Fornisce accesso rapido a colonne, chiavi primarie e conversione verso Pydantic.
+    Every ORM entity of the project has to extend this class. It gives quick access to
+    columns and primary keys, plus the conversion towards Pydantic.
     """
 
     @classmethod
     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à.
+        """Generate a Pydantic model dynamically from the entity columns.
 
-        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``.
+        Iterates over the ORM-mapped columns and builds the model fields honouring the
+        nullability and the given default values; ``Geometry`` columns are mapped onto
+        ``WKBElement``. When the caller passes neither ``__config__`` nor ``__base__``, the
+        generated model gets the same configuration as ``ExtBaseModel``. The default is all
+        or nothing: passing ``__config__`` puts the whole configuration in the hands of the
+        caller, and passing ``__base__`` lets the base carry its own.
 
         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.
+            model_name (str, optional): Name of the generated model. When not given,
+                ``{ClassName}Model`` is used.
+            full_optional (bool): If ``True``, every field becomes ``Optional`` with a
+                ``None`` default, regardless of the nullability in the database.
                 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``.
+            default_values (dict[str, Any], optional): ``{field_name: default_value}`` map
+                overriding the inferred defaults.
+            include_only (Sequence[str], optional): Attribute names to restrict the model to.
+                When ``None``, every mapped column is included.
+            **create_model_kwargs: Additional arguments passed to ``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)
+            Type[BaseModel]: Dynamically generated Pydantic class.
         """
+        if "__config__" not in create_model_kwargs.keys() and "__base__" not in create_model_kwargs.keys():
+            create_model_kwargs["__config__"] = ConfigDict(from_attributes=True, populate_by_name=True, arbitrary_types_allowed=True, validate_default=True)
+
         if not default_values:
             default_values = dict()
         mapper: Mapper = inspect(cls)
@@ -67,70 +72,76 @@ class Base:
 
     @classmethod
     def columns(cls):
-        """Restituisce la collezione di colonne della tabella associata all'entità.
+        """Return the column collection of the table the entity is mapped to.
 
         Returns:
-            ReadOnlyColumnCollection: Collezione delle colonne SQLAlchemy.
-
-        Example:
-            >>> User.columns()
+            ReadOnlyColumnCollection: Collection of the SQLAlchemy columns.
         """
         return cls.__table__.c
 
     @classmethod
     def columns_names(cls):
-        """Restituisce i nomi di tutte le colonne della tabella.
+        """Return the names of every column of the table.
 
         Returns:
-            list[str]: Lista dei nomi delle colonne nell'ordine di definizione.
-
-        Example:
-            >>> User.columns_names()
-            ['id', 'name', 'email']
+            list[str]: Names of the columns, in definition order. They are the **database**
+                names, which differ from the Python attribute names on the entities
+                declaring an explicit column name.
         """
         return [col.name for col in cls.__table__.c]
 
     @classmethod
     def primary_key(cls):
-        """Restituisce le colonne che compongono la chiave primaria della tabella.
+        """Return the columns making up the primary key of the table.
 
         Returns:
-            list[Column]: Lista delle colonne che formano la primary key.
-
-        Example:
-            >>> User.primary_key()
-            [Column('id', Integer(), ...)]
+            list[Column]: Columns forming the primary key.
         """
         return cls.__table__.primary_key.columns.values()
 
     def to_dict(self):
-        """Converte l'istanza in un dizionario ``{colonna: valore}``.
+        """Convert the instance into an ``{attribute: value}`` dictionary.
 
-        Returns:
-            dict[str, Any]: Dizionario con i valori correnti dell'istanza.
+        The keys are the names of the **Python attributes** of the mapped columns, not the
+        names of the columns in the database; the two differ only on the entities declaring
+        an explicit column name. Relationships are not included, only columns.
 
-        Example:
-            >>> user.to_dict()
-            {'id': 1, 'name': 'Mario', 'email': 'mario@example.com'}
+        Returns:
+            dict[str, Any]: Current values of the instance.
         """
-        return {key: getattr(self, key) for key in self.__class__.columns_names()}
+        return {key: getattr(self, key) for key in _attributes_names(self.__class__)}
 
 
-def retrieve_mapper_entity(entity_name: str):
-    """Cerca e restituisce una sottoclasse di ``Base`` per nome della classe.
+@lru_cache(maxsize=None)
+def _attributes_names(entity: type) -> tuple[str, ...]:
+    """Return the Python attribute names of the mapped columns, memoized per class.
 
-    Itera su ``Base.__subclasses__()``: trova quindi solo le sottoclassi **dirette**
-    di ``Base``, non quelle annidate in ulteriori livelli di ereditarietà.
+    The memoization is at module level rather than a class attribute: the cache key is
+    the class itself, so a subclass in single table inheritance gets its own tuple
+    instead of inheriting the one of its parent. The names are read from
+    ``__mapper__.columns`` and not from ``column_attrs``, which would force
+    ``configure_mappers()``.
 
     Args:
-        entity_name (str): Nome della classe ORM da cercare (es. ``"User"``).
+        entity (type): ORM class to inspect.
 
     Returns:
-        Type[Base] | None: La classe ORM corrispondente, o ``None`` se non trovata.
+        tuple[str, ...]: Attribute names, in definition order.
+    """
+    return tuple(entity.__mapper__.columns.keys())
 
-    Example:
-        >>> retrieve_mapper_entity("User").__tablename__
-        'users'
+
+def retrieve_mapper_entity(entity_name: str):
+    """Look up a subclass of ``Base`` by class name.
+
+    Iterates over ``Base.__subclasses__()``, so it only finds the **direct** subclasses
+    of ``Base`` and not the ones nested in further inheritance levels.
+
+    Args:
+        entity_name (str): Name of the ORM class to look for, such as ``"User"``.
+
+    Returns:
+        Type[Base] | None: The matching ORM class, or ``None`` when not found.
     """
     for mapper in Base.__subclasses__():
         if mapper.__name__ == entity_name:
@@ -138,20 +149,16 @@ def retrieve_mapper_entity(entity_name: str):
 
 
 def retrieve_mapper_from_table(table_name: str):
-    """Cerca e restituisce una sottoclasse di ``Base`` per nome della tabella.
+    """Look up a subclass of ``Base`` by table name.
 
-    Itera su ``Base.__subclasses__()``: trova quindi solo le sottoclassi **dirette**
-    di ``Base``, non quelle annidate in ulteriori livelli di ereditarietà.
+    Iterates over ``Base.__subclasses__()``, so it only finds the **direct** subclasses
+    of ``Base`` and not the ones nested in further inheritance levels.
 
     Args:
-        table_name (str): Nome della tabella nel database (es. ``"users"``).
+        table_name (str): Name of the table in the database, such as ``"users"``.
 
     Returns:
-        Type[Base] | None: La classe ORM corrispondente, o ``None`` se non trovata.
-
-    Example:
-        >>> retrieve_mapper_from_table("users").__name__
-        'User'
+        Type[Base] | None: The matching ORM class, or ``None`` when not found.
     """
     for mapper in Base.__subclasses__():
         if mapper.__tablename__ == table_name:

general/interface/metadata/__init__.py

@@ -0,0 +1,12 @@
+"""CRUD and spatial layer over reflected ``Table`` objects, without the ORM.
+
+Alternative to the repositories to operate on tables having no ORM model: the schema
+is reflected at runtime and the tables are resolved by name. Unlike the
+repositories, this layer does **not** use the handler pipeline and does **not** map
+the SQLAlchemy exceptions onto HTTP exceptions.
+"""
+
+from .crud_metadata import *
+from .geom_metadata import *
+
+__all__ = ["CrudMetadata", "GeomMetadata"]