issue23591: add docs; code cleanup; more tests

2 files changed, 75 insertions, 21 deletions

diff --git a/Lib/enum.py b/Lib/enum.py
index e89c17d..8369631 100644
--- a/Lib/enum.py
+++ b/Lib/enum.py
@@ -10,7 +10,7 @@ except ImportError:
     from collections import OrderedDict
 
 
-__all__ = ['EnumMeta', 'Enum', 'IntEnum', 'Flags', 'IntFlags', 'unique']
+__all__ = ['EnumMeta', 'Enum', 'IntEnum', 'Flag', 'IntFlag', 'unique']
 
 
 def _is_descriptor(obj):
@@ -104,7 +104,7 @@ class EnumMeta(type):
             enum_dict['_generate_next_value_'] = getattr(first_enum, '_generate_next_value_', None)
         return enum_dict
 
-    def __new__(metacls, cls, bases, classdict, **kwds):
+    def __new__(metacls, cls, bases, classdict):
         # an Enum class is final once enumeration items have been defined; it
         # cannot be mixed with other types (int, float, etc.) if it has an
         # inherited __new__ unless a new __new__ is defined (or the resulting
@@ -614,7 +614,7 @@ class IntEnum(int, Enum):
 def _reduce_ex_by_name(self, proto):
     return self.name
 
-class Flags(Enum):
+class Flag(Enum):
     """Support for flags"""
     @staticmethod
     def _generate_next_value_(name, start, count, last_value):
@@ -736,7 +736,7 @@ class Flags(Enum):
         return self.__class__(inverted)
 
 
-class IntFlags(int, Flags):
+class IntFlag(int, Flag):
     """Support for integer-based Flags"""
 
     @classmethod
diff --git a/Lib/test/test_enum.py b/Lib/test/test_enum.py
index 1831895..cfe1b18 100644
--- a/Lib/test/test_enum.py
+++ b/Lib/test/test_enum.py
@@ -3,7 +3,7 @@ import inspect
 import pydoc
 import unittest
 from collections import OrderedDict
-from enum import Enum, IntEnum, EnumMeta, Flags, IntFlags, unique
+from enum import Enum, IntEnum, EnumMeta, Flag, IntFlag, unique
 from io import StringIO
 from pickle import dumps, loads, PicklingError, HIGHEST_PROTOCOL
 from test import support
@@ -33,6 +33,14 @@ try:
 except Exception as exc:
     FloatStooges = exc
 
+try:
+    class FlagStooges(Flag):
+        LARRY = 1
+        CURLY = 2
+        MOE = 3
+except Exception as exc:
+    FlagStooges = exc
+
 # for pickle test and subclass tests
 try:
     class StrEnum(str, Enum):
@@ -1633,13 +1641,13 @@ class TestOrder(unittest.TestCase):
                 verde = green
 
 
-class TestFlags(unittest.TestCase):
+class TestFlag(unittest.TestCase):
     """Tests of the Flags."""
 
-    class Perm(Flags):
+    class Perm(Flag):
         R, W, X = 4, 2, 1
 
-    class Open(Flags):
+    class Open(Flag):
         RO = 0
         WO = 1
         RW = 2
@@ -1760,7 +1768,7 @@ class TestFlags(unittest.TestCase):
         self.assertIs((Open.WO|Open.CE) & ~Open.WO, Open.CE)
 
     def test_programatic_function_string(self):
-        Perm = Flags('Perm', 'R W X')
+        Perm = Flag('Perm', 'R W X')
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -1775,7 +1783,7 @@ class TestFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
     def test_programatic_function_string_with_start(self):
-        Perm = Flags('Perm', 'R W X', start=8)
+        Perm = Flag('Perm', 'R W X', start=8)
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -1790,7 +1798,7 @@ class TestFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
     def test_programatic_function_string_list(self):
-        Perm = Flags('Perm', ['R', 'W', 'X'])
+        Perm = Flag('Perm', ['R', 'W', 'X'])
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -1805,7 +1813,7 @@ class TestFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
     def test_programatic_function_iterable(self):
-        Perm = Flags('Perm', (('R', 2), ('W', 8), ('X', 32)))
+        Perm = Flag('Perm', (('R', 2), ('W', 8), ('X', 32)))
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -1820,7 +1828,7 @@ class TestFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
     def test_programatic_function_from_dict(self):
-        Perm = Flags('Perm', OrderedDict((('R', 2), ('W', 8), ('X', 32))))
+        Perm = Flag('Perm', OrderedDict((('R', 2), ('W', 8), ('X', 32))))
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -1834,16 +1842,42 @@ class TestFlags(unittest.TestCase):
             self.assertIn(e, Perm)
             self.assertIs(type(e), Perm)
 
+    def test_pickle(self):
+        if isinstance(FlagStooges, Exception):
+            raise FlagStooges
+        test_pickle_dump_load(self.assertIs, FlagStooges.CURLY|FlagStooges.MOE)
+        test_pickle_dump_load(self.assertIs, FlagStooges)
+
 
-class TestIntFlags(unittest.TestCase):
+    def test_containment(self):
+        Perm = self.Perm
+        R, W, X = Perm
+        RW = R | W
+        RX = R | X
+        WX = W | X
+        RWX = R | W | X
+        self.assertTrue(R in RW)
+        self.assertTrue(R in RX)
+        self.assertTrue(R in RWX)
+        self.assertTrue(W in RW)
+        self.assertTrue(W in WX)
+        self.assertTrue(W in RWX)
+        self.assertTrue(X in RX)
+        self.assertTrue(X in WX)
+        self.assertTrue(X in RWX)
+        self.assertFalse(R in WX)
+        self.assertFalse(W in RX)
+        self.assertFalse(X in RW)
+
+class TestIntFlag(unittest.TestCase):
     """Tests of the IntFlags."""
 
-    class Perm(IntFlags):
+    class Perm(IntFlag):
         X = 1 << 0
         W = 1 << 1
         R = 1 << 2
 
-    class Open(IntFlags):
+    class Open(IntFlag):
         RO = 0
         WO = 1
         RW = 2
@@ -2003,7 +2037,7 @@ class TestIntFlags(unittest.TestCase):
         self.assertIs((Open.WO|Open.CE) & ~Open.WO, Open.CE)
 
     def test_programatic_function_string(self):
-        Perm = IntFlags('Perm', 'R W X')
+        Perm = IntFlag('Perm', 'R W X')
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -2019,7 +2053,7 @@ class TestIntFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
     def test_programatic_function_string_with_start(self):
-        Perm = IntFlags('Perm', 'R W X', start=8)
+        Perm = IntFlag('Perm', 'R W X', start=8)
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -2035,7 +2069,7 @@ class TestIntFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
     def test_programatic_function_string_list(self):
-        Perm = IntFlags('Perm', ['R', 'W', 'X'])
+        Perm = IntFlag('Perm', ['R', 'W', 'X'])
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -2051,7 +2085,7 @@ class TestIntFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
     def test_programatic_function_iterable(self):
-        Perm = IntFlags('Perm', (('R', 2), ('W', 8), ('X', 32)))
+        Perm = IntFlag('Perm', (('R', 2), ('W', 8), ('X', 32)))
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -2067,7 +2101,7 @@ class TestIntFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
     def test_programatic_function_from_dict(self):
-        Perm = IntFlags('Perm', OrderedDict((('R', 2), ('W', 8), ('X', 32))))
+        Perm = IntFlag('Perm', OrderedDict((('R', 2), ('W', 8), ('X', 32))))
         lst = list(Perm)
         self.assertEqual(len(lst), len(Perm))
         self.assertEqual(len(Perm), 3, Perm)
@@ -2083,6 +2117,26 @@ class TestIntFlags(unittest.TestCase):
             self.assertIs(type(e), Perm)
 
 
+    def test_containment(self):
+        Perm = self.Perm
+        R, W, X = Perm
+        RW = R | W
+        RX = R | X
+        WX = W | X
+        RWX = R | W | X
+        self.assertTrue(R in RW)
+        self.assertTrue(R in RX)
+        self.assertTrue(R in RWX)
+        self.assertTrue(W in RW)
+        self.assertTrue(W in WX)
+        self.assertTrue(W in RWX)
+        self.assertTrue(X in RX)
+        self.assertTrue(X in WX)
+        self.assertTrue(X in RWX)
+        self.assertFalse(R in WX)
+        self.assertFalse(W in RX)
+        self.assertFalse(X in RW)
+
 class TestUnique(unittest.TestCase):
 
     def test_unique_clean(self):