[Python-checkins] peps: A couple of corrections and additions.

[barry.warsaw]

http://hg.python.org/peps/rev/5eded0863992
changeset:   4834:5eded0863992
user:        Barry Warsaw <barry at python.org>
date:        Fri Apr 05 13:52:37 2013 -0400
summary:
  A couple of corrections and additions.

files:
  pep-0435.txt |  68 ++++++++++++++++++++++-----------------
  1 files changed, 39 insertions(+), 29 deletions(-)


diff --git a/pep-0435.txt b/pep-0435.txt
--- a/pep-0435.txt
+++ b/pep-0435.txt
@@ -115,7 +115,7 @@
 ...while their repr has more information::
 
     >>> print(repr(Colors.red))
-    <EnumValue: Colors.red [int=1]>
+    <EnumValue: Colors.red [value=1]>
 
 The enumeration value names are available through the class members::
 
@@ -148,10 +148,16 @@
     >>> print(repr(Colors))
     <Colors {red: 1, green: 2, blue: 3}>
 
-The ``Enum`` class supports iteration.  The returned order is not guaranteed
-(unless you use `IntEnum`_)::
+The ``Enum`` class supports iteration.  Iteration is defined as the
+sorted order of the item values::
 
-    >>> [v.name for v in MoreColors]
+    >>> class FiveColors(Enum):
+    ...     pink = 4
+    ...     cyan = 5
+    ...     green = 2
+    ...     blue = 3
+    ...     red = 1
+    >>> [v.name for v in FiveColors]
     ['red', 'green', 'blue', 'pink', 'cyan']
 
 Enumeration values are hashable, so they can be used in dictionaries and sets::
@@ -166,18 +172,18 @@
 ``Enum`` subclass, passing in the integer value for the item you want::
 
     >>> Colors[1]
-    <EnumValue: Colors.red [int=1]>
+    <EnumValue: Colors.red [value=1]>
     >>> Colors[2]
-    <EnumValue: Colors.green [int=2]>
+    <EnumValue: Colors.green [value=2]>
     >>> Colors[3]
-    <EnumValue: Colors.blue [int=3]>
+    <EnumValue: Colors.blue [value=3]>
     >>> Colors[1] is Colors.red
     True
 
 The string name of the enumeration value is also accepted::
 
     >>> Colors['red']
-    <EnumValue: Colors.red [int=1]>
+    <EnumValue: Colors.red [value=1]>
     >>> Colors['blue'] is Colors.blue
     True
 
@@ -263,9 +269,9 @@
     >>> Colors.blue is MoreColors.blue
     True
 
-However, these are not doing comparisons against the integer equivalent values,
-because if you define an enumeration with similar item names and integer values,
-they will not be identical::
+However, these are not doing comparisons against the integer
+equivalent values, because if you define an enumeration with similar
+item names and integer values, they will not be identical::
 
     >>> class OtherColors(Enum):
     ...     red = 1
@@ -335,19 +341,19 @@
 Here ``Enum`` is used to provide readable (and syntactically valid!) names for
 some special values, as well as group them together.
 
-While ``Enum`` supports this flexibility, one should only use it in very special
-cases.  Code will be most readable when actual values of enumerations aren't
-important and enumerations are just used for their naming and comparison
-properties.
+While ``Enum`` supports this flexibility, one should only use it in
+very special cases.  Code will be most readable when actual values of
+enumerations aren't important and enumerations are just used for their
+naming and comparison properties.
 
 
 IntEnum
 -------
 
-A variation of ``Enum`` is proposed that also subclasses ``int`` - ``IntEnum``.
-Such enumerations behave much more similarly to integers.  In particular, they
-can be compared to integers; by extensions, enumerations of different types can
-also be compared to each other::
+A variation of ``Enum`` is proposed where the enumeration values also
+subclasses ``int`` - ``IntEnum``.  These values can be compared to
+integers; by extensions, enumerations of different types can also be
+compared to each other::
 
     >>> from enum import IntEnum
     >>> class Shape(IntEnum):
@@ -367,7 +373,6 @@
 
 However they still can't be compared to ``Enum``::
 
-    >>> from enum import Enum, IntEnum
     >>> class Shape(IntEnum):
     ...   circle = 1
     ...   square = 2
@@ -379,7 +384,7 @@
     >>> Shape.circle == Colors.red
     False
 
-``IntEnum`` behaves like an integer in other ways you'd expect::
+``IntEnum`` values behave like integers in other ways you'd expect::
 
     >>> int(Shape.circle)
     1
@@ -388,12 +393,13 @@
     >>> [i for i in range(Shape.square)]
     [0, 1]
 
-For the vast majority of code, ``Enum`` is strongly recommended.  Since
-``IntEnum`` breaks some semantic promises of an enumeration (by being comparable
-to integers, and thus by transitivity to other unrelated enumerations), it
-should be used only in special cases where there's no other choice; for example,
-when integer constants are replaced with enumerations and backwards
-compatibility is required with code that still expects integers.
+For the vast majority of code, ``Enum`` is strongly recommended.
+Since ``IntEnum`` breaks some semantic promises of an enumeration (by
+being comparable to integers, and thus by transitivity to other
+unrelated enumerations), it should be used only in special cases where
+there's no other choice; for example, when integer constants are
+replaced with enumerations and backwards compatibility is required
+with code that still expects integers.
 
 
 Pickling
@@ -415,7 +421,6 @@
     >>> Animals = Enum('Animals', 'ant bee cat dog')
     >>> Animals
     <Animals {ant: 1, bee: 2, cat: 3, dog: 4}>
-    >>>
     >>> Animals.ant
     <EnumValue: Animals.ant [value=1]>
     >>> Animals.ant.value
@@ -443,6 +448,12 @@
     >>> Enum('Animals', (('ant', 'one'), ('bee', 'two'), ('cat', 'three'), ('dog', 'four')))
     <Animals {dog: four, ant: one, cat: three, bee: two}>
 
+The second argument can also be a dictionary mapping names to values::
+
+    >>> levels = dict(debug=10, info=20, warning=30, severe=40)
+    >>> Enum('Levels', levels)
+    <Levels {debug: 10, info: 20, warning: 30, severe: 40}>
+
 
 Proposed variations
 ===================
@@ -600,4 +611,3 @@
    fill-column: 70
    coding: utf-8
    End:
-

-- 
Repository URL: http://hg.python.org/peps