Revert "bpo-40066: [Enum] update str() and format() output (GH-30582)" (GH-30632)

This reverts commit acf7403f9baea3ae1119fc6b4a3298522188bf96.

3 files changed, 240 insertions, 301 deletions

diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
index fa0e228..6c09b99 100644
--- a/Doc/howto/enum.rst
+++ b/Doc/howto/enum.rst
@@ -2,10 +2,15 @@
 Enum HOWTO
 ==========
 
+:Author: Ethan Furman <ethan at stoneleaf dot us>
+
 .. _enum-basic-tutorial:
 
 .. currentmodule:: enum
 
+Basic Enum Tutorial
+-------------------
+
 An :class:`Enum` is a set of symbolic names bound to unique values.  They are
 similar to global variables, but they offer a more useful :func:`repr()`,
 grouping, type-safety, and a few other features.
@@ -23,14 +28,6 @@ selection of values.  For example, the days of the week::
     ...     SATURDAY = 6
     ...     SUNDAY = 7
 
- Or perhaps the RGB primary colors::
-
-    >>> from enum import Enum
-    >>> class Color(Enum):
-    ...     RED = 1
-    ...     GREEN = 2
-    ...     BLUE = 3
-
 As you can see, creating an :class:`Enum` is as simple as writing a class that
 inherits from :class:`Enum` itself.
 
@@ -44,14 +41,13 @@ important, but either way that value can be used to get the corresponding
 member::
 
     >>> Weekday(3)
-    <Weekday.WEDNESDAY: 3>
+    Weekday.WEDNESDAY
 
-As you can see, the ``repr()`` of a member shows the enum name, the member name,
-and the value.  The ``str()`` of a member shows only the enum name and member
-name::
+As you can see, the ``repr()`` of a member shows the enum name and the
+member name.  The ``str()`` on a member shows only its name::
 
     >>> print(Weekday.THURSDAY)
-    Weekday.THURSDAY
+    THURSDAY
 
 The *type* of an enumeration member is the enum it belongs to::
 
@@ -101,8 +97,8 @@ The complete :class:`Weekday` enum now looks like this::
 Now we can find out what today is!  Observe::
 
     >>> from datetime import date
-    >>> Weekday.from_date(date.today())     # doctest: +SKIP
-    <Weekday.TUESDAY: 2>
+    >>> Weekday.from_date(date.today())
+    Weekday.TUESDAY
 
 Of course, if you're reading this on some other day, you'll see that day instead.
 
@@ -128,21 +124,21 @@ Just like the original :class:`Weekday` enum above, we can have a single selecti
 
     >>> first_week_day = Weekday.MONDAY
     >>> first_week_day
-    <Weekday.MONDAY: 1>
+    Weekday.MONDAY
 
 But :class:`Flag` also allows us to combine several members into a single
 variable::
 
     >>> weekend = Weekday.SATURDAY | Weekday.SUNDAY
     >>> weekend
-    <Weekday.SATURDAY|SUNDAY: 96>
+    Weekday.SATURDAY|Weekday.SUNDAY
 
 You can even iterate over a :class:`Flag` variable::
 
     >>> for day in weekend:
     ...     print(day)
-    Weekday.SATURDAY
-    Weekday.SUNDAY
+    SATURDAY
+    SUNDAY
 
 Okay, let's get some chores set up::
 
@@ -177,7 +173,6 @@ yourself some work and use :func:`auto()` for the values::
 
 .. _enum-advanced-tutorial:
 
-
 Programmatic access to enumeration members and their attributes
 ---------------------------------------------------------------
 
@@ -186,16 +181,16 @@ situations where ``Color.RED`` won't do because the exact color is not known
 at program-writing time).  ``Enum`` allows such access::
 
     >>> Color(1)
-    <Color.RED: 1>
+    Color.RED
     >>> Color(3)
-    <Color.BLUE: 3>
+    Color.BLUE
 
 If you want to access enum members by *name*, use item access::
 
     >>> Color['RED']
-    <Color.RED: 1>
+    Color.RED
     >>> Color['GREEN']
-    <Color.GREEN: 2>
+    Color.GREEN
 
 If you have an enum member and need its :attr:`name` or :attr:`value`::
 
@@ -217,7 +212,7 @@ Having two enum members with the same name is invalid::
     ...
     Traceback (most recent call last):
     ...
-    TypeError: 'SQUARE' already defined as 2
+    TypeError: 'SQUARE' already defined as: 2
 
 However, an enum member can have other names associated with it.  Given two
 entries ``A`` and ``B`` with the same value (and ``A`` defined first), ``B``
@@ -232,11 +227,11 @@ By-name lookup of ``B`` will also return the member ``A``::
     ...     ALIAS_FOR_SQUARE = 2
     ...
     >>> Shape.SQUARE
-    <Shape.SQUARE: 2>
+    Shape.SQUARE
     >>> Shape.ALIAS_FOR_SQUARE
-    <Shape.SQUARE: 2>
+    Shape.SQUARE
     >>> Shape(2)
-    <Shape.SQUARE: 2>
+    Shape.SQUARE
 
 .. note::
 
@@ -304,7 +299,7 @@ Iteration
 Iterating over the members of an enum does not provide the aliases::
 
     >>> list(Shape)
-    [<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
+    [Shape.SQUARE, Shape.DIAMOND, Shape.CIRCLE]
 
 The special attribute ``__members__`` is a read-only ordered mapping of names
 to members.  It includes all names defined in the enumeration, including the
@@ -313,10 +308,10 @@ aliases::
     >>> for name, member in Shape.__members__.items():
     ...     name, member
     ...
-    ('SQUARE', <Shape.SQUARE: 2>)
-    ('DIAMOND', <Shape.DIAMOND: 1>)
-    ('CIRCLE', <Shape.CIRCLE: 3>)
-    ('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)
+    ('SQUARE', Shape.SQUARE)
+    ('DIAMOND', Shape.DIAMOND)
+    ('CIRCLE', Shape.CIRCLE)
+    ('ALIAS_FOR_SQUARE', Shape.SQUARE)
 
 The ``__members__`` attribute can be used for detailed programmatic access to
 the enumeration members.  For example, finding all the aliases::
@@ -365,8 +360,8 @@ below)::
 Allowed members and attributes of enumerations
 ----------------------------------------------
 
-Most of the examples above use integers for enumeration values.  Using integers
-is short and handy (and provided by default by the `Functional API`_), but not
+Most of the examples above use integers for enumeration values.  Using integers is
+short and handy (and provided by default by the `Functional API`_), but not
 strictly enforced.  In the vast majority of use-cases, one doesn't care what
 the actual value of an enumeration is.  But if the value *is* important,
 enumerations can have arbitrary values.
@@ -394,7 +389,7 @@ usual.  If we have this enumeration::
 Then::
 
     >>> Mood.favorite_mood()
-    <Mood.HAPPY: 3>
+    Mood.HAPPY
     >>> Mood.HAPPY.describe()
     ('HAPPY', 3)
     >>> str(Mood.FUNKY)
@@ -430,7 +425,7 @@ any members.  So this is forbidden::
     ...
     Traceback (most recent call last):
     ...
-    TypeError: <enum 'MoreColor'> cannot extend <enum 'Color'>
+    TypeError: MoreColor: cannot extend enumeration 'Color'
 
 But this is allowed::
 
@@ -481,9 +476,11 @@ The :class:`Enum` class is callable, providing the following functional API::
     >>> Animal
     <enum 'Animal'>
     >>> Animal.ANT
-    <Animal.ANT: 1>
+    Animal.ANT
+    >>> Animal.ANT.value
+    1
     >>> list(Animal)
-    [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
+    [Animal.ANT, Animal.BEE, Animal.CAT, Animal.DOG]
 
 The semantics of this API resemble :class:`~collections.namedtuple`. The first
 argument of the call to :class:`Enum` is the name of the enumeration.
@@ -628,7 +625,16 @@ StrEnum
 The second variation of :class:`Enum` that is provided is also a subclass of
 :class:`str`.  Members of a :class:`StrEnum` can be compared to strings;
 by extension, string enumerations of different types can also be compared
-to each other.
+to each other.  :class:`StrEnum` exists to help avoid the problem of getting
+an incorrect member::
+
+    >>> from enum import StrEnum
+    >>> class Directions(StrEnum):
+    ...     NORTH = 'north',    # notice the trailing comma
+    ...     SOUTH = 'south'
+
+Before :class:`StrEnum`, ``Directions.NORTH`` would have been the :class:`tuple`
+``('north',)``.
 
 .. versionadded:: 3.11
 
@@ -639,8 +645,9 @@ IntFlag
 The next variation of :class:`Enum` provided, :class:`IntFlag`, is also based
 on :class:`int`.  The difference being :class:`IntFlag` members can be combined
 using the bitwise operators (&, \|, ^, ~) and the result is still an
-:class:`IntFlag` member, if possible.  Like :class:`IntEnum`, :class:`IntFlag`
-members are also integers and can be used wherever an :class:`int` is used.
+:class:`IntFlag` member, if possible.  However, as the name implies, :class:`IntFlag`
+members also subclass :class:`int` and can be used wherever an :class:`int` is
+used.
 
 .. note::
 
@@ -663,7 +670,7 @@ Sample :class:`IntFlag` class::
     ...     X = 1
     ...
     >>> Perm.R | Perm.W
-    <Perm.R|W: 6>
+    Perm.R|Perm.W
     >>> Perm.R + Perm.W
     6
     >>> RW = Perm.R | Perm.W
@@ -678,11 +685,11 @@ It is also possible to name the combinations::
     ...     X = 1
     ...     RWX = 7
     >>> Perm.RWX
-    <Perm.RWX: 7>
+    Perm.RWX
     >>> ~Perm.RWX
-    <Perm: 0>
+    Perm(0)
     >>> Perm(7)
-    <Perm.RWX: 7>
+    Perm.RWX
 
 .. note::
 
@@ -695,7 +702,7 @@ Another important difference between :class:`IntFlag` and :class:`Enum` is that
 if no flags are set (the value is 0), its boolean evaluation is :data:`False`::
 
     >>> Perm.R & Perm.X
-    <Perm: 0>
+    Perm(0)
     >>> bool(Perm.R & Perm.X)
     False
 
@@ -703,7 +710,7 @@ Because :class:`IntFlag` members are also subclasses of :class:`int` they can
 be combined with them (but may lose :class:`IntFlag` membership::
 
     >>> Perm.X | 4
-    <Perm.R|X: 5>
+    Perm.R|Perm.X
 
     >>> Perm.X | 8
     9
@@ -719,7 +726,7 @@ be combined with them (but may lose :class:`IntFlag` membership::
 :class:`IntFlag` members can also be iterated over::
 
     >>> list(RW)
-    [<Perm.R: 4>, <Perm.W: 2>]
+    [Perm.R, Perm.W]
 
 .. versionadded:: 3.11
 
@@ -746,7 +753,7 @@ flags being set, the boolean evaluation is :data:`False`::
     ...     GREEN = auto()
     ...
     >>> Color.RED & Color.GREEN
-    <Color: 0>
+    Color(0)
     >>> bool(Color.RED & Color.GREEN)
     False
 
@@ -760,7 +767,7 @@ while combinations of flags won't::
     ...     WHITE = RED | BLUE | GREEN
     ...
     >>> Color.WHITE
-    <Color.WHITE: 7>
+    Color.WHITE
 
 Giving a name to the "no flags set" condition does not change its boolean
 value::
@@ -772,7 +779,7 @@ value::
     ...     GREEN = auto()
     ...
     >>> Color.BLACK
-    <Color.BLACK: 0>
+    Color.BLACK
     >>> bool(Color.BLACK)
     False
 
@@ -780,7 +787,7 @@ value::
 
     >>> purple = Color.RED | Color.BLUE
     >>> list(purple)
-    [<Color.RED: 1>, <Color.BLUE: 2>]
+    [Color.RED, Color.BLUE]
 
 .. versionadded:: 3.11
 
@@ -805,16 +812,16 @@ simple to implement independently::
         pass
 
 This demonstrates how similar derived enumerations can be defined; for example
-a :class:`FloatEnum` that mixes in :class:`float` instead of :class:`int`.
+a :class:`StrEnum` that mixes in :class:`str` instead of :class:`int`.
 
 Some rules:
 
 1. When subclassing :class:`Enum`, mix-in types must appear before
    :class:`Enum` itself in the sequence of bases, as in the :class:`IntEnum`
    example above.
-2. Mix-in types must be subclassable. For example, :class:`bool` and
-   :class:`range` are not subclassable and will throw an error during Enum
-   creation if used as the mix-in type.
+2. Mix-in types must be subclassable. For example,
+   :class:`bool` and :class:`range` are not subclassable
+   and will throw an error during Enum creation if used as the mix-in type.
 3. While :class:`Enum` can have members of any type, once you mix in an
    additional type, all the members must have values of that type, e.g.
    :class:`int` above.  This restriction does not apply to mix-ins which only
@@ -822,18 +829,15 @@ Some rules:
 4. When another data type is mixed in, the :attr:`value` attribute is *not the
    same* as the enum member itself, although it is equivalent and will compare
    equal.
-5. %-style formatting:  ``%s`` and ``%r`` call the :class:`Enum` class's
+5. %-style formatting:  `%s` and `%r` call the :class:`Enum` class's
    :meth:`__str__` and :meth:`__repr__` respectively; other codes (such as
-   ``%i`` or ``%h`` for IntEnum) treat the enum member as its mixed-in type.
+   `%i` or `%h` for IntEnum) treat the enum member as its mixed-in type.
 6. :ref:`Formatted string literals <f-strings>`, :meth:`str.format`,
-   and :func:`format` will use the enum's :meth:`__str__` method.
-
-.. note::
-
-   Because :class:`IntEnum`, :class:`IntFlag`, and :class:`StrEnum` are
-   designed to be drop-in replacements for existing constants, their
-   :meth:`__str__` method has been reset to their data types
-   :meth:`__str__` method.
+   and :func:`format` will use the mixed-in type's :meth:`__format__`
+   unless :meth:`__str__` or :meth:`__format__` is overridden in the subclass,
+   in which case the overridden methods or :class:`Enum` methods will be used.
+   Use the !s and !r format codes to force usage of the :class:`Enum` class's
+   :meth:`__str__` and :meth:`__repr__` methods.
 
 When to use :meth:`__new__` vs. :meth:`__init__`
 ------------------------------------------------
@@ -862,10 +866,10 @@ want one of them to be the value::
     ...
 
     >>> print(Coordinate['PY'])
-    Coordinate.PY
+    PY
 
     >>> print(Coordinate(3))
-    Coordinate.VY
+    VY
 
 
 Finer Points
@@ -923,8 +927,8 @@ and raise an error if the two do not match::
     Traceback (most recent call last):
     ...
     TypeError: member order does not match _order_:
-      ['RED', 'BLUE', 'GREEN']
-      ['RED', 'GREEN', 'BLUE']
+    ['RED', 'BLUE', 'GREEN']
+    ['RED', 'GREEN', 'BLUE']
 
 .. note::
 
@@ -945,36 +949,35 @@ but remain normal attributes.
 """"""""""""""""""""
 
 Enum members are instances of their enum class, and are normally accessed as
-``EnumClass.member``.  In Python versions ``3.5`` to ``3.10`` you could access
-members from other members -- this practice was discouraged, and in ``3.11``
-:class:`Enum` returns to not allowing it::
+``EnumClass.member``.  In Python versions ``3.5`` to ``3.9`` you could access
+members from other members -- this practice was discouraged, and in ``3.12``
+:class:`Enum` will return to not allowing it, while in ``3.10`` and ``3.11``
+it will raise a :exc:`DeprecationWarning`::
 
     >>> class FieldTypes(Enum):
     ...     name = 0
     ...     value = 1
     ...     size = 2
     ...
-    >>> FieldTypes.value.size
-    Traceback (most recent call last):
-    ...
-    AttributeError: <enum 'FieldTypes'> member has no attribute 'size'
-
+    >>> FieldTypes.value.size       # doctest: +SKIP
+    DeprecationWarning: accessing one member from another is not supported,
+      and will be disabled in 3.12
+    <FieldTypes.size: 2>
 
 .. versionchanged:: 3.5
-.. versionchanged:: 3.11
 
 
 Creating members that are mixed with other data types
 """""""""""""""""""""""""""""""""""""""""""""""""""""
 
 When subclassing other data types, such as :class:`int` or :class:`str`, with
-an :class:`Enum`, all values after the ``=`` are passed to that data type's
+an :class:`Enum`, all values after the `=` are passed to that data type's
 constructor.  For example::
 
-    >>> class MyEnum(IntEnum):      # help(int) -> int(x, base=10) -> integer
-    ...     example = '11', 16      # so x='11' and base=16
-    ...
-    >>> MyEnum.example.value        # and hex(11) is...
+    >>> class MyEnum(IntEnum):
+    ...     example = '11', 16      # '11' will be interpreted as a hexadecimal
+    ...                             # number
+    >>> MyEnum.example.value
     17
 
 
@@ -997,12 +1000,13 @@ Plain :class:`Enum` classes always evaluate as :data:`True`.
 """""""""""""""""""""""""""""
 
 If you give your enum subclass extra methods, like the `Planet`_
-class below, those methods will show up in a :func:`dir` of the member,
-but not of the class::
+class below, those methods will show up in a :func:`dir` of the member and the
+class. Attributes defined in an :func:`__init__` method will only show up in a
+:func:`dir` of the member::
 
-    >>> dir(Planet)                         # doctest: +SKIP
-    ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
-    >>> dir(Planet.EARTH)                   # doctest: +SKIP
+    >>> dir(Planet)
+    ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__init__', '__members__', '__module__', 'surface_gravity']
+    >>> dir(Planet.EARTH)
     ['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', 'surface_gravity', 'value']
 
 
@@ -1021,10 +1025,19 @@ are comprised of a single bit::
     ...     CYAN = GREEN | BLUE
     ...
     >>> Color(3)  # named combination
-    <Color.YELLOW: 3>
+    Color.YELLOW
     >>> Color(7)      # not named combination
-    <Color.RED|GREEN|BLUE: 7>
+    Color.RED|Color.GREEN|Color.BLUE
 
+``StrEnum`` and :meth:`str.__str__`
+"""""""""""""""""""""""""""""""""""
+
+An important difference between :class:`StrEnum` and other Enums is the
+:meth:`__str__` method; because :class:`StrEnum` members are strings, some
+parts of Python will read the string data directly, while others will call
+:meth:`str()`. To make those two operations have the same result,
+:meth:`StrEnum.__str__` will be the same as :meth:`str.__str__` so that
+``str(StrEnum.member) == StrEnum.member`` is true.
 
 ``Flag`` and ``IntFlag`` minutia
 """"""""""""""""""""""""""""""""
@@ -1047,16 +1060,16 @@ the following are true:
 - only canonical flags are returned during iteration::
 
     >>> list(Color.WHITE)
-    [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
+    [Color.RED, Color.GREEN, Color.BLUE]
 
 - negating a flag or flag set returns a new flag/flag set with the
   corresponding positive integer value::
 
     >>> Color.BLUE
-    <Color.BLUE: 4>
+    Color.BLUE
 
     >>> ~Color.BLUE
-    <Color.RED|GREEN: 3>
+    Color.RED|Color.GREEN
 
 - names of pseudo-flags are constructed from their members' names::
 
@@ -1066,29 +1079,25 @@ the following are true:
 - multi-bit flags, aka aliases, can be returned from operations::
 
     >>> Color.RED | Color.BLUE
-    <Color.PURPLE: 5>
+    Color.PURPLE
 
     >>> Color(7)  # or Color(-1)
-    <Color.WHITE: 7>
+    Color.WHITE
 
     >>> Color(0)
-    <Color.BLACK: 0>
+    Color.BLACK
 
-- membership / containment checking: zero-valued flags are always considered
-  to be contained::
+- membership / containment checking has changed slightly -- zero-valued flags
+  are never considered to be contained::
 
     >>> Color.BLACK in Color.WHITE
-    True
+    False
 
-  otherwise, only if all bits of one flag are in the other flag will True
-  be returned::
+  otherwise, if all bits of one flag are in the other flag, True is returned::
 
     >>> Color.PURPLE in Color.WHITE
     True
 
-    >>> Color.GREEN in Color.PURPLE
-    False
-
 There is a new boundary mechanism that controls how out-of-range / invalid
 bits are handled: ``STRICT``, ``CONFORM``, ``EJECT``, and ``KEEP``:
 
@@ -1172,7 +1181,7 @@ Using :class:`auto` would look like::
     ...     GREEN = auto()
     ...
     >>> Color.GREEN
-    <Color.GREEN: 3>
+    <Color.GREEN>
 
 
 Using :class:`object`
@@ -1185,24 +1194,10 @@ Using :class:`object` would look like::
     ...     GREEN = object()
     ...     BLUE = object()
     ...
-    >>> Color.GREEN                         # doctest: +SKIP
-    <Color.GREEN: <object object at 0x...>>
-
-This is also a good example of why you might want to write your own
-:meth:`__repr__`::
-
-    >>> class Color(Enum):
-    ...     RED = object()
-    ...     GREEN = object()
-    ...     BLUE = object()
-    ...     def __repr__(self):
-    ...         return "<%s.%s>" % (self.__class__.__name__, self._name_)
-    ...
     >>> Color.GREEN
     <Color.GREEN>
 
 
-
 Using a descriptive string
 """"""""""""""""""""""""""
 
@@ -1214,7 +1209,9 @@ Using a string as the value would look like::
     ...     BLUE = 'too fast!'
     ...
     >>> Color.GREEN
-    <Color.GREEN: 'go'>
+    <Color.GREEN>
+    >>> Color.GREEN.value
+    'go'
 
 
 Using a custom :meth:`__new__`
@@ -1235,7 +1232,9 @@ Using an auto-numbering :meth:`__new__` would look like::
     ...     BLUE = ()
     ...
     >>> Color.GREEN
-    <Color.GREEN: 2>
+    <Color.GREEN>
+    >>> Color.GREEN.value
+    2
 
 To make a more general purpose ``AutoNumber``, add ``*args`` to the signature::
 
@@ -1258,7 +1257,7 @@ to handle any extra arguments::
     ...     BLEACHED_CORAL = () # New color, no Pantone code yet!
     ...
     >>> Swatch.SEA_GREEN
-    <Swatch.SEA_GREEN: 2>
+    <Swatch.SEA_GREEN>
     >>> Swatch.SEA_GREEN.pantone
     '1246'
     >>> Swatch.BLEACHED_CORAL.pantone
@@ -1385,9 +1384,30 @@ An example to show the :attr:`_ignore_` attribute in use::
     ...         Period['day_%d' % i] = i
     ...
     >>> list(Period)[:2]
-    [<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
+    [Period.day_0, Period.day_1]
     >>> list(Period)[-2:]
-    [<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]
+    [Period.day_365, Period.day_366]
+
+
+Conforming input to Flag
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To create a :class:`Flag` enum that is more resilient to out-of-bounds results
+from mathematical operations, you can use the :attr:`FlagBoundary.CONFORM`
+setting::
+
+    >>> from enum import Flag, CONFORM, auto
+    >>> class Weekday(Flag, boundary=CONFORM):
+    ...     MONDAY = auto()
+    ...     TUESDAY = auto()
+    ...     WEDNESDAY = auto()
+    ...     THURSDAY = auto()
+    ...     FRIDAY = auto()
+    ...     SATURDAY = auto()
+    ...     SUNDAY = auto()
+    >>> today = Weekday.TUESDAY
+    >>> Weekday(today + 22)  # what day is three weeks from tomorrow?
+    >>> Weekday.WEDNESDAY
 
 
 .. _enumtype-examples:
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 906c60b..8bb19dc 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -31,7 +31,7 @@ An enumeration:
 * uses *call* syntax to return members by value
 * uses *index* syntax to return members by name
 
-Enumerations are created either by using :keyword:`class` syntax, or by
+Enumerations are created either by using the :keyword:`class` syntax, or by
 using function-call syntax::
 
    >>> from enum import Enum
@@ -45,7 +45,7 @@ using function-call syntax::
    >>> # functional syntax
    >>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE'])
 
-Even though we can use :keyword:`class` syntax to create Enums, Enums
+Even though we can use the :keyword:`class` syntax to create Enums, Enums
 are not normal Python classes.  See
 :ref:`How are Enums different? <enum-class-differences>` for more details.
 
@@ -53,7 +53,7 @@ are not normal Python classes.  See
 
    - The class :class:`Color` is an *enumeration* (or *enum*)
    - The attributes :attr:`Color.RED`, :attr:`Color.GREEN`, etc., are
-     *enumeration members* (or *members*) and are functionally constants.
+     *enumeration members* (or *enum members*) and are functionally constants.
    - The enum members have *names* and *values* (the name of
      :attr:`Color.RED` is ``RED``, the value of :attr:`Color.BLUE` is
      ``3``, etc.)
@@ -110,10 +110,15 @@ Module Contents
       :class:`StrEnum` defaults to the lower-cased version of the member name,
       while other Enums default to 1 and increase from there.
 
-   :func:`property`
+   :func:`global_enum`
+
+      :class:`Enum` class decorator to apply the appropriate global `__repr__`,
+      and export its members into the global name space.
+
+   :func:`.property`
 
       Allows :class:`Enum` members to have attributes without conflicting with
-      member names.
+      other members' names.
 
    :func:`unique`
 
@@ -126,7 +131,7 @@ Module Contents
 
 
 .. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
-.. versionadded:: 3.11  ``StrEnum``, ``EnumCheck``, ``FlagBoundary``, ``property``
+.. versionadded:: 3.11  ``StrEnum``, ``EnumCheck``, ``FlagBoundary``
 
 ---------------
 
@@ -140,11 +145,6 @@ Data Types
    to subclass *EnumType* -- see :ref:`Subclassing EnumType <enumtype-examples>`
    for details.
 
-   *EnumType* is responsible for setting the correct :meth:`__repr__`,
-   :meth:`__str__`, :meth:`__format__`, and :meth:`__reduce__` methods on the
-   final *enum*, as well as creating the enum members, properly handling
-   duplicates, providing iteration over the enum class, etc.
-
    .. method:: EnumType.__contains__(cls, member)
 
       Returns ``True`` if member belongs to the ``cls``::
@@ -162,31 +162,32 @@ Data Types
    .. method:: EnumType.__dir__(cls)
 
       Returns ``['__class__', '__doc__', '__members__', '__module__']`` and the
-      names of the members in *cls*::
+      names of the members in ``cls``. User-defined methods and methods from
+      mixin classes will also be included::
 
         >>> dir(Color)
-        ['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']
+        ['BLUE', 'GREEN', 'RED', '__class__', '__doc__', '__members__', '__module__']
 
    .. method:: EnumType.__getattr__(cls, name)
 
       Returns the Enum member in *cls* matching *name*, or raises an :exc:`AttributeError`::
 
         >>> Color.GREEN
-        <Color.GREEN: 2>
+        Color.GREEN
 
    .. method:: EnumType.__getitem__(cls, name)
 
-      Returns the Enum member in *cls* matching *name*, or raises an :exc:`KeyError`::
+      Returns the Enum member in *cls* matching *name*, or raises a :exc:`KeyError`::
 
         >>> Color['BLUE']
-        <Color.BLUE: 3>
+        Color.BLUE
 
    .. method:: EnumType.__iter__(cls)
 
       Returns each member in *cls* in definition order::
 
         >>> list(Color)
-        [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]
+        [Color.RED, Color.GREEN, Color.BLUE]
 
    .. method:: EnumType.__len__(cls)
 
@@ -200,7 +201,7 @@ Data Types
       Returns each member in *cls* in reverse definition order::
 
         >>> list(reversed(Color))
-        [<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]
+        [Color.BLUE, Color.GREEN, Color.RED]
 
 
 .. class:: Enum
@@ -231,7 +232,7 @@ Data Types
    .. attribute:: Enum._ignore_
 
       ``_ignore_`` is only used during creation and is removed from the
-      enumeration once creation is complete.
+      enumeration once that is complete.
 
       ``_ignore_`` is a list of names that will not become members, and whose
       names will also be removed from the completed enumeration.  See
@@ -260,7 +261,7 @@ Data Types
    .. method:: Enum.__dir__(self)
 
       Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
-      any public methods defined on *self.__class__*::
+      any public methods defined on ``self.__class__`` or a mixin class::
 
          >>> from datetime import date
          >>> class Weekday(Enum):
@@ -275,7 +276,7 @@ Data Types
          ...     def today(cls):
          ...         print('today is %s' % cls(date.today().isoweekday()).name)
          >>> dir(Weekday.SATURDAY)
-         ['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']
+         ['__class__', '__doc__', '__module__', 'name', 'today', 'value']
 
    .. method:: Enum._generate_next_value_(name, start, count, last_values)
 
@@ -297,11 +298,6 @@ Data Types
          >>> PowersOfThree.SECOND.value
          6
 
-   .. method:: Enum.__init_subclass__(cls, \**kwds)
-
-      A *classmethod* that is used to further configure subsequent subclasses.
-      By default, does nothing.
-
    .. method:: Enum._missing_(cls, value)
 
       A *classmethod* for looking up values not found in *cls*.  By default it
@@ -321,55 +317,42 @@ Data Types
          >>> Build.DEBUG.value
          'debug'
          >>> Build('deBUG')
-         <Build.DEBUG: 'debug'>
+         Build.DEBUG
 
    .. method:: Enum.__repr__(self)
 
       Returns the string used for *repr()* calls.  By default, returns the
-      *Enum* name, member name, and value, but can be overridden::
+      *Enum* name and the member name, but can be overridden::
 
-         >>> class OtherStyle(Enum):
-         ...     ALTERNATE = auto()
-         ...     OTHER = auto()
-         ...     SOMETHING_ELSE = auto()
+         >>> class OldStyle(Enum):
+         ...     RETRO = auto()
+         ...     OLD_SCHOOl = auto()
+         ...     YESTERYEAR = auto()
          ...     def __repr__(self):
          ...         cls_name = self.__class__.__name__
-         ...         return f'{cls_name}.{self.name}'
-         >>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
-         (OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')
+         ...         return f'<{cls_name}.{self.name}: {self.value}>'
+         >>> OldStyle.RETRO
+         <OldStyle.RETRO: 1>
 
    .. method:: Enum.__str__(self)
 
       Returns the string used for *str()* calls.  By default, returns the
-      *Enum* name and member name, but can be overridden::
+      member name, but can be overridden::
 
-         >>> class OtherStyle(Enum):
-         ...     ALTERNATE = auto()
-         ...     OTHER = auto()
-         ...     SOMETHING_ELSE = auto()
+         >>> class OldStyle(Enum):
+         ...     RETRO = auto()
+         ...     OLD_SCHOOl = auto()
+         ...     YESTERYEAR = auto()
          ...     def __str__(self):
-         ...         return f'{self.name}'
-         >>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
-         (<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')
-
-   .. method:: Enum.__format__(self)
-
-      Returns the string used for *format()* and *f-string* calls.  By default,
-      returns :meth:`__str__` returns, but can be overridden::
-
-         >>> class OtherStyle(Enum):
-         ...     ALTERNATE = auto()
-         ...     OTHER = auto()
-         ...     SOMETHING_ELSE = auto()
-         ...     def __format__(self, spec):
-         ...         return f'{self.name}'
-         >>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
-         (<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')
+         ...         cls_name = self.__class__.__name__
+         ...         return f'{cls_name}.{self.name}'
+         >>> OldStyle.RETRO
+         OldStyle.RETRO
 
-   .. note::
+.. note::
 
-      Using :class:`auto` with :class:`Enum` results in integers of increasing value,
-      starting with ``1``.
+   Using :class:`auto` with :class:`Enum` results in integers of increasing value,
+   starting with ``1``.
 
 
 .. class:: IntEnum
@@ -384,7 +367,7 @@ Data Types
       ...     TWO = 2
       ...     THREE = 3
       >>> Numbers.THREE
-      <Numbers.THREE: 3>
+      Numbers.THREE
       >>> Numbers.ONE + Numbers.TWO
       3
       >>> Numbers.THREE + 5
@@ -392,14 +375,10 @@ Data Types
       >>> Numbers.THREE == 3
       True
 
-   .. note::
+.. note::
 
-      Using :class:`auto` with :class:`IntEnum` results in integers of increasing
-      value, starting with ``1``.
-
-   .. versionchanged:: 3.11 :meth:`__str__` is now :func:`int.__str__` to
-      better support the *replacement of existing constants* use-case.
-      :meth:`__format__` was already :func:`int.__format__` for that same reason.
+   Using :class:`auto` with :class:`IntEnum` results in integers of increasing value,
+   starting with ``1``.
 
 
 .. class:: StrEnum
@@ -413,16 +392,13 @@ Data Types
              instead of ``isinstance(str, unknown)``), and in those locations you
              will need to use ``str(StrEnum.member)``.
 
-   .. note::
 
-      Using :class:`auto` with :class:`StrEnum` results in the lower-cased member
-      name as the value.
+.. note::
 
-   .. note:: :meth:`__str__` is :func:`str.__str__` to better support the
-      *replacement of existing constants* use-case.  :meth:`__format__` is likewise
-      :func:`int.__format__` for that same reason.
+   Using :class:`auto` with :class:`StrEnum` results in values of the member name,
+   lower-cased.
 
-   .. versionadded:: 3.11
+.. versionadded:: 3.11
 
 .. class:: Flag
 
@@ -455,9 +431,9 @@ Data Types
       Returns all contained members::
 
          >>> list(Color.RED)
-         [<Color.RED: 1>]
+         [Color.RED]
          >>> list(purple)
-         [<Color.RED: 1>, <Color.BLUE: 4>]
+         [Color.RED, Color.BLUE]
 
    .. method:: __len__(self):
 
@@ -485,52 +461,42 @@ Data Types
       Returns current flag binary or'ed with other::
 
          >>> Color.RED | Color.GREEN
-         <Color.RED|GREEN: 3>
+         Color.RED|Color.GREEN
 
    .. method:: __and__(self, other)
 
       Returns current flag binary and'ed with other::
 
          >>> purple & white
-         <Color.RED|BLUE: 5>
+         Color.RED|Color.BLUE
          >>> purple & Color.GREEN
-         <Color: 0>
+         0x0
 
    .. method:: __xor__(self, other)
 
       Returns current flag binary xor'ed with other::
 
          >>> purple ^ white
-         <Color.GREEN: 2>
+         Color.GREEN
          >>> purple ^ Color.GREEN
-         <Color.RED|GREEN|BLUE: 7>
+         Color.RED|Color.GREEN|Color.BLUE
 
    .. method:: __invert__(self):
 
       Returns all the flags in *type(self)* that are not in self::
 
          >>> ~white
-         <Color: 0>
+         0x0
          >>> ~purple
-         <Color.GREEN: 2>
+         Color.GREEN
          >>> ~Color.RED
-         <Color.GREEN|BLUE: 6>
-
-   .. method:: _numeric_repr_
-
-      Function used to format any remaining unnamed numeric values.  Default is
-      the value's repr; common choices are :func:`hex` and :func:`oct`.
-
-   .. note::
+         Color.GREEN|Color.BLUE
 
-      Using :class:`auto` with :class:`Flag` results in integers that are powers
-      of two, starting with ``1``.
+.. note::
 
-   .. versionchanged:: 3.11  The *repr()* of zero-valued flags has changed.  It
-      is now::
+   Using :class:`auto` with :class:`Flag` results in integers that are powers
+   of two, starting with ``1``.
 
-          >>> Color(0)
-          <Color: 0>
 
 .. class:: IntFlag
 
@@ -543,9 +509,9 @@ Data Types
       ...     GREEN = auto()
       ...     BLUE = auto()
       >>> Color.RED & 2
-      <Color: 0>
+      0x0
       >>> Color.RED | 2
-      <Color.RED|GREEN: 3>
+      Color.RED|Color.GREEN
 
    If any integer operation is performed with an *IntFlag* member, the result is
    not an *IntFlag*::
@@ -558,25 +524,15 @@ Data Types
       * the result is a valid *IntFlag*: an *IntFlag* is returned
       * the result is not a valid *IntFlag*: the result depends on the *FlagBoundary* setting
 
-   The *repr()* of unnamed zero-valued flags has changed.  It is now:
-
-      >>> Color(0)
-      <Color: 0>
-
-   .. note::
-
-      Using :class:`auto` with :class:`IntFlag` results in integers that are powers
-      of two, starting with ``1``.
-
-   .. versionchanged:: 3.11 :meth:`__str__` is now :func:`int.__str__` to
-      better support the *replacement of existing constants* use-case.
-      :meth:`__format__` was already :func:`int.__format__` for that same reason.
+.. note::
 
+   Using :class:`auto` with :class:`IntFlag` results in integers that are powers
+   of two, starting with ``1``.
 
 .. class:: EnumCheck
 
    *EnumCheck* contains the options used by the :func:`verify` decorator to ensure
-   various constraints; failed constraints result in a :exc:`ValueError`.
+   various constraints; failed constraints result in a :exc:`TypeError`.
 
    .. attribute:: UNIQUE
 
@@ -626,11 +582,11 @@ Data Types
          ...
          ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]
 
-   .. note::
+.. note::
 
-      CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members.
+   CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members.
 
-   .. versionadded:: 3.11
+.. versionadded:: 3.11
 
 .. class:: FlagBoundary
 
@@ -650,7 +606,7 @@ Data Types
          >>> StrictFlag(2**2 + 2**4)
          Traceback (most recent call last):
          ...
-         ValueError: <flag 'StrictFlag'> invalid value 20
+         ValueError: StrictFlag: invalid value: 20
              given 0b0 10100
            allowed 0b0 00111
 
@@ -665,7 +621,7 @@ Data Types
          ...     GREEN = auto()
          ...     BLUE = auto()
          >>> ConformFlag(2**2 + 2**4)
-         <ConformFlag.BLUE: 4>
+         ConformFlag.BLUE
 
    .. attribute:: EJECT
 
@@ -691,52 +647,12 @@ Data Types
          ...     GREEN = auto()
          ...     BLUE = auto()
          >>> KeepFlag(2**2 + 2**4)
-         <KeepFlag.BLUE|16: 20>
+         KeepFlag.BLUE|0x10
 
 .. versionadded:: 3.11
 
 ---------------
 
-Supported ``__dunder__`` names
-""""""""""""""""""""""""""""""
-
-:attr:`__members__` is a read-only ordered mapping of ``member_name``:``member``
-items.  It is only available on the class.
-
-:meth:`__new__`, if specified, must create and return the enum members; it is
-also a very good idea to set the member's :attr:`_value_` appropriately.  Once
-all the members are created it is no longer used.
-
-
-Supported ``_sunder_`` names
-""""""""""""""""""""""""""""
-
-- ``_name_`` -- name of the member
-- ``_value_`` -- value of the member; can be set / modified in ``__new__``
-
-- ``_missing_`` -- a lookup function used when a value is not found; may be
-  overridden
-- ``_ignore_`` -- a list of names, either as a :class:`list` or a :class:`str`,
-  that will not be transformed into members, and will be removed from the final
-  class
-- ``_order_`` -- used in Python 2/3 code to ensure member order is consistent
-  (class attribute, removed during class creation)
-- ``_generate_next_value_`` -- used to get an appropriate value for an enum
-  member; may be overridden
-
-   .. note::
-
-       For standard :class:`Enum` classes the next value chosen is the last value seen
-       incremented by one.
-
-       For :class:`Flag` classes the next value chosen will be the next highest
-       power-of-two, regardless of the last value seen.
-
-.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
-.. versionadded:: 3.7 ``_ignore_``
-
----------------
-
 Utilities and Decorators
 ------------------------
 
@@ -752,6 +668,15 @@ Utilities and Decorators
    ``_generate_next_value_`` can be overridden to customize the values used by
    *auto*.
 
+.. decorator:: global_enum
+
+   A :keyword:`class` decorator specifically for enumerations.  It replaces the
+   :meth:`__repr__` method with one that shows *module_name*.*member_name*.  It
+   also injects the members, and their aliases, into the global namespace they
+   were defined in.
+
+.. versionadded:: 3.11
+
 .. decorator:: property
 
    A decorator similar to the built-in *property*, but specifically for
@@ -763,7 +688,7 @@ Utilities and Decorators
              *Enum* class, and *Enum* subclasses can define members with the
              names ``value`` and ``name``.
 
-   .. versionadded:: 3.11
+.. versionadded:: 3.11
 
 .. decorator:: unique
 
@@ -789,7 +714,7 @@ Utilities and Decorators
    :class:`EnumCheck` are used to specify which constraints should be checked
    on the decorated enumeration.
 
-   .. versionadded:: 3.11
+.. versionadded:: 3.11
 
 ---------------
 
@@ -801,20 +726,14 @@ Notes
     These three enum types are designed to be drop-in replacements for existing
     integer- and string-based values; as such, they have extra limitations:
 
-    - ``__str__`` uses the value and not the name of the enum member
+    - ``format()`` will use the value of the enum member, unless ``__str__``
+      has been overridden
 
-    - ``__format__``, because it uses ``__str__``, will also use the value of
-      the enum member instead of its name
+    - ``StrEnum.__str__`` uses the value and not the name of the enum member
 
-    If you do not need/want those limitations, you can either create your own
-    base class by mixing in the ``int`` or ``str`` type yourself::
+    If you do not need/want those limitations, you can create your own base
+    class by mixing in the ``int`` or ``str`` type yourself::
 
         >>> from enum import Enum
         >>> class MyIntEnum(int, Enum):
         ...     pass
-
-   or you can reassign the appropriate :meth:`str`, etc., in your enum::
-
-        >>> from enum import IntEnum
-        >>> class MyIntEnum(IntEnum):
-        ...     __str__ = IntEnum.__str__
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 4d8488a..eb33d7e 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -2070,7 +2070,7 @@ to speed up repeated connections from the same clients.
       :attr:`SSLContext.verify_flags` returns :class:`VerifyFlags` flags:
 
          >>> ssl.create_default_context().verify_flags  # doctest: +SKIP
-         <VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>
+         ssl.VERIFY_X509_TRUSTED_FIRST
 
 .. attribute:: SSLContext.verify_mode
 
@@ -2082,7 +2082,7 @@ to speed up repeated connections from the same clients.
       :attr:`SSLContext.verify_mode` returns :class:`VerifyMode` enum:
 
          >>> ssl.create_default_context().verify_mode
-         <VerifyMode.CERT_REQUIRED: 2>
+         ssl.CERT_REQUIRED
 
 .. index:: single: certificates