How to document callables with multiple signatures? (original) (raw)

Style guide now proposes:

These are the evolving guidelines for how to include function signatures in the reference guide. As outlined in Diátaxis, reference material should prioritize precision and completeness.

And:

If a function accepts positional-only or keyword-only arguments, include the slash and the star in the signature as appropriate

Though, this doesn’t cover case of functions with multiple signatures, like the math.log().

So far, such callables have no support from the inspect module (see Add support for multiple signatures · Issue #73536 · python/cpython · GitHub). Should we wait for solution here or can describe such functions consistently in sphinx docs right now?

I think we have only two options, both present in current docs:

1. Describe such callables as having several signatures, each with a correct parameter_list. Examples: range() or max().
2. Use non-Python syntax, enclosing optional arguments by brackets, like this itertools.repeat(object [, times]) (sometimes this syntax also requires to specify multiple signatures). Examples: itertools.islice() or range() (just in a different place).

An issue as example: `times` argument of `itertools.repeat()` accepts a negative number and doesn't accept `None` · Issue #135330 · python/cpython · GitHub

tjreedy (Terry Jan Reedy) June 10, 2025, 9:09am 2

All Python functions have a single signature. Some C functions have optional arguments without a default. In the normal case, where no confusion ensues, this is indicated with []s. There is also the additional complication and confusion Multiple lines are used when stuffing the complete signature on one line is more confusing that having all on one line.

For instance, range(start_or_stop, [stop_if_start, step=1], /) is considered more confusing than the two lines (which currently omit the ‘/’). (I believe we once have a single line like this but with shorter and less elucidating names.) I think [step] in stdtypes is an error and the discrepancy should be fixed.

Note: when positional-only was added to Python functions, there was reluctance to add ‘/’ everywhere relevant (such as range). I think this was a mistake as the heuristic rules as to when to add were confusing and ambiguous to some, and the omission is a nuisance. I forgot that start and stop are not legal, as deceptively indicated by the omission.

storchaka (Serhiy Storchaka) June 10, 2025, 9:33am 3

This is an old issue, and there is no urge to do something about it right now. After resolving Add support for multiple signatures · Issue #73536 · python/cpython · GitHub and improving support of multisignatures in Argument Clinic, such style will become more common.

skirpichev (Sergey B Kirpichev) June 10, 2025, 9:53am 4

That’s true. Though, for something like range() such signature will look rather unhelpful: range(*args).

It’s just one example. Other - when meaning of arguments depends on its count, like for range().

In pure-Python world there is the typing.overload. For documentation and introspection you would like rather to show overloaded signatures rather the actual implementation (which may look like func(*args, *kwargs)).

This syntax is not explained in docs. Should we assume readers understand it?

Documentation is not automatically generated with something like the autodoc sphinx extension. We have to manually update one. Why not now?

Which one?