python-general-be-lib 0.11.2__py3-none-any.whl → 0.11.3__py3-none-any.whl

general/exception/crud_exceptions.py

@@ -17,7 +17,6 @@ __all__ = [
     "InternalServerException",
 ]
 
-from sqlalchemy.exc import DataError, IntegrityError, NoResultFound, OperationalError
 
 from .exception_interface import ExceptionInterface
 
@@ -111,6 +110,8 @@ def raise_http_exception(e: Exception):
         BadRequestException: On ``DataError`` or ``IntegrityError``.
         Exception: The original exception, for every other type.
     """
+    from sqlalchemy.exc import DataError, IntegrityError, NoResultFound, OperationalError
+
     match e:
         case OperationalError():
             raise ServiceUnavailableException()

general/interface/base/__init__.py

@@ -1,7 +1,12 @@
-"""SQLAlchemy declarative base class and preconfigured Pydantic models."""
+"""SQLAlchemy declarative base class and preconfigured Pydantic models.
 
-from .base_model import *
-from .declarative_base import *
+The public symbols are resolved lazily (PEP 562): importing this package does not import
+the modules behind them, so reaching one of them does not pay for the heavier siblings.
+The ``TYPE_CHECKING`` block is what keeps the static types — without it a type checker
+would see every symbol as ``Any``, silently, and the ``py.typed`` marker would promise
+types the consumer does not get.
+"""
+from typing import TYPE_CHECKING
 
 __all__ = [
     "Base",
@@ -10,3 +15,45 @@ __all__ = [
     "ExtBaseModel",
     "CamelExtBaseModel",
 ]
+
+if TYPE_CHECKING:  # i type checker leggono da qui, il runtime no
+    from .base_model import CamelExtBaseModel, ExtBaseModel
+    from .declarative_base import Base, retrieve_mapper_entity, retrieve_mapper_from_table
+
+_MODULES = {
+    "Base": ".declarative_base",
+    "retrieve_mapper_entity": ".declarative_base",
+    "retrieve_mapper_from_table": ".declarative_base",
+    "ExtBaseModel": ".base_model",
+    "CamelExtBaseModel": ".base_model",
+}
+
+
+def __getattr__(name: str):
+    """Resolve a public symbol, importing its module on first access.
+
+    Args:
+        name (str): Name of the attribute being read.
+
+    Returns:
+        Any: The requested symbol.
+
+    Raises:
+        AttributeError: If the name is not part of the public surface.
+    """
+    module = _MODULES.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib import import_module
+
+    return getattr(import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """List the public surface without importing anything.
+
+    Returns:
+        list[str]: The names in ``__all__``.
+    """
+    return list(__all__)

general/interface/base/declarative_base.py

@@ -3,7 +3,6 @@ __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
@@ -54,6 +53,8 @@ class Base:
         Returns:
             Type[BaseModel]: Dynamically generated Pydantic class.
         """
+        from geoalchemy2 import Geometry, WKBElement
+
         create_model_kwargs.setdefault("__module__", cls.__module__)
 
         if "__config__" not in create_model_kwargs.keys() and "__base__" not in create_model_kwargs.keys():

general/interface/metadata/__init__.py

@@ -1,12 +1,58 @@
 """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.
+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. It goes through the **same**
+handler pipeline as the ORM layer, built per table from the reflected ``Table.c``, and maps
+the SQLAlchemy exceptions onto the same HTTP exceptions.
+
+The public symbols are resolved lazily (PEP 562): importing this package does not import
+the modules behind them, so reaching one of them does not pay for the heavier siblings.
+The ``TYPE_CHECKING`` block is what keeps the static types — without it a type checker
+would see every symbol as ``Any``, silently, and the ``py.typed`` marker would promise
+types the consumer does not get.
 """
+from typing import TYPE_CHECKING
+
+__all__ = [
+    "CrudMetadata",
+    "GeomMetadata",
+]
+
+if TYPE_CHECKING:  # i type checker leggono da qui, il runtime no
+    from .crud_metadata import CrudMetadata
+    from .geom_metadata import GeomMetadata
+
+_MODULES = {
+    "CrudMetadata": ".crud_metadata",
+    "GeomMetadata": ".geom_metadata",
+}
+
+
+def __getattr__(name: str):
+    """Resolve a public symbol, importing its module on first access.
+
+    Args:
+        name (str): Name of the attribute being read.
+
+    Returns:
+        Any: The requested symbol.
+
+    Raises:
+        AttributeError: If the name is not part of the public surface.
+    """
+    module = _MODULES.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib import import_module
+
+    return getattr(import_module(module, __name__), name)
+
 
-from .crud_metadata import *
-from .geom_metadata import *
+def __dir__() -> list[str]:
+    """List the public surface without importing anything.
 
-__all__ = ["CrudMetadata", "GeomMetadata"]
+    Returns:
+        list[str]: The names in ``__all__``.
+    """
+    return list(__all__)

general/interface/repository/__init__.py

@@ -1,9 +1,12 @@
-"""ORM repositories: generic CRUD, spatial, many-to-many and views."""
+"""ORM repositories: generic CRUD, spatial, many-to-many and views.
 
-from .crud_repository import *
-from .geometry_repository import *
-from .many_to_many_repository import *
-from .view_repository import *
+The public symbols are resolved lazily (PEP 562): importing this package does not import
+the modules behind them, so reaching one of them does not pay for the heavier siblings.
+The ``TYPE_CHECKING`` block is what keeps the static types — without it a type checker
+would see every symbol as ``Any``, silently, and the ``py.typed`` marker would promise
+types the consumer does not get.
+"""
+from typing import TYPE_CHECKING
 
 __all__ = [
     "CrudRepository",
@@ -11,3 +14,46 @@ __all__ = [
     "ManyToManyRepository",
     "ViewRepository",
 ]
+
+if TYPE_CHECKING:  # i type checker leggono da qui, il runtime no
+    from .crud_repository import CrudRepository
+    from .geometry_repository import GeometryRepository
+    from .many_to_many_repository import ManyToManyRepository
+    from .view_repository import ViewRepository
+
+_MODULES = {
+    "CrudRepository": ".crud_repository",
+    "GeometryRepository": ".geometry_repository",
+    "ManyToManyRepository": ".many_to_many_repository",
+    "ViewRepository": ".view_repository",
+}
+
+
+def __getattr__(name: str):
+    """Resolve a public symbol, importing its module on first access.
+
+    Args:
+        name (str): Name of the attribute being read.
+
+    Returns:
+        Any: The requested symbol.
+
+    Raises:
+        AttributeError: If the name is not part of the public surface.
+    """
+    module = _MODULES.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib import import_module
+
+    return getattr(import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """List the public surface without importing anything.
+
+    Returns:
+        list[str]: The names in ``__all__``.
+    """
+    return list(__all__)

general/interface/repository/crud_repository.py

@@ -147,7 +147,14 @@ class CrudRepository[Entity: Base | Type[Base]]:
         self.columns = self.entity.columns()
         self._relationship_attributes = None  # popolato lazy dalla property relationship_attributes
 
-        base_handler = handler_class(self.columns) if handler_class else BaseHandler(self.columns)
+        # ``handler_class`` accetta una classe — che si costruisce dalle colonne — oppure
+        # un'istanza già pronta: il suggerimento di tipo prometteva entrambe e ne reggeva una
+        if handler_class is None:
+            base_handler = BaseHandler(self.columns)
+        elif isinstance(handler_class, type):
+            base_handler = handler_class(self.columns)
+        else:
+            base_handler = handler_class
 
         self.stmt_manager = StatementManager(handlers=handlers, base_handler=base_handler)
 

general/interface/repository/handler/handler.py

@@ -32,22 +32,3 @@ class Handler:
                 the handler claims nothing.
         """
         return []
-
-    def handle(self, stmt, neq=False, where=None):
-        """Apply the conditions of this handler alone to a statement.
-
-        Adapter for the isolated use of a handler, outside the ``StatementManager``
-        pipeline: it collects the conditions of ``conditions`` and adds them with a single
-        ``.where()`` call. Nothing is applied when the handler produces no condition.
-
-        Args:
-            stmt (Select | Update | Delete): Statement to apply the filters to.
-            neq (bool): If ``True``, the conditions are negated. Default: ``False``.
-            where (dict[str, Any]): Filters. The keys the handler claims are removed
-                in-place. Default: ``None``.
-
-        Returns:
-            Select | Update | Delete: Statement with the WHERE conditions applied.
-        """
-        conditions = self.conditions(neq=neq, where=where)
-        return stmt.where(*conditions) if conditions else stmt

general/interface/repository/handler/statement_manager.py

@@ -5,6 +5,8 @@ from typing import Any, Type
 from sqlalchemy import ColumnElement, Delete, Select, Update
 
 from general.exception.crud_exceptions import HasNoAttributeException
+from sqlalchemy.sql.base import ReadOnlyColumnCollection
+
 from .base_handler import BaseHandler
 
 
@@ -27,19 +29,49 @@ class StatementManager:
     def __init__(self, handlers: list[BaseHandler | Type[BaseHandler]] = None, base_handler: BaseHandler = None):
         """Initialize the manager with the handler list and the mandatory base handler.
 
+        A handler can be given as an instance or as a class: a class is built with the
+        columns of the ``base_handler``, which is what every handler needs and the only
+        thing some of them need. Building it here is what makes a wrong handler fail at
+        construction, where the caller can read the cause, instead of at the first query.
+
         Args:
-            handlers (list[BaseHandler], optional): Additional handlers to run before the
-                base handler, such as ``JsonHandler`` or ``ILikeHandler``.
+            handlers (list[BaseHandler | Type[BaseHandler]], optional): Additional handlers
+                to run before the base handler, such as ``JsonHandler`` or ``ILikeHandler``.
+                Each one as an instance or as a class.
             base_handler (BaseHandler): Main handler for the standard filters. Mandatory.
 
         Raises:
             ValueError: If ``base_handler`` is not provided.
+            TypeError: If a handler class needs more than the columns to be built.
         """
         if not base_handler:
-            raise ValueError("StatemantManager: base_handler is not set")
-        self._handlers = handlers if handlers else []
+            raise ValueError("StatementManager: base_handler is not set")
+        self._handlers = [self._instance_of(handler, base_handler.columns) for handler in handlers] if handlers else []
         self._base_handler = base_handler
 
+    @staticmethod
+    def _instance_of(handler: BaseHandler | Type[BaseHandler], columns: ReadOnlyColumnCollection) -> BaseHandler:
+        """Return the handler itself, building it from the columns when given as a class.
+
+        Args:
+            handler (BaseHandler | Type[BaseHandler]): Handler instance or class.
+            columns (ReadOnlyColumnCollection): Columns to build a class with.
+
+        Returns:
+            BaseHandler: The handler ready to be run by the pipeline.
+
+        Raises:
+            TypeError: If the class needs more arguments than the columns, with the name of
+                the handler and the suggestion to pass an instance.
+        """
+        if not isinstance(handler, type):
+            return handler
+
+        try:
+            return handler(columns)
+        except TypeError as e:
+            raise TypeError(f"{handler.__name__} needs more than the columns to be built: pass an instance, not the class") from e
+
     def conditions(self, neq: bool = False, where: dict[str, Any] = None) -> list[ColumnElement[Any]]:
         """Collect the conditions of every handler without touching any statement.
 

general/logger.py

@@ -1,5 +1,6 @@
 import logging
 import logging.config
+import reprlib
 from functools import wraps
 from time import perf_counter
 
@@ -21,6 +22,11 @@ color = COLOR['BLUE']
 end_color = COLOR['ENDC']
 exc_color = COLOR['RED']
 
+# Bounded repr of the call arguments for the error record: truncates long strings,
+# collections and object reprs, and falls back to a placeholder when an argument's
+# own ``__repr__`` raises, so that it cannot replace the original exception.
+_args_repr = reprlib.Repr(maxlevel=3, maxtuple=10, maxlist=10, maxdict=10, maxset=10, maxstring=200, maxother=200)
+
 LOGGING_CONFIG = {
     "version": 1,
     "disable_existing_loggers": False,
@@ -100,8 +106,9 @@ def log(func):
     ``HTTPException`` is propagated as is, any other exception is converted into an
     ``InternalServerException``, whose ``detail`` does not carry the original message so
     that internal details never reach the HTTP response body. The call arguments are not
-    serialized on the happy path; on error they are attached to the record as the
-    ``func_args`` and ``func_kwargs`` structured fields, available to a JSON handler.
+    serialized on the happy path; on error their truncated ``repr`` is appended to the
+    message, and they are also attached to the record as the ``func_args`` and
+    ``func_kwargs`` structured fields, available to a JSON handler.
 
     The wrapper is **synchronous**: applied to a coroutine function it measures the
     coroutine creation time, not its execution, and does not intercept the exceptions
@@ -123,7 +130,8 @@ def log(func):
             result = func(*args, **kwargs)
         except Exception as e:
             extra = dict(func_args=args, func_kwargs=kwargs)
-            logging.exception(f"Exception {exc_color} {func_name} {end_color}: {repr(e)}", extra=extra)
+            call = f"args={_args_repr.repr(args)} kwargs={_args_repr.repr(kwargs)}"
+            logging.exception(f"Exception {exc_color} {func_name} {end_color}: {repr(e)} - {call}", extra=extra)
             raise e.with_traceback(None) if isinstance(e, HTTPException) else InternalServerException()
         else:
             logging.info(f"{color} {func_name} {end_color} completed in {(perf_counter() - start):.3f} seconds")

{python_general_be_lib-0.11.2.dist-info → python_general_be_lib-0.11.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.11.2
+Version: 0.11.3
 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
@@ -31,6 +31,7 @@ Requires-Dist: testcontainers[postgres]>=4; extra == "dev"
 Requires-Dist: psycopg[binary]>=3; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
 Dynamic: license-file
 
 # python-general-be-lib

{python_general_be_lib-0.11.2.dist-info → python_general_be_lib-0.11.3.dist-info}/RECORD

@@ -1,42 +1,42 @@
 general/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 general/context.py,sha256=ArxisBIbmij72IWKQwBfJBhmAucUGlMnEPRQnYl1A6k,1165
-general/logger.py,sha256=P-7-BLtO1XC2m43wXrnJcTakr2iZBE0gUkMVppJ9exE,4506
+general/logger.py,sha256=MnK8ZDA9x4xhX0KcpOxTieosnFIhFVwSa8b52Q4T9tA,5039
 general/paginator_dto.py,sha256=DB2hfcrckuEiHEIORLT4EgCcnX4AYYKGlHRr-l-Q1Cw,3741
 general/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 general/exception/__init__.py,sha256=MZpSDUKeopct7ZqMd1g4XlNS8sM9mmXIlHTIYPOhu9c,849
 general/exception/access_exceptions.py,sha256=tNIBjxM0-5iSOXDc7Il01eb36mEk-POQGVaHhCpG278,744
-general/exception/crud_exceptions.py,sha256=JZs3dXBOp0dYZ5yfNBbMSd2xoLTCMxXxz1myt46Ql2g,4351
+general/exception/crud_exceptions.py,sha256=7zA9J8KPlvK9MpHbhFEmFpdGVMcqw7hCyRGSJB4-K7U,4356
 general/exception/exception_interface.py,sha256=k7KreAYMwKPQQghkCissdu3ASZZqrRFWM1lAGzeR8sM,1294
 general/interface/__init__.py,sha256=G11sI1Oxtb-Z_-ORAuKS_Kkdwopt1uXmEXYtZEJYiLs,445
-general/interface/base/__init__.py,sha256=fA1hdSY5TX6k_UpvA0eAfYeNWkXY6fPrHBqZVIdf6PY,270
+general/interface/base/__init__.py,sha256=wRKbvb8lF33_2iG100mEQXz1tEkh9BF5bPcIi7ri_Rk,1801
 general/interface/base/base_model.py,sha256=aIzrRZVUytmbgmEH1bya29rVFOm-Njinn_JXkgkBrr8,2575
-general/interface/base/declarative_base.py,sha256=1AAjGQ7df8MQWcJAGQJlg5N_eTc93FHbMhgh4nIm7a0,9293
-general/interface/metadata/__init__.py,sha256=pXKYY4uO92eQI3gtuG4FKZbBi76gu-VJLxaAy-emeP8,474
+general/interface/base/declarative_base.py,sha256=J-q6nJIdYixFk9tgWjmGVII2cHeOazf0e4snaO_rHhI,9302
+general/interface/metadata/__init__.py,sha256=CawnfGK7WcJmtqi9CjEjBqCyX_vuHFK-Td1orXTH__U,1849
 general/interface/metadata/crud_metadata.py,sha256=SfV2__zgkTTeX1opLHDMRIeyB1DKiObr7pGOHkGVFlo,48120
 general/interface/metadata/geom_metadata.py,sha256=xWNZnWhN_Om91pcqSsURKi5EUYNZh444zDqMwoOpq84,15508
 general/interface/mixin/__init__.py,sha256=M5-e6T_R63Utwh3_WcmoE3wanwIZjNjbgLYrrFlSpTA,659
 general/interface/mixin/audit_mixin.py,sha256=N2JDD9JxXDMeBqu0yAlhVWFOK3EeUA2b215hPvXytUU,1421
 general/interface/mixin/softdelete_mixin.py,sha256=526luzM4DBCorcq99kZ6BYqtQKKJCpnxX9rSEigfyIU,2148
 general/interface/mixin/timestamp_mixin.py,sha256=wmcIx2Y8jgVqg9A-1E61BvkcKCo52ZjKNHeKfXJmUl0,2220
-general/interface/repository/__init__.py,sha256=eWoNy35LVu6sDrK5ju7VAeoclknKO0-yTgjVckJpi8s,321
-general/interface/repository/crud_repository.py,sha256=2Jh_Y86QWFF14HnopvYSSVablmhkOdFe799VRj0TQFI,55629
+general/interface/repository/__init__.py,sha256=QQD6okLfRozC0uOZPGrwOUDKJyZTgpObvwJ3OOSJdbM,1813
+general/interface/repository/crud_repository.py,sha256=Hr7APBsN1uFqEfM78ZSIcgheg4ilvND4OMc7TBNOlcw,55962
 general/interface/repository/geometry_repository.py,sha256=Fmv0qhfqumnU5fiETMMAmiB0UyG43b19jlPXQ8cJ9CU,11289
 general/interface/repository/many_to_many_repository.py,sha256=KRJ2SMUGDYNoGV-ea541wlWg0FW4NQ_Ry85aJBarmC8,11183
 general/interface/repository/view_repository.py,sha256=wxDGw7kenuVrDd9nfh7-omw2m9Jex5WzF_lhEiqPoA0,7902
 general/interface/repository/handler/__init__.py,sha256=uhtGETCY-s9lJsn919u0e7XnPsGjBjxjjtJFnn5XrV4,686
 general/interface/repository/handler/base_handler.py,sha256=aVT6s60rsdZUqQlKWlUyuiGgVxzFLJCb7uztn859sL4,3363
-general/interface/repository/handler/handler.py,sha256=o_wD9L5sF4RySyetOJHMRE7Ho_3PqP5gWCj2zw9D7Lk,2467
+general/interface/repository/handler/handler.py,sha256=tzoJXjf43bgdczwSbcvVeUtt6xZU6ZSkVgfMFwuu2eg,1538
 general/interface/repository/handler/ilike_handler.py,sha256=OM3klDlx7ixqWF7kklWj8kbgVY_5ZNitcQ0usGnQP_0,4015
 general/interface/repository/handler/interval_handler.py,sha256=4TtEcpzUFZeyB-yitib5Kpe3U67aS07uye4K7jXrtG4,5517
 general/interface/repository/handler/json_handler.py,sha256=f_nGemsxTPJ3W0xkU99sCFA0EVo1xa8p803NyjcGJT4,4414
 general/interface/repository/handler/json_ilike_handler.py,sha256=icfA4dO8E_W_KUEG5HB1nLVI1jfjxzkG8ZJ-IaCd4kY,3530
 general/interface/repository/handler/or_handler.py,sha256=UOjIh77H4y-x434YGLYRfVIXKnod1M5XPiMf71V2JTg,3137
 general/interface/repository/handler/soft_delete_handler.py,sha256=1WD1n6q5plyJ0RDniJcEwNlic1WJqXvSlCj99VLc_3A,4100
-general/interface/repository/handler/statement_manager.py,sha256=EBv2ApCBYfo18fqoALftMxsN-_2Yq9n-yzfEQkh9ZLg,6612
+general/interface/repository/handler/statement_manager.py,sha256=JSj6K-iQJ06kLdsMTOqK62cIvR87ioOA1LmLTGpqrB0,8205
 general/utils/__init__.py,sha256=_SPe88reIZ0JxwK7mp-u_p-9c4hCcZ-daUihi0gymNk,103
 general/utils/consts.py,sha256=nE75Ud7sVuDw9K_xmIJNjL_5f_BVJmwGNPGFYc26H3Y,264
-python_general_be_lib-0.11.2.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
-python_general_be_lib-0.11.2.dist-info/METADATA,sha256=I67gtlqhPnQO3MMb7REVx8989XeHBIRAkQwxZ53r-No,3410
-python_general_be_lib-0.11.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_general_be_lib-0.11.2.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
-python_general_be_lib-0.11.2.dist-info/RECORD,,
+python_general_be_lib-0.11.3.dist-info/licenses/LICENSE,sha256=iUaO1XZyB9P3Tmog0OILuTisP6vXGe3QKz-4yRTxOFk,1069
+python_general_be_lib-0.11.3.dist-info/METADATA,sha256=kXWrKc_wD4H6khCeqnluMKmFoD-8AopOF8m3RXISA1s,3452
+python_general_be_lib-0.11.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_general_be_lib-0.11.3.dist-info/top_level.txt,sha256=tTZePW8_CNUqSgKFd2SEH72ZbnhS0OYjRsgcv0ikSFY,8
+python_general_be_lib-0.11.3.dist-info/RECORD,,