Path: csiph.com!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: Ethan Furman <ethan@stoneleaf.us>
Newsgroups: comp.lang.python.announce
Subject: [ANN] aenum 1.3.0 released
Date: Sun, 13 Mar 2016 00:20:41 -0800
Lines: 183
Approved: python-announce-list@python.org
Message-ID: <mailman.57.1457870308.12893.python-announce-list@python.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
User-Agent: Mozilla/5.0 (X11; Linux i686; rv:31.0) Gecko/20100101 Thunderbird/31.2.0
Precedence: list
Xref: csiph.com comp.lang.python.announce:2067

I am thrilled to announce the release of

   aenum 1.3.0


aenum --- advanced enumerations, named tuples, and named 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 ``Constant`` is a class of named values 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 ``Constant`` 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.

``Constant``
~~~~~~~~~~
    Constant class for creating groups of constants.  These names cannot
    be rebound to other values.

``Enum``
~~~~~~
    Base class for creating enumerated constants.

``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 ``Constant`` 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 ``Constant``.


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 Constants
------------------

``Constant`` is similar to ``Enum``, but do not support the ``Enum``
protocols, and have no restrictions on duplications::

     >>> class K(Constant):
     ...     PI = 3.141596
     ...     TAU = 2 * PI
     ...
     >>> K.TAU
     6.283192

-------------------------------------------------------------------

Some of the inspirations:

An Enum of Enums:  http://stackoverflow.com/q/30471864/208880

C-like Enums:      http://stackoverflow.com/q/29264941/208880

Extending Enums:   http://stackoverflow.com/q/28126314/208880

Named constants:   http://stackoverflow.com/q/31537316/208880