Advanced Enumerations (compatible with Python's stdlib Enum), NamedTuples, and NamedConstants
Project description
aenum --- support for advanced enumerations, namedtuples, and constants
===========================================================================
aenum includes the new Python stdlib enum module available in Python 3.4
backported for previous versions of Python from 2.7 and 3.3+
tested on 2.7, and 3.3+
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.
Module Contents
---------------
``NamedTuple``
^^^^^^^^^^^^^^
Base class for ``creating NamedTuples``_, either by subclassing or via it's
functional API.
``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.
``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.
``constant``
^^^^^^^^^^^^
Descriptor to add constant values to an ``Enum``
``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 into a namespace (usually ``globals()``.
``extend_enum``
^^^^^^^^^^^^^^^
Helper for adding new ``Enum`` members after creation.
``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 can be created using the ``class`` syntax, which makes them
easy to read and write. To define an enumeration, subclass ``Enum`` as
follows::
>>> from aenum import Enum
>>> class Color(Enum):
... red = 1
... green = 2
... blue = 3
The ``Enum`` class is also callable, providing the following functional API::
>>> Animal = Enum('Animal', 'ant bee cat dog')
>>> Animal
<enum 'Animal'>
>>> Animal.ant
<Animal.ant: 1>
>>> Animal.ant.value
1
>>> list(Animal)
[<Animal.ant: 1>, <Animal.bee: 2>, <Animal.cat: 3>, <Animal.dog: 4>]
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__)
Advanced
^^^^^^^^
The simple method of creating ``NamedTuples`` requires always specifying all
possible arguments when creating instances; failure to do so will raise
exceptions.
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)
Creating NamedConstants
------------------
>>> class K(NamedConstant):
... PI = 3.141596
... TAU = 2 * PI
...
>>> K.TAU
6.283192
===========================================================================
aenum includes the new Python stdlib enum module available in Python 3.4
backported for previous versions of Python from 2.7 and 3.3+
tested on 2.7, and 3.3+
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.
Module Contents
---------------
``NamedTuple``
^^^^^^^^^^^^^^
Base class for ``creating NamedTuples``_, either by subclassing or via it's
functional API.
``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.
``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.
``constant``
^^^^^^^^^^^^
Descriptor to add constant values to an ``Enum``
``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 into a namespace (usually ``globals()``.
``extend_enum``
^^^^^^^^^^^^^^^
Helper for adding new ``Enum`` members after creation.
``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 can be created using the ``class`` syntax, which makes them
easy to read and write. To define an enumeration, subclass ``Enum`` as
follows::
>>> from aenum import Enum
>>> class Color(Enum):
... red = 1
... green = 2
... blue = 3
The ``Enum`` class is also callable, providing the following functional API::
>>> Animal = Enum('Animal', 'ant bee cat dog')
>>> Animal
<enum 'Animal'>
>>> Animal.ant
<Animal.ant: 1>
>>> Animal.ant.value
1
>>> list(Animal)
[<Animal.ant: 1>, <Animal.bee: 2>, <Animal.cat: 3>, <Animal.dog: 4>]
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__)
Advanced
^^^^^^^^
The simple method of creating ``NamedTuples`` requires always specifying all
possible arguments when creating instances; failure to do so will raise
exceptions.
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)
Creating NamedConstants
------------------
>>> class K(NamedConstant):
... PI = 3.141596
... TAU = 2 * PI
...
>>> K.TAU
6.283192
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
aenum-1.3.2.zip
(68.6 kB
view hashes)
aenum-1.3.2.tar.gz
(61.9 kB
view hashes)
Built Distribution
aenum-1.3.2-py2.py3-none-any.whl
(64.6 kB
view hashes)
Close
Hashes for aenum-1.3.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c2190a69c8792d623f008bc8ef18ac3cd95d7561d1fe22ad245e9c50af8ccf3d |
|
MD5 | ae24393019fdece114ebaad1b51abdd0 |
|
BLAKE2b-256 | 1917e40816248bd8708aea4d15ddf4f485e1d9ad19f35c3028bcb41f51bb944f |