I’m thinking (as an outcome of this thread) about the PEP that will expose the __text_signature__ (which is undocumented and private so far) string attribute for extension modules. With some minor additions for its format specification (return annotations so far).
Maybe we could hit two rabbits in one shot and include basic support for multiple signatures?
The proposed extension of the __text_signature__ (perhaps, renamed in this case as __text_signatures__) format is trivial: lets just list all different signatures one by one, separated by a newline. Each signature has a parameter list, enclosed by round brackets, optionally followed by ‘->’ and an expression (for return annotation). For example, in the log() case this will look like:
($module, x, /)
($module, x, base, /)
The attribute will be created from the docstring just as we do it now (modulo renaming). Later we could modify the AC to support generation of the docstring from the clinic input, proposed above by Raymond, add the inspect.signatures(), etc.
Fancy syntax using square brackets for optional arguments might look more economical. But I suspect its more suitable for typeless languages. Also, above proposal is almost compatible with Python syntax: every valid text signature, after simple tweaks, will be ast.parse()-able.