python-general-be-lib 0.8.4__tar.gz → 0.9.1__tar.gz

{python_general_be_lib-0.8.4/python_general_be_lib.egg-info → python_general_be_lib-0.9.1}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.8.4
+Version: 0.9.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
 Project-URL: Homepage, https://github.com/Arpes-IS/python-general-be-lib
 Project-URL: Repository, https://github.com/Arpes-IS/python-general-be-lib
+Project-URL: Changelog, https://github.com/Arpes-IS/python-general-be-lib/blob/main/CHANGELOG.md
 Keywords: backend,sqlalchemy,fastapi,pydantic,repository,crud,geoalchemy2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -31,7 +32,6 @@ Requires-Dist: psycopg[binary]>=3; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
-Dynamic: requires-python
 
 # python-general-be-lib
 
@@ -50,7 +50,7 @@ pip install python-general-be-lib
 ```python
 from sqlalchemy import create_engine
 
-from general.interface.repository.crud_repository import CrudRepository
+from general.interface.repository import CrudRepository
 
 engine = create_engine("postgresql://user:pass@localhost/db")
 repo = CrudRepository(entity=User, model=UserModel, engine=engine)
@@ -72,3 +72,13 @@ repo.find(active=True, order_by="name", asc=True)
 | Paginazione | `PaginatorRequestModel`, `PaginatorResponseModel` |
 | Eccezioni | `ExceptionInterface` e sottoclassi HTTP (400/401/403/404/422/500/503) |
 | Logging | `init_logger`, decorator `@log` |
+
+---
+
+## Documentazione
+
+| Documento | Contenuto |
+|---|---|
+| [`CHANGELOG.md`](https://github.com/Arpes-IS/python-general-be-lib/blob/main/CHANGELOG.md) | Modifiche per versione, con le note di migrazione |
+| `general/README.md` | Panoramica della libreria: struttura, contratto sulle sessioni, handler, operazioni spaziali |
+| `general/DOCS.md` | Riferimento completo, metodo per metodo |

{python_general_be_lib-0.8.4 → python_general_be_lib-0.9.1}/README.md

@@ -15,7 +15,7 @@ pip install python-general-be-lib
 ```python
 from sqlalchemy import create_engine
 
-from general.interface.repository.crud_repository import CrudRepository
+from general.interface.repository import CrudRepository
 
 engine = create_engine("postgresql://user:pass@localhost/db")
 repo = CrudRepository(entity=User, model=UserModel, engine=engine)
@@ -36,4 +36,14 @@ repo.find(active=True, order_by="name", asc=True)
 | Basi | `Base` (declarative base estesa), `ExtBaseModel`, `CamelExtBaseModel` |
 | Paginazione | `PaginatorRequestModel`, `PaginatorResponseModel` |
 | Eccezioni | `ExceptionInterface` e sottoclassi HTTP (400/401/403/404/422/500/503) |
-| Logging | `init_logger`, decorator `@log` |
+| Logging | `init_logger`, decorator `@log` |
+
+---
+
+## Documentazione
+
+| Documento | Contenuto |
+|---|---|
+| [`CHANGELOG.md`](https://github.com/Arpes-IS/python-general-be-lib/blob/main/CHANGELOG.md) | Modifiche per versione, con le note di migrazione |
+| `general/README.md` | Panoramica della libreria: struttura, contratto sulle sessioni, handler, operazioni spaziali |
+| `general/DOCS.md` | Riferimento completo, metodo per metodo |

python_general_be_lib-0.9.1/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",
+]

python_general_be_lib-0.9.1/general/exception/access_exceptions.py

@@ -0,0 +1,22 @@
+"""HTTP exceptions for authentication and authorization.
+
+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 - Authenticated user without the permissions for the requested resource."""
+    status_code = 403
+    default_message = "Risorsa non accessibile da questo utente"
+
+
+class UnauthorizedException(ExceptionInterface):
+    """401 - Request without valid credentials."""
+    status_code = 401
+    default_message = "Non autorizzato"

python_general_be_lib-0.9.1/general/exception/crud_exceptions.py

@@ -0,0 +1,89 @@
+"""HTTP exceptions for the persistence operations.
+
+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 - Invalid request data or violated integrity constraint.
+
+    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 - No record matches the requested criteria.
+
+    Raised in place of ``NoResultFound``.
+    """
+    status_code = 404
+    default_message = "Dato non trovato"
+
+
+class ServiceUnavailableException(ExceptionInterface):
+    """503 - Database unreachable.
+
+    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 - Syntactically valid but unprocessable entity.
+
+    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 - Column or attribute missing on the entity.
+
+    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 = ""):
+        """Compose the detail according to the presence of the attribute name.
+
+        Args:
+            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", )
+        else:
+            super().__init__(custom_message="Alcuni attributi non sono presenti per questa entità", )
+
+
+class InternalServerException(ExceptionInterface):
+    """500 - Unexpected internal error.
+
+    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"

python_general_be_lib-0.9.1/general/exception/exception_interface.py

@@ -0,0 +1,31 @@
+__all__ = ["ExceptionInterface"]
+
+from fastapi import HTTPException
+
+
+class ExceptionInterface(HTTPException):
+    """Base interface for every exception of the library.
+
+    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): 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):
+        """Compose the ``detail`` from the default message and the custom one.
+
+        Args:
+            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)

python_general_be_lib-0.9.1/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.
+"""

python_general_be_lib-0.9.1/general/interface/base/__init__.py

@@ -0,0 +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",
+]

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

@@ -0,0 +1,73 @@
+__all__ = ["ExtBaseModel", "CamelExtBaseModel"]
+
+from functools import lru_cache
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+@lru_cache(maxsize=None)
+def _alias_to_name(model: type[BaseModel]) -> dict[str, str]:
+    """Build the ``{alias: field_name}`` map of a model, once per class.
+
+    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):
+    """Base Pydantic model carrying the shared configuration.
+
+    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):
+    """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:
+        """Return the Python field name given a camelCase alias.
+
+        Useful to resolve the internal field name when receiving a payload with camelCase
+        keys.
+
+        Args:
+            alias (str): camelCase alias of the field, such as ``"myField"``.
+
+        Returns:
+            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):
+    """Pydantic model with the standard configuration for the ORM integration.
+
+    Inherits from ``ConfigModel``. Meant as the base of every model that has to be
+    validated from a SQLAlchemy entity.
+    """
+    pass
+
+
+class CamelExtBaseModel(CamelConfigModel):
+    """Pydantic model with automatic camelCase aliases and ORM integration.
+
+    Inherits from ``CamelConfigModel``. Meant for the cases where the API exposes
+    camelCase fields while the code works in snake_case.
+    """
+    pass

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

@@ -0,0 +1,165 @@
+__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, ConfigDict
+from sqlalchemy.inspection import inspect
+from sqlalchemy.orm import Mapper, as_declarative
+
+
+@as_declarative()
+class Base:
+    """SQLAlchemy declarative base class enriched with utility methods.
+
+    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):
+        """Generate a Pydantic model dynamically from the entity columns.
+
+        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): 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): ``{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]: 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)
+
+        # ``mapper.columns`` è indicizzato per **nome di attributo** e non forza la
+        # configurazione dei mapper: ``column_attrs``/``attrs``/``relationships`` la
+        # forzerebbero, e chiamare ``to_pydantic`` a import-time — il pattern
+        # documentato — romperebbe le relationship con forward-ref non ancora
+        # risolvibili (stessa ragione per cui ``relationship_attributes`` è lazy).
+        selected = [(name, column) for name, column in mapper.columns.items()
+                    if include_only is None or name in include_only]
+
+        model_name = f"{cls.__name__}Model" if not model_name else model_name
+        fields = dict()
+        field_values = {name: None if full_optional else ... for name, _ in selected}
+        field_values.update(default_values)
+        for field_name, col in selected:
+            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):
+        """Return the column collection of the table the entity is mapped to.
+
+        Returns:
+            ReadOnlyColumnCollection: Collection of the SQLAlchemy columns.
+        """
+        return cls.__table__.c
+
+    @classmethod
+    def columns_names(cls):
+        """Return the names of every column of the table.
+
+        Returns:
+            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):
+        """Return the columns making up the primary key of the table.
+
+        Returns:
+            list[Column]: Columns forming the primary key.
+        """
+        return cls.__table__.primary_key.columns.values()
+
+    def to_dict(self):
+        """Convert the instance into an ``{attribute: value}`` dictionary.
+
+        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.
+
+        Returns:
+            dict[str, Any]: Current values of the instance.
+        """
+        return {key: getattr(self, key) for key in _attributes_names(self.__class__)}
+
+
+@lru_cache(maxsize=None)
+def _attributes_names(entity: type) -> tuple[str, ...]:
+    """Return the Python attribute names of the mapped columns, memoized per class.
+
+    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 (type): ORM class to inspect.
+
+    Returns:
+        tuple[str, ...]: Attribute names, in definition order.
+    """
+    return tuple(entity.__mapper__.columns.keys())
+
+
+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:
+            return mapper
+
+
+def retrieve_mapper_from_table(table_name: str):
+    """Look up a subclass of ``Base`` by table name.
+
+    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): Name of the table in the database, such as ``"users"``.
+
+    Returns:
+        Type[Base] | None: The matching ORM class, or ``None`` when not found.
+    """
+    for mapper in Base.__subclasses__():
+        if mapper.__tablename__ == table_name:
+            return mapper

python_general_be_lib-0.9.1/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"]