issue23591: more docs; slight change to repr

Doc/library/enum.rst

@@ -574,7 +574,7 @@ It is also possible to name the combinations::
     >>> 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 @@ flags being set, the boolean evaluation is :data:`False`::
     >>> 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::
 

Lib/enum.py

@@ -692,14 +692,11 @@ class Flag(Enum):
         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__

Lib/test/test_enum.py

@@ -1688,12 +1688,12 @@ class TestFlag(unittest.TestCase):
         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 @@ class TestIntFlag(unittest.TestCase):
         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 @@ class TestIntFlag(unittest.TestCase):
         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>')