> I assumed that anything that had a __text_signature__ wasn't going
> to have any other kind of signature information.  Therefore, if the
> object had a __text_signature__ attribute, then I already knew that's
> the best approach and it should definitely be first.

That's likely true for CPython itself, at least currently. I don't think
it's generally a safe assumption in the CPython ecosystem, which includes
things like Cython, Numba, Nuitka and others, i.e. a growing number of
tools that can create function-like native callables with a signature that
is worth introspecting. They may or may not provide a function-like
signature, but if they do (and at least Cython and Nuitka provide one),
then that's the best you can get. Reducing it to a string representation,
especially now that we have annotations for Python signatures, sounds like
a major step backwards.

> Are there callables in CPython that have *both* a __text_signature__
> *and* have signature information derivable from another source, where
> you *don't* want to use __text_signature__?

Anything that inherits from PyCFunction will inherit "__text_signature__"
automatically. I should mention that this inheritance is actually not
allowed, according to the type flags in PyCFunction_Type. It's just that
Cython has been doing it that way for years, mainly because there are some
barriers in CPython (don't remember which) that prevent other types from
doing similar things.

> I would be very interested if you knew of docstrings in the wild that
> innocently start with "sig=(" and yet aren't intended to be text
> signatures compatible with inspect.Signature.

I agree that it's an unlikely start for a docstring. That's why it was
chosen, after all.

Safer ways to do it would be extending the type, or adding a flag in some
way, but that's going to a) hurt more than the current situation, and b)
become wasteful at some point when the __text_signature__ actually gets
replaced by a proper function interface for CPython builtins. The fact that
that wasn't doable for Py3.4 any more doesn't mean it shouldn't be done at all.