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

{python_general_be_lib-0.11.1 → 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.1
+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.1 → 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.1 → 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
@@ -31,6 +30,11 @@ class Base:
         or nothing: passing ``__config__`` puts the whole configuration in the hands of the
         caller, and passing ``__base__`` lets the base carry its own.
 
+        The generated class is stamped with the module of the entity, unless the caller
+        passes ``__module__``: ``create_model`` reads the calling frame otherwise, so every
+        generated model would claim to live in this module and a ``repr`` would point at
+        the library instead of the entity.
+
         Args:
             model_name (str, optional): Name of the generated model. When not given,
                 ``{ClassName}Model`` is used.
@@ -49,6 +53,10 @@ 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():
             create_model_kwargs["__config__"] = ConfigDict(from_attributes=True, populate_by_name=True, arbitrary_types_allowed=True, validate_default=True)
 

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.1 → python_general_be_lib-0.11.3}/general/interface/metadata/crud_metadata.py

@@ -342,7 +342,7 @@ class CrudMetadata:
         if rows:
             return rows[0]
         if strict:
-            raise EntityNotFoundException()
+            raise EntityNotFoundException(custom_message=table.name)
         return None
 
     def _get(self, table: Table, connection: Connection, pk: Any, columns: list[str] = None, **kwhere):
@@ -429,7 +429,7 @@ class CrudMetadata:
         if rows:
             return rows[0]
         if strict:
-            raise EntityNotFoundException()
+            raise EntityNotFoundException(custom_message=table.name)
         return None
 
     def insert(self, from_table: str, connection: Connection = None, models: list[Type[BaseModel] | BaseModel] = None, values: list[dict[str, Any]] = None, returning: bool = True,

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.1 → 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)
 
@@ -423,7 +430,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
         if records:
             return records[0]
         if strict:
-            raise EntityNotFoundException()
+            raise EntityNotFoundException(custom_message=self.entity.__name__)
         return None
 
     def _get(self, session: Session, pk: Any, columns: list[str] = None, exclude_columns: list[str] = None, **kwhere):
@@ -523,7 +530,7 @@ class CrudRepository[Entity: Base | Type[Base]]:
         if records:
             return records[0]
         if strict:
-            raise EntityNotFoundException()
+            raise EntityNotFoundException(custom_message=self.entity.__name__)
         return None
 
     def _find(self, session: Session, where: dict[str, Any] = None, columns: list[str] = None, exclude_columns: list[str] = None, limit: int = 0, orders_by: dict[str, bool] = None, **kwhere):

{python_general_be_lib-0.11.1 → 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.1 → 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.1 → 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.1 → 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.1"
+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.1 → 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.1
+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.1 → 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.1 → 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.1 → python_general_be_lib-0.11.3}/tests/test_find_one.py

@@ -56,6 +56,14 @@ def test_con_strict_alza_il_404(repo: CrudRepository) -> None:
     assert errore.value.status_code == 404
 
 
+def test_il_404_nomina_l_entita(repo: CrudRepository) -> None:
+    """Con più letture in fila il 404 deve dire **quale** è andata a vuoto."""
+    with pytest.raises(EntityNotFoundException) as errore:
+        repo.find_one(nome="nessuno", strict=True)
+
+    assert errore.value.detail == "Dato non trovato - Utente"
+
+
 def test_con_strict_la_sessione_viene_chiusa_prima_del_raise(repo: CrudRepository, engine: Engine) -> None:
     """Il ``raise`` sta **dopo** ``_return``, che è quello che chiude la sessione.
 

{python_general_be_lib-0.11.1 → python_general_be_lib-0.11.3}/tests/test_get.py

@@ -62,6 +62,14 @@ def test_con_strict_alza_il_404(repo: CrudRepository) -> None:
     assert errore.value.status_code == 404
 
 
+def test_il_404_nomina_l_entita(repo: CrudRepository) -> None:
+    """Con più letture in fila il 404 deve dire **quale** è andata a vuoto."""
+    with pytest.raises(EntityNotFoundException) as errore:
+        repo.get(999, strict=True)
+
+    assert errore.value.detail == "Dato non trovato - Utente"
+
+
 def test_costa_una_sola_query(repo: CrudRepository, engine: Engine) -> None:
     with assert_query_count(engine, 1, verbs=["SELECT"]):
         repo.get(1)