Extending Typeguard is a confusing process for multiple reasons

[giladbarnea]

Thanks for this very useful project.

I'm currently developing an annotated-types typeguard plugin and encountered some potentially confusing behavior I'd like to bring up regarding custom lookup functions.

Currently, registered custom lookup functions are only invoked when the annotated type is not found in _checkers.origin_type_checkers.

Reading the Extending Typeguard docs and playing around a bit, it took me some time to realize that by design, custom lookup funcs are not meant for extending standard lib type checks (421#issuecomment-2016548538).

There are several aspects that could be made clearer:

1. Silent failure: The behavior is silent when custom checkers aren't triggered
2. The documentation examples using tuple and Annotated[tuple] suggest that standard types checking is encouraged
3. The checker_lookup_functions list structure implies support for multiple checkers, however, in practice, only the first is invoked.

I believe adding checks for standard types is a legitimate use case. Here is an example I made up that accurately represents my real need with the annotated-types plugin:
https://gist.github.com/giladbarnea/a8f31ceba99b42b17e8fe276466d3d5f

This aligns with validation patterns seen in Pydantic/JSON Schema and Python 3.11's exception groups.

For now, I've compromised on using checker_lookup_functions.insert(0, ...) to bypass the limitation, but it's a hack: I've now implicitly lost the "basic" typeguard check and have to either call check_type_internal or isinstance.

Proposed improvements:

1. If discouraging standard type checking remains the intended approach:
   1. Add explicit warnings/errors when custom lookup funcs won't be invoked
   2. Implement an explicit override mechanism (e.g., origin_type_checkers[float] = my_checker), rather than a list to append to
2. Alternatively, if extending standard checks could be supported, I'm happy to contribute a PR, just let me know.

Thanks! Would appreciate your thoughts on this.