@Raymond, you raise valid concerns to be sure.  Hoping we can work something out.

@Ethan, what are your thoughts?


It's not just C that has enums where you can define a unique group of names and omit the values for clarity when they are not significant:  

C++: http://en.cppreference.com/w/cpp/language/enum
C#: https://msdn.microsoft.com/en-us/library/sbbt4032.aspx
Java: https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html
Rust: https://doc.rust-lang.org/book/enums.html

In my experience this is the most common and simple use case for enums.

Raymond, what are your thoughts about the version of AutoEnum that requires that a bare tuple be used as the value.  It has been in the Python docs since 3.4 and was actually the original request of this issue: https://docs.python.org/library/enum.html#autonumber

It avoids many of the concerns that you've raised while still providing a way to create Enums in the normal class declaration method users would expect with a minimum amount of boilerplate.  Note that normally you want to use @enum.unique with a normal Enum, but AutoEnum also allows you to omit that boilerplate as you can't accidentally alias the values.

@enum.unique
class Color(enum.Enum):
    aquamarine = 1
    blue = 2
    fushia = 3
    # inserting a member here (perhaps because it's clearest to keep these in alphabetic order)
    # results in having to increment all following members
    ...
    green = 40
    red = 41

vs.

class Color(enum.AutoEnum):
    aquamarine = ()
    blue = ()
    fushia = ()
    # inserting a member here (perhaps because it's clearest to keep these in alphabetic order)
    # results in no refactoring
    ... (30+ more)
    green = ()
    red = ()

A big advantage of the class based Enums compared to the functional API is that you can clearly document an Enum and its members in way Sphinx can take advantage of and developers would be used to.


# Assuming tuple assignment version for this example.
class ClientOperationMode(enum.AutoEnum):
    """Modes of operations of the network client."""

    push = ()
    """The client pushes data to the server automatically."""

    pull = ()
    """The client pulls commands from the server."""

    hybrid = ()
    """The client both pushes data and pulls for commands from the server."""

Sphinx will document this AutoEnum like a normal class, pulling in the class docstring, and attribute docstrings.

I don't see an obvious way to do this in the functional API docs: https://docs.python.org/library/enum.html#functional-api