iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Consistent formatting & cleanup, explicit namespacing of make. Updated todo

This commit is contained in:
Eli Bendersky 2013-02-23 09:16:16 -08:00
parent 6f23bce51b
commit 5e8e6fa2d9
1 changed files with 52 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
pepdraft-0435.txt
View File

@ -64,8 +64,10 @@ Module & type name
================== ==================
We propose to add a module named ``enum`` to the standard library. The main We propose to add a module named ``enum`` to the standard library. The main
type exposed by this module is ``Enum``. type exposed by this module is ``Enum``. Hence, to import the ``Enum`` type
user code will run::
>>> from enum import Enum
Proposed semantics for the new enumeration type Proposed semantics for the new enumeration type
=============================================== ===============================================
@ -76,8 +78,8 @@ Creating an Enum
Enumerations are created using the class syntax, which makes them easy to read Enumerations are created using the class syntax, which makes them easy to read
and write. Every enumeration value must have a unique integer value and the and write. Every enumeration value must have a unique integer value and the
only restriction on their names is that they must be valid Python identifiers. only restriction on their names is that they must be valid Python identifiers.
To define an enumeration, derive from the Enum class and add attributes with To define an enumeration, derive from the ``Enum`` class and add attributes with
assignment to their integer values. assignment to their integer values::
>>> from enum import Enum >>> from enum import Enum
>>> class Colors(Enum): >>> class Colors(Enum):
@ -85,7 +87,7 @@ assignment to their integer values.
... green = 2 ... green = 2
... blue = 3 ... blue = 3
Enumeration values are compared by identity. Enumeration values are compared by identity::
>>> Colors.red is Colors.red >>> Colors.red is Colors.red
True True
@ -96,17 +98,17 @@ Enumeration values are compared by identity.
>>> Colors.blue is Colors.red >>> Colors.blue is Colors.red
False False
Enumeration values have nice, human readable string representations... Enumeration values have nice, human readable string representations::
>>> print(Colors.red) >>> print(Colors.red)
Colors.red Colors.red
...while their repr has more information. ...while their repr has more information::
>>> print(repr(Colors.red)) >>> print(repr(Colors.red))
<EnumValue: Colors.red [int=1]> <EnumValue: Colors.red [int=1]>
The enumeration value names are available through the class members. The enumeration value names are available through the class members::
>>> for member in Colors.__members__: >>> for member in Colors.__members__:
... print(member) ... print(member)
@ -115,13 +117,13 @@ The enumeration value names are available through the class members.
blue blue
Let's say you wanted to encode an enumeration value in a database. You might Let's say you wanted to encode an enumeration value in a database. You might
want to get the enumeration class object from an enumeration value. want to get the enumeration class object from an enumeration value::
>>> cls = Colors.red.enum >>> cls = Colors.red.enum
>>> print(cls.__name__) >>> print(cls.__name__)
Colors Colors
Enums also have a property that contains just their item name. Enums also have a property that contains just their item name::
>>> print(Colors.red.name) >>> print(Colors.red.name)
red red
@ -130,21 +132,21 @@ Enums also have a property that contains just their item name.
>>> print(Colors.blue.name) >>> print(Colors.blue.name)
blue blue
The str and repr of the enumeration class also provides useful information. The str and repr of the enumeration class also provides useful information::
>>> print(Colors) >>> print(Colors)
<Colors {red: 1, green: 2, blue: 3}> <Colors {red: 1, green: 2, blue: 3}>
>>> print(repr(Colors)) >>> print(repr(Colors))
<Colors {red: 1, green: 2, blue: 3}> <Colors {red: 1, green: 2, blue: 3}>
You can extend previously defined Enums by subclassing. You can extend previously defined Enums by subclassing::
>>> class MoreColors(Colors): >>> class MoreColors(Colors):
... pink = 4 ... pink = 4
... cyan = 5 ... cyan = 5
When extended in this way, the base enumeration's values are identical to the When extended in this way, the base enumeration's values are identical to the
same named values in the derived class. same named values in the derived class::
>>> Colors.red is MoreColors.red >>> Colors.red is MoreColors.red
True True
@ -153,7 +155,7 @@ same named values in the derived class.
However, these are not doing comparisons against the integer equivalent However, these are not doing comparisons against the integer equivalent
values, because if you define an enumeration with similar item names and values, because if you define an enumeration with similar item names and
integer values, they will not be identical. integer values, they will not be identical::
>>> class OtherColors(Enum): >>> class OtherColors(Enum):
... red = 1 ... red = 1
@ -164,7 +166,7 @@ integer values, they will not be identical.
>>> Colors.blue is not OtherColors.blue >>> Colors.blue is not OtherColors.blue
True True
These enumeration values are not equal, nor do they hash equally. These enumeration values are not equal, nor do they hash equally::
>>> Colors.red == OtherColors.red >>> Colors.red == OtherColors.red
False False
@ -172,7 +174,7 @@ These enumeration values are not equal, nor do they hash equally.
2 2
Ordered comparisons between enumeration values are *not* supported. Enums are Ordered comparisons between enumeration values are *not* supported. Enums are
not integers! not integers::
>>> Colors.red < Colors.blue >>> Colors.red < Colors.blue
Traceback (most recent call last): Traceback (most recent call last):
@ -191,14 +193,14 @@ not integers!
... ...
NotImplementedError NotImplementedError
Equality comparisons are defined though. Equality comparisons are defined though::
>>> Colors.blue == Colors.blue >>> Colors.blue == Colors.blue
True True
>>> Colors.green != Colors.blue >>> Colors.green != Colors.blue
True True
Enumeration values do not support ordered comparisons. Enumeration values do not support ordered comparisons::
>>> Colors.red < Colors.blue >>> Colors.red < Colors.blue
Traceback (most recent call last): Traceback (most recent call last):
@ -222,7 +224,7 @@ Enumeration values do not support ordered comparisons.
NotImplementedError NotImplementedError
While equality comparisons are allowed, comparisons against non-enumeration While equality comparisons are allowed, comparisons against non-enumeration
values will always compare not equal. values will always compare not equal::
>>> Colors.green == 2 >>> Colors.green == 2
False False
@ -235,7 +237,7 @@ values will always compare not equal.
If you really want the integer equivalent values, you can convert enumeration If you really want the integer equivalent values, you can convert enumeration
values explicitly using the ``int()`` built-in. This is quite convenient for values explicitly using the ``int()`` built-in. This is quite convenient for
storing enums in a database for example. storing enums in a database for example::
>>> int(Colors.red) >>> int(Colors.red)
1 1
@ -244,8 +246,8 @@ storing enums in a database for example.
>>> int(Colors.blue) >>> int(Colors.blue)
3 3
You can also convert back to the enumeration value by calling the Enum class, You can also convert back to the enumeration value by calling the Enum subclass,
passing in the integer value for the item you want. passing in the integer value for the item you want::
>>> Colors(1) >>> Colors(1)
<EnumValue: Colors.red [int=1]> <EnumValue: Colors.red [int=1]>
@ -256,14 +258,14 @@ passing in the integer value for the item you want.
>>> Colors(1) is Colors.red >>> Colors(1) is Colors.red
True True
The Enum class also accepts the string name of the enumeration value. The Enum subclass also accepts the string name of the enumeration value::
>>> Colors('red') >>> Colors('red')
<EnumValue: Colors.red [int=1]> <EnumValue: Colors.red [int=1]>
>>> Colors('blue') is Colors.blue >>> Colors('blue') is Colors.blue
True True
You get exceptions though, if you try to use invalid arguments. You get exceptions though, if you try to use invalid arguments::
>>> Colors('magenta') >>> Colors('magenta')
Traceback (most recent call last): Traceback (most recent call last):
@ -275,7 +277,7 @@ You get exceptions though, if you try to use invalid arguments.
ValueError: 99 ValueError: 99
The Enum base class also supports getitem syntax, exactly equivalent to the The Enum base class also supports getitem syntax, exactly equivalent to the
class's call semantics. class's call semantics::
>>> Colors[1] >>> Colors[1]
<EnumValue: Colors.red [int=1]> <EnumValue: Colors.red [int=1]>
@ -299,7 +301,7 @@ class's call semantics.
ValueError: 99 ValueError: 99
The integer equivalent values serve another purpose. You may not define two The integer equivalent values serve another purpose. You may not define two
enumeration values with the same integer value. enumeration values with the same integer value::
>>> class Bad(Enum): >>> class Bad(Enum):
... cartman = 1 ... cartman = 1
@ -311,7 +313,7 @@ enumeration values with the same integer value.
... ...
TypeError: Multiple enum values: 3 TypeError: Multiple enum values: 3
You also may not duplicate values in derived enumerations. You also may not duplicate values in derived enumerations::
>>> class BadColors(Colors): >>> class BadColors(Colors):
... yellow = 4 ... yellow = 4
@ -321,14 +323,14 @@ You also may not duplicate values in derived enumerations.
TypeError: Multiple enum values: 2 TypeError: Multiple enum values: 2
The Enum class support iteration. Enumeration values are returned in the The Enum class support iteration. Enumeration values are returned in the
sorted order of their integer equivalent values. sorted order of their integer equivalent values::
>>> [v.name for v in MoreColors] >>> [v.name for v in MoreColors]
['red', 'green', 'blue', 'pink', 'cyan'] ['red', 'green', 'blue', 'pink', 'cyan']
>>> [int(v) for v in MoreColors] >>> [int(v) for v in MoreColors]
[1, 2, 3, 4, 5] [1, 2, 3, 4, 5]
Enumeration values are hashable, so they can be used in dictionaries and sets. Enumeration values are hashable, so they can be used in dictionaries and sets::
>>> apples = {} >>> apples = {}
>>> apples[Colors.red] = 'red delicious' >>> apples[Colors.red] = 'red delicious'
@ -342,7 +344,7 @@ Enumeration values are hashable, so they can be used in dictionaries and sets.
Pickling Pickling
-------- --------
Enumerations created with the class syntax can also be pickled and unpickled: Enumerations created with the class syntax can also be pickled and unpickled::
>>> from enum.tests.fruit import Fruit >>> from enum.tests.fruit import Fruit
>>> from pickle import dumps, loads >>> from pickle import dumps, loads
@ -358,25 +360,25 @@ which takes an iterable object or dictionary to provide the item names and
values. ``make()`` is a static method. values. ``make()`` is a static method.
The first argument to ``make()`` is the name of the enumeration, and it returns 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 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 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 a sequence of strings which name the enumeration items. In this case, the
values are automatically assigned starting from 1:: values are automatically assigned starting from 1::
>>> from enum import make >>> import enum
>>> make('Animals', ('ant', 'bee', 'cat', 'dog')) >>> enum.make('Animals', ('ant', 'bee', 'cat', 'dog'))
<Animals {ant: 1, bee: 2, cat: 3, dog: 4}> <Animals {ant: 1, bee: 2, cat: 3, dog: 4}>
The items in source can also be 2-tuples, where the first item is the The items in source can also be 2-tuples, where the first item is the
enumeration value name and the second is the integer value to assign to the enumeration value name and the second is the integer value to assign to the
value. If 2-tuples are used, all items must be 2-tuples. value. If 2-tuples are used, all items must be 2-tuples::
>>> def enumiter(): >>> def enumiter():
... start = 1 ... start = 1
... while True: ... while True:
... yield start ... yield start
... start <<= 1 ... start <<= 1
>>> make('Flags', zip(list('abcdefg'), enumiter())) >>> enum.make('Flags', zip(list('abcdefg'), enumiter()))
<Flags {a: 1, b: 2, c: 4, d: 8, e: 16, f: 32, g: 64}> <Flags {a: 1, b: 2, c: 4, d: 8, e: 16, f: 32, g: 64}>
@ -402,24 +404,24 @@ common values in derived classes are identical (a singleton model). While PEP
complexity, though minimal, is hidden from users of the enumeration. complexity, though minimal, is hidden from users of the enumeration.
Unlike PEP 354, enumeration values can only be tested by identity comparison. Unlike PEP 354, enumeration values can only be tested by identity comparison.
This is to emphasis the fact that enumeration values are singletons, much like This is to emphasise the fact that enumeration values are singletons, much like
``None``. ``None``.
Acknowledgments Acknowledgments
=============== ===============
The ``flufl.enum`` implementation is based on an example by Jeremy Hylton. It This PEP describes the ``flufl.enum`` package by Barry Warsaw. ``flufl.enum``
has been modified and extended by Barry Warsaw for use in the `GNU Mailman`_ is based on an example by Jeremy Hylton. It has been modified and extended
project. Ben Finney is the author of the earlier enumeration PEP 354. by Barry Warsaw for use in the GNU Mailman [#]_ project. Ben Finney is the
author of the earlier enumeration PEP 354.
.. _`GNU Mailman`: http://www.list.org
References References
========== ==========
.. [#] http://mail.python.org/pipermail/python-ideas/2013-January/019003.html .. [#] http://mail.python.org/pipermail/python-ideas/2013-January/019003.html
.. [#] http://mail.python.org/pipermail/python-ideas/2013-February/019373.html .. [#] http://mail.python.org/pipermail/python-ideas/2013-February/019373.html
.. [#] http://www.list.org
Copyright Copyright
========= =========
@ -429,10 +431,15 @@ This document has been placed in the public domain.
Todo Todo
==== ====
* Mark PEP 354 "superseded by" this one * Mark PEP 354 "superseded by" this one, if accepted
* New package name within stdlib * New package name within stdlib - enum? (top-level)
* ``from enum import make`` creates a not-very-descriptive "make" name. Maybe * "Convenience API" says "make() is a static method" - what does this mean?
``make_enum`` or ``enum`` is better? make seems to be a simple module-level function in the implementation.
* For make, can we add an API like namedtuple's?
make('Animals, 'ant bee cat dog')
I.e. when make sees a string argument it splits it, making it similar to a
tuple but with far less manual quote typing. OTOH, it just saves a ".split"
so may not be worth the effort ?
.. ..
Local Variables: Local Variables: