| ``aenum`` --- support for advanced enumerations, namedtuples, and constants |
| =========================================================================== |
| |
| .. :synopsis:: enumerations are sets of symbolic names bound to unique, |
| constant values; namedtuples are fixed- or variable-length |
| tuples with the positions addressable by field name as well as by index; |
| constants are classes of named constants that cannot be rebound. |
| .. :moduleauthor:: Ethan Furman <ethan@stoneleaf.us> |
| |
| ---------------- |
| |
| An ``Enum`` is a set of symbolic names (members) bound to unique, constant |
| values. Within an enumeration, the members can be compared by identity, and |
| the enumeration itself can be iterated over. |
| |
| A ``NamedTuple`` is a class-based, fixed-length tuple with a name for each |
| possible position accessible using attribute-access notation. |
| |
| A ``NamedConstant`` is a class whose members cannot be rebound; it lacks all |
| other ``Enum`` capabilities, however; consequently, it can have duplicate |
| values. There is also a ``module`` function that can insert the |
| ``NamedConstant`` class into ``sys.modules`` where it will appear to be a |
| module whose top-level names cannot be rebound. |
| |
| .. note:: |
| ``constant`` refers to names not being rebound; mutable objects can be |
| mutated. |
| |
| |
| Module Contents |
| --------------- |
| |
| This module defines five enumeration classes that can be used to define unique |
| sets of names and values, one ``Enum`` class decorator, one ``NamedTuple`` |
| class, one ``NamedConstant`` class, and several helpers. |
| |
| ``NamedConstant`` |
| |
| NamedConstant class for creating groups of constants. These names cannot be |
| rebound to other values. |
| |
| ``Enum`` |
| |
| Base class for creating enumerated constants. See section `Enum Functional API`_ |
| for an alternate construction syntax. |
| |
| ``AutoNumber`` |
| |
| Flag to Enum constructor specifying auto numbering. |
| |
| .. note:: |
| |
| In Python 3 this turns on auto-attribute creation; use _ignore_ to |
| shield objects outside the Enum that you want access to during creation |
| (property, classmethod, and staticmethod are shielded by default, but |
| only if a custom _ignore_ is not specified). |
| |
| ``MultiValue`` |
| |
| Flag to Enum constructor specifying that each item of tuple value is a separate |
| value for that member; the first tuple item is the canonical one. |
| |
| ``NoAlias`` |
| |
| Flag to Enum Constructor specifying that duplicate valued members are distinct |
| and not aliases; by-value lookups are disabled. |
| |
| ``Unique`` |
| |
| Flag to Enum constructor specifying that duplicate valued members are not |
| allowed. |
| |
| .. note:: |
| The flags are inherited by the enumeration's subclasses. To use them in |
| Python 2 assign to ``_settings_`` in the class body. |
| |
| ``IntEnum`` |
| |
| Base class for creating enumerated constants that are also subclasses of ``int``. |
| |
| ``AutoNumberEnum`` |
| |
| Derived class that automatically assigns an ``int`` value to each member. |
| |
| ``OrderedEnum`` |
| |
| Derived class that adds ``<``, ``<=``, ``>=``, and ``>`` methods to an ``Enum``. |
| |
| ``UniqueEnum`` |
| |
| Derived class that ensures only one name is bound to any one value. |
| |
| ``unique`` |
| |
| Enum class decorator that ensures only one name is bound to any one value. |
| |
| .. note:: |
| |
| the ``UniqueEnum`` class, the ``unique`` decorator, and the Unique |
| flag all do the same thing; you do not need to use more than one of |
| them at the same time. |
| |
| ``NamedTuple`` |
| |
| Base class for `creating NamedTuples`_, either by subclassing or via it's |
| functional API. |
| |
| ``constant`` |
| |
| Descriptor to add constant values to an ``Enum``, or advanced constants to |
| ``NamedConstant``. |
| |
| ``convert`` |
| |
| Helper to transform target global variables into an ``Enum``. |
| |
| ``enum`` |
| |
| Helper for specifying keyword arguments when creating ``Enum`` members. |
| |
| ``export`` |
| |
| Helper for inserting ``Enum`` members ``NamedConstant`` constants into a |
| namespace (usually ``globals()``. |
| |
| ``extend_enum`` |
| |
| Helper for adding new ``Enum`` members, both stdlib and aenum. |
| |
| ``module`` |
| |
| Function to take a ``NamedConstant`` or ``Enum`` class and insert it into |
| ``sys.modules`` with the affect of a module whose top-level constant and |
| member names cannot be rebound. |
| |
| ``skip`` |
| |
| Descriptor to add a normal (non-``Enum`` member) attribute to an ``Enum`` |
| or ``NamedConstant``. |
| |
| |
| Creating an Enum |
| ---------------- |
| |
| Enumerations are created using the ``class`` syntax, which makes them |
| easy to read and write. An alternative creation method is described in |
| `Enum Functional API`_. To define an enumeration, subclass ``Enum`` as |
| follows:: |
| |
| >>> from aenum import Enum |
| >>> class Color(Enum): |
| ... red = 1 |
| ... green = 2 |
| ... blue = 3 |
| |
| *Nomenclature* |
| |
| - The class ``Color`` is an *enumeration* (or *enum*) |
| - The attributes ``Color.red``, ``Color.green``, etc., are |
| *enumeration members* (or *enum members*). |
| - The enum members have *names* and *values* (the name of |
| ``Color.red`` is ``red``, the value of ``Color.blue`` is |
| ``3``, etc.) |
| |
| .. note:: |
| |
| Even though we use the ``class`` syntax to create Enums, Enums |
| are not normal Python classes. See `How are Enums different?`_ for |
| more details. |
| |
| Enumeration members have human readable string representations:: |
| |
| >>> print(Color.red) |
| Color.red |
| |
| ...while their ``repr`` has more information:: |
| |
| >>> print(repr(Color.red)) |
| <Color.red: 1> |
| |
| The *type* of an enumeration member is the enumeration it belongs to:: |
| |
| >>> type(Color.red) |
| <aenum 'Color'> |
| >>> isinstance(Color.green, Color) |
| True |
| |
| Enumerations support iteration. In Python 3.x definition order is used; in |
| Python 2.x the definition order is not available, but class attribute |
| ``_order_`` is supported; otherwise, value order is used if posible, |
| otherwise alphabetical name order is used:: |
| |
| >>> class Shake(Enum): |
| ... _order_ = 'vanilla chocolate cookies mint' # only needed in 2.x |
| ... vanilla = 7 |
| ... chocolate = 4 |
| ... cookies = 9 |
| ... mint = 3 |
| ... |
| >>> for shake in Shake: |
| ... print(shake) |
| ... |
| Shake.vanilla |
| Shake.chocolate |
| Shake.cookies |
| Shake.mint |
| |
| The ``_order_`` attribute is always removed, but in 3.x it is also used to |
| verify that definition order is the same (useful for py2&3 code bases); |
| however, in the stdlib version it will be ignored and not removed. |
| |
| .. note:: |
| |
| To maintain compatibility with Python 3.4 and 3.5, use __order__ |
| instead (double leading and trailing underscores). |
| |
| Enumeration members are hashable, so they can be used in dictionaries and sets:: |
| |
| >>> apples = {} |
| >>> apples[Color.red] = 'red delicious' |
| >>> apples[Color.green] = 'granny smith' |
| >>> apples == {Color.red: 'red delicious', Color.green: 'granny smith'} |
| True |
| |
| In Python 3 the class syntax has a few extra advancements:: |
| |
| --> class Color( |
| ... Enum, |
| ... settings=(AutoNumber, MultiValue, NoAlias, Unique), |
| ... init='field_name1 field_name2 ...', |
| ... start=7, |
| ... ) |
| ... |
| |
| ``start`` is used to specify the starting value for ``AutoNumber``, and also |
| enables ``AutoNumber``:: |
| |
| --> class Count(Enum, start=11): |
| ... eleven |
| ... twelve |
| ... |
| --> Count.twelve.value == 12 |
| True |
| |
| ``init`` specifies the attribute names to store creation values to:: |
| |
| --> class Planet(Enum, init='mass radius'): |
| ... MERCURY = (3.303e+23, 2.4397e6) |
| ... EARTH = (5.976e+24, 6.37814e6) |
| ... |
| --> Planet.EARTH.value |
| (5.976e+24, 6378140.0) |
| --> Planet.EARTH.radius |
| 2.4397e6 |
| |
| The various settings enable special behavior: |
| |
| - ``AutoNumber`` is the same as specifying ``start=1`` |
| - ``AutoValue`` calls a user supplied ``_generate_next_value_`` to provide |
| missing/auto() values |
| - ``MultiValue`` allows multiple values per member instead of the usual 1 |
| - ``NoAlias`` allows different members to have the same value |
| - ``Unique`` disallows different members to have the same value |
| |
| .. note:: |
| |
| To use these features in Python 2 use the _sundered_ versions of |
| the names in the class body: ``_start_``, ``_init_``, ``_settings_``. |
| |
| |
| Programmatic access to enumeration members and their attributes |
| --------------------------------------------------------------- |
| |
| Sometimes it's useful to access members in enumerations programmatically (i.e. |
| situations where ``Color.red`` won't do because the exact color is not known |
| at program-writing time). ``Enum`` allows such access:: |
| |
| >>> Color(1) |
| <Color.red: 1> |
| >>> Color(3) |
| <Color.blue: 3> |
| |
| If you want to access enum members by *name*, use item access:: |
| |
| >>> Color['red'] |
| <Color.red: 1> |
| >>> Color['green'] |
| <Color.green: 2> |
| |
| If have an enum member and need its ``name`` or ``value``:: |
| |
| >>> member = Color.red |
| >>> member.name |
| 'red' |
| >>> member.value |
| 1 |
| |
| |
| Duplicating enum members and values |
| ----------------------------------- |
| |
| Having two enum members (or any other attribute) with the same name is invalid; |
| in Python 3.x this would raise an error, but in Python 2.x the second member |
| simply overwrites the first:: |
| |
| # python 2.x |
| --> class Shape(Enum): |
| ... square = 2 |
| ... square = 3 |
| ... |
| --> Shape.square |
| <Shape.square: 3> |
| |
| # python 3.x |
| --> class Shape(Enum): |
| ... square = 2 |
| ... square = 3 |
| Traceback (most recent call last): |
| ... |
| TypeError: Attempted to reuse key: 'square' |
| |
| However, two enum members are allowed to have the same value. Given two members |
| A and B with the same value (and A defined first), B is an alias to A. By-value |
| lookup of the value of A and B will return A. By-name lookup of B will also |
| return A:: |
| |
| >>> class Shape(Enum): |
| ... _order_ = 'square diamond circle' # needed in 2.x |
| ... square = 2 |
| ... diamond = 1 |
| ... circle = 3 |
| ... alias_for_square = 2 |
| ... |
| >>> Shape.square |
| <Shape.square: 2> |
| >>> Shape.alias_for_square |
| <Shape.square: 2> |
| >>> Shape(2) |
| <Shape.square: 2> |
| |
| |
| Allowing aliases is not always desirable. ``unique`` can be used to ensure |
| that none exist in a particular enumeration:: |
| |
| >>> from aenum import unique |
| >>> @unique |
| ... class Mistake(Enum): |
| ... _order_ = 'one two three' # only needed in 2.x |
| ... one = 1 |
| ... two = 2 |
| ... three = 3 |
| ... four = 3 |
| Traceback (most recent call last): |
| ... |
| ValueError: duplicate names found in <aenum 'Mistake'>: four -> three |
| |
| Iterating over the members of an enum does not provide the aliases:: |
| |
| >>> list(Shape) |
| [<Shape.square: 2>, <Shape.diamond: 1>, <Shape.circle: 3>] |
| |
| The special attribute ``__members__`` is a dictionary mapping names to members. |
| It includes all names defined in the enumeration, including the aliases:: |
| |
| >>> for name, member in sorted(Shape.__members__.items()): |
| ... name, member |
| ... |
| ('alias_for_square', <Shape.square: 2>) |
| ('circle', <Shape.circle: 3>) |
| ('diamond', <Shape.diamond: 1>) |
| ('square', <Shape.square: 2>) |
| |
| The ``__members__`` attribute can be used for detailed programmatic access to |
| the enumeration members. For example, finding all the aliases:: |
| |
| >>> [n for n, mbr in Shape.__members__.items() if mbr.name != n] |
| ['alias_for_square'] |
| |
| Comparisons |
| ----------- |
| |
| Enumeration members are compared by identity:: |
| |
| >>> Color.red is Color.red |
| True |
| >>> Color.red is Color.blue |
| False |
| >>> Color.red is not Color.blue |
| True |
| |
| Ordered comparisons between enumeration values are *not* supported. Enum |
| members are not integers (but see `IntEnum`_ below):: |
| |
| >>> Color.red < Color.blue |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in <module> |
| TypeError: unorderable types: Color() < Color() |
| |
| .. warning:: |
| |
| In Python 2 *everything* is ordered, even though the ordering may not |
| make sense. If you want your enumerations to have a sensible ordering |
| consider using an `OrderedEnum`_. |
| |
| |
| Equality comparisons are defined though:: |
| |
| >>> Color.blue == Color.red |
| False |
| >>> Color.blue != Color.red |
| True |
| >>> Color.blue == Color.blue |
| True |
| |
| Comparisons against non-enumeration values will always compare not equal |
| (again, ``IntEnum`` was explicitly designed to behave differently, see |
| below):: |
| |
| >>> Color.blue == 2 |
| False |
| |
| |
| Allowed members and attributes of enumerations |
| ---------------------------------------------- |
| |
| The examples above use integers for enumeration values. Using integers is |
| short and handy (and provided by default by the `Enum Functional API`_), but not |
| strictly enforced. In the vast majority of use-cases, one doesn't care what |
| the actual value of an enumeration is. But if the value *is* important, |
| enumerations can have arbitrary values. |
| |
| Enumerations are Python classes, and can have methods and special methods as |
| usual. If we have this enumeration:: |
| |
| >>> class Mood(Enum): |
| ... funky = 1 |
| ... happy = 3 |
| ... |
| ... def describe(self): |
| ... # self is the member here |
| ... return self.name, self.value |
| ... |
| ... def __str__(self): |
| ... return 'my custom str! {0}'.format(self.value) |
| ... |
| ... @classmethod |
| ... def favorite_mood(cls): |
| ... # cls here is the enumeration |
| ... return cls.happy |
| |
| Then:: |
| |
| >>> Mood.favorite_mood() |
| <Mood.happy: 3> |
| >>> Mood.happy.describe() |
| ('happy', 3) |
| >>> str(Mood.funky) |
| 'my custom str! 1' |
| |
| The rules for what is allowed are as follows: _sunder_ names (starting and |
| ending with a single underscore) are reserved by enum and cannot be used; |
| all other attributes defined within an enumeration will become members of this |
| enumeration, with the exception of *__dunder__* names and descriptors (methods |
| are also descriptors). |
| |
| .. note:: |
| |
| If your enumeration defines ``__new__`` and/or ``__init__`` then |
| whatever value(s) were given to the enum member will be passed into |
| those methods. See `Planet`_ for an example. |
| |
| |
| Restricted subclassing of enumerations |
| -------------------------------------- |
| |
| Subclassing an enumeration is allowed only if the enumeration does not define |
| any members. So this is forbidden:: |
| |
| >>> class MoreColor(Color): |
| ... pink = 17 |
| Traceback (most recent call last): |
| ... |
| TypeError: Cannot extend enumerations via subclassing. |
| |
| But this is allowed:: |
| |
| >>> class Foo(Enum): |
| ... def some_behavior(self): |
| ... pass |
| ... |
| >>> class Bar(Foo): |
| ... happy = 1 |
| ... sad = 2 |
| ... |
| |
| Allowing subclassing of enums that define members would lead to a violation of |
| some important invariants of types and instances. On the other hand, it makes |
| sense to allow sharing some common behavior between a group of enumerations. |
| (See `OrderedEnum`_ for an example.) |
| |
| |
| Pickling |
| -------- |
| |
| Enumerations can be pickled and unpickled:: |
| |
| >>> from aenum.test import Fruit |
| >>> from pickle import dumps, loads |
| >>> Fruit.tomato is loads(dumps(Fruit.tomato, 2)) |
| True |
| |
| The usual restrictions for pickling apply: picklable enums must be defined in |
| the top level of a module, since unpickling requires them to be importable |
| from that module. |
| |
| .. note:: |
| |
| With pickle protocol version 4 (introduced in Python 3.4) it is possible |
| to easily pickle enums nested in other classes. |
| |
| |
| |
| Enum Functional API |
| ------------------- |
| |
| The ``Enum`` class is callable, providing the following functional API:: |
| |
| >>> Animal = Enum('Animal', 'ant bee cat dog') |
| >>> Animal |
| <aenum 'Animal'> |
| >>> Animal.ant |
| <Animal.ant: 1> |
| >>> Animal.ant.value |
| 1 |
| >>> list(Animal) |
| [<Animal.ant: 1>, <Animal.bee: 2>, <Animal.cat: 3>, <Animal.dog: 4>] |
| |
| The semantics of this API resemble ``namedtuple``. The first argument |
| of the call to ``Enum`` is the name of the enumeration. |
| |
| The second argument is the *source* of enumeration member names. It can be a |
| whitespace-separated string of names, a sequence of names, a sequence of |
| 2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to |
| values. The last two options enable assigning arbitrary values to |
| enumerations; the others auto-assign increasing integers starting with 1. A |
| new class derived from ``Enum`` is returned. In other words, the above |
| assignment to ``Animal`` is equivalent to:: |
| |
| >>> class Animals(Enum): |
| ... ant = 1 |
| ... bee = 2 |
| ... cat = 3 |
| ... dog = 4 |
| |
| Pickling enums created with the functional API can be tricky as frame stack |
| implementation details are used to try and figure out which module the |
| enumeration is being created in (e.g. it will fail if you use a utility |
| function in separate module, and also may not work on IronPython or Jython). |
| The solution is to specify the module name explicitly as follows:: |
| |
| >>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__) |
| |
| Derived Enumerations |
| -------------------- |
| |
| IntEnum |
| ^^^^^^^ |
| |
| A variation of ``Enum`` is provided which is also a subclass of |
| ``int``. Members of an ``IntEnum`` can be compared to integers; |
| by extension, integer enumerations of different types can also be compared |
| to each other:: |
| |
| >>> from aenum import IntEnum |
| >>> class Shape(IntEnum): |
| ... circle = 1 |
| ... square = 2 |
| ... |
| >>> class Request(IntEnum): |
| ... post = 1 |
| ... get = 2 |
| ... |
| >>> Shape == 1 |
| False |
| >>> Shape.circle == 1 |
| True |
| >>> Shape.circle == Request.post |
| True |
| |
| However, they still can't be compared to standard ``Enum`` enumerations:: |
| |
| >>> class Shape(IntEnum): |
| ... circle = 1 |
| ... square = 2 |
| ... |
| >>> class Color(Enum): |
| ... red = 1 |
| ... green = 2 |
| ... |
| >>> Shape.circle == Color.red |
| False |
| |
| ``IntEnum`` values behave like integers in other ways you'd expect:: |
| |
| >>> int(Shape.circle) |
| 1 |
| >>> ['a', 'b', 'c'][Shape.circle] |
| 'b' |
| >>> [i for i in range(Shape.square)] |
| [0, 1] |
| |
| For the vast majority of code, ``Enum`` is strongly recommended, |
| since ``IntEnum`` breaks some semantic promises of an enumeration (by |
| being comparable to integers, and thus by transitivity to other |
| unrelated enumerations). It should be used only in special cases where |
| there's no other choice; for example, when integer constants are |
| replaced with enumerations and backwards compatibility is required with code |
| that still expects integers. |
| |
| |
| IntFlag |
| ^^^^^^^ |
| |
| The next variation of ``Enum`` provided, ``IntFlag``, is also based |
| on ``int``. The difference being ``IntFlag`` members can be combined |
| using the bitwise operators (&, \|, ^, ~) and the result is still an |
| ``IntFlag`` member. However, as the name implies, ``IntFlag`` |
| members also subclass ``int`` and can be used wherever an ``int`` is |
| used. Any operation on an ``IntFlag`` member besides the bit-wise |
| operations will lose the ``IntFlag`` membership. |
| |
| Sample ``IntFlag`` class:: |
| |
| >>> from aenum import IntFlag |
| >>> class Perm(IntFlag): |
| ... R = 4 |
| ... W = 2 |
| ... X = 1 |
| ... |
| >>> Perm.R | Perm.W |
| <Perm.R|W: 6> |
| >>> Perm.R + Perm.W |
| 6 |
| >>> RW = Perm.R | Perm.W |
| >>> Perm.R in RW |
| True |
| |
| It is also possible to name the combinations:: |
| |
| >>> class Perm(IntFlag): |
| ... R = 4 |
| ... W = 2 |
| ... X = 1 |
| ... RWX = 7 |
| >>> Perm.RWX |
| <Perm.RWX: 7> |
| >>> ~Perm.RWX |
| <Perm.-8: -8> |
| |
| Another important difference between ``IntFlag`` and ``Enum`` is that |
| if no flags are set (the value is 0), its boolean evaluation is ``False``:: |
| |
| >>> Perm.R & Perm.X |
| <Perm.0: 0> |
| >>> bool(Perm.R & Perm.X) |
| False |
| |
| Because ``IntFlag`` members are also subclasses of ``int`` they can |
| be combined with them:: |
| |
| >>> Perm.X | 8 |
| <Perm.8|X: 9> |
| |
| |
| Flag |
| ^^^^ |
| |
| The last variation is ``Flag``. Like ``IntFlag``, ``Flag`` |
| members can be combined using the bitwise operators (&, \|, ^, ~). Unlike |
| ``IntFlag``, they cannot be combined with, nor compared against, any |
| other ``Flag`` enumeration, nor ``int``. While it is possible to |
| specify the values directly it is recommended to use ``auto`` as the |
| value and let ``Flag`` select an appropriate value. |
| |
| Like ``IntFlag``, if a combination of ``Flag`` members results in no |
| flags being set, the boolean evaluation is ``False``:: |
| |
| >>> from aenum import Flag, auto |
| >>> class Color(Flag): |
| ... RED = auto() |
| ... BLUE = auto() |
| ... GREEN = auto() |
| ... |
| >>> Color.RED & Color.GREEN |
| <Color.0: 0> |
| >>> 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 = auto() |
| ... BLUE = auto() |
| ... GREEN = auto() |
| ... WHITE = RED | BLUE | GREEN |
| ... |
| --> Color.WHITE |
| <Color.WHITE: 7> |
| |
| Giving a name to the "no flags set" condition does not change its boolean |
| value:: |
| |
| >>> class Color(Flag): |
| ... BLACK = 0 |
| ... RED = auto() |
| ... BLUE = auto() |
| ... GREEN = auto() |
| ... |
| >>> Color.BLACK |
| <Color.BLACK: 0> |
| >>> bool(Color.BLACK) |
| False |
| |
| .. note:: |
| |
| For the majority of new code, ``Enum`` and ``Flag`` are strongly |
| recommended, since ``IntEnum`` and ``IntFlag`` break some |
| semantic promises of an enumeration (by being comparable to integers, and |
| thus by transitivity to other unrelated enumerations). ``IntEnum`` |
| and ``IntFlag`` should be used only in cases where ``Enum`` and |
| ``Flag`` will not do; for example, when integer constants are replaced |
| with enumerations, or for interoperability with other systems. |
| |
| |
| Others |
| ^^^^^^ |
| |
| While ``IntEnum`` is part of the ``aenum`` module, it would be very |
| simple to implement independently:: |
| |
| class IntEnum(int, Enum): |
| pass |
| |
| This demonstrates how similar derived enumerations can be defined; for example |
| a ``StrEnum`` that mixes in ``str`` instead of ``int``. |
| |
| Some rules: |
| |
| 1. When subclassing ``Enum``, mix-in types must appear before |
| ``Enum`` itself in the sequence of bases, as in the ``IntEnum`` |
| example above. |
| 2. While ``Enum`` can have members of any type, once you mix in an |
| additional type, all the members must have values of that type, e.g. |
| ``int`` above. This restriction does not apply to mix-ins which only |
| add methods and don't specify another data type such as ``int`` or |
| ``str``. |
| 3. When another data type is mixed in, the ``value`` attribute is *not the |
| same* as the enum member itself, although it is equivalant and will compare |
| equal. |
| 4. %-style formatting: ``%s`` and ``%r`` call ``Enum``'s ``__str__`` and |
| ``__repr__`` respectively; other codes (such as ``%i`` or ``%h`` for |
| IntEnum) treat the enum member as its mixed-in type. |
| |
| 5. ``str.__format__`` (or ``format``) will use the mixed-in |
| type's ``__format__``. If the ``Enum``'s ``str`` or |
| ``repr`` is desired use the ``!s`` or ``!r`` ``str`` format codes. |
| |
| .. note:: |
| |
| Prior to Python 3.4 there is a bug in ``str``'s %-formatting: ``int`` |
| subclasses are printed as strings and not numbers when the ``%d``, ``%i``, |
| or ``%u`` codes are used. |
| |
| |
| Extra Goodies |
| ------------- |
| |
| aenum supports a few extra techniques not found in the stdlib version. |
| |
| enum |
| ^^^^ |
| |
| If you have several items to initialize your ``Enum`` members with and |
| would like to use keyword arguments, the ``enum`` helper is for you:: |
| |
| >>> from aenum import enum |
| >>> class Presidents(Enum): |
| ... Washington = enum('George Washington', circa=1776, death=1797) |
| ... Jackson = enum('Andrew Jackson', circa=1830, death=1837) |
| ... Lincoln = enum('Abraham Lincoln', circa=1860, death=1865) |
| ... |
| >>> Presidents.Lincoln |
| <Presidents.Lincoln: enum('Abraham Lincoln', circa=1860, death=1865)> |
| |
| extend_enum |
| ^^^^^^^^^^^ |
| |
| For those rare cases when you need to create your ``Enum`` in pieces, you |
| can use ``extend_enum`` to add new members after the initial creation:: |
| |
| >>> from aenum import extend_enum |
| >>> class Color(Enum): |
| ... red = 1 |
| ... green = 2 |
| ... blue = 3 |
| ... |
| >>> list(Color) |
| [<Color.red: 1>, <Color.green: 2>, <Color.blue: 3>] |
| >>> extend_enum(Color, 'opacity', 4) |
| >>> list(Color) |
| [<Color.red: 1>, <Color.green: 2>, <Color.blue: 3>, <Color.opacity: 4>] |
| >>> Color.opacity in Color |
| True |
| >>> Color.opacity.name == 'opacity' |
| True |
| >>> Color.opacity.value == 4 |
| True |
| >>> Color(4) |
| <Color.opacity: 4> |
| >>> Color['opacity'] |
| <Color.opacity: 4> |
| |
| --> Color.__members__ |
| OrderedDict([ |
| ('red', <Color.red: 1>), |
| ('green', <Color.green: 2>), |
| ('blue', <Color.blue: 3>), |
| ('opacity', <Color.opacity: 4>) |
| ]) |
| |
| constant |
| ^^^^^^^^ |
| |
| If you need to have some constant value in your ``Enum`` that isn't a member, |
| use ``constant``:: |
| |
| >>> from aenum import constant |
| >>> class Planet(Enum): |
| ... MERCURY = (3.303e+23, 2.4397e6) |
| ... EARTH = (5.976e+24, 6.37814e6) |
| ... JUPITER = (1.9e+27, 7.1492e7) |
| ... URANUS = (8.686e+25, 2.5559e7) |
| ... G = constant(6.67300E-11) |
| ... def __init__(self, mass, radius): |
| ... self.mass = mass # in kilograms |
| ... self.radius = radius # in meters |
| ... @property |
| ... def surface_gravity(self): |
| ... # universal gravitational constant (m3 kg-1 s-2) |
| ... return self.G * self.mass / (self.radius * self.radius) |
| ... |
| >>> Planet.EARTH.value |
| (5.976e+24, 6378140.0) |
| >>> Planet.EARTH.surface_gravity |
| 9.802652743337129 |
| >>> Planet.G |
| 6.673e-11 |
| >>> Planet.G = 9 |
| Traceback (most recent call last): |
| ... |
| AttributeError: Planet: cannot rebind constant 'G' |
| |
| skip |
| ^^^^ |
| |
| If you need a standard attribute that is not converted into an ``Enum`` |
| member, use ``skip``:: |
| |
| >>> from aenum import skip |
| >>> class Color(Enum): |
| ... red = 1 |
| ... green = 2 |
| ... blue = 3 |
| ... opacity = skip(0.45) |
| ... |
| >>> Color.opacity |
| 0.45 |
| >>> Color.opacity = 0.77 |
| >>> Color.opacity |
| 0.77 |
| |
| start |
| ^^^^^ |
| |
| When using Python 3 you have the option of turning on auto-numbering |
| (useful for when you don't care which numbers are assigned as long as |
| they are consistent and in order):: |
| |
| >>> class Color(Enum, start=1): # doctest: +SKIP |
| ... red, green, blue |
| ... |
| >>> Color.blue |
| <Color.blue: 3> |
| |
| This can also be done in Python 2, albeit not as elegantly:: |
| |
| >>> class Color(Enum): # doctest: +SKIP |
| ... _start_ = 1 |
| ... red = auto() |
| ... green = auto() |
| ... blue = auto() |
| ... |
| >>> Color.blue |
| <Color.blue: 3> |
| |
| .. note:: auto-numbering turns off when a non-member is defined |
| |
| init |
| ^^^^ |
| |
| If you need an ``__init__`` method that does nothing besides save its |
| arguments, ``init`` is for you:: |
| |
| >>> class Planet(Enum, init='mass radius'): # doctest: +SKIP |
| ... MERCURY = (3.303e+23, 2.4397e6) |
| ... EARTH = (5.976e+24, 6.37814e6) |
| ... JUPITER = (1.9e+27, 7.1492e7) |
| ... URANUS = (8.686e+25, 2.5559e7) |
| ... G = constant(6.67300E-11) |
| ... @property |
| ... def surface_gravity(self): |
| ... # universal gravitational constant (m3 kg-1 s-2) |
| ... return self.G * self.mass / (self.radius * self.radius) |
| ... |
| >>> Planet.JUPITER.value |
| (1.9e+27, 71492000.0) |
| >>> Planet.JUPITER.mass |
| 1.9e+27 |
| |
| combining init and AutoValue |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| When a member will have multiple values, and some of them have an easy to |
| calculate default value, ``init`` and ``AutoValue`` can be combined. Here |
| is the Python 2 version:: |
| |
| >>> from aenum import AutoValue |
| >>> class SelectionEnum(Enum): |
| ... _init_ = 'db user' |
| ... _settings_ = AutoValue |
| ... def __new__(cls, *args, **kwds): |
| ... count = len(cls.__members__) |
| ... obj = object.__new__(cls) |
| ... obj._count = count |
| ... obj._value_ = args |
| ... return obj |
| ... @staticmethod |
| ... def _generate_next_value_(name, start, count, values, *args, **kwds): |
| ... return (name, ) + args |
| ... |
| >>> class NotificationType(SelectionEnum): |
| ... # usually, name is the same as db |
| ... # but not for blanks |
| ... blank = '', '' |
| ... C = 'Catalog' |
| ... S = 'Sheet' |
| ... B = 'Both' |
| ... |
| >>> NotificationType.blank |
| <NotificationType.blank: ('', '')> |
| >>> NotificationType.B |
| <NotificationType.B: ('B', 'Both')> |
| |
| |
| Decorators |
| ---------- |
| |
| unique |
| ^^^^^^ |
| |
| A ``class`` decorator specifically for enumerations. It searches an |
| enumeration's ``__members__`` gathering any aliases it finds; if any are |
| found ``ValueError`` is raised with the details:: |
| |
| >>> @unique |
| ... class NoDupes(Enum): |
| ... first = 'one' |
| ... second = 'two' |
| ... third = 'two' |
| Traceback (most recent call last): |
| ... |
| ValueError: duplicate names found in <aenum 'NoDupes'>: third -> second |
| |
| |
| Interesting examples |
| -------------------- |
| |
| While ``Enum`` and ``IntEnum`` are expected to cover the majority of |
| use-cases, they cannot cover them all. Here are recipes for some different |
| types of enumerations that can be used directly (the first three are included |
| in the module), or as examples for creating one's own. |
| |
| |
| AutoNumber |
| ^^^^^^^^^^ |
| |
| Avoids having to specify the value for each enumeration member:: |
| |
| >>> class AutoNumber(Enum): |
| ... def __new__(cls): |
| ... value = len(cls.__members__) + 1 |
| ... obj = object.__new__(cls) |
| ... obj._value_ = value |
| ... return obj |
| ... |
| >>> class Color(AutoNumber): |
| ... _order_ = "red green blue" # only needed in 2.x |
| ... red = () |
| ... green = () |
| ... blue = () |
| ... |
| >>> Color.green.value == 2 |
| True |
| |
| .. note:: |
| |
| The `__new__` method, if defined, is used during creation of the Enum |
| members; it is then replaced by Enum's `__new__` which is used after |
| class creation for lookup of existing members. Due to the way Enums are |
| supposed to behave, there is no way to customize Enum's `__new__` without |
| modifying the class after it is created. |
| |
| |
| UniqueEnum |
| ^^^^^^^^^^ |
| |
| Raises an error if a duplicate member name is found instead of creating an |
| alias:: |
| |
| >>> class UniqueEnum(Enum): |
| ... def __init__(self, *args): |
| ... cls = self.__class__ |
| ... if any(self.value == e.value for e in cls): |
| ... a = self.name |
| ... e = cls(self.value).name |
| ... raise ValueError( |
| ... "aliases not allowed in UniqueEnum: %r --> %r" |
| ... % (a, e)) |
| ... |
| >>> class Color(UniqueEnum): |
| ... _order_ = 'red green blue' |
| ... red = 1 |
| ... green = 2 |
| ... blue = 3 |
| ... grene = 2 |
| Traceback (most recent call last): |
| ... |
| ValueError: aliases not allowed in UniqueEnum: 'grene' --> 'green' |
| |
| |
| OrderedEnum |
| ^^^^^^^^^^^ |
| |
| An ordered enumeration that is not based on ``IntEnum`` and so maintains |
| the normal ``Enum`` invariants (such as not being comparable to other |
| enumerations):: |
| |
| >>> class OrderedEnum(Enum): |
| ... def __ge__(self, other): |
| ... if self.__class__ is other.__class__: |
| ... return self._value_ >= other._value_ |
| ... return NotImplemented |
| ... def __gt__(self, other): |
| ... if self.__class__ is other.__class__: |
| ... return self._value_ > other._value_ |
| ... return NotImplemented |
| ... def __le__(self, other): |
| ... if self.__class__ is other.__class__: |
| ... return self._value_ <= other._value_ |
| ... return NotImplemented |
| ... def __lt__(self, other): |
| ... if self.__class__ is other.__class__: |
| ... return self._value_ < other._value_ |
| ... return NotImplemented |
| ... |
| >>> class Grade(OrderedEnum): |
| ... __ordered__ = 'A B C D F' |
| ... A = 5 |
| ... B = 4 |
| ... C = 3 |
| ... D = 2 |
| ... F = 1 |
| ... |
| >>> Grade.C < Grade.A |
| True |
| |
| |
| Planet |
| ^^^^^^ |
| |
| If ``__new__`` or ``__init__`` is defined the value of the enum member |
| will be passed to those methods:: |
| |
| >>> class Planet(Enum): |
| ... MERCURY = (3.303e+23, 2.4397e6) |
| ... VENUS = (4.869e+24, 6.0518e6) |
| ... EARTH = (5.976e+24, 6.37814e6) |
| ... MARS = (6.421e+23, 3.3972e6) |
| ... JUPITER = (1.9e+27, 7.1492e7) |
| ... SATURN = (5.688e+26, 6.0268e7) |
| ... URANUS = (8.686e+25, 2.5559e7) |
| ... NEPTUNE = (1.024e+26, 2.4746e7) |
| ... def __init__(self, mass, radius): |
| ... self.mass = mass # in kilograms |
| ... self.radius = radius # in meters |
| ... @property |
| ... def surface_gravity(self): |
| ... # universal gravitational constant (m3 kg-1 s-2) |
| ... G = 6.67300E-11 |
| ... return G * self.mass / (self.radius * self.radius) |
| ... |
| >>> Planet.EARTH.value |
| (5.976e+24, 6378140.0) |
| >>> Planet.EARTH.surface_gravity |
| 9.802652743337129 |
| |
| |
| How are Enums different? |
| ------------------------ |
| |
| Enums have a custom metaclass that affects many aspects of both derived Enum |
| classes and their instances (members). |
| |
| |
| Enum Classes |
| ^^^^^^^^^^^^ |
| |
| The ``EnumMeta`` metaclass is responsible for providing the |
| ``__contains__``, ``__dir__``, ``__iter__`` and other methods that |
| allow one to do things with an ``Enum`` class that fail on a typical |
| class, such as ``list(Color)`` or ``some_var in Color``. ``EnumMeta`` is |
| responsible for ensuring that various other methods on the final ``Enum`` |
| class are correct (such as ``__new__``, ``__getnewargs__``, |
| ``__str__`` and ``__repr__``). |
| |
| .. note:: |
| |
| ``__dir__`` is not changed in the Python 2 line as it messes up some |
| of the decorators included in the stdlib. |
| |
| |
| Enum Members (aka instances) |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The most interesting thing about Enum members is that they are singletons. |
| ``EnumMeta`` creates them all while it is creating the ``Enum`` |
| class itself, and then puts a custom ``__new__`` in place to ensure |
| that no new ones are ever instantiated by returning only the existing |
| member instances. |
| |
| |
| Finer Points |
| ^^^^^^^^^^^^ |
| |
| ``Enum`` members are instances of an ``Enum`` class, and even though they |
| are accessible as `EnumClass.member1.member2`, they should not be |
| accessed directly from the member as that lookup may fail or, worse, |
| return something besides the ``Enum`` member you were looking for |
| (changed in version 1.1.1):: |
| |
| >>> class FieldTypes(Enum): |
| ... name = 1 |
| ... value = 2 |
| ... size = 3 |
| ... |
| >>> FieldTypes.value.size |
| <FieldTypes.size: 3> |
| >>> FieldTypes.size.value |
| 3 |
| |
| The ``__members__`` attribute is only available on the class. |
| |
| |
| ``__members__`` is always an ``OrderedDict``, with the order being the |
| definition order in Python 3.x or the order in ``_order_`` in Python 2.7; |
| if no ``_order_`` was specified in Python 2.7 then the order of |
| ``__members__`` is either increasing value or alphabetically by name. |
| |
| If you give your ``Enum`` subclass extra methods, like the `Planet`_ |
| class above, those methods will show up in a `dir` of the member, |
| but not of the class (in Python 3.x):: |
| |
| --> dir(Planet) |
| ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', |
| 'VENUS', '__class__', '__doc__', '__members__', '__module__'] |
| --> dir(Planet.EARTH) |
| ['__class__', '__doc__', '__module__', 'name', 'surface_gravity', 'value'] |
| |
| A ``__new__`` method will only be used for the creation of the |
| ``Enum`` members -- after that it is replaced. This means if you wish to |
| change how ``Enum`` members are looked up you either have to write a |
| helper function or a ``classmethod``. |
| |
| If the stdlib ``enum`` is available (Python 3.4+ and it hasn't been shadowed |
| by, for example, ``enum34``) then aenum will inherit from it. |
| |
| To use the ``AutoNumber``, ``MultiValue``, ``NoAlias``, and ``Unique`` flags |
| in Py2 or Py2/Py3 codebases, use ``_settings_ = ...`` in the class body. |
| |
| To use ``init`` in Py2 or Py2/Py3 codebases use ``_init_`` in the class body. |
| |
| To use ``start`` in Py2 or Py2/Py3 codebases use ``_start_`` in the class body. |
| |
| When creating class bodies dynamically, put any variables you need to use into |
| ``_ignore_``:: |
| |
| >>> from datetime import timedelta |
| >>> from aenum import NoAlias |
| >>> class Period(timedelta, Enum): |
| ... ''' |
| ... different lengths of time |
| ... ''' |
| ... _init_ = 'value period' |
| ... _settings_ = NoAlias |
| ... _ignore_ = 'Period i' |
| ... Period = vars() |
| ... for i in range(31): |
| ... Period['day_%d' % i] = i, 'day' |
| ... for i in range(15): |
| ... Period['week_%d' % i] = i*7, 'week' |
| ... |
| >>> hasattr(Period, '_ignore_') |
| False |
| >>> hasattr(Period, 'Period') |
| False |
| >>> hasattr(Period, 'i') |
| False |
| |
| The name listed in ``_ignore_``, as well as ``_ignore_`` itself, will not be |
| present in the final enumeration as neither attributes nor members. |
| |
| .. note:: |
| |
| except for __dunder__ attributes/methods, all _sunder_ attributes must |
| be before any thing else in the class body |
| |
| |
| Creating NamedTuples |
| -------------------- |
| |
| Simple |
| ^^^^^^ |
| |
| The most common way to create a new NamedTuple will be via the functional API:: |
| |
| >>> from aenum import NamedTuple |
| >>> Book = NamedTuple('Book', 'title author genre', module=__name__) |
| |
| This creates a ``NamedTuple`` called ``Book`` that will always contain three |
| items, each of which is also addressable as ``title``, ``author``, or ``genre``. |
| |
| ``Book`` instances can be created using positional or keyword argements or a |
| mixture of the two:: |
| |
| >>> b1 = Book('Lord of the Rings', 'J.R.R. Tolkien', 'fantasy') |
| >>> b2 = Book(title='Jhereg', author='Steven Brust', genre='fantasy') |
| >>> b3 = Book('Empire', 'Orson Scott Card', genre='scifi') |
| |
| If too few or too many arguments are used a ``TypeError`` will be raised:: |
| |
| >>> b4 = Book('Hidden Empire') |
| Traceback (most recent call last): |
| ... |
| TypeError: values not provided for field(s): author, genre |
| >>> b5 = Book(genre='business') |
| Traceback (most recent call last): |
| ... |
| TypeError: values not provided for field(s): title, author |
| |
| As a ``class`` the above ``Book`` ``NamedTuple`` would look like:: |
| |
| >>> class Book(NamedTuple): |
| ... title = 0 |
| ... author = 1 |
| ... genre = 2 |
| ... |
| |
| For compatibility with the stdlib ``namedtuple``, NamedTuple also has the |
| ``_asdict``, ``_make``, and ``_replace`` methods, and the ``_fields`` |
| attribute, which all function similarly:: |
| |
| >>> class Point(NamedTuple): |
| ... x = 0, 'horizontal coordinate', 1 |
| ... y = 1, 'vertical coordinate', -1 |
| ... |
| >>> class Color(NamedTuple): |
| ... r = 0, 'red component', 11 |
| ... g = 1, 'green component', 29 |
| ... b = 2, 'blue component', 37 |
| ... |
| >>> Pixel = NamedTuple('Pixel', Point+Color, module=__name__) |
| >>> pixel = Pixel(99, -101, 255, 128, 0) |
| |
| >>> pixel._asdict() |
| OrderedDict([('x', 99), ('y', -101), ('r', 255), ('g', 128), ('b', 0)]) |
| |
| >>> Point._make((4, 5)) |
| Point(x=4, y=5) |
| |
| >>> purple = Color(127, 0, 127) |
| >>> mid_gray = purple._replace(g=127) |
| >>> mid_gray |
| Color(r=127, g=127, b=127) |
| |
| >>> pixel._fields |
| ['x', 'y', 'r', 'g', 'b'] |
| |
| >>> Pixel._fields |
| ['x', 'y', 'r', 'g', 'b'] |
| |
| |
| Advanced |
| ^^^^^^^^ |
| |
| The simple method of creating ``NamedTuples`` requires always specifying all |
| possible arguments when creating instances; failure to do so will raise |
| exceptions:: |
| |
| >>> class Point(NamedTuple): |
| ... x = 0 |
| ... y = 1 |
| ... |
| >>> Point() |
| Traceback (most recent call last): |
| ... |
| TypeError: values not provided for field(s): x, y |
| >>> Point(1) |
| Traceback (most recent call last): |
| ... |
| TypeError: values not provided for field(s): y |
| >>> Point(y=2) |
| Traceback (most recent call last): |
| ... |
| TypeError: values not provided for field(s): x |
| |
| However, it is possible to specify both docstrings and default values when |
| creating a ``NamedTuple`` using the class method:: |
| |
| >>> class Point(NamedTuple): |
| ... x = 0, 'horizontal coordinate', 0 |
| ... y = 1, 'vertical coordinate', 0 |
| ... |
| >>> Point() |
| Point(x=0, y=0) |
| >>> Point(1) |
| Point(x=1, y=0) |
| >>> Point(y=2) |
| Point(x=0, y=2) |
| |
| It is also possible to create ``NamedTuples`` that only have named attributes |
| for certain fields; any fields without names can still be accessed by index:: |
| |
| >>> class Person(NamedTuple): |
| ... fullname = 2 |
| ... phone = 5 |
| ... |
| >>> p = Person('Ethan', 'Furman', 'Ethan Furman', |
| ... 'ethan at stoneleaf dot us', |
| ... 'ethan.furman', '999.555.1212') |
| >>> p |
| Person('Ethan', 'Furman', 'Ethan Furman', 'ethan at stoneleaf dot us', |
| 'ethan.furman', '999.555.1212') |
| >>> p.fullname |
| 'Ethan Furman' |
| >>> p.phone |
| '999.555.1212' |
| >>> p[0] |
| 'Ethan' |
| |
| In the above example the last named field was also the last field possible; in |
| those cases where you don't need to have the last possible field named, you can |
| provide a ``_size_`` of ``TupleSize.minimum`` to declare that more fields are |
| okay:: |
| |
| >>> from aenum import TupleSize |
| >>> class Person(NamedTuple): |
| ... _size_ = TupleSize.minimum |
| ... first = 0 |
| ... last = 1 |
| ... |
| |
| or, optionally if using Python 3:: |
| |
| >>> class Person(NamedTuple, size=TupleSize.minimum): # doctest: +SKIP |
| ... first = 0 |
| ... last = 1 |
| |
| and in use:: |
| |
| >>> Person('Ethan', 'Furman') |
| Person(first='Ethan', last='Furman') |
| |
| >>> Person('Ethan', 'Furman', 'ethan.furman') |
| Person('Ethan', 'Furman', 'ethan.furman') |
| |
| >>> Person('Ethan', 'Furman', 'ethan.furman', 'yay Python!') |
| Person('Ethan', 'Furman', 'ethan.furman', 'yay Python!') |
| |
| >>> Person('Ethan') |
| Traceback (most recent call last): |
| ... |
| TypeError: values not provided for field(s): last |
| |
| Also, for those cases where even named fields may not be present, you can |
| specify ``TupleSize.variable``:: |
| |
| >>> class Person(NamedTuple): |
| ... _size_ = TupleSize.variable |
| ... first = 0 |
| ... last = 1 |
| ... |
| |
| >>> Person('Ethan') |
| Person('Ethan') |
| |
| >>> Person(last='Furman') |
| Traceback (most recent call last): |
| ... |
| TypeError: values not provided for field(s): first |
| |
| Creating new ``NamedTuples`` from existing ``NamedTuples`` is simple:: |
| |
| >>> Point = NamedTuple('Point', 'x y') |
| >>> Color = NamedTuple('Color', 'r g b') |
| >>> Pixel = NamedTuple('Pixel', Point+Color, module=__name__) |
| >>> Pixel |
| <NamedTuple 'Pixel'> |
| |
| The existing fields in the bases classes are renumbered to fit the new class, |
| but keep their doc strings and default values. If you use standard |
| subclassing:: |
| |
| >>> Point = NamedTuple('Point', 'x y') |
| >>> class Pixel(Point): |
| ... r = 2, 'red component', 11 |
| ... g = 3, 'green component', 29 |
| ... b = 4, 'blue component', 37 |
| ... |
| >>> Pixel.__fields__ |
| ['x', 'y', 'r', 'g', 'b'] |
| |
| You must manage the numbering yourself. |
| |
| |
| Creating NamedConstants |
| ----------------------- |
| |
| A ``NamedConstant`` class is created much like an ``Enum``:: |
| |
| >>> from aenum import NamedConstant |
| >>> class Konstant(NamedConstant): |
| ... PI = 3.14159 |
| ... TAU = 2 * PI |
| |
| >>> Konstant.PI |
| <Konstant.PI: 3.14159> |
| |
| >> print(Konstant.PI) |
| 3.14159 |
| |
| >>> Konstant.PI = 'apple' |
| Traceback (most recent call last): |
| ... |
| AttributeError: Cannot rebind constant <Konstant.PI> |