Merge lp:~barry/flufl.enum/lp1162375 into lp:~barry/flufl.enum/trunk

[Barry Warsaw]

=== modified file 'README.rst'
--- README.rst	2012-04-19 21:55:28 +0000
+++ README.rst	2013-03-31 04:42:19 +0000
@@ -4,9 +4,9 @@
 
 A Python enumeration package.
 
-The ``flufl.enum`` library is yet another Python enumeration package.  Its
-goal is to provide simple, specific, concise semantics in an easy to read and
-write syntax.  ``flufl.enum`` has just enough of the features needed to make
+The ``flufl.enum`` library is a Python enumeration package.  Its goal is to
+provide simple, specific, concise semantics in an easy to read and write
+syntax.  ``flufl.enum`` has just enough of the features needed to make
 enumerations useful, but without a lot of extra baggage to weigh them down.
 This work grew out of the Mailman 3.0 project.
 

=== modified file 'flufl/enum/NEWS.rst'
--- flufl/enum/NEWS.rst	2013-03-30 00:04:40 +0000
+++ flufl/enum/NEWS.rst	2013-03-31 04:42:19 +0000
@@ -10,7 +10,8 @@
  * Add ``IntEnum`` class which returns int-subclass enum values. (LP: #1132976)
    - Add ``__index__()`` method to support slicing.  (LP: #1132972)
    - Add non-deprecated ``__int__()`` method.
-   - Add `make_int()` convenience function.
+ * Deprecate ``make()``; use ``Enum()`` instead.  Also, allow for calling
+   ``IntEnum()`` to create integer valued enums.  (LP: #1162375)
  * Add ``.value`` attribute to enum values.  (LP: #1132859)
  * For ``__getitem__()`` and ``__call__()``, fall back to using the ``.value``
    attribute if the argument has one. (LP: #1124596)

=== modified file 'flufl/enum/README.rst'
--- flufl/enum/README.rst	2013-03-01 23:31:57 +0000
+++ flufl/enum/README.rst	2013-03-31 04:42:19 +0000
@@ -2,30 +2,32 @@
 flufl.enum - A Python enumeration package
 =========================================
 
-This package is called ``flufl.enum``.  It is yet another Python enumeration
-package, but with a slightly different take on syntax and semantics than
-earlier such packages.
+This package is called ``flufl.enum``, a Python enumeration package.
 
 The goals of ``flufl.enum`` are to produce simple, specific, concise semantics
 in an easy to read and write syntax.  ``flufl.enum`` has just enough of the
 features needed to make enumerations useful, but without a lot of extra
 baggage to weigh them down.  This work grew out of the Mailman 3.0 project and
-it is the enum package used there.  Until version 3.0, this package was called
+it is the enum package used there.  This package was previously called
 ``munepy``.
 
+``flufl.enum`` is an implementation of the standard library enumeration
+package described in `PEP 435`_ for `Python 3.4`_.  It is available as a
+separate package for use in older Python versions.
+
 
 Requirements
 ============
 
-``flufl.enum`` requires Python 2.6 or newer, and is compatible with Python 3.
+``flufl.enum`` requires Python 2.7 or newer, and is compatible with Python 3.2
+and later.
 
 
 Documentation
 =============
 
-A `simple guide`_ to using the library is available within this package, in
-the form of doctests.   The manual is also available online in the Cheeseshop
-at:
+A `simple guide`_ to using the library is available within this package.  The
+manual is also available online at:
 
     http://package.python.org/flufl.enum
 
@@ -95,3 +97,5 @@
 
 .. _`simple guide`: docs/using.html
 .. _`virtualenv`: http://www.virtualenv.org/en/latest/index.html
+.. _`PEP 435`: http://www.python.org/dev/peps/pep-0435/
+.. _`Python 3.4`: http://www.python.org/dev/peps/pep-0429/

=== modified file 'flufl/enum/__init__.py'
--- flufl/enum/__init__.py	2013-03-30 00:13:26 +0000
+++ flufl/enum/__init__.py	2013-03-31 04:42:19 +0000
@@ -24,10 +24,9 @@
     'IntEnum',
     '__version__',
     'make',
-    'make_int',
     ]
 
 
 __version__ = '3.4'
 
-from ._enum import Enum, IntEnum, make, make_int
+from ._enum import Enum, IntEnum, make

=== modified file 'flufl/enum/_enum.py'
--- flufl/enum/_enum.py	2013-03-30 00:13:26 +0000
+++ flufl/enum/_enum.py	2013-03-31 04:42:19 +0000
@@ -23,7 +23,6 @@
     'Enum',
     'IntEnum',
     'make',
-    'make_int',
     ]
 
 
@@ -113,8 +112,14 @@
                     raise ValueError(item)
         return getattr(cls, attr)
 
-    # Support both MyEnum[i] and MyEnum(i)
-    __call__ = __getitem__
+    def __call__(cls, *args):
+        # One-argument calling is a deprecated synonym for getitem.
+        if len(args) == 1:
+            warnings.warn('MyEnum(arg) is deprecated; use MyEnum[arg]',
+                          DeprecationWarning, 2)
+            return cls.__getitem__(args[0])
+        name, source = args
+        return _make(cls, name, source)
 
 
 

@@ -176,7 +181,6 @@
     __hash__ = object.__hash__
 
 
-

 # Define the Enum class using metaclass syntax compatible with both Python 2
 # and Python 3.
 Enum = EnumMetaclass(str('Enum'), (), {
@@ -184,6 +188,7 @@
     })
 
 
+

 class IntEnumValue(int, EnumValue):
     """An EnumValue that is also an integer."""
 
@@ -217,7 +222,7 @@
 
 

 def _make(enum_class, name, source):
-    """The common implementation for `make()` and `make_int()`."""
+    """The common implementation for `Enum()` and `IntEnum()`."""
     namespace = {}
     illegals = []
     have_strings = None
@@ -272,12 +277,6 @@
     :raises ValueError: when a heterogeneous source is given, or when
         non-identifiers are used as enumeration value names.
     """
+    warnings.warn('make() is deprecated; use Enum(name, source)',
+                  DeprecationWarning, 2)
     return _make(Enum, name, source)
-
-def make_int(name, source):
-    """Return an Enum class from a name and a source.
-
-    This is exactly like the `make()` function, except that the enum values of
-    the returned enum are integer subclasses.
-    """
-    return _make(IntEnum, name, source)

=== modified file 'flufl/enum/docs/using.rst'
--- flufl/enum/docs/using.rst	2013-03-29 23:55:51 +0000
+++ flufl/enum/docs/using.rst	2013-03-31 04:42:19 +0000
@@ -11,8 +11,8 @@
 Within an enumeration, the values can be compared by identity, and the
 enumeration itself can be iterated over.  The underlying values can be
 retrieved from the enumeration items.  An integer based variant is provided
-which allows items to be used as slices, interoperability with
-integer-accepting C-based APIs, and for logical operations.
+which allows items to be used as slices, to interoperate with C-based APIs,
+and for logical operations.
 
 
 Motivation
@@ -92,16 +92,13 @@
 Convenience API
 ---------------
 
-Alternatively, you can create an enumeration using the `make()` convenience
-function, which takes an iterable object or dictionary providing the item
-names and values.  The first argument to `make()` is the name of the
-enumeration.
-
-If a sequence of identifiers is given, the values are auto-assigned integers
+Alternatively, you can create an enumeration functionally using the calling
+syntax on the `Enum` class.  The first argument is the name of the new
+enumeration, and the second argument is a sequence of strings, giving the
+names of the enumeration values.  The values are auto-assigned integers
 starting from 1.
 
-    >>> from flufl.enum import make
-    >>> Rush = make('Rush', 'geddy alex neil'.split())
+    >>> Rush = Enum('Rush', 'geddy alex neil'.split())
 
 The ``str`` and ``repr`` provide details.
 
@@ -110,7 +107,7 @@
     >>> print(repr(Rush.geddy))
     <EnumValue: Rush.geddy [value=1]>
 
-See the section on the `Functional API`_ for more information.
+See the section on the `Functional API`_ for more options and information.
 
 
 Values
@@ -316,39 +313,27 @@
 Conversions
 ===========
 
-You can convert back to the enumeration item by calling the ``Enum`` class,
-passing in the value for the item you want.
+You can convert back to the enumeration item by using the ``Enum`` class's
+``getitem`` syntax, passing in the value for the item you want.
 
-    >>> Colors(2)
+    >>> Colors[2]
     <EnumValue: Colors.green [value=2]>
-    >>> Rush('bass')
+    >>> Rush['bass']
     <EnumValue: Rush.geddy [value=bass]>
-    >>> Colors(1) is Colors.red
+    >>> Colors[1] is Colors.red
     True
 
 The ``Enum`` class also accepts the string name of the enumeration value.
 
-    >>> Colors('red')
-    <EnumValue: Colors.red [value=1]>
-    >>> Rush('alex')
-    <EnumValue: Rush.alex [value=guitar]>
-    >>> Colors('blue') is Colors.blue
-    True
-
-The ``Enum`` base class also supports ``getitem`` syntax, exactly equivalent
-to the class's call semantics.
-
-    >>> Colors[1]
-    <EnumValue: Colors.red [value=1]>
-    >>> Colors[1] is Colors.red
-    True
     >>> Colors['red']
     <EnumValue: Colors.red [value=1]>
-
-For consistency, both the call and getitem syntax accept an enum value.
-
-    >>> Colors(Colors.green)
-    <EnumValue: Colors.green [value=2]>
+    >>> Rush['alex']
+    <EnumValue: Rush.alex [value=guitar]>
+    >>> Colors['blue'] is Colors.blue
+    True
+
+For consistency, ``getitem`` syntax accept an enum value.
+
     >>> Colors[Colors.green]
     <EnumValue: Colors.green [value=2]>
 
@@ -417,18 +402,17 @@
 Functional API
 ==============
 
-As described above, you can create enumerations using the convenience function
-`make()`, which takes an iterable object or dictionary to provide the item
-names and values.
+As described above, you can create enumerations functionally using the calling
+syntax for ``Enum`` and ``IntEnum``.
 
-The first argument to `make()` is the name of the enumeration, and it returns
-the so-named ``Enum`` subclass.  The second argument is a `source` which can
-be either an iterable or a dictionary.  In the most basic usage, `source`
-returns a sequence of strings which name the enumeration items.  In this case,
-the values are automatically assigned starting from 1.
+The first argument is always the name of the enumeration, and it returns the
+so-named ``Enum`` (or ``IntEnum``) subclass.  The second argument is a
+`source` which can be either a sequence of strings or 2-tuples.  In the most
+basic usage, `source` is a sequence of strings which name the enumeration
+items.  In this case, the values are automatically assigned starting from 1.
 ::
 
-    >>> make('Animals', 'ant bee cat dog'.split())
+    >>> Enum('Animals', 'ant bee cat dog'.split())
     <Animals {ant: 1, bee: 2, cat: 3, dog: 4}>
 
 The items in source can also be 2-tuples, where the first item is the
@@ -440,15 +424,14 @@
     ...     while True:
     ...         yield start
     ...         start <<= 1
-    >>> make('Flags', zip(list('abcdefg'), enumiter()))
+    >>> Enum('Flags', zip(list('abcdefg'), enumiter()))
     <Flags {a: 1, b: 2, c: 4, d: 8, e: 16, f: 32, g: 64}>
 
-If you want to create ``IntEnum``s, use the `make_int()` function.  It has the
-same signature as `make()` but the items of the returned enum are int
-subclasses.
+If you want to create an ``IntEnum`` functionally, call that class instead.
+This has the same signature as calling `Enum` but the items of the returned
+enumeration are int subclasses.
 
-    >>> from flufl.enum import make_int
-    >>> Numbers = make_int('Numbers', 'one two three four'.split())
+    >>> Numbers = IntEnum('Numbers', 'one two three four'.split())
     >>> Numbers.three == 3
     True
 

=== modified file 'flufl/enum/tests/test_enum.py'
--- flufl/enum/tests/test_enum.py	2013-03-30 00:13:26 +0000
+++ flufl/enum/tests/test_enum.py	2013-03-31 04:42:19 +0000
@@ -26,9 +26,10 @@
     ]
 
 
+import warnings
 import unittest
 
-from flufl.enum import Enum, IntEnum, make, make_int
+from flufl.enum import Enum, IntEnum, make
 from operator import index
 
 
@@ -36,16 +37,6 @@
 class TestEnum(unittest.TestCase):
     """Additional unit tests."""
 
-    def test_invalid_call_arguments(self):
-        # Calling an Enum with invalid value raises an exception.
-        class Colors(Enum):
-            red = 1
-            green = 2
-            blue = 3
-        with self.assertRaises(ValueError) as cm:
-            Colors('magenta')
-        self.assertEqual(cm.exception.args, ('magenta',))
-
     def test_invalid_getitem_arguments(self):
         # getitem on an Enum with invalid value raises an exception.
         class Colors(Enum):
@@ -77,41 +68,46 @@
                 magenta = 2 # Oops!
         self.assertEqual(str(cm.exception), 'Multiple enum values: 2')
 
-    def test_enum_make_not_all_2_tuples(self):
+    def test_functional_api_not_all_2_tuples(self):
         # If 2-tuples are used, all items must be 2-tuples.
-        self.assertRaises(ValueError, make, 'Animals', (
+        self.assertRaises(ValueError, Enum, 'Animals', (
             ('ant', 1),
             ('bee', 2),
             'cat',
             ('dog', 4),
             ))
-        self.assertRaises(ValueError, make, 'Animals', (
+        self.assertRaises(ValueError, Enum, 'Animals', (
             ('ant', 1),
             ('bee', 2),
             ('cat',),
             ('dog', 4),
             ))
-        self.assertRaises(ValueError, make, 'Animals', (
+        self.assertRaises(ValueError, Enum, 'Animals', (
             ('ant', 1),
             ('bee', 2),
             ('cat', 3, 'oops'),
             ('dog', 4),
             ))
 
-    def test_make_identifiers(self):
-        # Ensure that the make() interface also enforces identifiers.
-        try:
-            make('Foo', ('1', '2', '3'))
-        except ValueError as exc:
-            self.assertEqual(exc.args[0], 'non-identifiers: 1 2 3')
-        else:
-            raise AssertionError('Expected a ValueError')
-        try:
-            make('Foo', (('ant', 1), ('bee', 2), ('3', 'cat')))
-        except ValueError as exc:
-            self.assertEqual(exc.args[0], 'non-identifiers: 3')
-        else:
-            raise AssertionError('Expected a ValueError')
+    def test_functional_api_identifiers(self):
+        # Ensure that the functional API enforces identifiers.
+        with self.assertRaises(ValueError) as cm:
+            Enum('Foo', ('1', '2', '3'))
+        self.assertEqual(cm.exception.args[0], 'non-identifiers: 1 2 3')
+        with self.assertRaises(ValueError) as cm:
+            Enum('Foo', (('ant', 1), ('bee', 2), ('3', 'cat')))
+        self.assertEqual(cm.exception.args[0], 'non-identifiers: 3')
+
+    def test_deprecate_make(self):
+        # LP: #1162375 -- use Enum() calling syntax instead.
+        with warnings.catch_warnings(record=True) as seen:
+            # In Python 3.3+ we can use self.assertWarns()
+            warnings.simplefilter('always')
+            Animals = make('Animals', 'ant bee cat'.split())
+        self.assertEqual(len(seen), 1)
+        self.assertEqual(seen[0].category, DeprecationWarning)
+        # We don't need to assert the deprecation message.
+        self.assertEqual(Animals.ant.value, 1)
 
 
 

@@ -134,9 +130,9 @@
         # are equal.
         self.assertEqual(index(Animals.bee), Animals.bee.__index__())
 
-    def test_make_int_type(self):
-        # make_int() enum values are ints.
-        Toppings = make_int(
+    def test_int_enums_type(self):
+        # IntEnum() enum values are ints.
+        Toppings = IntEnum(
             'Toppings',
             dict(olives=1, onions=2, mushrooms=4, cheese=8, garlic=16).items())
         self.assertEqual(Toppings.garlic, 16)