PEP 663: change title and adjust text

pep-0663.txt

@@ -1,5 +1,5 @@
 PEP: 663
-Title: Improving and Standardizing Enum str(), repr(), and format() behaviors
+Title: Standardizing Enum str(), repr(), and format() behaviors
 Version: $Revision$
 Last-Modified: $Date$
 Author: Ethan Furman <ethan@stoneleaf.us>
@@ -17,21 +17,29 @@ Abstract
 ========
 
 Update the ``repr()``, ``str()``, and ``format()`` of the various Enum types
-for consistency and to better match their intended purpose.
+to better match their intended purpose.  For example, ``IntEnum`` will have
+its ``str()`` change to match its ``format()``, while a user-mixed int-enum
+will have its ``format()`` match its ``str()``.  In all cases, an enum's
+``str()`` and ``format()`` will be the same (unless the user overrides
+``format()``).
+
+Add a global enum decorator which changes the ``str()`` and ``repr()``  (and
+``format()``) of the decorated enum to be a valid gobal reference: i.e.
+``re.IGNORECASE`` instead of ``<RegexFlag.IGNORECASE: 2>``.
 
 
 Motivation
 ==========
 
-The addition of ``StrEnum`` with its requirement to have its ``str()`` be its
-``value`` is inconsistent with other provided Enum's ``str``.
-
 Having the ``str()`` of ``IntEnum`` and ``IntFlag`` not be the value causes
 bugs and extra work when replacing existing constants.
 
 Having the ``str()`` and ``format()`` of an enum member be different can be
 confusing.
 
+The addition of ``StrEnum`` with its requirement to have its ``str()`` be its
+``value`` is inconsistent with other provided Enum's ``str``.
+
 The iteration of ``Flag`` members, which directly affects their ``repr()``, is
 inelegant at best, and buggy at worst.
 
@@ -50,7 +58,7 @@ should be true (and the same for ``format()``).
 
 IntEnum, IntFlag, and StrEnum should be as close to a drop-in replacement of
 existing integer and string constants as is possible.  Towards that goal, the
-str() output of each should be its inherent value; e.g. if ``Color`` is an
+``str()`` output of each should be its inherent value; e.g. if ``Color`` is an
 ``IntEnum``::
 
     >>> Color.RED
@@ -60,13 +68,14 @@ str() output of each should be its inherent value; e.g. if ``Color`` is an
     >>> format(Color.RED)
     '1'
 
-Note that format() already produces the correct output in 3.10, only str() needs
+Note that ``format()`` already produces the correct output, only ``str()`` needs
 updating.
 
 As much as possible, the ``str()``, ``repr()``, and ``format()`` of enum members
-should be standardized across the standard library.
+should be standardized across the standard library.  However, up to Python 3.10
+several enums in the standard library have a custom ``str()`` and/or ``repr()``.
 
-The repr() of Flag currently includes aliases, which it should not; fixing that
+The ``repr()`` of Flag currently includes aliases, which it should not; fixing that
 will, of course, already change its ``repr()`` in certain cases.
 
 
@@ -75,10 +84,10 @@ Specification
 
 There a three broad categories of enum usage:
 
-- simple: Enum or Flag
+- simple: ``Enum`` or ``Flag``
   a new enum class is created with no data type mixins
 
-- drop-in replacement: IntEnum, IntFlag, StrEnum
+- drop-in replacement: ``IntEnum``, ``IntFlag``, ``StrEnum``
   a new enum class is created which also subclasses ``int`` or ``str`` and uses
   ``int.__str__`` or ``str.__str__``
 
@@ -93,7 +102,7 @@ There are also two styles:
   ``str()`` (where appropriate)
 
 - global: the enumeration members are copied into their module's global
-  namespcae, and their module name shows in their ``repr()`` and ``str()``
+  namespace, and their module name shows in their ``repr()`` and ``str()``
   (where appropriate)
 
 Some sample enums::
@@ -115,7 +124,7 @@ Some sample enums::
        WHITE = 1
 
 Using the above enumerations, the following two tables show the old and new
-behavior (blank cells indicate no behavioral change):
+output (blank cells indicate no change):
 
 +--------+------------------------+-----------------+------------+-----------------------+
 | style  | category               | enum repr()     | enum str() | enum format()         |
@@ -211,7 +220,7 @@ As can be seen, ``repr()`` is primarily affected by whether the members are
 global, while ``str()`` is affected by being global or by being a drop-in
 replacement, with the drop-in replacement status having a higher priority.
 Also, the basic ``repr()`` and ``str()`` have changed for flags as the old
-style was very clunky.
+style was flawed.
 
 
 Backwards Compatibility