python-general-be-lib 0.11.2__tar.gz → 0.11.3__tar.gz

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/PKG-INFO

@@ -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 → python_general_be_lib-0.11.3}/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()

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

@@ -0,0 +1,59 @@
+"""SQLAlchemy declarative base class and preconfigured Pydantic models.
+
+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",
+    "retrieve_mapper_entity",
+    "retrieve_mapper_from_table",
+    "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__)

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/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():

python_general_be_lib-0.11.3/general/interface/metadata/__init__.py

@@ -0,0 +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. 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)
+
+
+def __dir__() -> list[str]:
+    """List the public surface without importing anything.
+
+    Returns:
+        list[str]: The names in ``__all__``.
+    """
+    return list(__all__)

python_general_be_lib-0.11.3/general/interface/repository/__init__.py

@@ -0,0 +1,59 @@
+"""ORM repositories: generic CRUD, spatial, many-to-many and views.
+
+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",
+    "GeometryRepository",
+    "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__)

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/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)
 

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/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

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/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.
 

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/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 → python_general_be_lib-0.11.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-general-be-lib"
-version = "0.11.2"
+version = "0.11.3"
 description = "General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, logger utilities."
 readme = "README.md"
 license = { text = "MIT" }
@@ -40,6 +40,7 @@ dev = [
     "psycopg[binary]>=3",
     "build",
     "twine",
+    "mypy>=1.11",
 ]
 
 [project.urls]

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/python_general_be_lib.egg-info/PKG-INFO

@@ -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 → python_general_be_lib-0.11.3}/python_general_be_lib.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ python_general_be_lib.egg-info/requires.txt
 python_general_be_lib.egg-info/top_level.txt
 tests/test_caricamento_parziale.py
 tests/test_compiled_cache.py
+tests/test_costo_import.py
 tests/test_engine_defaults.py
 tests/test_entity_has_columns.py
 tests/test_execute_contratto.py

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/python_general_be_lib.egg-info/requires.txt

@@ -11,3 +11,4 @@ testcontainers[postgres]>=4
 psycopg[binary]>=3
 build
 twine
+mypy>=1.11

python_general_be_lib-0.11.3/tests/test_costo_import.py

@@ -0,0 +1,155 @@
+"""Il costo di import per sottoalbero (1.10 di `.claude/piano-ottimizzazioni.md`).
+
+`general/__init__.py` è vuoto di proposito, così ogni percorso paga solo per il proprio
+sottoalbero. La regola valeva per la radice e **non era applicata un livello sotto**: tre
+catene la disfacevano, e nessuna di esse era visibile perché niente le verificava.
+
+- `crud_exceptions.py` importava `sqlalchemy.exc` a livello di modulo — 80 moduli — e in
+  quel file stanno anche le classi di eccezione, di cui `general/logger.py` usa una. Il
+  logger caricava quindi SQLAlchemy, contro quanto `CLAUDE.md` dichiara di lui.
+- `declarative_base.py` importava GeoAlchemy2 per le due righe di `to_pydantic` che mappano
+  una colonna geometrica, quindi `Base` — che ogni entità estende — trascinava PostGIS.
+- gli `__init__.py` dei package ri-esportavano tutto con `import *`, quindi raggiungere un
+  modulo leggero costava i fratelli pesanti.
+
+Questi test **non misurano millisecondi**, che sarebbero instabili: asseriscono cosa
+finisce in `sys.modules`, che è deterministico. È la forma che accorge del ritorno di un
+import ansioso il giorno in cui qualcuno lo rimette.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import pytest
+
+PESANTI = ("sqlalchemy", "geoalchemy2", "shapely")
+
+
+def moduli_caricati(istruzione: str) -> set[str]:
+    """Esegue l'import in un processo pulito e restituisce i pacchetti pesanti caricati."""
+    codice = f"{istruzione}\nimport sys\nprint(' '.join(p for p in {PESANTI!r} if p in sys.modules))"
+    esito = subprocess.run([sys.executable, "-c", codice], capture_output=True, text=True)
+    assert esito.returncode == 0, esito.stderr
+    return set(esito.stdout.split())
+
+
+# --------------------------------------------------- ciò che non deve essere caricato
+
+
+@pytest.mark.parametrize(
+    "istruzione, vietati",
+    [
+        ("import general.logger", {"sqlalchemy", "geoalchemy2", "shapely"}),
+        ("import general.exception", {"sqlalchemy", "geoalchemy2", "shapely"}),
+        ("import general.paginator_dto", {"sqlalchemy", "geoalchemy2", "shapely"}),
+        ("import general.context", {"sqlalchemy", "geoalchemy2", "shapely"}),
+        ("import general.utils", {"sqlalchemy", "geoalchemy2", "shapely"}),
+        ("import general.interface.repository.crud_repository", {"geoalchemy2", "shapely"}),
+        ("import general.interface.metadata.crud_metadata", {"geoalchemy2", "shapely"}),
+    ],
+    ids=lambda v: v.replace("import ", "") if isinstance(v, str) else "",
+)
+def test_un_modulo_non_paga_per_quello_che_non_usa(istruzione: str, vietati: set[str]) -> None:
+    assert moduli_caricati(istruzione) & vietati == set()
+
+
+def test_il_percorso_orm_carica_sqlalchemy_ma_non_postgis() -> None:
+    """La distinzione è il punto: l'ORM serve, PostGIS no — e prima venivano insieme."""
+    caricati = moduli_caricati("import general.interface.repository.crud_repository")
+
+    assert "sqlalchemy" in caricati
+    assert "geoalchemy2" not in caricati
+
+
+def test_chi_usa_le_geometrie_le_carica_eccome() -> None:
+    """La pigrizia non toglie niente: chi tocca il modulo spaziale ha le sue dipendenze."""
+    assert "geoalchemy2" in moduli_caricati("import general.interface.repository.geometry_repository")
+
+
+# ------------------------------------------------------- il package pigro si comporta
+
+
+@pytest.mark.parametrize(
+    "package, simbolo, modulo_dietro",
+    [
+        ("general.interface.base", "Base", "general.interface.base.declarative_base"),
+        ("general.interface.repository", "CrudRepository", "general.interface.repository.crud_repository"),
+        ("general.interface.metadata", "CrudMetadata", "general.interface.metadata.crud_metadata"),
+    ],
+)
+def test_importare_il_package_non_importa_i_moduli(package: str, simbolo: str, modulo_dietro: str) -> None:
+    """Il package si carica da solo; il modulo dietro arriva al primo accesso al simbolo."""
+    codice = (
+        f"import {package}, sys\n"
+        f"print('prima' if {modulo_dietro!r} in sys.modules else 'assente')\n"
+        f"_ = {package}.{simbolo}\n"
+        f"print('dopo' if {modulo_dietro!r} in sys.modules else 'mai')"
+    )
+    esito = subprocess.run([sys.executable, "-c", codice], capture_output=True, text=True)
+
+    assert esito.stdout.split() == ["assente", "dopo"], esito.stdout + esito.stderr
+
+
+@pytest.mark.parametrize(
+    "package, simbolo",
+    [
+        ("general.interface.base", "Base"),
+        ("general.interface.repository", "CrudRepository"),
+        ("general.interface.metadata", "GeomMetadata"),
+    ],
+)
+def test_il_simbolo_si_importa_come_prima(package: str, simbolo: str) -> None:
+    """Il `from package import X` del consumatore non cambia."""
+    esito = subprocess.run(
+        [sys.executable, "-c", f"from {package} import {simbolo}; print({simbolo}.__name__)"],
+        capture_output=True, text=True,
+    )
+
+    assert esito.stdout.strip() == simbolo, esito.stderr
+
+
+def test_un_nome_inesistente_alza_attributeerror() -> None:
+    """Il `__getattr__` non deve trasformare un typo in un ImportError oscuro."""
+    import general.interface.repository as package
+
+    with pytest.raises(AttributeError, match="Inesistente"):
+        _ = package.Inesistente
+
+
+def test_dir_elenca_la_superficie_senza_importare_niente() -> None:
+    """Senza `__dir__` un package pigro sembrerebbe vuoto in un REPL."""
+    import general.interface.repository as package
+
+    assert set(dir(package)) == set(package.__all__)
+
+
+# ------------------------------------------------------------- l'invariante dei tipi
+
+
+def test_i_tipi_restano_visibili_a_mypy(tmp_path) -> None:
+    """Il blocco ``TYPE_CHECKING`` è ciò che rende la pigrizia gratuita, e va difeso.
+
+    Senza, un type checker vede ``Any`` al posto di ogni simbolo della libreria: gli import
+    continuano a funzionare, `py.typed` viene ancora spedito, e il consumatore smette di
+    ricevere errori **in silenzio**. Verificato con mypy 2.3.1 il 2026-09-25: è la sola
+    regressione possibile di questo intervento, ed è invisibile senza un test.
+
+    mypy sta fra le dipendenze `[dev]` proprio per questo test; l'`importorskip` copre chi
+    esegue la suite senza l'extra.
+    """
+    api = pytest.importorskip("mypy.api", reason="mypy non installato")
+
+    sorgente = tmp_path / "consumatore.py"
+    sorgente.write_text(
+        "from general.interface.repository import CrudRepository\n"
+        "sbagliato: int = CrudRepository\n"
+    )
+    uscita, _, _ = api.run(["--ignore-missing-imports", "--follow-imports=silent",
+                            "--no-error-summary", str(sorgente)])
+
+    assert "Incompatible types in assignment" in uscita, (
+        f"mypy non vede più il tipo di CrudRepository: probabilmente manca il blocco "
+        f"TYPE_CHECKING in un __init__.py pigro.\n{uscita}"
+    )

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/tests/test_import_pubblici.py

@@ -8,15 +8,29 @@ test fissano gli import che devono funzionare e la pulizia di ciò che esce da
 Sono deliberatamente banali: il loro valore è che falliscono quando qualcuno aggiunge
 una classe pubblica e dimentica `__all__` o l'`__init__.py`, che è successo con
 `OrHandler` (mai esportato) e con `Handler` (esportato solo dopo averlo cercato).
+
+`SUPERFICIE` però è una **mappa scritta a mano**, e per un package nuovo non fallisce:
+non lo conosce. È successo con `general.utils`, aggiunto qui a mano *dopo* che il buco
+era stato trovato leggendo il codice — cioè il test non ha fatto la sola cosa per cui
+esiste (voce 1b.9). Da lì
+`test_ogni_package_della_libreria_e_censito`, che enumera i package davvero presenti e
+pretende che ognuno sia o in `SUPERFICIE` o nell'elenco esplicito di quelli vuoti per
+scelta.
 """
 
 from __future__ import annotations
 
 import importlib
+import pkgutil
 import types
 
 import pytest
 
+# Package senza superficie propria, **per scelta**: la radice resta vuota perché ogni
+# percorso di import paghi solo il proprio sottoalbero (voce 1.10 delle ottimizzazioni),
+# e ``general.interface`` è solo un contenitore di namespace.
+SENZA_SUPERFICIE = {"general", "general.interface"}
+
 # (package, simboli che devono essere importabili da lì)
 SUPERFICIE = {
     "general.utils": [
@@ -140,3 +154,53 @@ def test_general_interface_e_un_package_regolare() -> None:
 
     assert general.interface.__file__ is not None
     assert general.interface.__file__.endswith("__init__.py")
+
+
+# ------------------------------------------- che la mappa qui sopra resti completa
+
+
+def test_ogni_package_della_libreria_e_censito() -> None:
+    """Un package nuovo deve comparire in `SUPERFICIE` o essere dichiarato senza superficie.
+
+    È il test che mancava: gli altri verificano i package che qualcuno ha già elencato,
+    quindi non possono accorgersi di quello che nessuno ha elencato.
+    """
+    import general
+
+    presenti = {"general"} | {
+        modulo.name
+        for modulo in pkgutil.walk_packages(general.__path__, "general.")
+        if modulo.ispkg
+    }
+
+    assert presenti - set(SUPERFICIE) - SENZA_SUPERFICIE == set(), (
+        "package senza una voce in SUPERFICIE: aggiungila, oppure dichiaralo in SENZA_SUPERFICIE"
+    )
+
+
+@pytest.mark.parametrize("package", sorted(SENZA_SUPERFICIE))
+def test_i_package_senza_superficie_restano_vuoti(package: str) -> None:
+    """La radice vuota è una scelta di costo: se qualcuno ci esporta qualcosa, va saputo."""
+    modulo = importlib.import_module(package)
+
+    assert not hasattr(modulo, "__all__"), f"{package} ha smesso di essere vuoto"
+
+
+# ------------------------------- i package pigri hanno due elenchi da tenere allineati
+
+
+@pytest.mark.parametrize(
+    "package",
+    ["general.interface.base", "general.interface.repository", "general.interface.metadata"],
+)
+def test_i_package_pigri_hanno_all_e_modules_allineati(package: str) -> None:
+    """Il `__getattr__` pigro (ottim. 1.10) risolve da `_MODULES`, l'`import *` da `__all__`.
+
+    Delle due dimenticanze possibili una è rumorosa — un nome in `__all__` e non in
+    `_MODULES` fa fallire l'`import *` con `AttributeError` — e l'altra è **silenziosa**: un
+    nome in `_MODULES` e non in `__all__` funziona con l'import diretto e sparisce da
+    `import *` e da `dir()`.
+    """
+    modulo = importlib.import_module(package)
+
+    assert set(modulo.__all__) == set(modulo._MODULES)

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/tests/test_logger.py

@@ -61,7 +61,8 @@ class ArgomentoOstile:
 
     Serve a dimostrare che il decorator **non** serializza gli argomenti quando la
     chiamata va a buon fine: se lo facesse, questo ``__repr__`` farebbe fallire il
-    test in modo esplicito.
+    test in modo esplicito. Sul percorso di errore dimostra il contrario: il decorator
+    lo rappresenta, e la sua eccezione non deve sostituire quella originale.
     """
 
     def __repr__(self) -> str:
@@ -249,8 +250,8 @@ def test_l_errore_registra_traceback_e_argomenti_in_un_solo_record(caplog) -> No
     aggregatore di log finirebbero interlacciati con altre richieste e l'elenco degli
     argomenti si staccherebbe dal suo traceback.
 
-    Gli argomenti viaggiano come campi strutturati (``extra``) e non nel messaggio.
-    Le chiavi **non possono** chiamarsi ``args``: è un attributo riservato di
+    Gli argomenti viaggiano due volte: troncati nel messaggio, per chi legge il log
+    testuale, e interi come campi strutturati (``extra``), per un handler JSON. Le chiavi **non possono** chiamarsi ``args``: è un attributo riservato di
     ``LogRecord`` e ``Logger.makeRecord`` solleva
     ``KeyError: "Attempt to overwrite 'args' in LogRecord"`` — che, dentro un ``except``,
     sostituirebbe l'eccezione originale e trasformerebbe anche un 404 atteso in un
@@ -273,39 +274,96 @@ def test_l_errore_registra_traceback_e_argomenti_in_un_solo_record(caplog) -> No
     assert errori[0].func_kwargs == {"nota": "controllo"}
 
 
-def test_gli_argomenti_non_compaiono_nell_output_del_formatter_di_default(caplog) -> None:
-    """Caratterizzazione: con il formatter di ``LOGGING_CONFIG`` gli argomenti non si vedono.
+def test_gli_argomenti_compaiono_nell_output_del_formatter_di_default(caplog) -> None:
+    """Con il formatter di ``LOGGING_CONFIG`` gli argomenti si vedono nella riga di errore.
 
-    Sono attaccati al record come campi ``extra``, quindi disponibili a un handler
-    strutturato (JSON), ma il formatter di default
-    (``[%(asctime)s] %(levelname)s - %(message)s``) non li referenzia e l'informazione
-    non raggiunge il log.
-
-    Metterli direttamente nella stringa di formato non è possibile: ``%(func_args)s``
-    farebbe fallire la formattazione di **ogni altro** record, che quell'attributo non
-    ce l'ha. Serve una sottoclasse di ``Formatter`` che li accodi quando presenti.
-
-    Se verrà aggiunta, **questo test deve fallire** e va sostituito con l'asserzione
-    sull'output atteso.
+    Stanno nel **messaggio**, non in un campo che il formatter dovrebbe referenziare:
+    ``%(func_args)s`` nella stringa di formato farebbe fallire la formattazione di ogni
+    altro record, che quell'attributo non ce l'ha. Così valgono anche per chi configura
+    ``logging`` per conto proprio senza passare da ``init_logger``.
     """
     caplog.set_level(logging.INFO)
 
     @log
-    def esplode(identificativo):
+    def esplode(identificativo, nota=None):
         raise ValueError("boom")
 
-    # sentinella improbabile: un valore come `42` comparirebbe per caso nel
+    # sentinelle improbabili: un valore come `42` comparirebbe per caso nel
     # timestamp del formatter (`[2026-08-27 17:42:32]`), rendendo il test dipendente
     # dall'ora di esecuzione
-    sentinella = "ARGOMENTO-CHE-NON-DEVE-COMPARIRE"
+    posizionale, per_nome = "ARGOMENTO-POSIZIONALE", "ARGOMENTO-PER-NOME"
     with pytest.raises(InternalServerException):
-        esplode(sentinella)
+        esplode(posizionale, nota=per_nome)
 
     record = record_del_decorator(caplog)[0]
-    assert record.func_args == (sentinella,), "l'argomento deve essere sul record"
-
     formattato = logging.Formatter("[%(asctime)s] %(levelname)s - %(message)s").format(record)
-    assert sentinella not in formattato
+    assert f"args=('{posizionale}',)" in formattato
+    assert f"kwargs={{'nota': '{per_nome}'}}" in formattato
+
+
+def test_anche_una_http_exception_riporta_gli_argomenti(caplog) -> None:
+    """Il 404 propagato invariato ha gli argomenti nel messaggio come un 500."""
+    caplog.set_level(logging.INFO)
+
+    @log
+    def cerca(identificativo):
+        raise EntityNotFoundException()
+
+    with pytest.raises(EntityNotFoundException):
+        cerca("ID-CERCATO")
+
+    assert "args=('ID-CERCATO',)" in pulito(record_del_decorator(caplog)[0].getMessage())
+
+
+def test_gli_argomenti_voluminosi_vengono_troncati(caplog) -> None:
+    """Stringhe e collezioni lunghe sono accorciate, non stampate per intero.
+
+    Senza limite una chiamata con una lista di 1000 elementi o un payload di qualche
+    decina di KB produrrebbe una riga di log di quella dimensione a ogni errore. Il
+    valore intero resta disponibile in ``func_args``.
+    """
+    caplog.set_level(logging.INFO)
+
+    @log
+    def esplode(testo, elementi):
+        raise ValueError("boom")
+
+    testo, elementi = "x" * 10_000, list(range(1000))
+    with pytest.raises(InternalServerException):
+        esplode(testo, elementi)
+
+    record = record_del_decorator(caplog)[0]
+    messaggio = pulito(record.getMessage())
+    assert len(messaggio) < 1000, len(messaggio)
+    assert "..." in messaggio
+    assert record.func_args == (testo, elementi), "il record conserva i valori interi"
+
+
+@pytest.mark.parametrize(
+    ("eccezione", "attesa"),
+    [(ValueError("boom"), InternalServerException), (EntityNotFoundException(), EntityNotFoundException)],
+    ids=["errore-applicativo", "http-exception"],
+)
+def test_un_repr_che_solleva_non_sostituisce_l_eccezione_originale(caplog, eccezione, attesa) -> None:
+    """Un argomento che non si lascia rappresentare non cambia l'eccezione propagata.
+
+    La rappresentazione si costruisce **dentro** l'``except``: se il ``__repr__`` di un
+    argomento sollevasse fin lì — un'entità ORM staccata dalla sessione che tenta un
+    lazy load, un ``__repr__`` scritto male — la sua eccezione prenderebbe il posto di
+    quella originale, e anche un 404 atteso diventerebbe un 500. Al suo posto compare
+    un segnaposto con il nome della classe.
+    """
+    caplog.set_level(logging.INFO)
+
+    @log
+    def esplode(payload, altro=None):
+        raise eccezione
+
+    with pytest.raises(attesa):
+        esplode(ArgomentoOstile(), altro=ArgomentoOstile())
+
+    messaggio = pulito(record_del_decorator(caplog)[0].getMessage())
+    assert messaggio.count("<ArgomentoOstile instance at 0x") == 2, messaggio
 
 
 # --------------------------------------------------------------------- async

{python_general_be_lib-0.11.2 → python_general_be_lib-0.11.3}/tests/test_pipeline_handler.py

@@ -26,6 +26,7 @@ from general.interface.repository.handler.base_handler import BaseHandler
 from general.interface.repository.handler.handler import Handler
 from general.interface.repository.handler.ilike_handler import ILikeHandler
 from general.interface.repository.handler.interval_handler import IntervalHandler
+from general.interface.repository.handler.json_handler import JsonHandler
 from general.interface.repository.handler.json_ilike_handler import JsonILikeHandler
 from general.interface.repository.handler.or_handler import OrHandler
 from models import (
@@ -361,6 +362,55 @@ def test_la_pipeline_serve_anche_le_scritture(engine: Engine) -> None:
     assert "DELETE FROM documento" in sql_delete and "titolo ILIKE" in sql_delete
 
 
+# ------------------------------------- handler passati come classe invece che istanza
+
+
+def test_un_handler_si_registra_come_classe_oltre_che_come_istanza(engine: Engine) -> None:
+    """Il suggerimento di tipo prometteva entrambe le forme e ne reggeva una (voce 1b.9).
+
+    ``handlers=[SoftDeleteHandler]`` è quello che un consumatore scrive per attivare il soft
+    delete, e falliva con ``TypeError: conditions() missing 1 required positional argument:
+    'self'`` **alla prima query**: lontano dalla causa, e con un messaggio che parla di
+    ``self``. La forma a classe vale per **tutti** gli handler della libreria: gli argomenti
+    oltre alle colonne hanno tutti un default.
+    """
+    da_classe = CrudRepository(entity=Documento, model=DocumentoModel, engine=engine, handlers=[JsonHandler])
+    da_istanza = CrudRepository(entity=Documento, model=DocumentoModel, engine=engine,
+                                handlers=[JsonHandler(Documento.columns())])
+
+    sql = uno(captured_sql(da_classe.find, stato="attivo"))
+    assert clausola_where(uno(captured_sql(da_istanza.find, stato="attivo"))) == clausola_where(sql)
+    assert "attributi" in sql, "la chiave non-colonna è stata letta come sottochiave JSON"
+
+
+def test_una_classe_che_serve_altri_argomenti_fallisce_alla_costruzione(engine: Engine) -> None:
+    """E lo dice: il nome dell'handler e cosa fare, dove il chiamante può leggerlo.
+
+    Nessun handler della libreria ricade in questo caso — ecco perché serve un handler
+    custom per esercitarlo: è il consumatore che può scriverne uno con argomenti
+    obbligatori, e prima lo scopriva alla prima query.
+    """
+
+    class HandlerEsigente(Handler):
+        __slots__ = ("soglia",)
+
+        def __init__(self, columns, soglia):
+            self.soglia = soglia
+
+    with pytest.raises(TypeError, match="HandlerEsigente needs more than the columns"):
+        CrudRepository(entity=Documento, model=DocumentoModel, engine=engine, handlers=[HandlerEsigente])
+
+
+def test_handler_class_accetta_la_classe_e_l_istanza(engine: Engine) -> None:
+    """Il parametro gemello aveva il difetto opposto: dichiarava istanze e reggeva classi."""
+    da_classe = CrudRepository(entity=Documento, model=DocumentoModel, engine=engine, handler_class=BaseHandler)
+    da_istanza = CrudRepository(entity=Documento, model=DocumentoModel, engine=engine,
+                                handler_class=BaseHandler(Documento.columns()))
+
+    atteso = clausola_where(uno(captured_sql(da_classe.find, titolo="atto")))
+    assert clausola_where(uno(captured_sql(da_istanza.find, titolo="atto"))) == atteso
+
+
 def test_handler_e_importabile_dal_package() -> None:
     """``Handler`` è la classe che i BE estendono: deve stare nel package."""
     from general.interface.repository.handler import Handler as Esportato

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

@@ -1,12 +0,0 @@
-"""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.11.2/general/interface/metadata/__init__.py

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

python_general_be_lib-0.11.2/general/interface/repository/__init__.py

@@ -1,13 +0,0 @@
-"""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 *
-
-__all__ = [
-    "CrudRepository",
-    "GeometryRepository",
-    "ManyToManyRepository",
-    "ViewRepository",
-]