bpo-40066: Enum: modify `repr()` and `str()` (GH-22392)

* Enum: streamline repr() and str(); improve docs

- repr() is now ``enum_class.member_name``
- stdlib global enums are ``module_name.member_name``
- str() is now ``member_name``
- add HOW-TO section for ``Enum``
- change main documentation to be an API reference

19 files changed, 2107 insertions, 1373 deletions

diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
new file mode 100644
index 0000000..9ece93e
--- /dev/null
+++ b/Doc/howto/enum.rst
@@ -0,0 +1,1416 @@
+==========
+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.
+
+They are most useful when you have a variable that can take one of a limited
+selection of values.  For example, the days of the week::
+
+    >>> from enum import Enum
+    >>> class Weekday(Enum):
+    ...     MONDAY = 1
+    ...     TUESDAY = 2
+    ...     WEDNESDAY = 3
+    ...     THURSDAY = 4
+    ...     FRIDAY = 5
+    ...     SATURDAY = 6
+    ...     SUNDAY = 7
+
+As you can see, creating an :class:`Enum` is as simple as writing a class that
+inherits from :class:`Enum` itself.
+
+.. note:: Case of Enum Members
+
+    Because Enums are used to represent constants we recommend using
+    UPPER_CASE names for members, and will be using that style in our examples.
+
+Depending on the nature of the enum a member's value may or may not be
+important, but either way that value can be used to get the corresponding
+member::
+
+    >>> Weekday(3)
+    Weekday.WEDNESDAY
+
+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)
+    THURSDAY
+
+The *type* of an enumeration member is the enum it belongs to::
+
+    >>> type(Weekday.MONDAY)
+    <enum 'Weekday'>
+    >>> isinstance(Weekday.FRIDAY, Weekday)
+    True
+
+Enum members have an attribute that contains just their :attr:`name`::
+
+    >>> print(Weekday.TUESDAY.name)
+    TUESDAY
+
+Likewise, they have an attribute for their :attr:`value`::
+
+
+    >>> Weekday.WEDNESDAY.value
+    3
+
+Unlike many languages that treat enumerations solely as name/value pairs,
+Python Enums can have behavior added.  For example, :class:`datetime.date`
+has two methods for returning the weekday: :meth:`weekday` and :meth:`isoweekday`.
+The difference is that one of them counts from 0-6 and the other from 1-7.
+Rather than keep track of that ourselves we can add a method to the :class:`Weekday`
+enum to extract the day from the :class:`date` instance and return the matching
+enum member::
+
+        @classmethod
+        def from_date(cls, date):
+            return cls(date.isoweekday())
+
+The complete :class:`Weekday` enum now looks like this::
+
+    >>> class Weekday(Enum):
+    ...     MONDAY = 1
+    ...     TUESDAY = 2
+    ...     WEDNESDAY = 3
+    ...     THURSDAY = 4
+    ...     FRIDAY = 5
+    ...     SATURDAY = 6
+    ...     SUNDAY = 7
+    ...     #
+    ...     @classmethod
+    ...     def from_date(cls, date):
+    ...         return cls(date.isoweekday())
+
+Now we can find out what today is!  Observe::
+
+    >>> from datetime import date
+    >>> Weekday.from_date(date.today())
+    Weekday.TUESDAY
+
+Of course, if you're reading this on some other day, you'll see that day instead.
+
+This :class:`Weekday` enum is great if our variable only needs one day, but
+what if we need several?  Maybe we're writing a function to plot chores during
+a week, and don't want to use a :class:`list` -- we could use a different type
+of :class:`Enum`::
+
+    >>> from enum import Flag
+    >>> class Weekday(Flag):
+    ...     MONDAY = 1
+    ...     TUESDAY = 2
+    ...     WEDNESDAY = 4
+    ...     THURSDAY = 8
+    ...     FRIDAY = 16
+    ...     SATURDAY = 32
+    ...     SUNDAY = 64
+
+We've changed two things: we're inherited from :class:`Flag`, and the values are
+all powers of 2.
+
+Just like the original :class:`Weekday` enum above, we can have a single selection::
+
+    >>> first_week_day = Weekday.MONDAY
+    >>> first_week_day
+    Weekday.MONDAY
+
+But :class:`Flag` also allows us to combine several members into a single
+variable::
+
+    >>> weekend = Weekday.SATURDAY | Weekday.SUNDAY
+    >>> weekend
+    Weekday.SATURDAY|Weekday.SUNDAY
+
+You can even iterate over a :class:`Flag` variable::
+
+    >>> for day in weekend:
+    ...     print(day)
+    SATURDAY
+    SUNDAY
+
+Okay, let's get some chores set up::
+
+    >>> chores_for_ethan = {
+    ...     'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday.FRIDAY,
+    ...     'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,
+    ...     'answer SO questions': Weekday.SATURDAY,
+    ...     }
+
+And a function to display the chores for a given day::
+
+    >>> def show_chores(chores, day):
+    ...     for chore, days in chores.items():
+    ...         if day in days:
+    ...             print(chore)
+    >>> show_chores(chores_for_ethan, Weekday.SATURDAY)
+    answer SO questions
+
+In cases where the actual values of the members do not matter, you can save
+yourself some work and use :func:`auto()` for the values::
+
+    >>> from enum import auto
+    >>> class Weekday(Flag):
+    ...     MONDAY = auto()
+    ...     TUESDAY = auto()
+    ...     WEDNESDAY = auto()
+    ...     THURSDAY = auto()
+    ...     FRIDAY = auto()
+    ...     SATURDAY = auto()
+    ...     SUNDAY = auto()
+
+
+.. _enum-advanced-tutorial:
+
+Programmatic access to enumeration members and their attributes
+---------------------------------------------------------------
+
+Sometimes it's useful to access members in enumerations programmatically (i.e.
+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
+    >>> Color(3)
+    Color.BLUE
+
+If you want to access enum members by *name*, use item access::
+
+    >>> Color['RED']
+    Color.RED
+    >>> Color['GREEN']
+    Color.GREEN
+
+If you have an enum member and need its :attr:`name` or :attr:`value`::
+
+    >>> member = Color.RED
+    >>> member.name
+    'RED'
+    >>> member.value
+    1
+
+
+Duplicating enum members and values
+-----------------------------------
+
+Having two enum members with the same name is invalid::
+
+    >>> class Shape(Enum):
+    ...     SQUARE = 2
+    ...     SQUARE = 3
+    ...
+    Traceback (most recent call last):
+    ...
+    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``
+is an alias for the member ``A``.  By-value lookup of the value of ``A`` will
+return the member ``A``.  By-name lookup of ``A`` will return the member ``A``.
+By-name lookup of ``B`` will also return the member ``A``::
+
+    >>> class Shape(Enum):
+    ...     SQUARE = 2
+    ...     DIAMOND = 1
+    ...     CIRCLE = 3
+    ...     ALIAS_FOR_SQUARE = 2
+    ...
+    >>> Shape.SQUARE
+    Shape.SQUARE
+    >>> Shape.ALIAS_FOR_SQUARE
+    Shape.SQUARE
+    >>> Shape(2)
+    Shape.SQUARE
+
+.. note::
+
+    Attempting to create a member with the same name as an already
+    defined attribute (another member, a method, etc.) or attempting to create
+    an attribute with the same name as a member is not allowed.
+
+
+Ensuring unique enumeration values
+----------------------------------
+
+By default, enumerations allow multiple names as aliases for the same value.
+When this behavior isn't desired, you can use the :func:`unique` decorator::
+
+    >>> from enum import Enum, unique
+    >>> @unique
+    ... class Mistake(Enum):
+    ...     ONE = 1
+    ...     TWO = 2
+    ...     THREE = 3
+    ...     FOUR = 3
+    ...
+    Traceback (most recent call last):
+    ...
+    ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
+
+
+Using automatic values
+----------------------
+
+If the exact value is unimportant you can use :class:`auto`::
+
+    >>> from enum import Enum, auto
+    >>> class Color(Enum):
+    ...     RED = auto()
+    ...     BLUE = auto()
+    ...     GREEN = auto()
+    ...
+    >>> [member.value for member in Color]
+    [1, 2, 3]
+
+The values are chosen by :func:`_generate_next_value_`, which can be
+overridden::
+
+    >>> class AutoName(Enum):
+    ...     def _generate_next_value_(name, start, count, last_values):
+    ...         return name
+    ...
+    >>> class Ordinal(AutoName):
+    ...     NORTH = auto()
+    ...     SOUTH = auto()
+    ...     EAST = auto()
+    ...     WEST = auto()
+    ...
+    >>> [member.value for member in Color]
+    ['NORTH', 'SOUTH', 'EAST', 'WEST']
+
+.. note::
+
+    The :meth:`_generate_next_value_` method must be defined before any members.
+
+Iteration
+---------
+
+Iterating over the members of an enum does not provide the aliases::
+
+    >>> list(Shape)
+    [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
+aliases::
+
+    >>> for name, member in Shape.__members__.items():
+    ...     name, member
+    ...
+    ('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::
+
+    >>> [name for name, member in Shape.__members__.items() if member.name != name]
+    ['ALIAS_FOR_SQUARE']
+
+
+Comparisons
+-----------
+
+Enumeration members are compared by identity::
+
+    >>> Color.RED is Color.RED
+    True
+    >>> Color.RED is Color.BLUE
+    False
+    >>> Color.RED is not Color.BLUE
+    True
+
+Ordered comparisons between enumeration values are *not* supported.  Enum
+members are not integers (but see `IntEnum`_ below)::
+
+    >>> Color.RED < Color.BLUE
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    TypeError: '<' not supported between instances of 'Color' and 'Color'
+
+Equality comparisons are defined though::
+
+    >>> Color.BLUE == Color.RED
+    False
+    >>> Color.BLUE != Color.RED
+    True
+    >>> Color.BLUE == Color.BLUE
+    True
+
+Comparisons against non-enumeration values will always compare not equal
+(again, :class:`IntEnum` was explicitly designed to behave differently, see
+below)::
+
+    >>> Color.BLUE == 2
+    False
+
+
+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
+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.
+
+Enumerations are Python classes, and can have methods and special methods as
+usual.  If we have this enumeration::
+
+    >>> class Mood(Enum):
+    ...     FUNKY = 1
+    ...     HAPPY = 3
+    ...
+    ...     def describe(self):
+    ...         # self is the member here
+    ...         return self.name, self.value
+    ...
+    ...     def __str__(self):
+    ...         return 'my custom str! {0}'.format(self.value)
+    ...
+    ...     @classmethod
+    ...     def favorite_mood(cls):
+    ...         # cls here is the enumeration
+    ...         return cls.HAPPY
+    ...
+
+Then::
+
+    >>> Mood.favorite_mood()
+    Mood.HAPPY
+    >>> Mood.HAPPY.describe()
+    ('HAPPY', 3)
+    >>> str(Mood.FUNKY)
+    'my custom str! 1'
+
+The rules for what is allowed are as follows: names that start and end with
+a single underscore are reserved by enum and cannot be used; all other
+attributes defined within an enumeration will become members of this
+enumeration, with the exception of special methods (:meth:`__str__`,
+:meth:`__add__`, etc.), descriptors (methods are also descriptors), and
+variable names listed in :attr:`_ignore_`.
+
+Note:  if your enumeration defines :meth:`__new__` and/or :meth:`__init__` then
+any value(s) given to the enum member will be passed into those methods.
+See `Planet`_ for an example.
+
+
+Restricted Enum subclassing
+---------------------------
+
+A new :class:`Enum` class must have one base enum class, up to one concrete
+data type, and as many :class:`object`-based mixin classes as needed.  The
+order of these base classes is::
+
+    class EnumName([mix-in, ...,] [data-type,] base-enum):
+        pass
+
+Also, subclassing an enumeration is allowed only if the enumeration does not define
+any members.  So this is forbidden::
+
+    >>> class MoreColor(Color):
+    ...     PINK = 17
+    ...
+    Traceback (most recent call last):
+    ...
+    TypeError: MoreColor: cannot extend enumeration 'Color'
+
+But this is allowed::
+
+    >>> class Foo(Enum):
+    ...     def some_behavior(self):
+    ...         pass
+    ...
+    >>> class Bar(Foo):
+    ...     HAPPY = 1
+    ...     SAD = 2
+    ...
+
+Allowing subclassing of enums that define members would lead to a violation of
+some important invariants of types and instances.  On the other hand, it makes
+sense to allow sharing some common behavior between a group of enumerations.
+(See `OrderedEnum`_ for an example.)
+
+
+Pickling
+--------
+
+Enumerations can be pickled and unpickled::
+
+    >>> from test.test_enum import Fruit
+    >>> from pickle import dumps, loads
+    >>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
+    True
+
+The usual restrictions for pickling apply: picklable enums must be defined in
+the top level of a module, since unpickling requires them to be importable
+from that module.
+
+.. note::
+
+    With pickle protocol version 4 it is possible to easily pickle enums
+    nested in other classes.
+
+It is possible to modify how enum members are pickled/unpickled by defining
+:meth:`__reduce_ex__` in the enumeration class.
+
+
+Functional API
+--------------
+
+The :class:`Enum` class is callable, providing the following functional API::
+
+    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
+    >>> Animal
+    <enum 'Animal'>
+    >>> Animal.ANT
+    Animal.ANT
+    >>> Animal.ANT.value
+    1
+    >>> list(Animal)
+    [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.
+
+The second argument is the *source* of enumeration member names.  It can be a
+whitespace-separated string of names, a sequence of names, a sequence of
+2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to
+values.  The last two options enable assigning arbitrary values to
+enumerations; the others auto-assign increasing integers starting with 1 (use
+the ``start`` parameter to specify a different starting value).  A
+new class derived from :class:`Enum` is returned.  In other words, the above
+assignment to :class:`Animal` is equivalent to::
+
+    >>> class Animal(Enum):
+    ...     ANT = 1
+    ...     BEE = 2
+    ...     CAT = 3
+    ...     DOG = 4
+    ...
+
+The reason for defaulting to ``1`` as the starting number and not ``0`` is
+that ``0`` is ``False`` in a boolean sense, but by default enum members all
+evaluate to ``True``.
+
+Pickling enums created with the functional API can be tricky as frame stack
+implementation details are used to try and figure out which module the
+enumeration is being created in (e.g. it will fail if you use a utility
+function in separate module, and also may not work on IronPython or Jython).
+The solution is to specify the module name explicitly as follows::
+
+    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)
+
+.. warning::
+
+    If ``module`` is not supplied, and Enum cannot determine what it is,
+    the new Enum members will not be unpicklable; to keep errors closer to
+    the source, pickling will be disabled.
+
+The new pickle protocol 4 also, in some circumstances, relies on
+:attr:`~definition.__qualname__` being set to the location where pickle will be able
+to find the class.  For example, if the class was made available in class
+SomeData in the global scope::
+
+    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')
+
+The complete signature is::
+
+    Enum(
+        value='NewEnumName',
+        names=<...>,
+        *,
+        module='...',
+        qualname='...',
+        type=<mixed-in class>,
+        start=1,
+        )
+
+:value: What the new enum class will record as its name.
+
+:names: The enum members.  This can be a whitespace or comma separated string
+  (values will start at 1 unless otherwise specified)::
+
+    'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'
+
+  or an iterator of names::
+
+    ['RED', 'GREEN', 'BLUE']
+
+  or an iterator of (name, value) pairs::
+
+    [('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]
+
+  or a mapping::
+
+    {'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}
+
+:module: name of module where new enum class can be found.
+
+:qualname: where in module new enum class can be found.
+
+:type: type to mix in to new enum class.
+
+:start: number to start counting at if only names are passed in.
+
+.. versionchanged:: 3.5
+   The *start* parameter was added.
+
+
+Derived Enumerations
+--------------------
+
+IntEnum
+^^^^^^^
+
+The first variation of :class:`Enum` that is provided is also a subclass of
+:class:`int`.  Members of an :class:`IntEnum` can be compared to integers;
+by extension, integer enumerations of different types can also be compared
+to each other::
+
+    >>> from enum import IntEnum
+    >>> class Shape(IntEnum):
+    ...     CIRCLE = 1
+    ...     SQUARE = 2
+    ...
+    >>> class Request(IntEnum):
+    ...     POST = 1
+    ...     GET = 2
+    ...
+    >>> Shape == 1
+    False
+    >>> Shape.CIRCLE == 1
+    True
+    >>> Shape.CIRCLE == Request.POST
+    True
+
+However, they still can't be compared to standard :class:`Enum` enumerations::
+
+    >>> class Shape(IntEnum):
+    ...     CIRCLE = 1
+    ...     SQUARE = 2
+    ...
+    >>> class Color(Enum):
+    ...     RED = 1
+    ...     GREEN = 2
+    ...
+    >>> Shape.CIRCLE == Color.RED
+    False
+
+:class:`IntEnum` values behave like integers in other ways you'd expect::
+
+    >>> int(Shape.CIRCLE)
+    1
+    >>> ['a', 'b', 'c'][Shape.CIRCLE]
+    'b'
+    >>> [i for i in range(Shape.SQUARE)]
+    [0, 1]
+
+
+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.  :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.10
+
+
+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.  However, as the name implies, :class:`IntFlag`
+members also subclass :class:`int` and can be used wherever an :class:`int` is
+used.
+
+.. note::
+
+    Any operation on an :class:`IntFlag` member besides the bit-wise operations will
+    lose the :class:`IntFlag` membership.
+
+    Bit-wise operations that result in invalid :class:`IntFlag` values will lose the
+    :class:`IntFlag` membership.  See :class:`FlagBoundary` for
+    details.
+
+.. versionadded:: 3.6
+.. versionchanged:: 3.10
+
+Sample :class:`IntFlag` class::
+
+    >>> from enum import IntFlag
+    >>> class Perm(IntFlag):
+    ...     R = 4
+    ...     W = 2
+    ...     X = 1
+    ...
+    >>> Perm.R | Perm.W
+    Perm.R|Perm.W
+    >>> Perm.R + Perm.W
+    6
+    >>> RW = Perm.R | Perm.W
+    >>> Perm.R in RW
+    True
+
+It is also possible to name the combinations::
+
+    >>> class Perm(IntFlag):
+    ...     R = 4
+    ...     W = 2
+    ...     X = 1
+    ...     RWX = 7
+    >>> Perm.RWX
+    Perm.RWX
+    >>> ~Perm.RWX
+    Perm(0)
+    >>> Perm(7)
+    Perm.RWX
+
+.. note::
+
+    Named combinations are considered aliases.  Aliases do not show up during
+    iteration, but can be returned from by-value lookups.
+
+.. versionchanged:: 3.10
+
+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)
+    >>> bool(Perm.R & Perm.X)
+    False
+
+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|Perm.X
+
+    >>> Perm.X | 8
+    9
+
+.. note::
+
+    The negation operator, ``~``, always returns an :class:`IntFlag` member with a
+    positive value::
+
+        >>> (~Perm.X).value == (Perm.R|Perm.W).value == 6
+        True
+
+:class:`IntFlag` members can also be iterated over::
+
+    >>> list(RW)
+    [Perm.R, Perm.W]
+
+.. versionadded:: 3.10
+
+
+Flag
+^^^^
+
+The last variation is :class:`Flag`.  Like :class:`IntFlag`, :class:`Flag`
+members can be combined using the bitwise operators (&, \|, ^, ~).  Unlike
+:class:`IntFlag`, they cannot be combined with, nor compared against, any
+other :class:`Flag` enumeration, nor :class:`int`.  While it is possible to
+specify the values directly it is recommended to use :class:`auto` as the
+value and let :class:`Flag` select an appropriate value.
+
+.. versionadded:: 3.6
+
+Like :class:`IntFlag`, if a combination of :class:`Flag` members results in no
+flags being set, the boolean evaluation is :data:`False`::
+
+    >>> from enum import Flag, auto
+    >>> class Color(Flag):
+    ...     RED = auto()
+    ...     BLUE = auto()
+    ...     GREEN = auto()
+    ...
+    >>> Color.RED & Color.GREEN
+    Color(0)
+    >>> bool(Color.RED & Color.GREEN)
+    False
+
+Individual flags should have values that are powers of two (1, 2, 4, 8, ...),
+while combinations of flags won't::
+
+    >>> class Color(Flag):
+    ...     RED = auto()
+    ...     BLUE = auto()
+    ...     GREEN = auto()
+    ...     WHITE = RED | BLUE | GREEN
+    ...
+    >>> Color.WHITE
+    Color.WHITE
+
+Giving a name to the "no flags set" condition does not change its boolean
+value::
+
+    >>> class Color(Flag):
+    ...     BLACK = 0
+    ...     RED = auto()
+    ...     BLUE = auto()
+    ...     GREEN = auto()
+    ...
+    >>> Color.BLACK
+    Color.BLACK
+    >>> bool(Color.BLACK)
+    False
+
+:class:`Flag` members can also be iterated over::
+
+    >>> purple = Color.RED | Color.BLUE
+    >>> list(purple)
+    [Color.RED, Color.BLUE]
+
+.. versionadded:: 3.10
+
+.. note::
+
+    For the majority of new code, :class:`Enum` and :class:`Flag` are strongly
+    recommended, since :class:`IntEnum` and :class:`IntFlag` break some
+    semantic promises of an enumeration (by being comparable to integers, and
+    thus by transitivity to other unrelated enumerations).  :class:`IntEnum`
+    and :class:`IntFlag` should be used only in cases where :class:`Enum` and
+    :class:`Flag` will not do; for example, when integer constants are replaced
+    with enumerations, or for interoperability with other systems.
+
+
+Others
+^^^^^^
+
+While :class:`IntEnum` is part of the :mod:`enum` module, it would be very
+simple to implement independently::
+
+    class IntEnum(int, Enum):
+        pass
+
+This demonstrates how similar derived enumerations can be defined; for example
+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. 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
+   add methods and don't specify another type.
+3. 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.
+4. %-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.
+5. :ref:`Formatted string literals <f-strings>`, :meth:`str.format`,
+   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__`
+------------------------------------------------
+
+:meth:`__new__` must be used whenever you want to customize the actual value of
+the :class:`Enum` member.  Any other modifications may go in either
+:meth:`__new__` or :meth:`__init__`, with :meth:`__init__` being preferred.
+
+For example, if you want to pass several items to the constructor, but only
+want one of them to be the value::
+
+    >>> class Coordinate(bytes, Enum):
+    ...     """
+    ...     Coordinate with binary codes that can be indexed by the int code.
+    ...     """
+    ...     def __new__(cls, value, label, unit):
+    ...         obj = bytes.__new__(cls, [value])
+    ...         obj._value_ = value
+    ...         obj.label = label
+    ...         obj.unit = unit
+    ...         return obj
+    ...     PX = (0, 'P.X', 'km')
+    ...     PY = (1, 'P.Y', 'km')
+    ...     VX = (2, 'V.X', 'km/s')
+    ...     VY = (3, 'V.Y', 'km/s')
+    ...
+
+    >>> print(Coordinate['PY'])
+    PY
+
+    >>> print(Coordinate(3))
+    VY
+
+
+Finer Points
+^^^^^^^^^^^^
+
+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 by the `Functional API`_ and by
+  :class:`auto` 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_``
+
+To help keep Python 2 / Python 3 code in sync an :attr:`_order_` attribute can
+be provided.  It will be checked against the actual order of the enumeration
+and raise an error if the two do not match::
+
+    >>> class Color(Enum):
+    ...     _order_ = 'RED GREEN BLUE'
+    ...     RED = 1
+    ...     BLUE = 3
+    ...     GREEN = 2
+    ...
+    Traceback (most recent call last):
+    ...
+    TypeError: member order does not match _order_:
+    ['RED', 'BLUE', 'GREEN']
+    ['RED', 'GREEN', 'BLUE']
+
+.. note::
+
+    In Python 2 code the :attr:`_order_` attribute is necessary as definition
+    order is lost before it can be recorded.
+
+
+_Private__names
+"""""""""""""""
+
+Private names are not converted to enum members, but remain normal attributes.
+
+.. versionchanged:: 3.10
+
+
+``Enum`` member type
+""""""""""""""""""""
+
+Enum members are instances of their enum class, and are normally accessed as
+``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       # 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.10
+
+
+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
+constructor.  For example::
+
+    >>> class MyEnum(IntEnum):
+    ...     example = '11', 16      # '11' will be interpreted as a hexadecimal
+    ...                             # number
+    >>> MyEnum.example.value
+    17
+
+
+Boolean value of ``Enum`` classes and members
+"""""""""""""""""""""""""""""""""""""""""""""
+
+Enum classes that are mixed with non-:class:`Enum` types (such as
+:class:`int`, :class:`str`, etc.) are evaluated according to the mixed-in
+type's rules; otherwise, all members evaluate as :data:`True`.  To make your
+own enum's boolean evaluation depend on the member's value add the following to
+your class::
+
+    def __bool__(self):
+        return bool(self.value)
+
+Plain :class:`Enum` classes always evaluate as :data:`True`.
+
+
+``Enum`` classes with methods
+"""""""""""""""""""""""""""""
+
+If you give your enum subclass extra methods, like the `Planet`_
+class above, those methods will show up in a :func:`dir` of the member,
+but not of the class::
+
+    >>> dir(Planet)
+    ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
+    >>> dir(Planet.EARTH)
+    ['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', 'surface_gravity', 'value']
+
+
+Combining members of ``Flag``
+"""""""""""""""""""""""""""""
+
+Iterating over a combination of :class:`Flag` members will only return the members that
+are comprised of a single bit::
+
+    >>> class Color(Flag):
+    ...     RED = auto()
+    ...     GREEN = auto()
+    ...     BLUE = auto()
+    ...     MAGENTA = RED | BLUE
+    ...     YELLOW = RED | GREEN
+    ...     CYAN = GREEN | BLUE
+    ...
+    >>> Color(3)  # named combination
+    Color.YELLOW
+    >>> Color(7)      # not named combination
+    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
+""""""""""""""""""""""""""""""""
+
+Using the following snippet for our examples::
+
+    >>> class Color(IntFlag):
+    ...     BLACK = 0
+    ...     RED = 1
+    ...     GREEN = 2
+    ...     BLUE = 4
+    ...     PURPLE = RED | BLUE
+    ...     WHITE = RED | GREEN | BLUE
+    ...
+
+the following are true:
+
+- single-bit flags are canonical
+- multi-bit and zero-bit flags are aliases
+- only canonical flags are returned during iteration::
+
+    >>> list(Color.WHITE)
+    [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
+
+    >>> ~Color.BLUE
+    Color.RED|Color.GREEN
+
+- names of pseudo-flags are constructed from their members' names::
+
+    >>> (Color.RED | Color.GREEN).name
+    'RED|GREEN'
+
+- multi-bit flags, aka aliases, can be returned from operations::
+
+    >>> Color.RED | Color.BLUE
+    Color.PURPLE
+
+    >>> Color(7)  # or Color(-1)
+    Color.WHITE
+
+    >>> Color(0)
+    Color.BLACK
+
+- membership / containment checking has changed slightly -- zero valued flags
+  are never considered to be contained::
+
+    >>> Color.BLACK in Color.WHITE
+    False
+
+  otherwise, if all bits of one flag are in the other flag, True is returned::
+
+    >>> Color.PURPLE in Color.WHITE
+    True
+
+There is a new boundary mechanism that controls how out-of-range / invalid
+bits are handled: ``STRICT``, ``CONFORM``, ``EJECT``, and ``KEEP``:
+
+  * STRICT --> raises an exception when presented with invalid values
+  * CONFORM --> discards any invalid bits
+  * EJECT --> lose Flag status and become a normal int with the given value
+  * KEEP --> keep the extra bits
+           - keeps Flag status and extra bits
+           - extra bits do not show up in iteration
+           - extra bits do show up in repr() and str()
+
+The default for Flag is ``STRICT``, the default for ``IntFlag`` is ``EJECT``,
+and the default for ``_convert_`` is ``KEEP`` (see ``ssl.Options`` for an
+example of when ``KEEP`` is needed).
+
+
+.. _enum-class-differences:
+
+How are Enums different?
+------------------------
+
+Enums have a custom metaclass that affects many aspects of both derived :class:`Enum`
+classes and their instances (members).
+
+
+Enum Classes
+^^^^^^^^^^^^
+
+The :class:`EnumType` metaclass is responsible for providing the
+:meth:`__contains__`, :meth:`__dir__`, :meth:`__iter__` and other methods that
+allow one to do things with an :class:`Enum` class that fail on a typical
+class, such as `list(Color)` or `some_enum_var in Color`.  :class:`EnumType` is
+responsible for ensuring that various other methods on the final :class:`Enum`
+class are correct (such as :meth:`__new__`, :meth:`__getnewargs__`,
+:meth:`__str__` and :meth:`__repr__`).
+
+
+Enum Members (aka instances)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The most interesting thing about enum members is that they are singletons.
+:class:`EnumType` creates them all while it is creating the enum class itself,
+and then puts a custom :meth:`__new__` in place to ensure that no new ones are
+ever instantiated by returning only the existing member instances.
+
+
+.. _enum-cookbook:
+
+
+While :class:`Enum`, :class:`IntEnum`, :class:`StrEnum`, :class:`Flag`, and
+:class:`IntFlag` are expected to cover the majority of use-cases, they cannot
+cover them all.  Here are recipes for some different types of enumerations
+that can be used directly, or as examples for creating one's own.
+
+
+Omitting values
+^^^^^^^^^^^^^^^
+
+In many use-cases one doesn't care what the actual value of an enumeration
+is. There are several ways to define this type of simple enumeration:
+
+- use instances of :class:`auto` for the value
+- use instances of :class:`object` as the value
+- use a descriptive string as the value
+- use a tuple as the value and a custom :meth:`__new__` to replace the
+  tuple with an :class:`int` value
+
+Using any of these methods signifies to the user that these values are not
+important, and also enables one to add, remove, or reorder members without
+having to renumber the remaining members.
+
+
+Using :class:`auto`
+"""""""""""""""""""
+
+Using :class:`auto` would look like::
+
+    >>> class Color(Enum):
+    ...     RED = auto()
+    ...     BLUE = auto()
+    ...     GREEN = auto()
+    ...
+    >>> Color.GREEN
+    <Color.GREEN>
+
+
+Using :class:`object`
+"""""""""""""""""""""
+
+Using :class:`object` would look like::
+
+    >>> class Color(Enum):
+    ...     RED = object()
+    ...     GREEN = object()
+    ...     BLUE = object()
+    ...
+    >>> Color.GREEN
+    <Color.GREEN>
+
+
+Using a descriptive string
+""""""""""""""""""""""""""
+
+Using a string as the value would look like::
+
+    >>> class Color(Enum):
+    ...     RED = 'stop'
+    ...     GREEN = 'go'
+    ...     BLUE = 'too fast!'
+    ...
+    >>> Color.GREEN
+    <Color.GREEN>
+    >>> Color.GREEN.value
+    'go'
+
+
+Using a custom :meth:`__new__`
+""""""""""""""""""""""""""""""
+
+Using an auto-numbering :meth:`__new__` would look like::
+
+    >>> class AutoNumber(Enum):
+    ...     def __new__(cls):
+    ...         value = len(cls.__members__) + 1
+    ...         obj = object.__new__(cls)
+    ...         obj._value_ = value
+    ...         return obj
+    ...
+    >>> class Color(AutoNumber):
+    ...     RED = ()
+    ...     GREEN = ()
+    ...     BLUE = ()
+    ...
+    >>> Color.GREEN
+    <Color.GREEN>
+    >>> Color.GREEN.value
+    2
+
+To make a more general purpose ``AutoNumber``, add ``*args`` to the signature::
+
+    >>> class AutoNumber(Enum):
+    ...     def __new__(cls, *args):      # this is the only change from above
+    ...         value = len(cls.__members__) + 1
+    ...         obj = object.__new__(cls)
+    ...         obj._value_ = value
+    ...         return obj
+    ...
+
+Then when you inherit from ``AutoNumber`` you can write your own ``__init__``
+to handle any extra arguments::
+
+    >>> class Swatch(AutoNumber):
+    ...     def __init__(self, pantone='unknown'):
+    ...         self.pantone = pantone
+    ...     AUBURN = '3497'
+    ...     SEA_GREEN = '1246'
+    ...     BLEACHED_CORAL = () # New color, no Pantone code yet!
+    ...
+    >>> Swatch.SEA_GREEN
+    <Swatch.SEA_GREEN>
+    >>> Swatch.SEA_GREEN.pantone
+    '1246'
+    >>> Swatch.BLEACHED_CORAL.pantone
+    'unknown'
+
+.. note::
+
+    The :meth:`__new__` method, if defined, is used during creation of the Enum
+    members; it is then replaced by Enum's :meth:`__new__` which is used after
+    class creation for lookup of existing members.
+
+
+OrderedEnum
+^^^^^^^^^^^
+
+An ordered enumeration that is not based on :class:`IntEnum` and so maintains
+the normal :class:`Enum` invariants (such as not being comparable to other
+enumerations)::
+
+    >>> class OrderedEnum(Enum):
+    ...     def __ge__(self, other):
+    ...         if self.__class__ is other.__class__:
+    ...             return self.value >= other.value
+    ...         return NotImplemented
+    ...     def __gt__(self, other):
+    ...         if self.__class__ is other.__class__:
+    ...             return self.value > other.value
+    ...         return NotImplemented
+    ...     def __le__(self, other):
+    ...         if self.__class__ is other.__class__:
+    ...             return self.value <= other.value
+    ...         return NotImplemented
+    ...     def __lt__(self, other):
+    ...         if self.__class__ is other.__class__:
+    ...             return self.value < other.value
+    ...         return NotImplemented
+    ...
+    >>> class Grade(OrderedEnum):
+    ...     A = 5
+    ...     B = 4
+    ...     C = 3
+    ...     D = 2
+    ...     F = 1
+    ...
+    >>> Grade.C < Grade.A
+    True
+
+
+DuplicateFreeEnum
+^^^^^^^^^^^^^^^^^
+
+Raises an error if a duplicate member name is found instead of creating an
+alias::
+
+    >>> class DuplicateFreeEnum(Enum):
+    ...     def __init__(self, *args):
+    ...         cls = self.__class__
+    ...         if any(self.value == e.value for e in cls):
+    ...             a = self.name
+    ...             e = cls(self.value).name
+    ...             raise ValueError(
+    ...                 "aliases not allowed in DuplicateFreeEnum:  %r --> %r"
+    ...                 % (a, e))
+    ...
+    >>> class Color(DuplicateFreeEnum):
+    ...     RED = 1
+    ...     GREEN = 2
+    ...     BLUE = 3
+    ...     GRENE = 2
+    ...
+    Traceback (most recent call last):
+    ...
+    ValueError: aliases not allowed in DuplicateFreeEnum:  'GRENE' --> 'GREEN'
+
+.. note::
+
+    This is a useful example for subclassing Enum to add or change other
+    behaviors as well as disallowing aliases.  If the only desired change is
+    disallowing aliases, the :func:`unique` decorator can be used instead.
+
+
+Planet
+^^^^^^
+
+If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member
+will be passed to those methods::
+
+    >>> class Planet(Enum):
+    ...     MERCURY = (3.303e+23, 2.4397e6)
+    ...     VENUS   = (4.869e+24, 6.0518e6)
+    ...     EARTH   = (5.976e+24, 6.37814e6)
+    ...     MARS    = (6.421e+23, 3.3972e6)
+    ...     JUPITER = (1.9e+27,   7.1492e7)
+    ...     SATURN  = (5.688e+26, 6.0268e7)
+    ...     URANUS  = (8.686e+25, 2.5559e7)
+    ...     NEPTUNE = (1.024e+26, 2.4746e7)
+    ...     def __init__(self, mass, radius):
+    ...         self.mass = mass       # in kilograms
+    ...         self.radius = radius   # in meters
+    ...     @property
+    ...     def surface_gravity(self):
+    ...         # universal gravitational constant  (m3 kg-1 s-2)
+    ...         G = 6.67300E-11
+    ...         return G * self.mass / (self.radius * self.radius)
+    ...
+    >>> Planet.EARTH.value
+    (5.976e+24, 6378140.0)
+    >>> Planet.EARTH.surface_gravity
+    9.802652743337129
+
+.. _enum-time-period:
+
+TimePeriod
+^^^^^^^^^^
+
+An example to show the :attr:`_ignore_` attribute in use::
+
+    >>> from datetime import timedelta
+    >>> class Period(timedelta, Enum):
+    ...     "different lengths of time"
+    ...     _ignore_ = 'Period i'
+    ...     Period = vars()
+    ...     for i in range(367):
+    ...         Period['day_%d' % i] = i
+    ...
+    >>> list(Period)[:2]
+    [Period.day_0, Period.day_1]
+    >>> list(Period)[-2:]
+    [Period.day_365, Period.day_366]
+
+
+Conforming input to Flag
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Creating a :class:`Flag` enum that is more resilient out-of-bounds results to
+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:
+
+Subclassing EnumType
+--------------------
+
+While most enum needs can be met by customizing :class:`Enum` subclasses,
+either with class decorators or custom functions, :class:`EnumType` can be
+subclassed to provide a different Enum experience.
+
diff --git a/Doc/howto/index.rst b/Doc/howto/index.rst
index 593341c..e0dacd2 100644
--- a/Doc/howto/index.rst
+++ b/Doc/howto/index.rst
@@ -17,6 +17,7 @@ Currently, the HOWTOs are:
    cporting.rst
    curses.rst
    descriptor.rst
+   enum.rst
    functional.rst
    logging.rst
    logging-cookbook.rst
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 73b77cb..3a6b2aa 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -13,1368 +13,612 @@
 
 **Source code:** :source:`Lib/enum.py`
 
-----------------
-
-An enumeration is a set of symbolic names (members) bound to unique,
-constant values.  Within an enumeration, the members can be compared
-by identity, and the enumeration itself can be iterated over.
-
-.. note:: Case of Enum Members
+.. sidebar:: Important
 
-    Because Enums are used to represent constants we recommend using
-    UPPER_CASE names for enum members, and will be using that style
-    in our examples.
+   This page contains the API reference information. For tutorial
+   information and discussion of more advanced topics, see
 
+   * :ref:`Basic Tutorial <enum-basic-tutorial>`
+   * :ref:`Advanced Tutorial <enum-advanced-tutorial>`
+   * :ref:`Enum Cookbook <enum-cookbook>`
 
-Module Contents
----------------
-
-This module defines four enumeration classes that can be used to define unique
-sets of names and values: :class:`Enum`, :class:`IntEnum`, :class:`Flag`, and
-:class:`IntFlag`.  It also defines one decorator, :func:`unique`, and one
-helper, :class:`auto`.
-
-.. class:: Enum
-
-    Base class for creating enumerated constants.  See section
-    `Functional API`_ for an alternate construction syntax.
-
-.. class:: IntEnum
-
-    Base class for creating enumerated constants that are also
-    subclasses of :class:`int`.
-
-.. class:: StrEnum
-
-    Base class for creating enumerated constants that are also
-    subclasses of :class:`str`.
-
-.. class:: IntFlag
-
-    Base class for creating enumerated constants that can be combined using
-    the bitwise operators without losing their :class:`IntFlag` membership.
-    :class:`IntFlag` members are also subclasses of :class:`int`.
-
-.. class:: Flag
-
-    Base class for creating enumerated constants that can be combined using
-    the bitwise operations without losing their :class:`Flag` membership.
-
-.. function:: unique
-    :noindex:
-
-    Enum class decorator that ensures only one name is bound to any one value.
-
-.. class:: auto
-
-    Instances are replaced with an appropriate value for Enum members.
-    :class:`StrEnum` defaults to the lower-cased version of the member name,
-    while other Enums default to 1 and increase from there.
-
-.. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
-.. versionadded:: 3.10  ``StrEnum``
-
-Creating an Enum
 ----------------
 
-Enumerations are created using the :keyword:`class` syntax, which makes them
-easy to read and write.  An alternative creation method is described in
-`Functional API`_.  To define an enumeration, subclass :class:`Enum` as
-follows::
-
-    >>> from enum import Enum
-    >>> class Color(Enum):
-    ...     RED = 1
-    ...     GREEN = 2
-    ...     BLUE = 3
-    ...
-
-.. note:: Enum member values
-
-    Member values can be anything: :class:`int`, :class:`str`, etc..  If
-    the exact value is unimportant you may use :class:`auto` instances and an
-    appropriate value will be chosen for you.  Care must be taken if you mix
-    :class:`auto` with other values.
+An enumeration:
 
-.. note:: Nomenclature
-
-  - The class :class:`Color` is an *enumeration* (or *enum*)
-  - The attributes :attr:`Color.RED`, :attr:`Color.GREEN`, etc., are
-    *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.)
-
-.. note::
-
-    Even though we use the :keyword:`class` syntax to create Enums, Enums
-    are not normal Python classes.  See `How are Enums different?`_ for
-    more details.
-
-Enumeration members have human readable string representations::
-
-    >>> print(Color.RED)
-    Color.RED
-
-...while their ``repr`` has more information::
-
-    >>> print(repr(Color.RED))
-    <Color.RED: 1>
-
-The *type* of an enumeration member is the enumeration it belongs to::
-
-    >>> type(Color.RED)
-    <enum 'Color'>
-    >>> isinstance(Color.GREEN, Color)
-    True
-
-Enum members also have a property that contains just their item name::
-
-    >>> print(Color.RED.name)
-    RED
-
-Enumerations support iteration, in definition order::
-
-    >>> class Shake(Enum):
-    ...     VANILLA = 7
-    ...     CHOCOLATE = 4
-    ...     COOKIES = 9
-    ...     MINT = 3
-    ...
-    >>> for shake in Shake:
-    ...     print(shake)
-    ...
-    Shake.VANILLA
-    Shake.CHOCOLATE
-    Shake.COOKIES
-    Shake.MINT
-
-Enumeration members are hashable, so they can be used in dictionaries and sets::
-
-    >>> apples = {}
-    >>> apples[Color.RED] = 'red delicious'
-    >>> apples[Color.GREEN] = 'granny smith'
-    >>> apples == {Color.RED: 'red delicious', Color.GREEN: 'granny smith'}
-    True
+* is a set of symbolic names (members) bound to unique values
+* can be iterated over to return its members in definition order
+* uses :meth:`call` syntax to return members by value
+* uses :meth:`index` syntax to return members by name
 
+Enumerations are created either by using the :keyword:`class` syntax, or by
+using function-call syntax::
 
-Programmatic access to enumeration members and their attributes
----------------------------------------------------------------
+   >>> from enum import Enum
 
-Sometimes it's useful to access members in enumerations programmatically (i.e.
-situations where ``Color.RED`` won't do because the exact color is not known
-at program-writing time).  ``Enum`` allows such access::
+   >>> # class syntax
+   >>> class Color(Enum):
+   ...     RED = 1
+   ...     GREEN = 2
+   ...     BLUE = 3
 
-    >>> Color(1)
-    <Color.RED: 1>
-    >>> Color(3)
-    <Color.BLUE: 3>
+   >>> # functional syntax
+   >>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE'])
 
-If you want to access enum members by *name*, use item access::
+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.
 
-    >>> Color['RED']
-    <Color.RED: 1>
-    >>> Color['GREEN']
-    <Color.GREEN: 2>
-
-If you have an enum member and need its :attr:`name` or :attr:`value`::
-
-    >>> member = Color.RED
-    >>> member.name
-    'RED'
-    >>> member.value
-    1
-
-
-Duplicating enum members and values
------------------------------------
-
-Having two enum members with the same name is invalid::
-
-    >>> class Shape(Enum):
-    ...     SQUARE = 2
-    ...     SQUARE = 3
-    ...
-    Traceback (most recent call last):
-    ...
-    TypeError: 'SQUARE' already defined as: 2
-
-However, two enum members are allowed to have the same value.  Given two members
-A and B with the same value (and A defined first), B is an alias to A.  By-value
-lookup of the value of A and B will return A.  By-name lookup of B will also
-return A::
-
-    >>> class Shape(Enum):
-    ...     SQUARE = 2
-    ...     DIAMOND = 1
-    ...     CIRCLE = 3
-    ...     ALIAS_FOR_SQUARE = 2
-    ...
-    >>> Shape.SQUARE
-    <Shape.SQUARE: 2>
-    >>> Shape.ALIAS_FOR_SQUARE
-    <Shape.SQUARE: 2>
-    >>> Shape(2)
-    <Shape.SQUARE: 2>
-
-.. note::
-
-    Attempting to create a member with the same name as an already
-    defined attribute (another member, a method, etc.) or attempting to create
-    an attribute with the same name as a member is not allowed.
-
-
-Ensuring unique enumeration values
-----------------------------------
-
-By default, enumerations allow multiple names as aliases for the same value.
-When this behavior isn't desired, the following decorator can be used to
-ensure each value is used only once in the enumeration:
-
-.. decorator:: unique
-
-A :keyword:`class` decorator specifically for enumerations.  It searches an
-enumeration's :attr:`__members__` gathering any aliases it finds; if any are
-found :exc:`ValueError` is raised with the details::
-
-    >>> from enum import Enum, unique
-    >>> @unique
-    ... class Mistake(Enum):
-    ...     ONE = 1
-    ...     TWO = 2
-    ...     THREE = 3
-    ...     FOUR = 3
-    ...
-    Traceback (most recent call last):
-    ...
-    ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
-
-
-Using automatic values
-----------------------
-
-If the exact value is unimportant you can use :class:`auto`::
-
-    >>> from enum import Enum, auto
-    >>> class Color(Enum):
-    ...     RED = auto()
-    ...     BLUE = auto()
-    ...     GREEN = auto()
-    ...
-    >>> list(Color)
-    [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]
-
-The values are chosen by :func:`_generate_next_value_`, which can be
-overridden::
-
-    >>> class AutoName(Enum):
-    ...     def _generate_next_value_(name, start, count, last_values):
-    ...         return name
-    ...
-    >>> class Ordinal(AutoName):
-    ...     NORTH = auto()
-    ...     SOUTH = auto()
-    ...     EAST = auto()
-    ...     WEST = auto()
-    ...
-    >>> list(Ordinal)
-    [<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]
-
-.. note::
-
-    The goal of the default :meth:`_generate_next_value_` method is to provide
-    the next :class:`int` in sequence with the last :class:`int` provided, but
-    the way it does this is an implementation detail and may change.
-
-.. note::
-
-    The :meth:`_generate_next_value_` method must be defined before any members.
-
-Iteration
----------
-
-Iterating over the members of an enum does not provide the aliases::
-
-    >>> list(Shape)
-    [<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
-
-The special attribute ``__members__`` is a read-only ordered mapping of names
-to members.  It includes all names defined in the enumeration, including the
-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>)
-
-The ``__members__`` attribute can be used for detailed programmatic access to
-the enumeration members.  For example, finding all the aliases::
-
-    >>> [name for name, member in Shape.__members__.items() if member.name != name]
-    ['ALIAS_FOR_SQUARE']
+.. note:: Nomenclature
 
+   - The class :class:`Color` is an *enumeration* (or *enum*)
+   - The attributes :attr:`Color.RED`, :attr:`Color.GREEN`, etc., are
+     *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.)
 
-Comparisons
------------
 
-Enumeration members are compared by identity::
+Module Contents
+---------------
 
-    >>> Color.RED is Color.RED
-    True
-    >>> Color.RED is Color.BLUE
-    False
-    >>> Color.RED is not Color.BLUE
-    True
+   :class:`EnumType`
 
-Ordered comparisons between enumeration values are *not* supported.  Enum
-members are not integers (but see `IntEnum`_ below)::
-
-    >>> Color.RED < Color.BLUE
-    Traceback (most recent call last):
-      File "<stdin>", line 1, in <module>
-    TypeError: '<' not supported between instances of 'Color' and 'Color'
-
-Equality comparisons are defined though::
-
-    >>> Color.BLUE == Color.RED
-    False
-    >>> Color.BLUE != Color.RED
-    True
-    >>> Color.BLUE == Color.BLUE
-    True
+      The ``type`` for Enum and its subclasses.
 
-Comparisons against non-enumeration values will always compare not equal
-(again, :class:`IntEnum` was explicitly designed to behave differently, see
-below)::
+   :class:`Enum`
 
-    >>> Color.BLUE == 2
-    False
+      Base class for creating enumerated constants.
 
+   :class:`IntEnum`
 
-Allowed members and attributes of enumerations
-----------------------------------------------
+      Base class for creating enumerated constants that are also
+      subclasses of :class:`int`.
 
-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.
+   :class:`StrEnum`
 
-Enumerations are Python classes, and can have methods and special methods as
-usual.  If we have this enumeration::
+      Base class for creating enumerated constants that are also
+      subclasses of :class:`str`.
 
-    >>> class Mood(Enum):
-    ...     FUNKY = 1
-    ...     HAPPY = 3
-    ...
-    ...     def describe(self):
-    ...         # self is the member here
-    ...         return self.name, self.value
-    ...
-    ...     def __str__(self):
-    ...         return 'my custom str! {0}'.format(self.value)
-    ...
-    ...     @classmethod
-    ...     def favorite_mood(cls):
-    ...         # cls here is the enumeration
-    ...         return cls.HAPPY
-    ...
+   :class:`Flag`
 
-Then::
+      Base class for creating enumerated constants that can be combined using
+      the bitwise operations without losing their :class:`Flag` membership.
 
-    >>> Mood.favorite_mood()
-    <Mood.HAPPY: 3>
-    >>> Mood.HAPPY.describe()
-    ('HAPPY', 3)
-    >>> str(Mood.FUNKY)
-    'my custom str! 1'
-
-The rules for what is allowed are as follows: names that start and end with
-a single underscore are reserved by enum and cannot be used; all other
-attributes defined within an enumeration will become members of this
-enumeration, with the exception of special methods (:meth:`__str__`,
-:meth:`__add__`, etc.), descriptors (methods are also descriptors), and
-variable names listed in :attr:`_ignore_`.
-
-Note:  if your enumeration defines :meth:`__new__` and/or :meth:`__init__` then
-any value(s) given to the enum member will be passed into those methods.
-See `Planet`_ for an example.
-
-
-Restricted Enum subclassing
----------------------------
-
-A new :class:`Enum` class must have one base Enum class, up to one concrete
-data type, and as many :class:`object`-based mixin classes as needed.  The
-order of these base classes is::
-
-    class EnumName([mix-in, ...,] [data-type,] base-enum):
-        pass
-
-Also, subclassing an enumeration is allowed only if the enumeration does not define
-any members.  So this is forbidden::
-
-    >>> class MoreColor(Color):
-    ...     PINK = 17
-    ...
-    Traceback (most recent call last):
-    ...
-    TypeError: MoreColor: cannot extend enumeration 'Color'
-
-But this is allowed::
-
-    >>> class Foo(Enum):
-    ...     def some_behavior(self):
-    ...         pass
-    ...
-    >>> class Bar(Foo):
-    ...     HAPPY = 1
-    ...     SAD = 2
-    ...
-
-Allowing subclassing of enums that define members would lead to a violation of
-some important invariants of types and instances.  On the other hand, it makes
-sense to allow sharing some common behavior between a group of enumerations.
-(See `OrderedEnum`_ for an example.)
-
-
-Pickling
---------
-
-Enumerations can be pickled and unpickled::
-
-    >>> from test.test_enum import Fruit
-    >>> from pickle import dumps, loads
-    >>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
-    True
-
-The usual restrictions for pickling apply: picklable enums must be defined in
-the top level of a module, since unpickling requires them to be importable
-from that module.
+   :class:`IntFlag`
 
-.. note::
+      Base class for creating enumerated constants that can be combined using
+      the bitwise operators without losing their :class:`IntFlag` membership.
+      :class:`IntFlag` members are also subclasses of :class:`int`.
 
-    With pickle protocol version 4 it is possible to easily pickle enums
-    nested in other classes.
+   :class:`FlagBoundary`
 
-It is possible to modify how Enum members are pickled/unpickled by defining
-:meth:`__reduce_ex__` in the enumeration class.
+      An enumeration with the values ``STRICT``, ``CONFORM``, ``EJECT``, and
+      ``KEEP`` which allows for more fine-grained control over how invalid values
+      are dealt with in an enumeration.
 
+   :class:`auto`
 
-Functional API
---------------
+      Instances are replaced with an appropriate value for Enum members.
+      :class:`StrEnum` defaults to the lower-cased version of the member name,
+      while other Enums default to 1 and increase from there.
 
-The :class:`Enum` class is callable, providing the following functional API::
+   :func:`global_enum`
 
-    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
-    >>> Animal
-    <enum 'Animal'>
-    >>> Animal.ANT
-    <Animal.ANT: 1>
-    >>> Animal.ANT.value
-    1
-    >>> list(Animal)
-    [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
+      :class:`Enum` class decorator to apply the appropriate global `__repr__`,
+      and export its members into the global name space.
 
-The semantics of this API resemble :class:`~collections.namedtuple`. The first
-argument of the call to :class:`Enum` is the name of the enumeration.
+   :func:`property`
 
-The second argument is the *source* of enumeration member names.  It can be a
-whitespace-separated string of names, a sequence of names, a sequence of
-2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to
-values.  The last two options enable assigning arbitrary values to
-enumerations; the others auto-assign increasing integers starting with 1 (use
-the ``start`` parameter to specify a different starting value).  A
-new class derived from :class:`Enum` is returned.  In other words, the above
-assignment to :class:`Animal` is equivalent to::
+      Allows :class:`Enum` members to have attributes without conflicting with
+      other members' names.
 
-    >>> class Animal(Enum):
-    ...     ANT = 1
-    ...     BEE = 2
-    ...     CAT = 3
-    ...     DOG = 4
-    ...
+   :func:`unique`
 
-The reason for defaulting to ``1`` as the starting number and not ``0`` is
-that ``0`` is ``False`` in a boolean sense, but enum members all evaluate
-to ``True``.
+      Enum class decorator that ensures only one name is bound to any one value.
 
-Pickling enums created with the functional API can be tricky as frame stack
-implementation details are used to try and figure out which module the
-enumeration is being created in (e.g. it will fail if you use a utility
-function in separate module, and also may not work on IronPython or Jython).
-The solution is to specify the module name explicitly as follows::
 
-    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)
+.. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
+.. versionadded:: 3.10  ``StrEnum``
 
-.. warning::
 
-    If ``module`` is not supplied, and Enum cannot determine what it is,
-    the new Enum members will not be unpicklable; to keep errors closer to
-    the source, pickling will be disabled.
+Data Types
+----------
 
-The new pickle protocol 4 also, in some circumstances, relies on
-:attr:`~definition.__qualname__` being set to the location where pickle will be able
-to find the class.  For example, if the class was made available in class
-SomeData in the global scope::
 
-    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')
+.. class:: EnumType
 
-The complete signature is::
+   *EnumType* is the :term:`metaclass` for *enum* enumerations.  It is possible
+   to subclass *EnumType* -- see :ref:`Subclassing EnumType <enumtype-examples>`
+   for details.
 
-    Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)
+   .. method:: EnumType.__contains__(cls, member)
 
-:value: What the new Enum class will record as its name.
+      Returns ``True`` if member belongs to the ``cls``::
 
-:names: The Enum members.  This can be a whitespace or comma separated string
-  (values will start at 1 unless otherwise specified)::
+        >>> some_var = Color.RED
+        >>> some_var in Color
+        True
 
-    'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'
+   .. method:: EnumType.__dir__(cls)
 
-  or an iterator of names::
+      Returns ``['__class__', '__doc__', '__members__', '__module__']`` and the
+      names of the members in *cls*::
 
-    ['RED', 'GREEN', 'BLUE']
+        >>> dir(Color)
+        ['BLUE', 'GREEN', 'RED', '__class__', '__doc__', '__members__', '__module__']
 
-  or an iterator of (name, value) pairs::
+   .. method:: EnumType.__getattr__(cls, name)
 
-    [('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]
+      Returns the Enum member in *cls* matching *name*, or raises an :exc:`AttributeError`::
 
-  or a mapping::
+        >>> Color.GREEN
+        Color.GREEN
 
-    {'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}
+   .. method:: EnumType.__getitem__(cls, name)
 
-:module: name of module where new Enum class can be found.
+      Returns the Enum member in *cls* matching *name*, or raises an :exc:`KeyError`::
 
-:qualname: where in module new Enum class can be found.
+        >>> Color['BLUE']
+        Color.BLUE
 
-:type: type to mix in to new Enum class.
+   .. method:: EnumType.__iter__(cls)
 
-:start: number to start counting at if only names are passed in.
+      Returns each member in *cls* in definition order::
 
-.. versionchanged:: 3.5
-   The *start* parameter was added.
+        >>> list(Color)
+        [Color.RED, Color.GREEN, Color.BLUE]
 
+   .. method:: EnumType.__len__(cls)
 
-Derived Enumerations
---------------------
+      Returns the number of member in *cls*::
 
-IntEnum
-^^^^^^^
+        >>> len(Color)
+        3
 
-The first variation of :class:`Enum` that is provided is also a subclass of
-:class:`int`.  Members of an :class:`IntEnum` can be compared to integers;
-by extension, integer enumerations of different types can also be compared
-to each other::
+   .. method:: EnumType.__reversed__(cls)
 
-    >>> from enum import IntEnum
-    >>> class Shape(IntEnum):
-    ...     CIRCLE = 1
-    ...     SQUARE = 2
-    ...
-    >>> class Request(IntEnum):
-    ...     POST = 1
-    ...     GET = 2
-    ...
-    >>> Shape == 1
-    False
-    >>> Shape.CIRCLE == 1
-    True
-    >>> Shape.CIRCLE == Request.POST
-    True
+      Returns each member in *cls* in reverse definition order::
 
-However, they still can't be compared to standard :class:`Enum` enumerations::
+        >>> list(reversed(Color))
+        [Color.BLUE, Color.GREEN, Color.RED]
 
-    >>> class Shape(IntEnum):
-    ...     CIRCLE = 1
-    ...     SQUARE = 2
-    ...
-    >>> class Color(Enum):
-    ...     RED = 1
-    ...     GREEN = 2
-    ...
-    >>> Shape.CIRCLE == Color.RED
-    False
 
-:class:`IntEnum` values behave like integers in other ways you'd expect::
+.. class:: Enum
 
-    >>> int(Shape.CIRCLE)
-    1
-    >>> ['a', 'b', 'c'][Shape.CIRCLE]
-    'b'
-    >>> [i for i in range(Shape.SQUARE)]
-    [0, 1]
+   *Enum* is the base class for all *enum* enumerations.
 
+   .. attribute:: Enum.name
 
-StrEnum
-^^^^^^^
+      The name used to define the ``Enum`` member::
 
-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.  :class:`StrEnum` exists to help avoid the problem of getting
-an incorrect member::
+        >>> Color.BLUE.name
+        'BLUE'
 
-    >>> from enum import StrEnum
-    >>> class Directions(StrEnum):
-    ...     NORTH = 'north',    # notice the trailing comma
-    ...     SOUTH = 'south'
+   .. attribute:: Enum.value
 
-Before :class:`StrEnum`, ``Directions.NORTH`` would have been the :class:`tuple`
-``('north',)``.
+      The value given to the ``Enum`` member::
 
-.. note::
+         >>> Color.RED.value
+         1
 
-    Unlike other Enum's, ``str(StrEnum.member)`` will return the value of the
-    member instead of the usual ``"EnumClass.member"``.
+      .. note:: Enum member values
 
-.. versionadded:: 3.10
+         Member values can be anything: :class:`int`, :class:`str`, etc..  If
+         the exact value is unimportant you may use :class:`auto` instances and an
+         appropriate value will be chosen for you.  Care must be taken if you mix
+         :class:`auto` with other values.
 
+   .. attribute:: Enum._ignore_
 
-IntFlag
-^^^^^^^
+      ``_ignore_`` is only used during creation and is removed from the
+      enumeration once that is complete.
 
-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.  However, as the name implies, :class:`IntFlag`
-members also subclass :class:`int` and can be used wherever an :class:`int` is
-used.
+      ``_ignore_`` is a list of names that will not become members, and whose
+      names will also be removed from the completed enumeration.  See
+      :ref:`TimePeriod <enum-time-period>` for an example.
 
-.. note::
+   .. method:: Enum.__call__(cls, value, names=None, \*, module=None, qualname=None, type=None, start=1, boundary=None)
 
-    Any operation on an :class:`IntFlag` member besides the bit-wise operations will
-    lose the :class:`IntFlag` membership.
+      This method is called in two different ways:
 
-.. note::
+      * to look up an existing member:
 
-    Bit-wise operations that result in invalid :class:`IntFlag` values will lose the
-    :class:`IntFlag` membership.
-
-.. versionadded:: 3.6
-.. versionchanged:: 3.10
-
-Sample :class:`IntFlag` class::
-
-    >>> from enum import IntFlag
-    >>> class Perm(IntFlag):
-    ...     R = 4
-    ...     W = 2
-    ...     X = 1
-    ...
-    >>> Perm.R | Perm.W
-    <Perm.R|W: 6>
-    >>> Perm.R + Perm.W
-    6
-    >>> RW = Perm.R | Perm.W
-    >>> Perm.R in RW
-    True
-
-It is also possible to name the combinations::
-
-    >>> class Perm(IntFlag):
-    ...     R = 4
-    ...     W = 2
-    ...     X = 1
-    ...     RWX = 7
-    >>> Perm.RWX
-    <Perm.RWX: 7>
-    >>> ~Perm.RWX
-    <Perm: 0>
-    >>> Perm(7)
-    <Perm.RWX: 7>
+         :cls:   The enum class being called.
+         :value: The value to lookup.
+
+      * to use the ``cls`` enum to create a new enum:
+
+         :cls:   The enum class being called.
+         :value: The name of the new Enum to create.
+         :names: The names/values of the members for the new Enum.
+         :module:    The name of the module the new Enum is created in.
+         :qualname:  The actual location in the module where this Enum can be found.
+         :type:  A mix-in type for the new Enum.
+         :start: The first integer value for the Enum (used by :class:`auto`)
+         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only)
+
+   .. method:: Enum.__dir__(self)
+
+      Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
+      any public methods defined on *self.__class__*::
+
+         >>> from datetime import date
+         >>> class Weekday(Enum):
+         ...     MONDAY = 1
+         ...     TUESDAY = 2
+         ...     WEDNESDAY = 3
+         ...     THURSDAY = 4
+         ...     FRIDAY = 5
+         ...     SATURDAY = 6
+         ...     SUNDAY = 7
+         ...     @classmethod
+         ...     def today(cls):
+         ...         print('today is %s' % cls(date.today.isoweekday).naem)
+         >>> dir(Weekday.SATURDAY)
+         ['__class__', '__doc__', '__module__', 'name', 'today', 'value']
+
+   .. method:: Enum._generate_next_value_(name, start, count, last_values)
+
+         :name: The name of the member being defined (e.g. 'RED').
+         :start: The start value for the Enum; the default is 1.
+         :count: The number of members currently defined, not including this one.
+         :last_values: A list of the previous values.
+
+      A *staticmethod* that is used to determine the next value returned by
+      :class:`auto`::
+
+         >>> from enum import auto
+         >>> class PowersOfThree(Enum):
+         ...     @staticmethod
+         ...     def _generate_next_value_(name, start, count, last_values):
+         ...         return (count + 1) * 3
+         ...     FIRST = auto()
+         ...     SECOND = auto()
+         >>> PowersOfThree.SECOND.value
+         6
+
+   .. method:: Enum._missing_(cls, value)
+
+      A *classmethod* for looking up values not found in *cls*.  By default it
+      does nothing, but can be overridden to implement custom search behavior::
+
+         >>> from enum import StrEnum
+         >>> class Build(StrEnum):
+         ...     DEBUG = auto()
+         ...     OPTIMIZED = auto()
+         ...     @classmethod
+         ...     def _missing_(cls, value):
+         ...         value = value.lower()
+         ...         for member in cls:
+         ...             if member.value == value:
+         ...                 return member
+         ...         return None
+         >>> Build.DEBUG.value
+         'debug'
+         >>> Build('deBUG')
+         Build.DEBUG
+
+   .. method:: Enum.__repr__(self)
+
+      Returns the string used for *repr()* calls.  By default, returns the
+      *Enum* name and the member name, but can be overridden::
+
+         >>> class OldStyle(Enum):
+         ...     RETRO = auto()
+         ...     OLD_SCHOOl = auto()
+         ...     YESTERYEAR = auto()
+         ...     def __repr__(self):
+         ...         cls_name = self.__class__.__name__
+         ...         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
+      member name, but can be overridden::
+
+         >>> class OldStyle(Enum):
+         ...     RETRO = auto()
+         ...     OLD_SCHOOl = auto()
+         ...     YESTERYEAR = auto()
+         ...     def __str__(self):
+         ...         cls_name = self.__class__.__name__
+         ...         return f'{cls_name}.{self.name}'
+         >>> OldStyle.RETRO
+         OldStyle.RETRO
 
 .. note::
 
-    Named combinations are considered aliases.  Aliases do not show up during
-    iteration, but can be returned from by-value lookups.
-
-.. versionchanged:: 3.10
-
-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>
-    >>> bool(Perm.R & Perm.X)
-    False
+   Using :class:`auto` with :class:`Enum` results in integers of increasing value,
+   starting with ``1``.
 
-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>
+.. class:: IntEnum
 
-    >>> Perm.X | 8
-    9
+   *IntEnum* is the same as *Enum*, but its members are also integers and can be
+   used anywhere that an integer can be used.  If any integer operation is performed
+   with an *IntEnum* member, the resulting value loses its enumeration status.
+
+      >>> from enum import IntEnum
+      >>> class Numbers(IntEnum):
+      ...     ONE = 1
+      ...     TWO = 2
+      ...     THREE = 3
+      >>> Numbers.THREE
+      Numbers.THREE
+      >>> Numbers.ONE + Numbers.TWO
+      3
+      >>> Numbers.THREE + 5
+      8
+      >>> Numbers.THREE == 3
+      True
 
 .. note::
 
-    The negation operator, ``~``, always returns an :class:`IntFlag` member with a
-    positive value::
-
-        >>> (~Perm.X).value == (Perm.R|Perm.W).value == 6
-        True
-
-:class:`IntFlag` members can also be iterated over::
-
-    >>> list(RW)
-    [<Perm.R: 4>, <Perm.W: 2>]
-
-.. versionadded:: 3.10
-
-
-Flag
-^^^^
+   Using :class:`auto` with :class:`IntEnum` results in integers of increasing value,
+   starting with ``1``.
 
-The last variation is :class:`Flag`.  Like :class:`IntFlag`, :class:`Flag`
-members can be combined using the bitwise operators (&, \|, ^, ~).  Unlike
-:class:`IntFlag`, they cannot be combined with, nor compared against, any
-other :class:`Flag` enumeration, nor :class:`int`.  While it is possible to
-specify the values directly it is recommended to use :class:`auto` as the
-value and let :class:`Flag` select an appropriate value.
 
-.. versionadded:: 3.6
-
-Like :class:`IntFlag`, if a combination of :class:`Flag` members results in no
-flags being set, the boolean evaluation is :data:`False`::
-
-    >>> from enum import Flag, auto
-    >>> class Color(Flag):
-    ...     RED = auto()
-    ...     BLUE = auto()
-    ...     GREEN = auto()
-    ...
-    >>> Color.RED & Color.GREEN
-    <Color: 0>
-    >>> bool(Color.RED & Color.GREEN)
-    False
-
-Individual flags should have values that are powers of two (1, 2, 4, 8, ...),
-while combinations of flags won't::
-
-    >>> class Color(Flag):
-    ...     RED = auto()
-    ...     BLUE = auto()
-    ...     GREEN = auto()
-    ...     WHITE = RED | BLUE | GREEN
-    ...
-    >>> Color.WHITE
-    <Color.WHITE: 7>
-
-Giving a name to the "no flags set" condition does not change its boolean
-value::
-
-    >>> class Color(Flag):
-    ...     BLACK = 0
-    ...     RED = auto()
-    ...     BLUE = auto()
-    ...     GREEN = auto()
-    ...
-    >>> Color.BLACK
-    <Color.BLACK: 0>
-    >>> bool(Color.BLACK)
-    False
-
-:class:`Flag` members can also be iterated over::
-
-    >>> purple = Color.RED | Color.BLUE
-    >>> list(purple)
-    [<Color.RED: 1>, <Color.BLUE: 2>]
-
-.. versionadded:: 3.10
-
-.. note::
+.. class:: StrEnum
 
-    For the majority of new code, :class:`Enum` and :class:`Flag` are strongly
-    recommended, since :class:`IntEnum` and :class:`IntFlag` break some
-    semantic promises of an enumeration (by being comparable to integers, and
-    thus by transitivity to other unrelated enumerations).  :class:`IntEnum`
-    and :class:`IntFlag` should be used only in cases where :class:`Enum` and
-    :class:`Flag` will not do; for example, when integer constants are replaced
-    with enumerations, or for interoperability with other systems.
-
-
-Others
-^^^^^^
-
-While :class:`IntEnum` is part of the :mod:`enum` module, it would be very
-simple to implement independently::
-
-    class IntEnum(int, Enum):
-        pass
-
-This demonstrates how similar derived enumerations can be defined; for example
-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. 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
-   add methods and don't specify another type.
-3. 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.
-4. %-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.
-5. :ref:`Formatted string literals <f-strings>`, :meth:`str.format`,
-   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__`
-------------------------------------------------
-
-:meth:`__new__` must be used whenever you want to customize the actual value of
-the :class:`Enum` member.  Any other modifications may go in either
-:meth:`__new__` or :meth:`__init__`, with :meth:`__init__` being preferred.
-
-For example, if you want to pass several items to the constructor, but only
-want one of them to be the value::
-
-    >>> class Coordinate(bytes, Enum):
-    ...     """
-    ...     Coordinate with binary codes that can be indexed by the int code.
-    ...     """
-    ...     def __new__(cls, value, label, unit):
-    ...         obj = bytes.__new__(cls, [value])
-    ...         obj._value_ = value
-    ...         obj.label = label
-    ...         obj.unit = unit
-    ...         return obj
-    ...     PX = (0, 'P.X', 'km')
-    ...     PY = (1, 'P.Y', 'km')
-    ...     VX = (2, 'V.X', 'km/s')
-    ...     VY = (3, 'V.Y', 'km/s')
-    ...
-
-    >>> print(Coordinate['PY'])
-    Coordinate.PY
-
-    >>> print(Coordinate(3))
-    Coordinate.VY
-
-Interesting examples
---------------------
-
-While :class:`Enum`, :class:`IntEnum`, :class:`IntFlag`, and :class:`Flag` are
-expected to cover the majority of use-cases, they cannot cover them all.  Here
-are recipes for some different types of enumerations that can be used directly,
-or as examples for creating one's own.
-
-
-Omitting values
-^^^^^^^^^^^^^^^
-
-In many use-cases one doesn't care what the actual value of an enumeration
-is. There are several ways to define this type of simple enumeration:
-
-- use instances of :class:`auto` for the value
-- use instances of :class:`object` as the value
-- use a descriptive string as the value
-- use a tuple as the value and a custom :meth:`__new__` to replace the
-  tuple with an :class:`int` value
-
-Using any of these methods signifies to the user that these values are not
-important, and also enables one to add, remove, or reorder members without
-having to renumber the remaining members.
-
-Whichever method you choose, you should provide a :meth:`repr` that also hides
-the (unimportant) value::
-
-    >>> class NoValue(Enum):
-    ...     def __repr__(self):
-    ...         return '<%s.%s>' % (self.__class__.__name__, self.name)
-    ...
-
-
-Using :class:`auto`
-"""""""""""""""""""
-
-Using :class:`auto` would look like::
-
-    >>> class Color(NoValue):
-    ...     RED = auto()
-    ...     BLUE = auto()
-    ...     GREEN = auto()
-    ...
-    >>> Color.GREEN
-    <Color.GREEN>
-
-
-Using :class:`object`
-"""""""""""""""""""""
-
-Using :class:`object` would look like::
-
-    >>> class Color(NoValue):
-    ...     RED = object()
-    ...     GREEN = object()
-    ...     BLUE = object()
-    ...
-    >>> Color.GREEN
-    <Color.GREEN>
-
-
-Using a descriptive string
-""""""""""""""""""""""""""
-
-Using a string as the value would look like::
-
-    >>> class Color(NoValue):
-    ...     RED = 'stop'
-    ...     GREEN = 'go'
-    ...     BLUE = 'too fast!'
-    ...
-    >>> Color.GREEN
-    <Color.GREEN>
-    >>> Color.GREEN.value
-    'go'
-
-
-Using a custom :meth:`__new__`
-""""""""""""""""""""""""""""""
-
-Using an auto-numbering :meth:`__new__` would look like::
-
-    >>> class AutoNumber(NoValue):
-    ...     def __new__(cls):
-    ...         value = len(cls.__members__) + 1
-    ...         obj = object.__new__(cls)
-    ...         obj._value_ = value
-    ...         return obj
-    ...
-    >>> class Color(AutoNumber):
-    ...     RED = ()
-    ...     GREEN = ()
-    ...     BLUE = ()
-    ...
-    >>> Color.GREEN
-    <Color.GREEN>
-    >>> Color.GREEN.value
-    2
-
-To make a more general purpose ``AutoNumber``, add ``*args`` to the signature::
-
-    >>> class AutoNumber(NoValue):
-    ...     def __new__(cls, *args):      # this is the only change from above
-    ...         value = len(cls.__members__) + 1
-    ...         obj = object.__new__(cls)
-    ...         obj._value_ = value
-    ...         return obj
-    ...
-
-Then when you inherit from ``AutoNumber`` you can write your own ``__init__``
-to handle any extra arguments::
-
-    >>> class Swatch(AutoNumber):
-    ...     def __init__(self, pantone='unknown'):
-    ...         self.pantone = pantone
-    ...     AUBURN = '3497'
-    ...     SEA_GREEN = '1246'
-    ...     BLEACHED_CORAL = () # New color, no Pantone code yet!
-    ...
-    >>> Swatch.SEA_GREEN
-    <Swatch.SEA_GREEN>
-    >>> Swatch.SEA_GREEN.pantone
-    '1246'
-    >>> Swatch.BLEACHED_CORAL.pantone
-    'unknown'
+   *StrEnum* is the same as *Enum*, but its members are also strings and can be used
+   in most of the same places that a string can be used.  The result of any string
+   operation performed on or with a *StrEnum* member is not part of the enumeration.
 
-.. note::
+   .. note:: There are places in the stdlib that check for an exact :class:`str`
+             instead of a :class:`str` subclass (i.e. ``type(unknown) == str``
+             instead of ``isinstance(str, unknown)``), and in those locations you
+             will need to use ``str(StrEnum.member)``.
 
-    The :meth:`__new__` method, if defined, is used during creation of the Enum
-    members; it is then replaced by Enum's :meth:`__new__` which is used after
-    class creation for lookup of existing members.
-
-
-OrderedEnum
-^^^^^^^^^^^
-
-An ordered enumeration that is not based on :class:`IntEnum` and so maintains
-the normal :class:`Enum` invariants (such as not being comparable to other
-enumerations)::
-
-    >>> class OrderedEnum(Enum):
-    ...     def __ge__(self, other):
-    ...         if self.__class__ is other.__class__:
-    ...             return self.value >= other.value
-    ...         return NotImplemented
-    ...     def __gt__(self, other):
-    ...         if self.__class__ is other.__class__:
-    ...             return self.value > other.value
-    ...         return NotImplemented
-    ...     def __le__(self, other):
-    ...         if self.__class__ is other.__class__:
-    ...             return self.value <= other.value
-    ...         return NotImplemented
-    ...     def __lt__(self, other):
-    ...         if self.__class__ is other.__class__:
-    ...             return self.value < other.value
-    ...         return NotImplemented
-    ...
-    >>> class Grade(OrderedEnum):
-    ...     A = 5
-    ...     B = 4
-    ...     C = 3
-    ...     D = 2
-    ...     F = 1
-    ...
-    >>> Grade.C < Grade.A
-    True
-
-
-DuplicateFreeEnum
-^^^^^^^^^^^^^^^^^
-
-Raises an error if a duplicate member name is found instead of creating an
-alias::
-
-    >>> class DuplicateFreeEnum(Enum):
-    ...     def __init__(self, *args):
-    ...         cls = self.__class__
-    ...         if any(self.value == e.value for e in cls):
-    ...             a = self.name
-    ...             e = cls(self.value).name
-    ...             raise ValueError(
-    ...                 "aliases not allowed in DuplicateFreeEnum:  %r --> %r"
-    ...                 % (a, e))
-    ...
-    >>> class Color(DuplicateFreeEnum):
-    ...     RED = 1
-    ...     GREEN = 2
-    ...     BLUE = 3
-    ...     GRENE = 2
-    ...
-    Traceback (most recent call last):
-    ...
-    ValueError: aliases not allowed in DuplicateFreeEnum:  'GRENE' --> 'GREEN'
 
 .. note::
 
-    This is a useful example for subclassing Enum to add or change other
-    behaviors as well as disallowing aliases.  If the only desired change is
-    disallowing aliases, the :func:`unique` decorator can be used instead.
-
-
-Planet
-^^^^^^
-
-If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member
-will be passed to those methods::
-
-    >>> class Planet(Enum):
-    ...     MERCURY = (3.303e+23, 2.4397e6)
-    ...     VENUS   = (4.869e+24, 6.0518e6)
-    ...     EARTH   = (5.976e+24, 6.37814e6)
-    ...     MARS    = (6.421e+23, 3.3972e6)
-    ...     JUPITER = (1.9e+27,   7.1492e7)
-    ...     SATURN  = (5.688e+26, 6.0268e7)
-    ...     URANUS  = (8.686e+25, 2.5559e7)
-    ...     NEPTUNE = (1.024e+26, 2.4746e7)
-    ...     def __init__(self, mass, radius):
-    ...         self.mass = mass       # in kilograms
-    ...         self.radius = radius   # in meters
-    ...     @property
-    ...     def surface_gravity(self):
-    ...         # universal gravitational constant  (m3 kg-1 s-2)
-    ...         G = 6.67300E-11
-    ...         return G * self.mass / (self.radius * self.radius)
-    ...
-    >>> Planet.EARTH.value
-    (5.976e+24, 6378140.0)
-    >>> Planet.EARTH.surface_gravity
-    9.802652743337129
+   Using :class:`auto` with :class:`StrEnum` results in values of the member name,
+   lower-cased.
 
 
-TimePeriod
-^^^^^^^^^^
+.. class:: Flag
 
-An example to show the :attr:`_ignore_` attribute in use::
+   *Flag* members support the bitwise operators ``&`` (*AND*), ``|`` (*OR*),
+   ``^`` (*XOR*), and ``~`` (*INVERT*); the results of those operators are members
+   of the enumeration.
 
-    >>> from datetime import timedelta
-    >>> class Period(timedelta, Enum):
-    ...     "different lengths of time"
-    ...     _ignore_ = 'Period i'
-    ...     Period = vars()
-    ...     for i in range(367):
-    ...         Period['day_%d' % i] = i
-    ...
-    >>> list(Period)[:2]
-    [<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
-    >>> list(Period)[-2:]
-    [<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]
+   .. method:: __contains__(self, value)
 
+      Returns *True* if value is in self::
 
-How are Enums different?
-------------------------
+         >>> from enum import Flag, auto
+         >>> class Color(Flag):
+         ...     RED = auto()
+         ...     GREEN = auto()
+         ...     BLUE = auto()
+         >>> purple = Color.RED | Color.BLUE
+         >>> white = Color.RED | Color.GREEN | Color.BLUE
+         >>> Color.GREEN in purple
+         False
+         >>> Color.GREEN in white
+         True
+         >>> purple in white
+         True
+         >>> white in purple
+         False
 
-Enums have a custom metaclass that affects many aspects of both derived Enum
-classes and their instances (members).
+   .. method:: __iter__(self):
 
+      Returns all contained members::
 
-Enum Classes
-^^^^^^^^^^^^
+         >>> list(Color.RED)
+         [Color.RED]
+         >>> list(purple)
+         [Color.RED, Color.BLUE]
 
-The :class:`EnumMeta` metaclass is responsible for providing the
-:meth:`__contains__`, :meth:`__dir__`, :meth:`__iter__` and other methods that
-allow one to do things with an :class:`Enum` class that fail on a typical
-class, such as `list(Color)` or `some_enum_var in Color`.  :class:`EnumMeta` is
-responsible for ensuring that various other methods on the final :class:`Enum`
-class are correct (such as :meth:`__new__`, :meth:`__getnewargs__`,
-:meth:`__str__` and :meth:`__repr__`).
+   .. method:: __len__(self):
 
+      Returns number of members in flag::
 
-Enum Members (aka instances)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+         >>> len(Color.GREEN)
+         1
+         >>> len(white)
+         3
 
-The most interesting thing about Enum members is that they are singletons.
-:class:`EnumMeta` creates them all while it is creating the :class:`Enum`
-class itself, and then puts a custom :meth:`__new__` in place to ensure
-that no new ones are ever instantiated by returning only the existing
-member instances.
+   .. method:: __bool__(self):
 
+      Returns *True* if any members in flag, *False* otherwise::
 
-Finer Points
-^^^^^^^^^^^^
+         >>> bool(Color.GREEN)
+         True
+         >>> bool(white)
+         True
+         >>> black = Color(0)
+         >>> bool(black)
+         False
 
-Supported ``__dunder__`` names
-""""""""""""""""""""""""""""""
+   .. method:: __or__(self, other)
 
-:attr:`__members__` is a read-only ordered mapping of ``member_name``:``member``
-items.  It is only available on the class.
+      Returns current flag binary or'ed with other::
 
-: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.
+         >>> Color.RED | Color.GREEN
+         Color.RED|Color.GREEN
 
+   .. method:: __and__(self, other)
 
-Supported ``_sunder_`` names
-""""""""""""""""""""""""""""
+      Returns current flag binary and'ed with other::
 
-- ``_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 by the `Functional API`_ and by
-  :class:`auto` to get an appropriate value for an enum member; may be
-  overridden
+         >>> purple & white
+         Color.RED|Color.BLUE
+         >>> purple & Color.GREEN
+         0x0
 
-.. note::
+   .. method:: __xor__(self, other)
 
-    For standard :class:`Enum` classes the next value chosen is the last value seen
-    incremented by one.
+      Returns current flag binary xor'ed with other::
 
-    For :class:`Flag`-type classes the next value chosen will be the next highest
-    power-of-two, regardless of the last value seen.
+         >>> purple ^ white
+         Color.GREEN
+         >>> purple ^ Color.GREEN
+         Color.RED|Color.GREEN|Color.BLUE
 
-.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
-.. versionadded:: 3.7 ``_ignore_``
+   .. method:: __invert__(self):
 
-To help keep Python 2 / Python 3 code in sync an :attr:`_order_` attribute can
-be provided.  It will be checked against the actual order of the enumeration
-and raise an error if the two do not match::
+      Returns all the flags in *type(self)* that are not in self::
 
-    >>> class Color(Enum):
-    ...     _order_ = 'RED GREEN BLUE'
-    ...     RED = 1
-    ...     BLUE = 3
-    ...     GREEN = 2
-    ...
-    Traceback (most recent call last):
-    ...
-    TypeError: member order does not match _order_:
-    ['RED', 'BLUE', 'GREEN']
-    ['RED', 'GREEN', 'BLUE']
+         >>> ~white
+         0x0
+         >>> ~purple
+         Color.GREEN
+         >>> ~Color.RED
+         Color.GREEN|Color.BLUE
 
 .. note::
 
-    In Python 2 code the :attr:`_order_` attribute is necessary as definition
-    order is lost before it can be recorded.
-
-
-_Private__names
-"""""""""""""""
-
-Private names are not converted to Enum members, but remain normal attributes.
-
-.. versionchanged:: 3.10
-
-
-``Enum`` member type
-""""""""""""""""""""
+   Using :class:`auto` with :class:`Flag` results in integers that are powers
+   of two, starting with ``1``.
 
-:class:`Enum` members are instances of their :class:`Enum` class, and are
-normally accessed as ``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       # 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.10
-
-
-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
-constructor.  For example::
+.. class:: IntFlag
 
-    >>> class MyEnum(IntEnum):
-    ...     example = '11', 16      # '11' will be interpreted as a hexadecimal
-    ...                             # number
-    >>> MyEnum.example
-    <MyEnum.example: 17>
+   *IntFlag* is the same as *Flag*, but its members are also integers and can be
+   used anywhere that an integer can be used.
 
+      >>> from enum import IntFlag, auto
+      >>> class Color(IntFlag):
+      ...     RED = auto()
+      ...     GREEN = auto()
+      ...     BLUE = auto()
+      >>> Color.RED & 2
+      0x0
+      >>> Color.RED | 2
+      Color.RED|Color.GREEN
 
-Boolean value of ``Enum`` classes and members
-"""""""""""""""""""""""""""""""""""""""""""""
+   If any integer operation is performed with an *IntFlag* member, the result is
+   not an *IntFlag*::
 
-:class:`Enum` members that are mixed with non-:class:`Enum` types (such as
-:class:`int`, :class:`str`, etc.) are evaluated according to the mixed-in
-type's rules; otherwise, all members evaluate as :data:`True`.  To make your
-own Enum's boolean evaluation depend on the member's value add the following to
-your class::
+        >>> Color.RED + 2
+        3
 
-    def __bool__(self):
-        return bool(self.value)
+   If a *Flag* operation is performed with an *IntFlag* member and:
 
-:class:`Enum` classes always evaluate as :data:`True`.
+      * the result is a valid *IntFlag*: an *IntFlag* is returned
+      * the result is not a valid *IntFlag*: the result depends on the *FlagBoundary* setting
 
+.. note::
 
-``Enum`` classes with methods
-"""""""""""""""""""""""""""""
+   Using :class:`auto` with :class:`IntFlag` results in integers that are powers
+   of two, starting with ``1``.
 
-If you give your :class:`Enum` subclass extra methods, like the `Planet`_
-class above, those methods will show up in a :func:`dir` of the member,
-but not of the class::
+.. class:: FlagBoundary
 
-    >>> dir(Planet)
-    ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
-    >>> dir(Planet.EARTH)
-    ['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', 'surface_gravity', 'value']
+   *FlagBoundary* controls how out-of-range values are handled in *Flag* and its
+   subclasses.
 
+   .. attribute:: STRICT
 
-Combining members of ``Flag``
-"""""""""""""""""""""""""""""
+      Out-of-range values cause a :exc:`ValueError` to be raised.  This is the
+      default for :class:`Flag`::
 
-Iterating over a combination of Flag members will only return the members that
-are comprised of a single bit::
+         >>> from enum import STRICT
+         >>> class StrictFlag(Flag, boundary=STRICT):
+         ...     RED = auto()
+         ...     GREEN = auto()
+         ...     BLUE = auto()
+         >>> StrictFlag(2**2 + 2**4)
+         Traceback (most recent call last):
+         ...
+         ValueError: StrictFlag: invalid value: 20
+             given 0b0 10100
+           allowed 0b0 00111
 
-    >>> class Color(Flag):
-    ...     RED = auto()
-    ...     GREEN = auto()
-    ...     BLUE = auto()
-    ...     MAGENTA = RED | BLUE
-    ...     YELLOW = RED | GREEN
-    ...     CYAN = GREEN | BLUE
-    ...
-    >>> Color(3)
-    <Color.YELLOW: 3>
-    >>> Color(7)
-    <Color.RED|GREEN|BLUE: 7>
+   .. attribute:: CONFORM
 
-``StrEnum`` and :meth:`str.__str__`
-"""""""""""""""""""""""""""""""""""
+      Out-of-range values have invalid values removed, leaving a valid *Flag*
+      value::
 
-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.
+         >>> from enum import CONFORM
+         >>> class ConformFlag(Flag, boundary=CONFORM):
+         ...     RED = auto()
+         ...     GREEN = auto()
+         ...     BLUE = auto()
+         >>> ConformFlag(2**2 + 2**4)
+         ConformFlag.BLUE
 
-``Flag`` and ``IntFlag`` minutia
-""""""""""""""""""""""""""""""""
+   .. attribute:: EJECT
 
-The code sample::
+      Out-of-range values lose their *Flag* membership and revert to :class:`int`.
+      This is the default for :class:`IntFlag`::
 
-    >>> class Color(IntFlag):
-    ...     BLACK = 0
-    ...     RED = 1
-    ...     GREEN = 2
-    ...     BLUE = 4
-    ...     PURPLE = RED | BLUE
-    ...     WHITE = RED | GREEN | BLUE
-    ...
+         >>> from enum import EJECT
+         >>> class EjectFlag(Flag, boundary=EJECT):
+         ...     RED = auto()
+         ...     GREEN = auto()
+         ...     BLUE = auto()
+         >>> EjectFlag(2**2 + 2**4)
+         20
 
-- single-bit flags are canonical
-- multi-bit and zero-bit flags are aliases
-- only canonical flags are returned during iteration::
+   .. attribute:: KEEP
 
-    >>> list(Color.WHITE)
-    [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
+      Out-of-range values are kept, and the *Flag* membership is kept.  This is
+      used for some stdlib flags:
 
-- negating a flag or flag set returns a new flag/flag set with the
-  corresponding positive integer value::
+         >>> from enum import KEEP
+         >>> class KeepFlag(Flag, boundary=KEEP):
+         ...     RED = auto()
+         ...     GREEN = auto()
+         ...     BLUE = auto()
+         >>> KeepFlag(2**2 + 2**4)
+         KeepFlag.BLUE|0x10
 
-    >>> Color.GREEN
-    <Color.GREEN: 2>
 
-    >>> ~Color.GREEN
-    <Color.PURPLE: 5>
+Utilites and Decorators
+-----------------------
 
-- names of pseudo-flags are constructed from their members' names::
+.. class:: auto
 
-    >>> (Color.RED | Color.GREEN).name
-    'RED|GREEN'
+   *auto* can be used in place of a value.  If used, the *Enum* machinery will
+   call an *Enum*'s :meth:`_generate_next_value_` to get an appropriate value.
+   For *Enum* and *IntEnum* that appropriate value will be the last value plus
+   one; for *Flag* and *IntFlag* it will be the first power-of-two greater
+   than the last value; for *StrEnum* it will be the lower-cased version of the
+   member's name.
 
-- multi-bit flags, aka aliases, can be returned from operations::
+   ``_generate_next_value_`` can be overridden to customize the values used by
+   *auto*.
 
-    >>> Color.RED | Color.BLUE
-    <Color.PURPLE: 5>
+.. decorator:: global_enum
 
-    >>> Color(7)  # or Color(-1)
-    <Color.WHITE: 7>
+   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 the global namespace
+   they were defined in.
 
-- membership / containment checking has changed slightly -- zero valued flags
-  are never considered to be contained::
 
-    >>> Color.BLACK in Color.WHITE
-    False
+.. decorator:: property
 
-  otherwise, if all bits of one flag are in the other flag, True is returned::
+   A decorator similar to the built-in *property*, but specifically for
+   enumerations.  It allows member attributes to have the same names as members
+   themselves.
 
-    >>> Color.PURPLE in Color.WHITE
-    True
+   .. note:: the *property* and the member must be defined in separate classes;
+             for example, the *value* and *name* attributes are defined in the
+             *Enum* class, and *Enum* subclasses can define members with the
+             names ``value`` and ``name``.
 
-There is a new boundary mechanism that controls how out-of-range / invalid
-bits are handled: ``STRICT``, ``CONFORM``, ``EJECT``, and ``KEEP``:
+.. decorator:: unique
 
-  * STRICT --> raises an exception when presented with invalid values
-  * CONFORM --> discards any invalid bits
-  * EJECT --> lose Flag status and become a normal int with the given value
-  * KEEP --> keep the extra bits
-           - keeps Flag status and extra bits
-           - extra bits do not show up in iteration
-           - extra bits do show up in repr() and str()
+   A :keyword:`class` decorator specifically for enumerations.  It searches an
+   enumeration's :attr:`__members__`, gathering any aliases it finds; if any are
+   found :exc:`ValueError` is raised with the details::
+
+      >>> from enum import Enum, unique
+      >>> @unique
+      ... class Mistake(Enum):
+      ...     ONE = 1
+      ...     TWO = 2
+      ...     THREE = 3
+      ...     FOUR = 3
+      ...
+      Traceback (most recent call last):
+      ...
+      ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
 
-The default for Flag is ``STRICT``, the default for ``IntFlag`` is ``DISCARD``,
-and the default for ``_convert_`` is ``KEEP`` (see ``ssl.Options`` for an
-example of when ``KEEP`` is needed).
diff --git a/Doc/library/http.rst b/Doc/library/http.rst
index 14ee733..1569d50 100644
--- a/Doc/library/http.rst
+++ b/Doc/library/http.rst
@@ -35,7 +35,7 @@ associated messages through the :class:`http.HTTPStatus` enum:
 
       >>> from http import HTTPStatus
       >>> HTTPStatus.OK
-      <HTTPStatus.OK: 200>
+      HTTPStatus.OK
       >>> HTTPStatus.OK == 200
       True
       >>> HTTPStatus.OK.value
@@ -45,7 +45,7 @@ associated messages through the :class:`http.HTTPStatus` enum:
       >>> HTTPStatus.OK.description
       'Request fulfilled, document follows'
       >>> list(HTTPStatus)
-      [<HTTPStatus.CONTINUE: 100>, <HTTPStatus.SWITCHING_PROTOCOLS: 101>, ...]
+      [HTTPStatus.CONTINUE, HTTPStatus.SWITCHING_PROTOCOLS, ...]
 
 .. _http-status-codes:
 
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 31d804c..30b3c5e 100755
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -785,9 +785,9 @@ The :mod:`socket` module also offers various network-related services:
    system if IPv6 isn't enabled)::
 
       >>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
-      [(<AddressFamily.AF_INET6: 10>, <SocketType.SOCK_STREAM: 1>,
+      [(socket.AF_INET6, socket.SOCK_STREAM,
        6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
-       (<AddressFamily.AF_INET: 2>, <SocketType.SOCK_STREAM: 1>,
+       (socket.AF_INET, socket.SOCK_STREAM,
        6, '', ('93.184.216.34', 80))]
 
    .. versionchanged:: 3.2
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index c0789ee..9333168 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -2062,7 +2062,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
 
@@ -2074,7 +2074,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
 
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index e09cfb4..ea2834b 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -716,6 +716,14 @@ encodings
 :func:`encodings.normalize_encoding` now ignores non-ASCII characters.
 (Contributed by Hai Shi in :issue:`39337`.)
 
+enum
+----
+
+:class:`Enum` :func:`__repr__` now returns ``enum_name.member_name`` and
+:func:`__str__` now returns ``member_name``.  Stdlib enums available as
+module constants have a :func:`repr` of ``module_name.member_name``.
+(Contributed by Ethan Furman in :issue:`40066`.)
+
 gc
 --
 
diff --git a/Lib/enum.py b/Lib/enum.py
index 84c7b0d..f31779b 100644
--- a/Lib/enum.py
+++ b/Lib/enum.py
@@ -4,17 +4,18 @@ from builtins import property as _bltin_property, bin as _bltin_bin
 
 
 __all__ = [
-        'EnumMeta',
+        'EnumType', 'EnumMeta',
         'Enum', 'IntEnum', 'StrEnum', 'Flag', 'IntFlag',
         'auto', 'unique',
         'property',
         'FlagBoundary', 'STRICT', 'CONFORM', 'EJECT', 'KEEP',
+        'global_flag_repr', 'global_enum_repr', 'global_enum',
         ]
 
 
 # Dummy value for Enum and Flag as there are explicit checks for them
 # before they have been created.
-# This is also why there are checks in EnumMeta like `if Enum is not None`
+# This is also why there are checks in EnumType like `if Enum is not None`
 Enum = Flag = EJECT = None
 
 def _is_descriptor(obj):
@@ -285,7 +286,7 @@ class _EnumDict(dict):
     """
     Track enum member order and ensure member names are not reused.
 
-    EnumMeta will use the names found in self._member_names as the
+    EnumType will use the names found in self._member_names as the
     enumeration member names.
     """
     def __init__(self):
@@ -321,7 +322,8 @@ class _EnumDict(dict):
                 # check if members already defined as auto()
                 if self._auto_called:
                     raise TypeError("_generate_next_value_ must be defined before members")
-                setattr(self, '_generate_next_value', value)
+                _gnv = value.__func__ if isinstance(value, staticmethod) else value
+                setattr(self, '_generate_next_value', _gnv)
             elif key == '_ignore_':
                 if isinstance(value, str):
                     value = value.replace(',',' ').split()
@@ -368,7 +370,7 @@ class _EnumDict(dict):
             self[name] = value
 
 
-class EnumMeta(type):
+class EnumType(type):
     """
     Metaclass for Enum
     """
@@ -756,9 +758,9 @@ class EnumMeta(type):
         # module;
         # also, replace the __reduce_ex__ method so unpickling works in
         # previous Python versions
-        module_globals = vars(sys.modules[module])
+        module_globals = sys.modules[module].__dict__
         if source:
-            source = vars(source)
+            source = source.__dict__
         else:
             source = module_globals
         # _value2member_map_ is populated in the same order every time
@@ -776,7 +778,7 @@ class EnumMeta(type):
             members.sort(key=lambda t: t[0])
         cls = cls(name, members, module=module, boundary=boundary or KEEP)
         cls.__reduce_ex__ = _reduce_ex_by_name
-        module_globals.update(cls.__members__)
+        global_enum(cls)
         module_globals[name] = cls
         return cls
 
@@ -881,9 +883,10 @@ class EnumMeta(type):
         else:
             use_args = True
         return __new__, save_new, use_args
+EnumMeta = EnumType
 
 
-class Enum(metaclass=EnumMeta):
+class Enum(metaclass=EnumType):
     """
     Generic enumeration.
 
@@ -958,11 +961,10 @@ class Enum(metaclass=EnumMeta):
         return None
 
     def __repr__(self):
-        return "<%s.%s: %r>" % (
-                self.__class__.__name__, self._name_, self._value_)
+        return "%s.%s" % ( self.__class__.__name__, self._name_)
 
     def __str__(self):
-        return "%s.%s" % (self.__class__.__name__, self._name_)
+        return "%s" % (self._name_, )
 
     def __dir__(self):
         """
@@ -1220,19 +1222,28 @@ class Flag(Enum, boundary=STRICT):
         return self._value_.bit_count()
 
     def __repr__(self):
-        cls = self.__class__
-        if self._name_ is not None:
-            return '<%s.%s: %r>' % (cls.__name__, self._name_, self._value_)
+        cls_name = self.__class__.__name__
+        if self._name_ is None:
+            return "0x%x" % (self._value_, )
+        if _is_single_bit(self._value_):
+            return '%s.%s' % (cls_name, self._name_)
+        if self._boundary_ is not FlagBoundary.KEEP:
+            return '%s.' % cls_name + ('|%s.' % cls_name).join(self.name.split('|'))
         else:
-            # only zero is unnamed by default
-            return '<%s: %r>' % (cls.__name__, self._value_)
+            name = []
+            for n in self._name_.split('|'):
+                if n.startswith('0'):
+                    name.append(n)
+                else:
+                    name.append('%s.%s' % (cls_name, n))
+            return '|'.join(name)
 
     def __str__(self):
         cls = self.__class__
-        if self._name_ is not None:
-            return '%s.%s' % (cls.__name__, self._name_)
+        if self._name_ is None:
+            return '%s(%x)' % (cls.__name__, self._value_)
         else:
-            return '%s(%s)' % (cls.__name__, self._value_)
+            return self._name_
 
     def __bool__(self):
         return bool(self._value_)
@@ -1329,3 +1340,38 @@ def _power_of_two(value):
     if value < 1:
         return False
     return value == 2 ** _high_bit(value)
+
+def global_enum_repr(self):
+    return '%s.%s' % (self.__class__.__module__, self._name_)
+
+def global_flag_repr(self):
+    module = self.__class__.__module__
+    cls_name = self.__class__.__name__
+    if self._name_ is None:
+        return "%x" % (module, cls_name, self._value_)
+    if _is_single_bit(self):
+        return '%s.%s' % (module, self._name_)
+    if self._boundary_ is not FlagBoundary.KEEP:
+        return module + module.join(self.name.split('|'))
+    else:
+        name = []
+        for n in self._name_.split('|'):
+            if n.startswith('0'):
+                name.append(n)
+            else:
+                name.append('%s.%s' % (module, n))
+        return '|'.join(name)
+
+
+def global_enum(cls):
+    """
+    decorator that makes the repr() of an enum member reference its module
+    instead of its class; also exports all members to the enum's module's
+    global namespace
+    """
+    if issubclass(cls, Flag):
+        cls.__repr__ = global_flag_repr
+    else:
+        cls.__repr__ = global_enum_repr
+    sys.modules[cls.__module__].__dict__.update(cls.__members__)
+    return cls
diff --git a/Lib/inspect.py b/Lib/inspect.py
index 1f2cdeb..d6d2ce6 100644
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -2455,9 +2455,6 @@ class _ParameterKind(enum.IntEnum):
     KEYWORD_ONLY = 3
     VAR_KEYWORD = 4
 
-    def __str__(self):
-        return self._name_
-
     @property
     def description(self):
         return _PARAM_NAME_MAPPING[self]
diff --git a/Lib/plistlib.py b/Lib/plistlib.py
index 2eeebe4..5772efd 100644
--- a/Lib/plistlib.py
+++ b/Lib/plistlib.py
@@ -61,8 +61,7 @@ import struct
 from xml.parsers.expat import ParserCreate
 
 
-PlistFormat = enum.Enum('PlistFormat', 'FMT_XML FMT_BINARY', module=__name__)
-globals().update(PlistFormat.__members__)
+PlistFormat = enum.global_enum(enum.Enum('PlistFormat', 'FMT_XML FMT_BINARY', module=__name__))
 
 
 class UID:
diff --git a/Lib/re.py b/Lib/re.py
index a39ff04..5e40c7b 100644
--- a/Lib/re.py
+++ b/Lib/re.py
@@ -142,6 +142,7 @@ __all__ = [
 
 __version__ = "2.2.1"
 
+@enum.global_enum
 class RegexFlag(enum.IntFlag, boundary=enum.KEEP):
     ASCII = A = sre_compile.SRE_FLAG_ASCII # assume ascii "locale"
     IGNORECASE = I = sre_compile.SRE_FLAG_IGNORECASE # ignore case
@@ -154,22 +155,6 @@ class RegexFlag(enum.IntFlag, boundary=enum.KEEP):
     TEMPLATE = T = sre_compile.SRE_FLAG_TEMPLATE # disable backtracking
     DEBUG = sre_compile.SRE_FLAG_DEBUG # dump pattern after compilation
 
-    def __repr__(self):
-        res = ''
-        if self._name_:
-            member_names = self._name_.split('|')
-            constant = None
-            if member_names[-1].startswith('0x'):
-                constant = member_names.pop()
-            res = 're.' + '|re.'.join(member_names)
-            if constant:
-                res += '|%s' % constant
-        return res
-
-    __str__ = object.__str__
-
-globals().update(RegexFlag.__members__)
-
 # sre exception
 error = sre_compile.error
 
diff --git a/Lib/test/test_enum.py b/Lib/test/test_enum.py
index 69392e0..6002cd8 100644
--- a/Lib/test/test_enum.py
+++ b/Lib/test/test_enum.py
@@ -7,7 +7,7 @@ import sys
 import unittest
 import threading
 from collections import OrderedDict
-from enum import Enum, IntEnum, StrEnum, EnumMeta, Flag, IntFlag, unique, auto
+from enum import Enum, IntEnum, StrEnum, EnumType, Flag, IntFlag, unique, auto
 from enum import STRICT, CONFORM, EJECT, KEEP
 from io import StringIO
 from pickle import dumps, loads, PicklingError, HIGHEST_PROTOCOL
@@ -262,11 +262,8 @@ class TestEnum(unittest.TestCase):
             self.assertIn(e, Season)
             self.assertIs(type(e), Season)
             self.assertIsInstance(e, Season)
-            self.assertEqual(str(e), 'Season.' + season)
-            self.assertEqual(
-                    repr(e),
-                    '<Season.{0}: {1}>'.format(season, i),
-                    )
+            self.assertEqual(str(e), season)
+            self.assertEqual(repr(e), 'Season.{0}'.format(season))
 
     def test_value_name(self):
         Season = self.Season
@@ -440,7 +437,7 @@ class TestEnum(unittest.TestCase):
     def test_reserved__sunder_(self):
         with self.assertRaisesRegex(
                 ValueError,
-                "_sunder_ names, such as '_bad_', are reserved",
+                '_sunder_ names, such as ._bad_., are reserved',
             ):
             class Bad(Enum):
                 _bad_ = 1
@@ -488,7 +485,7 @@ class TestEnum(unittest.TestCase):
             two = 2.0
             def __format__(self, spec):
                 return 'Format!!'
-        self.assertEqual(str(EnumWithFormatOverride.one), 'EnumWithFormatOverride.one')
+        self.assertEqual(str(EnumWithFormatOverride.one), 'one')
         self.assertEqual('{}'.format(EnumWithFormatOverride.one), 'Format!!')
 
     def test_str_and_format_override_enum(self):
@@ -528,7 +525,7 @@ class TestEnum(unittest.TestCase):
             two = 2.0
             def __format__(self, spec):
                 return 'TestFloat success!'
-        self.assertEqual(str(TestFloat.one), 'TestFloat.one')
+        self.assertEqual(str(TestFloat.one), 'one')
         self.assertEqual('{}'.format(TestFloat.one), 'TestFloat success!')
 
     def assertFormatIsValue(self, spec, member):
@@ -614,6 +611,8 @@ class TestEnum(unittest.TestCase):
             A = 1
             B = 2
             C = 3
+            def __repr__(self):
+                return '<%s.%s: %r>' % (self.__class__.__name__, self._name_, self._value_)
         self.assertEqual(repr(MyEnum.A), '<MyEnum.A: 0x1>')
 
     def test_too_many_data_types(self):
@@ -1959,7 +1958,7 @@ class TestEnum(unittest.TestCase):
         self.assertEqual(Color.GREEN.value, 2)
         self.assertEqual(Color.BLUE.value, 3)
         self.assertEqual(Color.MAX, 3)
-        self.assertEqual(str(Color.BLUE), 'Color.BLUE')
+        self.assertEqual(str(Color.BLUE), 'BLUE')
         class Color(MaxMixin, StrMixin, Enum):
             RED = auto()
             GREEN = auto()
@@ -2330,64 +2329,62 @@ class TestFlag(unittest.TestCase):
 
     def test_str(self):
         Perm = self.Perm
-        self.assertEqual(str(Perm.R), 'Perm.R')
-        self.assertEqual(str(Perm.W), 'Perm.W')
-        self.assertEqual(str(Perm.X), 'Perm.X')
-        self.assertEqual(str(Perm.R | Perm.W), 'Perm.R|W')
-        self.assertEqual(str(Perm.R | Perm.W | Perm.X), 'Perm.R|W|X')
+        self.assertEqual(str(Perm.R), 'R')
+        self.assertEqual(str(Perm.W), 'W')
+        self.assertEqual(str(Perm.X), 'X')
+        self.assertEqual(str(Perm.R | Perm.W), 'R|W')
+        self.assertEqual(str(Perm.R | Perm.W | Perm.X), 'R|W|X')
         self.assertEqual(str(Perm(0)), 'Perm(0)')
-        self.assertEqual(str(~Perm.R), 'Perm.W|X')
-        self.assertEqual(str(~Perm.W), 'Perm.R|X')
-        self.assertEqual(str(~Perm.X), 'Perm.R|W')
-        self.assertEqual(str(~(Perm.R | Perm.W)), 'Perm.X')
+        self.assertEqual(str(~Perm.R), 'W|X')
+        self.assertEqual(str(~Perm.W), 'R|X')
+        self.assertEqual(str(~Perm.X), 'R|W')
+        self.assertEqual(str(~(Perm.R | Perm.W)), 'X')
         self.assertEqual(str(~(Perm.R | Perm.W | Perm.X)), 'Perm(0)')
-        self.assertEqual(str(Perm(~0)), 'Perm.R|W|X')
+        self.assertEqual(str(Perm(~0)), 'R|W|X')
 
         Open = self.Open
-        self.assertEqual(str(Open.RO), 'Open.RO')
-        self.assertEqual(str(Open.WO), 'Open.WO')
-        self.assertEqual(str(Open.AC), 'Open.AC')
-        self.assertEqual(str(Open.RO | Open.CE), 'Open.CE')
-        self.assertEqual(str(Open.WO | Open.CE), 'Open.WO|CE')
-        self.assertEqual(str(~Open.RO), 'Open.WO|RW|CE')
-        self.assertEqual(str(~Open.WO), 'Open.RW|CE')
-        self.assertEqual(str(~Open.AC), 'Open.CE')
-        self.assertEqual(str(~Open.CE), 'Open.AC')
-        self.assertEqual(str(~(Open.RO | Open.CE)), 'Open.AC')
-        self.assertEqual(str(~(Open.WO | Open.CE)), 'Open.RW')
+        self.assertEqual(str(Open.RO), 'RO')
+        self.assertEqual(str(Open.WO), 'WO')
+        self.assertEqual(str(Open.AC), 'AC')
+        self.assertEqual(str(Open.RO | Open.CE), 'CE')
+        self.assertEqual(str(Open.WO | Open.CE), 'WO|CE')
+        self.assertEqual(str(~Open.RO), 'WO|RW|CE')
+        self.assertEqual(str(~Open.WO), 'RW|CE')
+        self.assertEqual(str(~Open.AC), 'CE')
+        self.assertEqual(str(~(Open.RO | Open.CE)), 'AC')
+        self.assertEqual(str(~(Open.WO | Open.CE)), 'RW')
 
     def test_repr(self):
         Perm = self.Perm
-        self.assertEqual(repr(Perm.R), '<Perm.R: 4>')
-        self.assertEqual(repr(Perm.W), '<Perm.W: 2>')
-        self.assertEqual(repr(Perm.X), '<Perm.X: 1>')
-        self.assertEqual(repr(Perm.R | Perm.W), '<Perm.R|W: 6>')
-        self.assertEqual(repr(Perm.R | Perm.W | Perm.X), '<Perm.R|W|X: 7>')
-        self.assertEqual(repr(Perm(0)), '<Perm: 0>')
-        self.assertEqual(repr(~Perm.R), '<Perm.W|X: 3>')
-        self.assertEqual(repr(~Perm.W), '<Perm.R|X: 5>')
-        self.assertEqual(repr(~Perm.X), '<Perm.R|W: 6>')
-        self.assertEqual(repr(~(Perm.R | Perm.W)), '<Perm.X: 1>')
-        self.assertEqual(repr(~(Perm.R | Perm.W | Perm.X)), '<Perm: 0>')
-        self.assertEqual(repr(Perm(~0)), '<Perm.R|W|X: 7>')
+        self.assertEqual(repr(Perm.R), 'Perm.R')
+        self.assertEqual(repr(Perm.W), 'Perm.W')
+        self.assertEqual(repr(Perm.X), 'Perm.X')
+        self.assertEqual(repr(Perm.R | Perm.W), 'Perm.R|Perm.W')
+        self.assertEqual(repr(Perm.R | Perm.W | Perm.X), 'Perm.R|Perm.W|Perm.X')
+        self.assertEqual(repr(Perm(0)), '0x0')
+        self.assertEqual(repr(~Perm.R), 'Perm.W|Perm.X')
+        self.assertEqual(repr(~Perm.W), 'Perm.R|Perm.X')
+        self.assertEqual(repr(~Perm.X), 'Perm.R|Perm.W')
+        self.assertEqual(repr(~(Perm.R | Perm.W)), 'Perm.X')
+        self.assertEqual(repr(~(Perm.R | Perm.W | Perm.X)), '0x0')
+        self.assertEqual(repr(Perm(~0)), 'Perm.R|Perm.W|Perm.X')
 
         Open = self.Open
-        self.assertEqual(repr(Open.RO), '<Open.RO: 0>')
-        self.assertEqual(repr(Open.WO), '<Open.WO: 1>')
-        self.assertEqual(repr(Open.AC), '<Open.AC: 3>')
-        self.assertEqual(repr(Open.RO | Open.CE), '<Open.CE: 524288>')
-        self.assertEqual(repr(Open.WO | Open.CE), '<Open.WO|CE: 524289>')
-        self.assertEqual(repr(~Open.RO), '<Open.WO|RW|CE: 524291>')
-        self.assertEqual(repr(~Open.WO), '<Open.RW|CE: 524290>')
-        self.assertEqual(repr(~Open.AC), '<Open.CE: 524288>')
-        self.assertEqual(repr(~Open.CE), '<Open.AC: 3>')
-        self.assertEqual(repr(~(Open.RO | Open.CE)), '<Open.AC: 3>')
-        self.assertEqual(repr(~(Open.WO | Open.CE)), '<Open.RW: 2>')
+        self.assertEqual(repr(Open.RO), 'Open.RO')
+        self.assertEqual(repr(Open.WO), 'Open.WO')
+        self.assertEqual(repr(Open.AC), 'Open.AC')
+        self.assertEqual(repr(Open.RO | Open.CE), 'Open.CE')
+        self.assertEqual(repr(Open.WO | Open.CE), 'Open.WO|Open.CE')
+        self.assertEqual(repr(~Open.RO), 'Open.WO|Open.RW|Open.CE')
+        self.assertEqual(repr(~Open.WO), 'Open.RW|Open.CE')
+        self.assertEqual(repr(~Open.AC), 'Open.CE')
+        self.assertEqual(repr(~(Open.RO | Open.CE)), 'Open.AC')
+        self.assertEqual(repr(~(Open.WO | Open.CE)), 'Open.RW')
 
     def test_format(self):
         Perm = self.Perm
-        self.assertEqual(format(Perm.R, ''), 'Perm.R')
-        self.assertEqual(format(Perm.R | Perm.X, ''), 'Perm.R|X')
+        self.assertEqual(format(Perm.R, ''), 'R')
+        self.assertEqual(format(Perm.R | Perm.X, ''), 'R|X')
 
     def test_or(self):
         Perm = self.Perm
@@ -2707,7 +2704,7 @@ class TestFlag(unittest.TestCase):
         self.assertEqual(Color.GREEN.value, 2)
         self.assertEqual(Color.BLUE.value, 4)
         self.assertEqual(Color.ALL.value, 7)
-        self.assertEqual(str(Color.BLUE), 'Color.BLUE')
+        self.assertEqual(str(Color.BLUE), 'BLUE')
         class Color(AllMixin, StrMixin, Flag):
             RED = auto()
             GREEN = auto()
@@ -2850,77 +2847,70 @@ class TestIntFlag(unittest.TestCase):
 
     def test_str(self):
         Perm = self.Perm
-        self.assertEqual(str(Perm.R), 'Perm.R')
-        self.assertEqual(str(Perm.W), 'Perm.W')
-        self.assertEqual(str(Perm.X), 'Perm.X')
-        self.assertEqual(str(Perm.R | Perm.W), 'Perm.R|W')
-        self.assertEqual(str(Perm.R | Perm.W | Perm.X), 'Perm.R|W|X')
+        self.assertEqual(str(Perm.R), 'R')
+        self.assertEqual(str(Perm.W), 'W')
+        self.assertEqual(str(Perm.X), 'X')
+        self.assertEqual(str(Perm.R | Perm.W), 'R|W')
+        self.assertEqual(str(Perm.R | Perm.W | Perm.X), 'R|W|X')
         self.assertEqual(str(Perm.R | 8), '12')
         self.assertEqual(str(Perm(0)), 'Perm(0)')
         self.assertEqual(str(Perm(8)), '8')
-        self.assertEqual(str(~Perm.R), 'Perm.W|X')
-        self.assertEqual(str(~Perm.W), 'Perm.R|X')
-        self.assertEqual(str(~Perm.X), 'Perm.R|W')
-        self.assertEqual(str(~(Perm.R | Perm.W)), 'Perm.X')
+        self.assertEqual(str(~Perm.R), 'W|X')
+        self.assertEqual(str(~Perm.W), 'R|X')
+        self.assertEqual(str(~Perm.X), 'R|W')
+        self.assertEqual(str(~(Perm.R | Perm.W)), 'X')
         self.assertEqual(str(~(Perm.R | Perm.W | Perm.X)), 'Perm(0)')
         self.assertEqual(str(~(Perm.R | 8)), '-13')
-        self.assertEqual(str(Perm(~0)), 'Perm.R|W|X')
+        self.assertEqual(str(Perm(~0)), 'R|W|X')
         self.assertEqual(str(Perm(~8)), '-9')
 
         Open = self.Open
-        self.assertEqual(str(Open.RO), 'Open.RO')
-        self.assertEqual(str(Open.WO), 'Open.WO')
-        self.assertEqual(str(Open.AC), 'Open.AC')
-        self.assertEqual(str(Open.RO | Open.CE), 'Open.CE')
-        self.assertEqual(str(Open.WO | Open.CE), 'Open.WO|CE')
+        self.assertEqual(str(Open.RO), 'RO')
+        self.assertEqual(str(Open.WO), 'WO')
+        self.assertEqual(str(Open.AC), 'AC')
+        self.assertEqual(str(Open.RO | Open.CE), 'CE')
+        self.assertEqual(str(Open.WO | Open.CE), 'WO|CE')
         self.assertEqual(str(Open(4)), '4')
-        self.assertEqual(str(~Open.RO), 'Open.WO|RW|CE')
-        self.assertEqual(str(~Open.WO), 'Open.RW|CE')
-        self.assertEqual(str(~Open.AC), 'Open.CE')
-        self.assertEqual(str(~Open.CE), 'Open.AC')
-        self.assertEqual(str(~(Open.RO | Open.CE)), 'Open.AC')
-        self.assertEqual(str(~(Open.WO | Open.CE)), 'Open.RW')
+        self.assertEqual(str(~Open.RO), 'WO|RW|CE')
+        self.assertEqual(str(~Open.WO), 'RW|CE')
+        self.assertEqual(str(~Open.AC), 'CE')
+        self.assertEqual(str(~(Open.RO | Open.CE)), 'AC')
+        self.assertEqual(str(~(Open.WO | Open.CE)), 'RW')
         self.assertEqual(str(Open(~4)), '-5')
 
-        Skip = self.Skip
-        self.assertEqual(str(Skip(~4)), 'Skip.FIRST|SECOND|EIGHTH')
-
     def test_repr(self):
         Perm = self.Perm
-        self.assertEqual(repr(Perm.R), '<Perm.R: 4>')
-        self.assertEqual(repr(Perm.W), '<Perm.W: 2>')
-        self.assertEqual(repr(Perm.X), '<Perm.X: 1>')
-        self.assertEqual(repr(Perm.R | Perm.W), '<Perm.R|W: 6>')
-        self.assertEqual(repr(Perm.R | Perm.W | Perm.X), '<Perm.R|W|X: 7>')
+        self.assertEqual(repr(Perm.R), 'Perm.R')
+        self.assertEqual(repr(Perm.W), 'Perm.W')
+        self.assertEqual(repr(Perm.X), 'Perm.X')
+        self.assertEqual(repr(Perm.R | Perm.W), 'Perm.R|Perm.W')
+        self.assertEqual(repr(Perm.R | Perm.W | Perm.X), 'Perm.R|Perm.W|Perm.X')
         self.assertEqual(repr(Perm.R | 8), '12')
-        self.assertEqual(repr(Perm(0)), '<Perm: 0>')
+        self.assertEqual(repr(Perm(0)), '0x0')
         self.assertEqual(repr(Perm(8)), '8')
-        self.assertEqual(repr(~Perm.R), '<Perm.W|X: 3>')
-        self.assertEqual(repr(~Perm.W), '<Perm.R|X: 5>')
-        self.assertEqual(repr(~Perm.X), '<Perm.R|W: 6>')
-        self.assertEqual(repr(~(Perm.R | Perm.W)), '<Perm.X: 1>')
-        self.assertEqual(repr(~(Perm.R | Perm.W | Perm.X)), '<Perm: 0>')
+        self.assertEqual(repr(~Perm.R), 'Perm.W|Perm.X')
+        self.assertEqual(repr(~Perm.W), 'Perm.R|Perm.X')
+        self.assertEqual(repr(~Perm.X), 'Perm.R|Perm.W')
+        self.assertEqual(repr(~(Perm.R | Perm.W)), 'Perm.X')
+        self.assertEqual(repr(~(Perm.R | Perm.W | Perm.X)), '0x0')
         self.assertEqual(repr(~(Perm.R | 8)), '-13')
-        self.assertEqual(repr(Perm(~0)), '<Perm.R|W|X: 7>')
+        self.assertEqual(repr(Perm(~0)), 'Perm.R|Perm.W|Perm.X')
         self.assertEqual(repr(Perm(~8)), '-9')
 
         Open = self.Open
-        self.assertEqual(repr(Open.RO), '<Open.RO: 0>')
-        self.assertEqual(repr(Open.WO), '<Open.WO: 1>')
-        self.assertEqual(repr(Open.AC), '<Open.AC: 3>')
-        self.assertEqual(repr(Open.RO | Open.CE), '<Open.CE: 524288>')
-        self.assertEqual(repr(Open.WO | Open.CE), '<Open.WO|CE: 524289>')
+        self.assertEqual(repr(Open.RO), 'Open.RO')
+        self.assertEqual(repr(Open.WO), 'Open.WO')
+        self.assertEqual(repr(Open.AC), 'Open.AC')
+        self.assertEqual(repr(Open.RO | Open.CE), 'Open.CE')
+        self.assertEqual(repr(Open.WO | Open.CE), 'Open.WO|Open.CE')
         self.assertEqual(repr(Open(4)), '4')
-        self.assertEqual(repr(~Open.RO), '<Open.WO|RW|CE: 524291>')
-        self.assertEqual(repr(~Open.WO), '<Open.RW|CE: 524290>')
-        self.assertEqual(repr(~Open.AC), '<Open.CE: 524288>')
-        self.assertEqual(repr(~(Open.RO | Open.CE)), '<Open.AC: 3>')
-        self.assertEqual(repr(~(Open.WO | Open.CE)), '<Open.RW: 2>')
+        self.assertEqual(repr(~Open.RO), 'Open.WO|Open.RW|Open.CE')
+        self.assertEqual(repr(~Open.WO), 'Open.RW|Open.CE')
+        self.assertEqual(repr(~Open.AC), 'Open.CE')
+        self.assertEqual(repr(~(Open.RO | Open.CE)), 'Open.AC')
+        self.assertEqual(repr(~(Open.WO | Open.CE)), 'Open.RW')
         self.assertEqual(repr(Open(~4)), '-5')
 
-        Skip = self.Skip
-        self.assertEqual(repr(Skip(~4)), '<Skip.FIRST|SECOND|EIGHTH: 11>')
-
     def test_format(self):
         Perm = self.Perm
         self.assertEqual(format(Perm.R, ''), '4')
@@ -3252,7 +3242,7 @@ class TestIntFlag(unittest.TestCase):
         self.assertEqual(Color.GREEN.value, 2)
         self.assertEqual(Color.BLUE.value, 4)
         self.assertEqual(Color.ALL.value, 7)
-        self.assertEqual(str(Color.BLUE), 'Color.BLUE')
+        self.assertEqual(str(Color.BLUE), 'BLUE')
         class Color(AllMixin, StrMixin, IntFlag):
             RED = auto()
             GREEN = auto()
@@ -3374,6 +3364,8 @@ class TestUnique(unittest.TestCase):
             value = 4
 
 
+class TestEnumTypeSubclassing(unittest.TestCase):
+    pass
 
 expected_help_output_with_docs = """\
 Help on class Color in module %s:
@@ -3390,11 +3382,11 @@ class Color(enum.Enum)
  |\x20\x20
  |  Data and other attributes defined here:
  |\x20\x20
- |  blue = <Color.blue: 3>
+ |  blue = Color.blue
  |\x20\x20
- |  green = <Color.green: 2>
+ |  green = Color.green
  |\x20\x20
- |  red = <Color.red: 1>
+ |  red = Color.red
  |\x20\x20
  |  ----------------------------------------------------------------------
  |  Data descriptors inherited from enum.Enum:
@@ -3406,7 +3398,7 @@ class Color(enum.Enum)
  |      The value of the Enum member.
  |\x20\x20
  |  ----------------------------------------------------------------------
- |  Readonly properties inherited from enum.EnumMeta:
+ |  Readonly properties inherited from enum.EnumType:
  |\x20\x20
  |  __members__
  |      Returns a mapping of member name->value.
@@ -3427,11 +3419,11 @@ class Color(enum.Enum)
  |\x20\x20
  |  Data and other attributes defined here:
  |\x20\x20
- |  blue = <Color.blue: 3>
+ |  blue = Color.blue
  |\x20\x20
- |  green = <Color.green: 2>
+ |  green = Color.green
  |\x20\x20
- |  red = <Color.red: 1>
+ |  red = Color.red
  |\x20\x20
  |  ----------------------------------------------------------------------
  |  Data descriptors inherited from enum.Enum:
@@ -3441,7 +3433,7 @@ class Color(enum.Enum)
  |  value
  |\x20\x20
  |  ----------------------------------------------------------------------
- |  Data descriptors inherited from enum.EnumMeta:
+ |  Data descriptors inherited from enum.EnumType:
  |\x20\x20
  |  __members__"""
 
@@ -3468,7 +3460,7 @@ class TestStdLib(unittest.TestCase):
 
     def test_inspect_getmembers(self):
         values = dict((
-                ('__class__', EnumMeta),
+                ('__class__', EnumType),
                 ('__doc__', 'An enumeration.'),
                 ('__members__', self.Color.__members__),
                 ('__module__', __name__),
@@ -3495,11 +3487,11 @@ class TestStdLib(unittest.TestCase):
         from inspect import Attribute
         values = [
                 Attribute(name='__class__', kind='data',
-                    defining_class=object, object=EnumMeta),
+                    defining_class=object, object=EnumType),
                 Attribute(name='__doc__', kind='data',
                     defining_class=self.Color, object='An enumeration.'),
                 Attribute(name='__members__', kind='property',
-                    defining_class=EnumMeta, object=EnumMeta.__members__),
+                    defining_class=EnumType, object=EnumType.__members__),
                 Attribute(name='__module__', kind='data',
                     defining_class=self.Color, object=__name__),
                 Attribute(name='blue', kind='data',
@@ -3589,6 +3581,45 @@ class TestIntEnumConvert(unittest.TestCase):
                 ('test.test_enum', '__main__')[__name__=='__main__'],
                 filter=lambda x: x.startswith('CONVERT_TEST_'))
 
+    def test_convert_repr_and_str(self):
+        module = ('test.test_enum', '__main__')[__name__=='__main__']
+        test_type = enum.IntEnum._convert_(
+                'UnittestConvert',
+                module,
+                filter=lambda x: x.startswith('CONVERT_TEST_'))
+        self.assertEqual(repr(test_type.CONVERT_TEST_NAME_A), '%s.CONVERT_TEST_NAME_A' % module)
+        self.assertEqual(str(test_type.CONVERT_TEST_NAME_A), 'CONVERT_TEST_NAME_A')
+        self.assertEqual(format(test_type.CONVERT_TEST_NAME_A), '5')
+
+# global names for StrEnum._convert_ test
+CONVERT_STR_TEST_2 = 'goodbye'
+CONVERT_STR_TEST_1 = 'hello'
+
+class TestStrEnumConvert(unittest.TestCase):
+
+    def test_convert(self):
+        test_type = enum.StrEnum._convert_(
+                'UnittestConvert',
+                ('test.test_enum', '__main__')[__name__=='__main__'],
+                filter=lambda x: x.startswith('CONVERT_STR_'))
+        # Ensure that test_type has all of the desired names and values.
+        self.assertEqual(test_type.CONVERT_STR_TEST_1, 'hello')
+        self.assertEqual(test_type.CONVERT_STR_TEST_2, 'goodbye')
+        # Ensure that test_type only picked up names matching the filter.
+        self.assertEqual([name for name in dir(test_type)
+                          if name[0:2] not in ('CO', '__')],
+                         [], msg='Names other than CONVERT_STR_* found.')
+
+    def test_convert_repr_and_str(self):
+        module = ('test.test_enum', '__main__')[__name__=='__main__']
+        test_type = enum.StrEnum._convert_(
+                'UnittestConvert',
+                module,
+                filter=lambda x: x.startswith('CONVERT_STR_'))
+        self.assertEqual(repr(test_type.CONVERT_STR_TEST_1), '%s.CONVERT_STR_TEST_1' % module)
+        self.assertEqual(str(test_type.CONVERT_STR_TEST_2), 'goodbye')
+        self.assertEqual(format(test_type.CONVERT_STR_TEST_1), 'hello')
+
 
 if __name__ == '__main__':
     unittest.main()
diff --git a/Lib/test/test_pydoc.py b/Lib/test/test_pydoc.py
index 3bc0e9e..61575b5 100644
--- a/Lib/test/test_pydoc.py
+++ b/Lib/test/test_pydoc.py
@@ -453,7 +453,7 @@ class PydocDocTest(unittest.TestCase):
             zero = 0
             one = 1
         doc = pydoc.render_doc(BinaryInteger)
-        self.assertIn('<BinaryInteger.zero: 0>', doc)
+        self.assertIn('BinaryInteger.zero', doc)
 
     def test_mixed_case_module_names_are_lower_cased(self):
         # issue16484
diff --git a/Lib/test/test_signal.py b/Lib/test/test_signal.py
index f973d4f..8f943be 100644
--- a/Lib/test/test_signal.py
+++ b/Lib/test/test_signal.py
@@ -872,7 +872,7 @@ class PendingSignalsTests(unittest.TestCase):
 
         %s
 
-        blocked = %s
+        blocked = %r
         signum = signal.SIGALRM
 
         # child: block and wait the signal
diff --git a/Lib/test/test_socket.py b/Lib/test/test_socket.py
index bc28030..f91e000 100755
--- a/Lib/test/test_socket.py
+++ b/Lib/test/test_socket.py
@@ -1518,9 +1518,9 @@ class GeneralModuleTests(unittest.TestCase):
         infos = socket.getaddrinfo(HOST, 80, socket.AF_INET, socket.SOCK_STREAM)
         for family, type, _, _, _ in infos:
             self.assertEqual(family, socket.AF_INET)
-            self.assertEqual(str(family), 'AddressFamily.AF_INET')
+            self.assertEqual(str(family), 'AF_INET')
             self.assertEqual(type, socket.SOCK_STREAM)
-            self.assertEqual(str(type), 'SocketKind.SOCK_STREAM')
+            self.assertEqual(str(type), 'SOCK_STREAM')
         infos = socket.getaddrinfo(HOST, None, 0, socket.SOCK_STREAM)
         for _, socktype, _, _, _ in infos:
             self.assertEqual(socktype, socket.SOCK_STREAM)
@@ -1793,8 +1793,8 @@ class GeneralModuleTests(unittest.TestCase):
         # Make sure that the AF_* and SOCK_* constants have enum-like string
         # reprs.
         with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            self.assertEqual(str(s.family), 'AddressFamily.AF_INET')
-            self.assertEqual(str(s.type), 'SocketKind.SOCK_STREAM')
+            self.assertEqual(str(s.family), 'AF_INET')
+            self.assertEqual(str(s.type), 'SOCK_STREAM')
 
     def test_socket_consistent_sock_type(self):
         SOCK_NONBLOCK = getattr(socket, 'SOCK_NONBLOCK', 0)
diff --git a/Lib/test/test_ssl.py b/Lib/test/test_ssl.py
index fa77406..4ef1fb8 100644
--- a/Lib/test/test_ssl.py
+++ b/Lib/test/test_ssl.py
@@ -381,7 +381,7 @@ class BasicSocketTests(unittest.TestCase):
         # Make sure that the PROTOCOL_* constants have enum-like string
         # reprs.
         proto = ssl.PROTOCOL_TLS
-        self.assertEqual(str(proto), '_SSLMethod.PROTOCOL_TLS')
+        self.assertEqual(str(proto), 'PROTOCOL_TLS')
         ctx = ssl.SSLContext(proto)
         self.assertIs(ctx.protocol, proto)
 
diff --git a/Lib/test/test_unicode.py b/Lib/test/test_unicode.py
index 42c77f0..d47cf28 100644
--- a/Lib/test/test_unicode.py
+++ b/Lib/test/test_unicode.py
@@ -1467,18 +1467,18 @@ class UnicodeTest(string_tests.CommonTest,
             ABC = 'abc'
         # Testing Unicode formatting strings...
         self.assertEqual("%s, %s" % (Str.ABC, Str.ABC),
-                         'Str.ABC, Str.ABC')
+                         'ABC, ABC')
         self.assertEqual("%s, %s, %d, %i, %u, %f, %5.2f" %
                         (Str.ABC, Str.ABC,
                          Int.IDES, Int.IDES, Int.IDES,
                          Float.PI, Float.PI),
-                         'Str.ABC, Str.ABC, 15, 15, 15, 3.141593,  3.14')
+                         'ABC, ABC, 15, 15, 15, 3.141593,  3.14')
 
         # formatting jobs delegated from the string implementation:
         self.assertEqual('...%(foo)s...' % {'foo':Str.ABC},
-                         '...Str.ABC...')
+                         '...ABC...')
         self.assertEqual('...%(foo)s...' % {'foo':Int.IDES},
-                         '...Int.IDES...')
+                         '...IDES...')
         self.assertEqual('...%(foo)i...' % {'foo':Int.IDES},
                          '...15...')
         self.assertEqual('...%(foo)d...' % {'foo':Int.IDES},
diff --git a/Misc/NEWS.d/next/Library/2020-09-23-21-58-34.bpo-40066.f1dr_5.rst b/Misc/NEWS.d/next/Library/2020-09-23-21-58-34.bpo-40066.f1dr_5.rst
new file mode 100644
index 0000000..6d2c68e
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2020-09-23-21-58-34.bpo-40066.f1dr_5.rst
@@ -0,0 +1,4 @@
+Enum's `repr()` and `str()` have changed: `repr()` is now *EnumClass.MemberName*
+and `str()` is *MemberName*.  Additionally, stdlib Enum's whose contents are
+available as module attributes, such as `RegexFlag.IGNORECASE`, have their
+`repr()` as *module.name*, e.g. `re.IGNORECASE`.
diff --git a/Misc/NEWS.d/next/Library/2021-03-25-21-26-30.bpo-40066.7EBQ3_.rst b/Misc/NEWS.d/next/Library/2021-03-25-21-26-30.bpo-40066.7EBQ3_.rst
new file mode 100644
index 0000000..11903f8
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2021-03-25-21-26-30.bpo-40066.7EBQ3_.rst
@@ -0,0 +1,3 @@
+Enum: adjust ``repr()`` to show only enum and member name (not value, nor
+angle brackets) and ``str()`` to show only member name.  Update and improve
+documentation to match.