Provide better error messaging when type resolution fails

[KRRT7]

https://github.com/twisted/pydoctor

crosshair cover pydoctor.templatewriter.pages.init

source_tag('')
Traceback (most recent call last):
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/bin/crosshair", line 10, in <module>
    sys.exit(main())
             ^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/main.py", line 969, in main
    sys.exit(unwalled_main(cmd_args))
             ^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/main.py", line 930, in unwalled_main
    return cover(args, defaults.overlay(options), sys.stdout, sys.stderr)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/main.py", line 773, in cover
    paths = path_cover(
            ^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/path_cover.py", line 130, in path_cover
    explore_paths(run_path, sig, options, search_root, on_path_complete)
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 1375, in explore_paths
    pre_args = gen_args(sig)
               ^^^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 755, in gen_args
    value = proxy_maker(param.annotation, smt_name, allow_subtypes)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "proxy_arg_obj.py", line 698, in proxy_arg_obj
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/libimpl/builtinslib.py", line 4146, in make_union_choice
    return creator(pytypes[-1])
           ^^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 585, in __call__
    return proxy_for_type(
           ^^^^^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 705, in proxy_for_type
    return proxy_for_class(typ, varname)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 494, in proxy_for_class
    args = gen_args(constructor_sig)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 755, in gen_args
    value = proxy_maker(param.annotation, smt_name, allow_subtypes)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "proxy_arg_primary.py", line 705, in proxy_arg_primary
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 494, in proxy_for_class
    args = gen_args(constructor_sig)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 755, in gen_args
    value = proxy_maker(param.annotation, smt_name, allow_subtypes)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "proxy_arg_system.py", line 705, in proxy_arg_system
  File "/Users/krrt7/Desktop/work/pydoctor/.venv/lib/python3.11/site-packages/crosshair/core.py", line 474, in proxy_for_class
    data_members = get_type_hints(typ)
                   ^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/.local/share/uv/python/cpython-3.11.13-macos-aarch64-none/lib/python3.11/typing.py", line 2377, in get_type_hints
    value = _eval_type(value, base_globals, base_locals)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/.local/share/uv/python/cpython-3.11.13-macos-aarch64-none/lib/python3.11/typing.py", line 395, in _eval_type
    return t._evaluate(globalns, localns, recursive_guard)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/krrt7/.local/share/uv/python/cpython-3.11.13-macos-aarch64-none/lib/python3.11/typing.py", line 905, in _evaluate
    eval(self.__forward_code__, globalns, localns),
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<string>", line 1, in <module>
NameError: name 'SyntaxTreeParser' is not defined. Did you mean: 'syntaxTreeParser'?

[pschanely]

@KRRT7 sorry for the delaying in replying here. Thanks for the report, and I hope you keep them coming!

CrossHair relies on typing.get_type_hints to collect type information. It is unfortunately common for this to fail however, and that's the case here:

>>> from pydoctor.model import System
>>> import typing
>>> typing.get_type_hints(System)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/python/3.12.1/lib/python3.12/typing.py", line 2209, in get_type_hints
    value = _eval_type(value, base_globals, base_locals)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/python/3.12.1/lib/python3.12/typing.py", line 400, in _eval_type
    return t._evaluate(globalns, localns, recursive_guard)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/python/3.12.1/lib/python3.12/typing.py", line 907, in _evaluate
    eval(self.__forward_code__, globalns, localns),
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<string>", line 1, in <module>
NameError: name 'SyntaxTreeParser' is not defined

An import for SyntaxTreeParser is needed.

I think (but am not positive) that type checkers will generally error on this too, since it's potentially ambiguous where SyntaxTreeParser should be imported from.

[pschanely]

Hmm, on further thought, I'll re-open this and re-purpose it for improving our error messaging here.

[KRRT7]

I'll keep them coming, unfortunately I had to focus on other things so I hadn't been paying attention to crosshairs errors, I think I'll enable error reporting for them on our side and forward to you