Add a default docstring to Enum subclasses

[ncoghlan]

BPO	23900
Nosy	@warsaw, @ncoghlan, @ethanfurman, @serhiy-storchaka

^{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 = 'https://github.com/ethanfurman'
closed_at = <Date 2015-04-12.06:23:24.383>
created_at = <Date 2015-04-09.16:42:37.725>
labels = ['type-feature']
title = 'Add a default docstring to Enum subclasses'
updated_at = <Date 2015-04-14.08:03:04.070>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2015-04-14.08:03:04.070>
actor = 'serhiy.storchaka'
assignee = 'ethan.furman'
closed = True
closed_date = <Date 2015-04-12.06:23:24.383>
closer = 'python-dev'
components = []
creation = <Date 2015-04-09.16:42:37.725>
creator = 'ncoghlan'
dependencies = []
files = []
hgrepos = []
issue_num = 23900
keywords = []
message_count = 4.0
messages = ['240348', '240486', '240545', '240856']
nosy_count = 6.0
nosy_names = ['barry', 'ncoghlan', 'eli.bendersky', 'ethan.furman', 'python-dev', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23900'
versions = ['Python 3.5']

[ncoghlan]

Issue bpo-15582 added docstring inheritance to the inspect module. This means that Enum subclasses without their own docstring now inherit the generic docstring from the base class definition:

>>> import enum, inspect
>>> class MyEnum(enum.Enum):
...   a = 1
... 
>>> inspect.getdoc(MyEnum)
'Generic enumeration.\n\nDerive from this class to define new enumerations.'

Perhaps the metaclass could automatically derive a more suitable docstring if the subclass doesn't set one of its own?

[ethanfurman]

We could do something like:

'An enumeration.'

and perhaps even something like:

'An enumeration based on <int>.'

It's not much, but is better than the obviously wrong generic version.

[python-dev]

New changeset 684aadcabcc7 by Ethan Furman in branch 'default':
Close bpo-23900: add default __doc__ to new enumerations that do not specify one.
https://hg.python.org/cpython/rev/684aadcabcc7

[serhiy-storchaka]

May be don't add __doc__ if sys.flags.optimize >= 2?