Skip to content

Commit

Permalink
[Enum] Remove automatic docstring generation (pythonGH-94188)
Browse files Browse the repository at this point in the history
  • Loading branch information
@dignissimus
dignissimus authored Jun 23, 2022
1 parent 9a95fa9 commit 28a2ccf
Show file tree
Hide file tree
Showing 2 changed files with 4 additions and 267 deletions.
105 changes: 0 additions & 105 deletions Lib/enum.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -536,111 +536,6 @@ def __new__(metacls, cls, bases, classdict, *, boundary=None, _simple=False, **k
# update classdict with any changes made by __init_subclass__
classdict.update(enum_class.__dict__)
#
# create a default docstring if one has not been provided
if enum_class.__doc__ is None:
if not member_names or not list(enum_class):
enum_class.__doc__ = classdict['__doc__'] = _dedent("""\
Create a collection of name/value pairs.
Example enumeration:
>>> class Color(Enum):
... RED = 1
... BLUE = 2
... GREEN = 3
Access them by:
- attribute access::
>>> Color.RED
<Color.RED: 1>
- value lookup:
>>> Color(1)
<Color.RED: 1>
- name lookup:
>>> Color['RED']
<Color.RED: 1>
Enumerations can be iterated over, and know how many members they have:
>>> len(Color)
3
>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]
Methods can be added to enumerations, and members can have their own
attributes -- see the documentation for details.
""")
else:
member = list(enum_class)[0]
enum_length = len(enum_class)
cls_name = enum_class.__name__
if enum_length == 1:
list_line = 'list(%s)' % cls_name
list_repr = '[<%s.%s: %r>]' % (cls_name, member.name, member.value)
elif enum_length == 2:
member2 = list(enum_class)[1]
list_line = 'list(%s)' % cls_name
list_repr = '[<%s.%s: %r>, <%s.%s: %r>]' % (
cls_name, member.name, member.value,
cls_name, member2.name, member2.value,
)
else:
member2 = list(enum_class)[1]
member3 = list(enum_class)[2]
list_line = 'list(%s)%s' % (cls_name, ('','[:3]')[enum_length > 3])
list_repr = '[<%s.%s: %r>, <%s.%s: %r>, <%s.%s: %r>]' % (
cls_name, member.name, member.value,
cls_name, member2.name, member2.value,
cls_name, member3.name, member3.value,
)
enum_class.__doc__ = classdict['__doc__'] = _dedent("""\
A collection of name/value pairs.
Access them by:
- attribute access::
>>> %s.%s
<%s.%s: %r>
- value lookup:
>>> %s(%r)
<%s.%s: %r>
- name lookup:
>>> %s[%r]
<%s.%s: %r>
Enumerations can be iterated over, and know how many members they have:
>>> len(%s)
%r
>>> %s
%s
Methods can be added to enumerations, and members can have their own
attributes -- see the documentation for details.
"""
% (cls_name, member.name,
cls_name, member.name, member.value,
cls_name, member.value,
cls_name, member.name, member.value,
cls_name, member.name,
cls_name, member.name, member.value,
cls_name, enum_length,
list_line, list_repr,
))
#
# double check that repr and friends are not the mixin's or various
# things break (such as pickle)
# however, if the method is defined in the Enum itself, don't replace
Expand Down
166 changes: 4 additions & 162 deletions Lib/test/test_enum.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4054,36 +4054,6 @@ class TestEnumTypeSubclassing(unittest.TestCase):
class Color(enum.Enum)
| Color(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
|\x20\x20
| A collection of name/value pairs.
|\x20\x20
| Access them by:
|\x20\x20
| - attribute access::
|\x20\x20
| >>> Color.CYAN
| <Color.CYAN: 1>
|\x20\x20
| - value lookup:
|\x20\x20
| >>> Color(1)
| <Color.CYAN: 1>
|\x20\x20
| - name lookup:
|\x20\x20
| >>> Color['CYAN']
| <Color.CYAN: 1>
|\x20\x20
| Enumerations can be iterated over, and know how many members they have:
|\x20\x20
| >>> len(Color)
| 3
|\x20\x20
| >>> list(Color)
| [<Color.CYAN: 1>, <Color.MAGENTA: 2>, <Color.YELLOW: 3>]
|\x20\x20
| Methods can be added to enumerations, and members can have their own
| attributes -- see the documentation for details.
|\x20\x20
| Method resolution order:
| Color
| enum.Enum
Expand Down Expand Up @@ -4329,157 +4299,29 @@ def test__all__(self):
def test_doc_1(self):
class Single(Enum):
ONE = 1
self.assertEqual(
Single.__doc__,
dedent("""\
A collection of name/value pairs.
Access them by:
- attribute access::
>>> Single.ONE
<Single.ONE: 1>
- value lookup:
>>> Single(1)
<Single.ONE: 1>
- name lookup:
>>> Single['ONE']
<Single.ONE: 1>
Enumerations can be iterated over, and know how many members they have:
>>> len(Single)
1
>>> list(Single)
[<Single.ONE: 1>]
Methods can be added to enumerations, and members can have their own
attributes -- see the documentation for details.
"""))
self.assertEqual(Single.__doc__, None)

def test_doc_2(self):
class Double(Enum):
ONE = 1
TWO = 2
self.assertEqual(
Double.__doc__,
dedent("""\
A collection of name/value pairs.
Access them by:
- attribute access::
>>> Double.ONE
<Double.ONE: 1>
- value lookup:
>>> Double(1)
<Double.ONE: 1>
- name lookup:
>>> Double['ONE']
<Double.ONE: 1>
Enumerations can be iterated over, and know how many members they have:
>>> len(Double)
2
>>> list(Double)
[<Double.ONE: 1>, <Double.TWO: 2>]
Methods can be added to enumerations, and members can have their own
attributes -- see the documentation for details.
"""))
self.assertEqual(Double.__doc__, None)


def test_doc_1(self):
class Triple(Enum):
ONE = 1
TWO = 2
THREE = 3
self.assertEqual(
Triple.__doc__,
dedent("""\
A collection of name/value pairs.
Access them by:
- attribute access::
>>> Triple.ONE
<Triple.ONE: 1>
- value lookup:
>>> Triple(1)
<Triple.ONE: 1>
- name lookup:
>>> Triple['ONE']
<Triple.ONE: 1>
Enumerations can be iterated over, and know how many members they have:
>>> len(Triple)
3
>>> list(Triple)
[<Triple.ONE: 1>, <Triple.TWO: 2>, <Triple.THREE: 3>]
Methods can be added to enumerations, and members can have their own
attributes -- see the documentation for details.
"""))
self.assertEqual(Triple.__doc__, None)

def test_doc_1(self):
class Quadruple(Enum):
ONE = 1
TWO = 2
THREE = 3
FOUR = 4
self.assertEqual(
Quadruple.__doc__,
dedent("""\
A collection of name/value pairs.
Access them by:
- attribute access::
>>> Quadruple.ONE
<Quadruple.ONE: 1>
- value lookup:
>>> Quadruple(1)
<Quadruple.ONE: 1>
- name lookup:
>>> Quadruple['ONE']
<Quadruple.ONE: 1>
Enumerations can be iterated over, and know how many members they have:
>>> len(Quadruple)
4
>>> list(Quadruple)[:3]
[<Quadruple.ONE: 1>, <Quadruple.TWO: 2>, <Quadruple.THREE: 3>]
Methods can be added to enumerations, and members can have their own
attributes -- see the documentation for details.
"""))
self.assertEqual(Quadruple.__doc__, None)


# These are unordered here on purpose to ensure that declaration order
Expand Down

0 comments on commit 28a2ccf

Please sign in to comment.