Docs: Add a recipe for robust runtime introspection

[AlexWaygood]

Followup to #203

[srittau]

get_typing_objects_by_name_of() could actually be useful for typing_extensions itself, even if we normally only add typing backports.

Also, did you profile that the cache actually has a positive performance benefit?

[AlexWaygood]

get_typing_objects_by_name_of() could actually be useful for typing_extensions itself

Well, I thought so too (see #203), but it was open for nearly two weeks and there didn't seem to be much interest in it from people who I imagined might be users of the function. @JelleZijlstra and @adriangb suggested we add a recipe to the docs instead :)

Also, did you profile that the cache actually has a positive performance benefit?

I haven't actually, no. That's a good point; I'll do that. Though @JelleZijlstra mentioned in #203 (comment) that having a cache on a function very much like this had been crucial to keeping pyanalyze performant.

[srittau]

If Jelle said that, that's good enough for me.

[AlexWaygood]

I did some benchmarking anyway, using this script (I called it utils.py and put it in typing_extensions/src/):

Benchmark script

import functools
import typing
import typing_extensions
from typing import Tuple, Any
from typing_extensions import get_origin

# Use an unbounded cache for this function, for optimal performance
# @functools.lru_cache(maxsize=None)
def get_typing_objects_by_name_of(name: str) -> Tuple[Any, ...]:
   result = tuple(
       getattr(module, name)
       # You could potentially also include mypy_extensions here,
       # if your library supports mypy_extensions
       for module in (typing, typing_extensions)
       if hasattr(module, name)
   )
   if not result:
       raise ValueError(
           f"Neither typing nor typing_extensions has an object called {name!r}"
       )
   return result


def is_typing_name(obj: object, name: str) -> bool:
   return any(obj is thing for thing in get_typing_objects_by_name_of(name))


is_literal = functools.partial(is_typing_name, name="Literal")


def _bench():
   is_literal(typing.Literal)
   is_literal(typing_extensions.Literal)
   is_literal(typing.Any)
   is_literal(get_origin(typing.Literal[42]))
   is_literal(get_origin(typing_extensions.Final[42]))

I ran these commands from the typing_extensions/src/ directory:

>python -m timeit -s "from utils import _bench" "_bench()"
50000 loops, best of 5: 4.51 usec per loop

With the @lru_cache(maxsize=None) line commented out:

>python -m timeit -s "from utils import _bench" "_bench()"
50000 loops, best of 5: 7.66 usec per loop

So, the cache does indeed seem to speed things up quite a lot!

[AlexWaygood]

Adding the second cache speeds it up further, to 1.99 usec per loop. I think that's reasonable, though I think it makes sense to make that one a bounded cache rather than an unbounded one.