changeset:   103033:8e9d3a5d47d5
user:        Ethan Furman <ethan@stoneleaf.us>
date:        Sun Sep 04 11:39:01 2016 -0700
files:       Doc/library/enum.rst Lib/enum.py Lib/test/test_enum.py
description:
issue23591: more docs; slight change to repr


diff -r 1bd1e31a3298 -r 8e9d3a5d47d5 Doc/library/enum.rst
--- a/Doc/library/enum.rst	Sun Sep 04 11:29:13 2016 -0700
+++ b/Doc/library/enum.rst	Sun Sep 04 11:39:01 2016 -0700
@@ -574,7 +574,7 @@
     >>> Perm.RWX
     <Perm.RWX: 7>
     >>> ~Perm.RWX
-    <Perm.0: 0>
+    <Perm.-8: -8>
 
 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`::
@@ -615,6 +615,17 @@
     >>> 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 = 1
+    ...     blue = 2
+    ...     green = 4
+    ...     white = 7
+    ...     # or
+    ...     # white = red | blue | green
+
 Giving a name to the "no flags set" condition does not change its boolean
 value::
 
diff -r 1bd1e31a3298 -r 8e9d3a5d47d5 Lib/enum.py
--- a/Lib/enum.py	Sun Sep 04 11:29:13 2016 -0700
+++ b/Lib/enum.py	Sun Sep 04 11:39:01 2016 -0700
@@ -692,14 +692,11 @@
         if self._name_ is not None:
             return '<%s.%s: %r>' % (cls.__name__, self._name_, self._value_)
         members = self._decompose_()
-        if len(members) == 1 and members[0]._name_ is None:
-            return '<%s: %r>' % (cls.__name__, members[0]._value_)
-        else:
-            return '<%s.%s: %r>' % (
-                    cls.__name__,
-                    '|'.join([str(m._name_ or m._value_) for m in members]),
-                    self._value_,
-                    )
+        return '<%s.%s: %r>' % (
+                cls.__name__,
+                '|'.join([str(m._name_ or m._value_) for m in members]),
+                self._value_,
+                )
 
     def __str__(self):
         cls = self.__class__
diff -r 1bd1e31a3298 -r 8e9d3a5d47d5 Lib/test/test_enum.py
--- a/Lib/test/test_enum.py	Sun Sep 04 11:29:13 2016 -0700
+++ b/Lib/test/test_enum.py	Sun Sep 04 11:39:01 2016 -0700
@@ -1688,12 +1688,12 @@
         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(0)), '<Perm.0: 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.R | Perm.W | Perm.X)), '<Perm.0: 0>')
         self.assertEqual(repr(Perm(~0)), '<Perm.R|W|X: 7>')
 
         Open = self.Open
@@ -1933,13 +1933,13 @@
         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 | 8), '<Perm.8|R: 12>')
-        self.assertEqual(repr(Perm(0)), '<Perm: 0>')
-        self.assertEqual(repr(Perm(8)), '<Perm: 8>')
+        self.assertEqual(repr(Perm(0)), '<Perm.0: 0>')
+        self.assertEqual(repr(Perm(8)), '<Perm.8: 8>')
         self.assertEqual(repr(~Perm.R), '<Perm.W|X|-8: -5>')
         self.assertEqual(repr(~Perm.W), '<Perm.R|X|-8: -3>')
         self.assertEqual(repr(~Perm.X), '<Perm.R|W|-8: -2>')
         self.assertEqual(repr(~(Perm.R | Perm.W)), '<Perm.X|-8: -7>')
-        self.assertEqual(repr(~(Perm.R | Perm.W | Perm.X)), '<Perm: -8>')
+        self.assertEqual(repr(~(Perm.R | Perm.W | Perm.X)), '<Perm.-8: -8>')
         self.assertEqual(repr(~(Perm.R | 8)), '<Perm.W|X|-16: -13>')
         self.assertEqual(repr(Perm(~0)), '<Perm.R|W|X|-8: -1>')
         self.assertEqual(repr(Perm(~8)), '<Perm.R|W|X|-16: -9>')
@@ -1950,7 +1950,7 @@
         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.CE|WO: 524289>')
-        self.assertEqual(repr(Open(4)), '<Open: 4>')
+        self.assertEqual(repr(Open(4)), '<Open.4: 4>')
         self.assertEqual(repr(~Open.RO), '<Open.CE|AC|-524292: -1>')
         self.assertEqual(repr(~Open.WO), '<Open.CE|RW|-524292: -2>')
         self.assertEqual(repr(~Open.AC), '<Open.CE|-524292: -4>')