Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[3.11] gh-93976: [Enum] Remove automatic docstring generation (GH-94188) #94191

Merged
merged 1 commit into from
Jun 23, 2022
Merged

[3.11] gh-93976: [Enum] Remove automatic docstring generation (GH-94188) #94191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 0 additions & 105 deletions Lib/enum.py
View file
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4073,36 +4073,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 @@ -4348,157 +4318,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