allow Python code to determine class help text

[ethanfurman]

BPO	29363
Nosy	@rhettinger, @ncoghlan, @larryhastings, @ethanfurman, @serhiy-storchaka, @1st1, @zhangyangyu

^{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-24.18:06:33.702>
labels = ['type-bug', '3.7', 'expert-argument-clinic']
title = 'allow Python code to determine class help text'
updated_at = <Date 2017-01-24.20:27:11.637>
user = 'https://github.com/ethanfurman'

bugs.python.org fields:

activity = <Date 2017-01-24.20:27:11.637>
actor = 'ethan.furman'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Argument Clinic']
creation = <Date 2017-01-24.18:06:33.702>
creator = 'ethan.furman'
dependencies = []
files = []
hgrepos = []
issue_num = 29363
keywords = []
message_count = 6.0
messages = ['286199', '286200', '286202', '286210', '286211', '286214']
nosy_count = 7.0
nosy_names = ['rhettinger', 'ncoghlan', 'larry', 'ethan.furman', 'serhiy.storchaka', 'yselivanov', 'xiang.zhang']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue29363'
versions = ['Python 3.7']

[ethanfurman]

From bpo-29338, msg286139:
--------------------------
It is easy to fix the [pydoc] test by adding missed lines. But I'm not sure that output the (correct) signature of enum classes makes the help better.

    Color(value, names=None, *, module=None, qualname=None, type=None, start=1)

Ethan, what are your thoughts?

[ethanfurman]

That that is very unhelpful help text. :(

Better would be:

    Color(value)

So how do we allow Python code to determine the help text?

[serhiy-storchaka]

This line is came from the signature of the __call__ method.

>>> import enum, inspect
>>> class A(enum.Enum):
...    x = 1
... 
>>> inspect.signature(A)
<Signature (value, names=None, *, module=None, qualname=None, type=None, start=1)>
>>> inspect.signature(A.__call__)
<Signature (value, names=None, *, module=None, qualname=None, type=None, start=1)>
>>> inspect.signature(enum.EnumMeta.__call__)
<Signature (cls, value, names=None, *, module=None, qualname=None, type=None, start=1)>

But calling A with optional arguments doesn't work.

>>> A(1)
<A.x: 1>
>>> A('B', {'y': 2})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/serhiy/py/cpython/Lib/enum.py", line 293, in __call__
    return cls._create_(value, names, module=module, qualname=qualname, type=type, start=start)
  File "/home/serhiy/py/cpython/Lib/enum.py", line 378, in _create_
    _, first_enum = cls._get_mixins_(bases)
  File "/home/serhiy/py/cpython/Lib/enum.py", line 436, in _get_mixins_
    raise TypeError("Cannot extend enumerations")
TypeError: Cannot extend enumerations

[ethanfurman]

There are actually two signatures:

EnumCls(value) --> return member with value value

EnumCls(name, members, module, qualname, type, start) --> create new Enum

An example of the first:

class A(Enum):
    x = 1
A(1) --> <A.x: 1>

an example of the second:

class A(Enum):
    pass
B = A('B', {'y':2})
B(2) --> <B.y: 2>

The reason for the error you see is that Enums with members cannot be further subclassed.

[serhiy-storchaka]

I'm wondering is it worth to set different __call__ methods for enum types with and without members?

[ethanfurman]

Probably not because an enum class' __call__ comes from the type EnumMeta -- so having two different __call__ methods would mean two different metaclasses, and I'm pretty sure I don't want to go there. ;)

There is a __doc__ defined for the __call__ method, though -- is there a reason inspect isn't using that?

[serhiy-storchaka]

Enum.__signature__ was added in #100039. So the signature of enum classes is now (*values). It can be improved further by showing the signature of actual __new__ or __init__.