classification
Title: Add a default docstring to Enum subclasses
Type: enhancement Stage: resolved
Components: Versions: Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ethan.furman Nosy List: barry, eli.bendersky, ethan.furman, ncoghlan, python-dev, serhiy.storchaka
Priority: normal Keywords:

Created on 2015-04-09 16:42 by ncoghlan, last changed 2015-04-14 08:03 by serhiy.storchaka. This issue is now closed.

Messages (4)
msg240348 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2015-04-09 16:42
Issue #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?
msg240486 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2015-04-11 16:47
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.
msg240545 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-04-12 06:23
New changeset 684aadcabcc7 by Ethan Furman in branch 'default':
Close issue23900: add default __doc__ to new enumerations that do not specify one.
https://hg.python.org/cpython/rev/684aadcabcc7
msg240856 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-04-14 08:03
May be don't add __doc__ if sys.flags.optimize >= 2?
History
Date User Action Args
2015-04-14 08:03:04serhiy.storchakasetmessages: + msg240856
2015-04-12 06:23:24python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg240545

resolution: fixed
stage: needs patch -> resolved
2015-04-11 16:47:07ethan.furmansetassignee: ethan.furman
messages: + msg240486
2015-04-09 16:42:37ncoghlancreate