Merge pull request #383 from reagento/feature/impoved-errors

Complete rework of error messages

Author: zhPavel

docs/changelog/fragments/+hide_traceback.breaking.rst

@@ -0,0 +1,2 @@
+Remove ``hide_traceback`` parameter of ``Retort`` (it is also removed from ``Retort.replace`` method).
+Now, you can control rendering error via ``error_renderer``. Yo can pass ``None`` to show python ``ExceptionGroup``

docs/changelog/fragments/+hints-fix.bugfix.rst

@@ -1 +1 @@
-Fix error hint generation for model conversion
+Fix error at hint generation for model conversion

docs/changelog/fragments/+new-errors.feature.rst

@@ -0,0 +1,36 @@
+Completely rework error rendering.
+Now, all errors of loader, dumper and converter generation uses new, compact and clear display mode.
+Also, many error texts are improved.
+
+.. code-block:: text
+   :caption: Old error example
+
+      | adaptix.AggregateCannotProvide: Cannot create loader for model. Loaders for some fields cannot be created (1 sub-exception)
+      | Location: `Book`
+      +-+---------------- 1 ----------------
+        | adaptix.AggregateCannotProvide: Cannot create loader for model. Cannot fetch InputNameLayout (1 sub-exception)
+        | Location: `Book.author: Person`
+        +-+---------------- 1 ----------------
+          | adaptix.CannotProvide: Required fields ['last_name'] are skipped
+          | Location: `Book.author: Person`
+          +------------------------------------
+
+    The above exception was the direct cause of the following exception:
+
+    Traceback (most recent call last):
+      ...
+    adaptix.ProviderNotFoundError: Cannot produce loader for type <class '__main__.Book'>
+    Note: The attached exception above contains verbose description of the problem
+
+
+.. code-block:: text
+   :caption: New error example
+
+    Traceback (most recent call last):
+      ...
+    adaptix.ProviderNotFoundError: Cannot produce loader for type <class '__main__.Book'>
+      × Cannot create loader for model. Loaders for some fields cannot be created
+      │ Location: ‹Book›
+      ╰──▷ Cannot create loader for model. Cannot fetch `InputNameLayout`
+         │ Location: ‹Book.author: Person›
+         ╰──▷ Required fields ['last_name'] are skipped

docs/changelog/fragments/+retort-replace.breaking.rst

@@ -0,0 +1 @@
+Now, ``Retort.replace`` method takes ``Omitted`` to skip value instead of ``None``.

docs/examples/loading-and-dumping/extended_usage/fields_filtering_only.pytb

@@ -1,13 +1,6 @@
-  | adaptix.AggregateCannotProvide: Cannot create loader for model. Cannot fetch InputNameLayout (1 sub-exception)
-  | Location: `User`
-  +-+---------------- 1 ----------------
-    | adaptix.CannotProvide: Required fields ['password_hash'] are skipped
-    | Location: `User`
-    +------------------------------------
-
-The above exception was the direct cause of the following exception:
-
 Traceback (most recent call last):
   ...
-adaptix.NoSuitableProvider: Cannot produce loader for type <class 'docs.examples.extended_usage.fields_filtering_only.User'>
-Note: The attached exception above contains verbose description of the problem
+adaptix.ProviderNotFoundError: Cannot produce loader for type <class '__main__.User'>
+  × Cannot create loader for model. Cannot fetch `InputNameLayout`
+  │ Location: ‹User›
+  ╰──▷ Required fields ['password_hash'] are skipped

docs/examples/loading-and-dumping/extended_usage/fields_filtering_skip.pytb

@@ -1,13 +1,6 @@
-  | adaptix.AggregateCannotProvide: Cannot create loader for model. Cannot fetch InputNameLayout (1 sub-exception)
-  | Location: `User`
-  +-+---------------- 1 ----------------
-    | adaptix.CannotProvide: Required fields ['password_hash'] are skipped
-    | Location: `User`
-    +------------------------------------
-
-The above exception was the direct cause of the following exception:
-
 Traceback (most recent call last):
   ...
-adaptix.NoSuitableProvider: Cannot produce loader for type <class 'docs.examples.extended_usage.fields_filtering_skip.User'>
-Note: The attached exception above contains verbose description of the problem
+adaptix.ProviderNotFoundError: Cannot produce loader for type <class '__main__.User'>
+  × Cannot create loader for model. Cannot fetch `InputNameLayout`
+  │ Location: ‹User›
+  ╰──▷ Required fields ['password_hash'] are skipped

pyproject.toml

@@ -122,6 +122,9 @@ line-length = 120
 output-format = "concise"
 
 [tool.ruff.lint]
+
+allowed-confusables = ['×', '‹', '›']
+
 select = ['ALL']
 fixable = [
   'Q000',
@@ -177,7 +180,7 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ['F401']
 
-"test_*" = ['S101', 'PLR2004', 'PLC0105', 'N806', 'FA102', 'UP035', 'UP006']
+"test_*" = ['S101', 'PLR2004', 'PLC0105', 'N806', 'FA102', 'UP035', 'UP006', 'E501']
 "tests/*/local_helpers.py" = ['S101', 'PLR2004', 'PLC0105', 'N806', 'FA102']
 "tests/*/data_*.py" = ['F821']
 "tests/tests_helpers/*" = ['INP001', 'S101']

src/adaptix/_internal/conversion/facade/retort.py

@@ -64,12 +64,6 @@ def _calculate_derived(self) -> None:
         super()._calculate_derived()
         self._simple_converter_cache: dict[tuple[TypeHint, TypeHint, Optional[str]], Converter] = {}
 
-    def replace(self: AR, *, hide_traceback: Optional[bool] = None) -> AR:
-        with self._clone() as clone:
-            if hide_traceback is not None:
-                clone._hide_traceback = hide_traceback
-        return clone
-
     def extend(self: AR, *, recipe: Iterable[Provider]) -> AR:
         with self._clone() as clone:
             clone._instance_recipe = (
@@ -187,7 +181,7 @@ def convert(self, src_obj: Any, dst: type[DstT], *, recipe: Iterable[Provider] =
         src = type(src_obj)
         if is_generic_class(src):
             raise ValueError(
-                f"Can not infer the actual type of generic class instance ({src!r}),"
+                f"Cannot infer the actual type of generic class instance ({src!r}),"
                 " you have to use `get_converter` explicitly passing the type of object",
             )
 

src/adaptix/_internal/conversion/linking_provider.py

@@ -1,14 +1,13 @@
 import itertools
 from collections.abc import Iterable, Mapping
-from typing import Callable, NoReturn, Optional, TypeVar, Union
+from typing import Callable, Optional, TypeVar, Union
 
 from ..common import Coercer, OneArgCoercer, VarTuple
 from ..model_tools.definitions import DefaultFactory, DefaultValue, InputField, InputShape, Param, ParamKind
 from ..model_tools.introspection.callable import get_callable_shape
 from ..provider.essential import CannotProvide, Mediator, mandatory_apply_by_iterable
-from ..provider.fields import input_field_to_loc
 from ..provider.loc_stack_filtering import LocStackChecker
-from ..provider.loc_stack_tools import format_loc_stack
+from ..provider.loc_stack_tools import format_loc_stack, get_callable_name
 from ..provider.location import FieldLoc
 from ..utils import add_note
 from .provider_template import LinkingProvider
@@ -99,26 +98,26 @@ def _get_linking(
             try:
                 source = name_to_field_source[param.name]
             except KeyError:
-                self._raise_link_error(request, input_field, "Cannot match `{}` with model field")
+                raise CannotProvide(
+                    f"Cannot match function parameter ‹{input_field.id}› with any model field",
+                    is_terminal=True,
+                    is_demonstrative=True,
+                )
         else:
             if idx == 0:
                 return LinkingResult(linking=ModelLinking())
 
             try:
                 source = name_to_context_source[param.name]
             except KeyError:
-                self._raise_link_error(request, input_field, "Cannot match `{}` with converter parameter")
+                raise CannotProvide(
+                    f"Cannot match function parameter ‹{input_field.id}› with any converter parameter",
+                    is_terminal=True,
+                    is_demonstrative=True,
+                )
 
         return LinkingResult(linking=FieldLinking(source=source, coercer=None))
 
-    def _raise_link_error(self, request: LinkingRequest, input_field: InputField, template: str) -> NoReturn:
-        dest = request.destination.append_with(input_field_to_loc(input_field).complement_with_func(self._func))
-        raise CannotProvide(
-            template.format(format_loc_stack(dest)),
-            is_terminal=True,
-            is_demonstrative=True,
-        ) from None
-
     def _create_param_specs(
         self,
         mediator: Mediator,
@@ -161,13 +160,16 @@ def _provide_linking(self, mediator: Mediator, request: LinkingRequest) -> Linki
             param_specs = self._create_param_specs(
                 mediator,
                 request,
-                lambda: "Cannot create linking for function. Linkings for some parameters are not found",
+                lambda: (
+                    f"Cannot create linking for function ‹{get_callable_name(self._func)}›."
+                    f" Linkings for some parameters are not found"
+                ),
             )
         except CannotProvide as e:
             if len(request.sources) > 0:
                 src_desc = format_loc_stack(request.sources[0].reversed_slice(1))
                 dst_desc = format_loc_stack(request.destination)
-                add_note(e, f"Linking: `{src_desc} => {dst_desc}`")
+                add_note(e, f"Linking: {src_desc} ──▷ {dst_desc}")
             raise
 
         return LinkingResult(

src/adaptix/_internal/conversion/model_coercer_provider.py

@@ -1,10 +1,11 @@
-from collections.abc import Iterable, Mapping
+import sys
+from collections.abc import Iterable, Mapping, Sequence
 from inspect import Parameter, Signature
-from typing import Callable, Optional, Union
+from typing import Callable, Optional
 
 from ..code_tools.compiler import BasicClosureCompiler, ClosureCompiler
 from ..code_tools.name_sanitizer import BuiltinNameSanitizer, NameSanitizer
-from ..common import Coercer
+from ..common import Coercer, TypeHint
 from ..conversion.broaching.code_generator import BroachingCodeGenerator, BroachingPlan, BuiltinBroachingCodeGenerator
 from ..conversion.broaching.definitions import (
     AccessorElement,
@@ -27,12 +28,14 @@
     ModelLinking,
     UnlinkedOptionalPolicyRequest,
 )
+from ..feature_requirement import HAS_PY_310
 from ..model_tools.definitions import DefaultValue, InputField, InputShape, OutputShape, ParamKind, create_key_accessor
 from ..morphing.model.basic_gen import compile_closure_with_globals_capturing, fetch_code_gen_hook
 from ..provider.essential import AggregateCannotProvide, CannotProvide, Mediator, mandatory_apply_by_iterable
 from ..provider.fields import input_field_to_loc, output_field_to_loc
 from ..provider.loc_stack_filtering import LocStack
-from ..provider.location import AnyLoc, InputFieldLoc, InputFuncFieldLoc, OutputFieldLoc
+from ..provider.loc_stack_tools import format_loc_stack, format_type, get_callable_name
+from ..provider.location import AnyLoc, OutputFieldLoc
 from ..provider.shape_provider import InputShapeRequest, OutputShapeRequest, provide_generic_resolved_shape
 from ..utils import add_note
 from .provider_template import CoercerProvider
@@ -53,7 +56,7 @@ def _provide_coercer(self, mediator: Mediator, request: CoercerRequest) -> Coerc
         return self._make_coercer(mediator, request, broaching_plan)
 
     def _fetch_shapes(self, mediator: Mediator, request: CoercerRequest) -> tuple[InputShape, OutputShape]:
-        exception_and_type_list = []
+        exception_and_type_list: list[tuple[CannotProvide, LocStack]] = []
         try:
             dst_shape = self._fetch_dst_shape(mediator, request.dst)
         except CannotProvide as e:
@@ -67,17 +70,31 @@ def _fetch_shapes(self, mediator: Mediator, request: CoercerRequest) -> tuple[In
         if len(exception_and_type_list) == 1:
             raise CannotProvide(
                 parent_notes_gen=lambda: [
-                    f"Hint: Class `{self._loc_stack_to_view_string(exception_and_type_list[0][1])}` is not recognized as model."
+                    f"Hint: Type {format_type(exception_and_type_list[0][1].last.type)} is not recognized as model."
                     " Did your forget `@dataclass` decorator? Check documentation what model kinds are supported",
                 ],
             )
         if len(exception_and_type_list) == 2:  # noqa: PLR2004
             raise AggregateCannotProvide(
-                "Classes are not recognized as models",
+                "Types are not recognized as models",
                 [exc for exc, tp in exception_and_type_list],
+                parent_notes_gen=lambda: self._types_are_not_models_parent_notes_gen(
+                    loc_stack.last.type for exc, loc_stack in exception_and_type_list
+                ),
             )
         return dst_shape, src_shape
 
+    def _types_are_not_models_parent_notes_gen(self, types: Iterable[TypeHint]) -> Sequence[str]:
+        if (
+            HAS_PY_310
+            and all(getattr(tp, "__module__", None) not in sys.stdlib_module_names for tp in types)
+        ):
+            return [
+                "Hint: Types are not recognized as models."
+                " Did your forget `@dataclass` decorator? Check documentation what model kinds are supported",
+            ]
+        return []
+
     def _make_coercer(
         self,
         mediator: Mediator,
@@ -190,7 +207,6 @@ def _generate_field_linking_to_sub_plan(
         self,
         mediator: Mediator,
         request: CoercerRequest,
-        loc: Union[InputFieldLoc, InputFuncFieldLoc],
         linking: FieldLinking,
     ) -> BroachingPlan:
         if linking.coercer is not None:
@@ -200,7 +216,7 @@ def _generate_field_linking_to_sub_plan(
                 CoercerRequest(
                     src=linking.source,
                     ctx=request.ctx,
-                    dst=request.dst.append_with(loc),
+                    dst=request.dst,
                 ),
             )
 
@@ -287,7 +303,9 @@ def generate_sub_plan(input_field: InputField, linking_result: LinkingResult):
             if isinstance(linking_result.linking, FunctionLinking):
                 return self._generate_function_linking_to_sub_plan(
                     mediator=mediator,
-                    request=request,
+                    request=request.append_dst_loc(
+                        input_field_to_loc(input_field),
+                    ),
                     linking=linking_result.linking,
                 )
             if isinstance(linking_result.linking, ModelLinking):
@@ -299,21 +317,31 @@ def generate_sub_plan(input_field: InputField, linking_result: LinkingResult):
                 field_loc = input_field_to_loc(input_field)
                 return self._generate_field_linking_to_sub_plan(
                     mediator=mediator,
-                    request=request,
-                    loc=field_loc.complement_with_func(parent_func) if parent_func is not None else field_loc,
+                    request=request.append_dst_loc(
+                        field_loc.complement_with_func(parent_func) if parent_func is not None else field_loc,
+                    ),
                     linking=linking_result.linking,
                 )
             raise TypeError
 
-        field_sub_plans = mandatory_apply_by_iterable(
-            generate_sub_plan,
-            field_linkings,
-            lambda: (
-                "Cannot create coercer for models. Coercers for some linkings are not found"
-                if parent_func is None else
-                "Cannot create coercer for model and function. Coercers for some linkings are not found"
-            ),
-        )
+        try:
+            field_sub_plans = mandatory_apply_by_iterable(
+                generate_sub_plan,
+                field_linkings,
+                lambda: (
+                    "Cannot create coercer for models. Coercers for some linkings are not found"
+                    if parent_func is None else
+                    f"Cannot create coercer for model and function ‹{get_callable_name(parent_func)}›."
+                    f" Coercers for some linkings are not found"
+                ),
+            )
+        except CannotProvide as e:
+            if parent_func is not None:
+                src_desc = format_loc_stack(request.src)
+                dst_desc = format_loc_stack(request.dst)
+                add_note(e, f"Linking: {src_desc} ──▷ {dst_desc}")
+            raise
+
         return {
             dst_field: sub_plan
             for (dst_field, linking), sub_plan in zip(field_linkings, field_sub_plans)
@@ -368,7 +396,7 @@ def _make_constructor_call(
                 args.append(KeywordArg(param.name, sub_plan))
             elif param.kind == ParamKind.POS_ONLY and has_skipped_params:
                 raise CannotProvide(
-                    "Can not generate consistent constructor call,"
+                    "Cannot generate consistent constructor call,"
                     " positional-only parameter is skipped",
                     is_demonstrative=True,
                 )