Add support for multiple signatures

[serhiy-storchaka]

BPO	29350
Nosy	@rhettinger, @larryhastings, @serhiy-storchaka, @1st1

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-01-23.10:26:05.098>
labels = ['3.7', 'type-feature', 'library']
title = 'Add support of multiple signatures'
updated_at = <Date 2017-01-23.17:51:01.471>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2017-01-23.17:51:01.471>
actor = 'serhiy.storchaka'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2017-01-23.10:26:05.098>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 29350
keywords = []
message_count = 3.0
messages = ['286068', '286101', '286104']
nosy_count = 4.0
nosy_names = ['rhettinger', 'larry', 'serhiy.storchaka', 'yselivanov']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue29350'
versions = ['Python 3.7']

Linked PRs

• gh-73536: Add support for multi-signatures #117671

[serhiy-storchaka]

Some functions can be described by the single signature. See examples in msg285647. Selected examples:

 dict.pop(key)
 dict.pop(key, default)

 type(obj)
 type(name, bases, mapping)

 range(stop)
 range(start, stop, step=1)

 min(iterable, *, key=identity)
 min(iterable, *, default, key=identity)
 min(*args, key=identity)

I think the only way to resolve this problem is to add the support of multiple signatures in inspect, pydoc, Argument Clinic, etc.

[1st1]

Signature object provides methods like .bind(), which will be hard to define if a function has many signatures. Also, inspect.signature currently returns one Signature object, that shouldn't be changed.

Wouldn't it be easier instead of this:
type(obj)
type(name, bases, mapping)

do this:
type(obj_or_name, bases=None, mapping=None)

And explain what really is going on in the docstring?

[serhiy-storchaka]

It can be do, but I don't think it is worth. Making bases and mapping optional arguments does not make much sense to me. And there is no a value that can be used as a default value for the second parameter in dict.pop().

[serhiy-storchaka]

#117671 is a draft implementation. It adds MultiSignature, which is a subclass of Signature, but supports iteration and has length. inspect.signatures() always returns a MultiSignature, even if it contains a single signature. inspect.signature() can also return a MultiSignature. pydoc and all other stdlib code was updated to support multisignatures. All builtin functions and methods of builtin classes except type() and super() has now signatures, i.e. are supported by inspect.signature() and inspect.signatures().

>>> import inspect
>>> inspect.signature(range)
<MultiSignature (stop, /)|(start, stop, step=1, /)>
>>> print(inspect.signature(range))
(stop, /)
(start, stop, step=1, /)
>>> 
>>> inspect.signature(dict.pop)
<MultiSignature (self, key, /)|(self, key, default, /)>
>>> print(inspect.signature(dict.pop))
(self, key, /)
(self, key, default, /)
>>> 
>>> inspect.signature(min)
<MultiSignature (iterable, /, *, key=None)|(iterable, /, *, default, key=None)|(arg1, arg2, /, *args, key=None)>
>>> print(inspect.signature(min))
(iterable, /, *, key=None)
(iterable, /, *, default, key=None)
(arg1, arg2, /, *args, key=None)

MultiSignature's attribute parameters is a union of all parameters in all subsignatures, and return_annotation is a union of return annotations of subsignatures. bind() and bind_partial() are supported, but replace() does not.

Future features:

• Union and itersection of Signature and MultiSignature objects. An intersection will be useful to find the common signature for __new__ and __init__ methods (one of them can contain *args, **kwargs).
• Partial signature. Like bind_partial(), but instead of a BoundArguments object it should return a new (multi-)signature object after binding arguments. It will help to get the signature of bound and class methods, partial and partialmethod objects.
• Generate multi-signatures in Argument Clinic if default values are not representable.
• Generate multi-signatures in Argument Clinic for optional groups.
• Support multi-signatures in functools.singledispatch and typing.override().

[encukou]

IMO, this should be a PEP.
It's an exciting improvement, and it has a wide reach -- areas like typing, dynamic dispatch, or documentation will all be affected.