# `enum` — Soporte para enumeraciones

Nuevo en la versión 3.4.

Código fuente: Lib/enum.py

Una enumeración es un conjunto de nombres simbólicos (miembros) vinculados a valores únicos y constantes. Dentro de una enumeración, los miembros se pueden comparar por identidad, y la enumeración en sí se puede iterar.

Nota

Caso de miembros de Enum

Debido a que las enumeraciones se usan para representar constantes, recomendamos usar nombres UPPER_CASE para los miembros de enumeración, y usaremos ese estilo en nuestros ejemplos.

## Contenido del Módulo

Este módulo define cuatro clases de enumeración que se pueden usar para definir conjuntos únicos de nombres y valores: `Enum`, `IntEnum`, `Flag`, and `IntFlag`. También define un decorador, `unique()`, y un ayudante, `auto`.

class `enum.``Enum`

  Clase base para crear constantes enumeradas. Consulte la sección API Funcional para obtener una sintaxis de construcción alternativa.

class `enum.``IntEnum`

  Clase base para crear constantes enumeradas que también son sub clases de `int`.

class `enum.``IntFlag`

  Clase base para crear constantes enumeradas que se pueden combinar usando los operadores bitwise sin perder su membresía `IntFlag`. Los miembros de `IntFlag` también son subclases de `int`.

class `enum.``Flag`

  Clase base para crear constantes enumeradas que se pueden combinar utilizando las operaciones bitwise sin perder su membresía `Flag`.

`enum.``unique`()

  El decorador de clase Enum que garantiza que solo un nombre esté vinculado a cualquier valor.

class `enum.``auto`

  Las instancias se reemplazan con un valor apropiado para los miembros de Enum. El valor inicial comienza en 1.

Nuevo en la versión 3.6: `Flag`, `IntFlag`, `auto`

## Creando un Enum

Las enumeraciones son creadas usando la sintaxis `class`, lo que las hace de fácil lectura y escritura. Un método de creación alternativo se describe en API Funcional. Para definir una enumeración, hacer una subclase `Enum` de la siguiente manera:

    >>> from enum import Enum
    >>> class Color(Enum):
    ...     RED = 1
    ...     GREEN = 2
    ...     BLUE = 3
    ...

Nota

Valores de miembros de Enum

Los valores de los miembros pueden ser cualquier cosa: `int`, `str`, etc.. Si el valor exacto no es importante, puede usar instancias `auto` y se elegirá un valor apropiado para usted. Se debe tener cuidado si se mezcla `auto` con otros valores.

Nota

Nomenclatura

- La clase `Color` es una enumeración (o enum)

- Los atributos `Color.RED`, `Color.GREEN`, etc., son miembros de enumeración (o miembros de enum) y son funcionalmente constantes.

- Los miembros de la enumeración tienen nombres y valores (el nombre de `Color.RED` es `ROJO`, el valor de `Color.BLUE` es `3`, etc. )

Nota

Aunque usamos la sintaxis `class` para crear Enums, los Enums no son clases normales de Python. Consulte ¿En qué se diferencian las enumeraciones? para obtener más detalles.

Los miembros de la enumeración tienen representaciones de cadenas legibles para humanos

    >>> print(Color.RED)
    Color.RED

…mientras que su `repr` tiene más información

    >>> print(repr(Color.RED))
    <Color.RED: 1>

El tipo de un miembro de enumeración es la enumeración a la que pertenece:

    >>> type(Color.RED)
    <enum 'Color'>
    >>> isinstance(Color.GREEN, Color)
    True
    >>>

Los miembros de Enum también tienen una propiedad que contiene solo su nombre del elemento

    >>> print(Color.RED.name)
    RED

Las enumeraciones soportan iteración, en orden de definición:

    >>> class Shake(Enum):
    ...     VANILLA = 7
    ...     CHOCOLATE = 4
    ...     COOKIES = 9
    ...     MINT = 3
    ...
    >>> for shake in Shake:
    ...     print(shake)
    ...
    Shake.VANILLA
    Shake.CHOCOLATE
    Shake.COOKIES
    Shake.MINT

Los miembros de la enumeración son hasheables, por lo que pueden usarse en diccionarios y conjuntos:

    >>> apples = {}
    >>> apples[Color.RED] = 'red delicious'
    >>> apples[Color.GREEN] = 'granny smith'
    >>> apples == {Color.RED: 'red delicious', Color.GREEN: 'granny smith'}
    True

## Acceso programático a los miembros de la enumeración y sus atributos

A veces es útil acceder a los miembros en enumeraciones mediante programación (es decir, situaciones en las que `Color.RED` no funcionará porque no se conoce el color exacto al momento de escribir el programa). `Enum` permite dicho acceso:

    >>> Color(1)
    <Color.RED: 1>
    >>> Color(3)
    <Color.BLUE: 3>

Si desea acceder a los miembros de enumeración por nombre, use el acceso a elementos:

    >>> Color['RED']
    <Color.RED: 1>
    >>> Color['GREEN']
    <Color.GREEN: 2>

Si tiene un miembro enum y necesita su `name` o `value`:

    >>> member = Color.RED
    >>> member.name
    'RED'
    >>> member.value
    1

## Duplicando miembros y valores enum

Tener dos miembros enum con el mismo nombre no es válido:

    >>> class Shape(Enum):
    ...     SQUARE = 2
    ...     SQUARE = 3
    ...
    Traceback (most recent call last):
    ...
    TypeError: Attempted to reuse key: 'SQUARE'

Sin embargo, se permite que dos miembros enum tengan el mismo valor. Dado que dos miembros A y B tienen el mismo valor (y A se definió primero), B es un alias de A. La búsqueda por valor del valor de A y B retornará A. La búsqueda por nombre de B también retornará A:

    >>> class Shape(Enum):
    ...     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>

Nota

Intentar crear un miembro con el mismo nombre que un atributo ya definido (otro miembro, un método, etc.) o intentar crear un atributo con el mismo nombre que un miembro no está permitido.

## Garantizando valores de enumeración únicos

Por defecto, las enumeraciones permiten múltiples nombres como alias para el mismo valor. Cuando no se desea este comportamiento, se puede usar el siguiente decorador para garantizar que cada valor se use solo una vez en la enumeración:

`@``enum.``unique`

Un decorador de `class` específicamente para enumeraciones. Busca una enumeración `__members__` reuniendo cualquier alias que encuentre; si no se encuentra alguno se genera un `ValueError` con los detalles:

    >>> from enum import Enum, unique
    >>> @unique
    ... class Mistake(Enum):
    ...     ONE = 1
    ...     TWO = 2
    ...     THREE = 3
    ...     FOUR = 3
    ...
    Traceback (most recent call last):
    ...
    ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE

## Usando valores automáticos

Si el valor exacto no es importante, puede usar `auto`:

    >>> from enum import Enum, auto
    >>> class Color(Enum):
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
    ...
    >>> list(Color)
    [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Los valores se eligen por `_generate_next_value_()`, que se puede invalidar:

    >>> class AutoName(Enum):
    ...     def _generate_next_value_(name, start, count, last_values):
    ...         return name
    ...
    >>> class Ordinal(AutoName):
    ...     NORTH = auto()
    ...     SOUTH = auto()
    ...     EAST = auto()
    ...     WEST = auto()
    ...
    >>> list(Ordinal)
    [<Ordinal.NORTH: 'NORTH'>, <Ordinal.SOUTH: 'SOUTH'>, <Ordinal.EAST: 'EAST'>, <Ordinal.WEST: 'WEST'>]

Nota

El objetivo del método predeterminado `_generate_next_value_()` es proporcionar el siguiente `int` en secuencia con el último `int` proporcionado, pero la forma en que lo hace es un detalle de implementación y puede cambiar.

Nota

El método `_generate_next_value_()` debe definirse antes que cualquier miembro.

## Iteración

Iterar sobre los miembros de una enumeración no proporciona los alias:

    >>> list(Shape)
    [<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]

El atributo especial `__members__` es una asignación ordenada de solo lectura de nombres a miembros. Incluye todos los nombres definidos en la enumeración, incluidos los alias:

    >>> for name, member in Shape.__members__.items():
    ...     name, member
    ...
    ('SQUARE', <Shape.SQUARE: 2>)
    ('DIAMOND', <Shape.DIAMOND: 1>)
    ('CIRCLE', <Shape.CIRCLE: 3>)
    ('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)

El atributo `__members__` se puede usar para el acceso programático detallado a los miembros de la enumeración. Por ejemplo, encontrar todos los alias:

    >>> [name for name, member in Shape.__members__.items() if member.name != name]
    ['ALIAS_FOR_SQUARE']

## Comparaciones

Los miembros de la enumeración se comparan por identidad:

    >>> Color.RED is Color.RED
    True
    >>> Color.RED is Color.BLUE
    False
    >>> Color.RED is not Color.BLUE
    True

Las comparaciones ordenadas entre valores de enumeración no son soportadas. Los miembros de Enum no son enteros (pero vea IntEnum a continuación):

    >>> Color.RED < Color.BLUE
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: '<' not supported between instances of 'Color' and 'Color'

Aunque, las comparaciones de igualdad se definen:

    >>> Color.BLUE == Color.RED
    False
    >>> Color.BLUE != Color.RED
    True
    >>> Color.BLUE == Color.BLUE
    True

Las comparaciones con valores de no enumeración siempre se compararán no iguales (de nuevo, `IntEnum` fue diseñado explícitamente para comportarse de manera diferente, ver más abajo):

    >>> Color.BLUE == 2
    False

## Miembros permitidos y atributos de enumeraciones

Los ejemplos anteriores usan números enteros para los valores de enumeración. El uso de enteros es breve y útil (y lo proporciona de forma predeterminada la API Funcional), pero no se aplica estrictamente. En la gran mayoría de los casos de uso, a uno no le importa cuál es el valor real de una enumeración. Pero si el valor es importante, las enumeraciones pueden tener valores arbitrarios.

Las enumeraciones son clases de Python y pueden tener métodos y métodos especiales como de costumbre. Si tenemos esta enumeración

    >>> 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
    ...

Después:

    >>> Mood.favorite_mood()
    <Mood.HAPPY: 3>
    >>> Mood.HAPPY.describe()
    ('HAPPY', 3)
    >>> str(Mood.FUNKY)
    'my custom str! 1'

Las reglas para lo que está permitido son las siguientes: los nombres que comienzan y terminan con un solo guión bajo están reservados por enum y no se pueden usar; todos los demás atributos definidos dentro de una enumeración se convertirán en miembros de esta enumeración, con la excepción de métodos especiales (`__str__()`, `__add__()`, etc.), descriptores (los métodos también son descriptores) y nombres de variables listado en `_ignore_`.

Nota: si tu enumeración define `__new__()` o `__init__()`, los valores que se hayan dado al miembro enum se pasarán a esos métodos. Ver Planet para un ejemplo.

## Subclases restringidas de Enum

Una nueva clase `Enum` debe tener una clase base Enum, hasta un tipo de datos concreto, y tantas clases mixin basadas en `object` como sean necesarias. El orden de estas clases base es:

    class EnumName([mix-in, ...,] [data-type,] base-enum):
        pass

Además, la subclasificación de una enumeración solo está permitida si la enumeración no define ningún miembro. Entonces esto está prohibido:

    >>> class MoreColor(Color):
    ...     PINK = 17
    ...
    Traceback (most recent call last):
    ...
    TypeError: MoreColor: cannot extend enumeration 'Color'

Pero esto es permitido:

    >>> class Foo(Enum):
    ...     def some_behavior(self):
    ...         pass
    ...
    >>> class Bar(Foo):
    ...     HAPPY = 1
    ...     SAD = 2
    ...

Permitir la subclasificación de enumeraciones que definen miembros conduciría a una violación de algunos invariantes importantes de tipos e instancias. Por otro lado, tiene sentido permitir compartir un comportamiento común entre un grupo de enumeraciones. (Ver OrderedEnum para un ejemplo.)

## Serialización

Las enumeraciones se pueden serializar y desempaquetar:

    >>> from test.test_enum import Fruit
    >>> from pickle import dumps, loads
    >>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
    True

Se aplican las restricciones habituales para la serialización (pickling): las enum seleccionables se deben definir en el nivel superior de un módulo, ya que el desempaquetado requiere que sean importables desde ese módulo.

Nota

Con la versión 4 del protocolo de serialización (pickle), es posible seleccionar fácilmente las enumeraciones anidadas en otras clases.

Es posible modificar la forma en que los miembros de Enum se serializan/desempaquetan definiendo `__reduce_ex__()` en la clase de enumeración.

## API Funcional

La clase `Enum` es invocable, proporcionando la siguiente API funcional:

    >>> 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>]

La semántica de esta API se parece a `namedtuple`. El primer argumento de la llamada a `Enum` es el nombre de la enumeración.

El segundo argumento es la fuente de los nombres de los miembros de la enumeración. Puede se una cadena de nombres separados por espacios en blanco, una secuencia de 2 tuplas con pares de clave/valor, o un mapeo de nombres y valores (ej. diccionario). Las últimas dos opciones permiten asignar valores arbitrarios a las enumeraciones; los otros asignan automáticamente enteros crecientes comenzando con 1 (use el parámetros `start` para especificar un valor de inicio diferente). Se regresa una nueva clase derivada de `Enum`. En otras palabras, la asignación de arriba `Animal` es equivalente a:

    >>> class Animal(Enum):
    ...     ANT = 1
    ...     BEE = 2
    ...     CAT = 3
    ...     DOG = 4
    ...

La razón por la que el valor predeterminado es `1` como numero inicial y no `0` es que `0` es `False` en sentido booleano, pero todos los miembros enum evalúan como `True`.

Las enumeraciones serializadas creadas con la API funcional pueden ser complicadas ya que los detalles de implementación de la pila se usan para tratar de averiguar en qué módulo se está creando la enumeración (ej. fallará si usa una función de utilidad en un módulo separado, y también puede no funcionar en IronPython o Jython). La solución es especificar el nombre del módulo explícitamente de la siguiente manera:

    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)

Advertencia

Si no se suministra un `module`, y Enum no puede determinar que es, los miembros del nuevo Enum no se podrán desempaquetar; para mantener los errores más cerca de la fuente, la serialización se deshabilitará.

El nuevo protocolo 4 de serialización también, en ciertas circunstancias, se basa en `__qualname__` se establece en la ubicación donde la serialización podrá encontrar la clase. Por ejemplo, si la clase se hizo disponible en la clase SomeData en el campo global:

    >>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')

La firma completa es:

    Enum(value='NewEnumName', names=<...>, *, module='...', qualname='...', type=<mixed-in class>, start=1)

valor

  Lo que la nueva clase Enum registrará como su nombre.

nombres

  Los miembros de Enum. Esto puede ser un espacio en blanco o una cadena separada por comas (los valores empezarán en 1 a menos que se especifique lo contrario):

      'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'

  o un iterador de nombres:

      ['RED', 'GREEN', 'BLUE']

  o un iterador de pares(nombre,valor):

      [('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]

  o un mapeo:

      {'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}

módulo

  nombre del módulo donde se puede encontrar la nueva clase Enum.

qualname

  donde en el módulo se puede encontrar la nueva clase Enum.

tipo

  escriba para mezclar en la nueva clase Enum.

inicio

  número para comenzar a contar sí solo se pasan nombres.

Distinto en la versión 3.5: Se agregó el parámetro start.

## Enumeraciones derivadas

### IntEnum

La primera variación de `Enum` que se proporciona también es una subclase de `int`. Los miembros de `IntEnum` se pueden comparar con enteros; por extensión, las enumeraciones enteras de diferentes tipos también se pueden comparar entre sí:

    >>> from enum 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

Sin embargo, todavía no se pueden comparar con las enumeraciones estándar `Enum`:

    >>> class Shape(IntEnum):
    ...     CIRCLE = 1
    ...     SQUARE = 2
    ...
    >>> class Color(Enum):
    ...     RED = 1
    ...     GREEN = 2
    ...
    >>> Shape.CIRCLE == Color.RED
    False

los valores `IntEnum` se comportan como enteros en otras maneras que esperarías:

    >>> int(Shape.CIRCLE)
    1
    >>> ['a', 'b', 'c'][Shape.CIRCLE]
    'b'
    >>> [i for i in range(Shape.SQUARE)]
    [0, 1]

### IntFlag

La siguiente variación de `Enum` proporcionada, `IntFlag`, también se basa en `int`. La diferencia es que los miembros `IntFlag` se pueden combinar usando los operadores (&, |, ^, ~) y el resultado es un miembro `IntFlag`. Sin embargo, como su nombre lo indica, los miembros de `IntFlag` también son subclase `int` y pueden usarse siempre que `int` se use. Cualquier operación en un miembro `IntFlag` además de las operaciones de bit perderán la membresía `IntFlag`.

Nuevo en la versión 3.6.

Clase muestra `IntFlag`:

    >>> from enum 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

También es posible nombrar las combinaciones:

    >>> class Perm(IntFlag):
    ...     R = 4
    ...     W = 2
    ...     X = 1
    ...     RWX = 7
    >>> Perm.RWX
    <Perm.RWX: 7>
    >>> ~Perm.RWX
    <Perm.-8: -8>

Otra diferencia importante entre `IntFlag` y `Enum` es que si no hay banderas establecidas (el valor es 0), su evaluación booleana es `False`:

    >>> Perm.R & Perm.X
    <Perm.0: 0>
    >>> bool(Perm.R & Perm.X)
    False

Porque los miembros `IntFlag` también son subclases de `int` se pueden combinar con ellos:

    >>> Perm.X | 8
    <Perm.8|X: 9>

### Bandera

La última variación es `Flag`. Al igual que `IntFlag`, `Flag` los miembros se pueden combinar usando los operadores (&, |, ^, ~). A diferencia de `IntFlag`, no pueden combinar ni comparar con ninguna otra enumeración `Flag`, ni con `int`. Es posible especificar los valores directamente, se recomienda usar `auto` como el valor y dejar que `Flag` seleccione el valor apropiado.

Nuevo en la versión 3.6.

Al igual que `IntFlag`, si una combinación de miembros `Flag` resultan en que no se establezcan banderas, la evaluación booleana es `False`:

    >>> from enum 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

Las banderas individuales deben tener valores que sean potencias de dos (1, 2, 4, 8, …), mientras que las combinaciones de banderas no:

    >>> class Color(Flag):
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
    ...     WHITE = RED | BLUE | GREEN
    ...
    >>> Color.WHITE
    <Color.WHITE: 7>

Dar un nombre a la condición «sin banderas establecidas» no cambia su valor booleano:

    >>> class Color(Flag):
    ...     BLACK = 0
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
    ...
    >>> Color.BLACK
    <Color.BLACK: 0>
    >>> bool(Color.BLACK)
    False

Nota

Para la mayoría del código nuevo, `Enum` y `Flag` son muy recomendables, ya que `IntEnum` y `IntFlag` rompen algunas promesas semánticas de una enumeración (al ser comparables con enteros, y por transitividad a otras enumeraciones no relacionadas). `IntEnum` y `IntFlag` deben usarse solo en casos donde `Enum` y `Flag` no son suficientes: por ejemplo, cuando las constantes enteras se reemplazan por enumeraciones, o por interoperabilidad con otros sistemas.

### Otros

Mientras que `IntEnum` es parte del módulo `enum`, sería muy simple de implementar de forma independiente:

    class IntEnum(int, Enum):
        pass

Esto demuestra que similares pueden ser las enumeraciones derivadas; por ejemplo una `StrEnum` que se mezcla en `str` en lugar de `int`.

Algunas reglas:

1. Al subclasificar `Enum`, los tipos mixtos deben aparecer antes `Enum` en la secuencia de bases, como en el ejemplo anterior `IntEnum`.

2. Mientras que `Enum` puede tener miembros de cualquier tipo, una vez que se mezcle tipos adicionales, todos los miembros deben de tener los valores de ese tipo, por ejemplo, `int` de arriba. Esta restricción no se aplica a las mezclas que solo agregan métodos y no especifican otro tipo.

3. Cuando se mezcla otro tipo de datos, el atributo `value` no es el mismo que el mismo miembro enum, aunque es equivalente y se comparará igual.

4. Formato %-style: %s y %r llaman, respectivamente, a `__str__()` y `__repr__()` de la clase `Enum`; otros códigos (como &i o %h para IntEnum) tratan al miembro enum como su tipo mixto.

5. Cadenas de caracteres literales formateadas, `str.format()`, y `format()` usará el tipo mixto `__format__()` a menos que `__str__()` o `__format__()` se sobreescriba en la subclase, en cuyo caso se utilizarán los métodos anulados o `Enum`. Use los códigos de formato !s y !r para forzar el uso de los métodos `Enum` de las clases `__str__()` y `__repr__()`.

## Cuándo usar `__new__()` contra `__init__()`

`__new__()` debe usarse siempre que desee personalizar el valor del miembro real `Emum`. Cualquier otra modificación puede ir en `__new__()` o `__init__()`, prefiriendo siempre `__init__()`.

Por ejemplo, si desea pasar varios elementos al constructor, pero solo desea que uno de ellos sea el valor:

    >>> class Coordinate(bytes, Enum):
    ...     """
    ...     Coordinate with binary codes that can be indexed by the int code.
    ...     """
    ...     def __new__(cls, value, label, unit):
    ...         obj = bytes.__new__(cls, [value])
    ...         obj._value_ = value
    ...         obj.label = label
    ...         obj.unit = unit
    ...         return obj
    ...     PX = (0, 'P.X', 'km')
    ...     PY = (1, 'P.Y', 'km')
    ...     VX = (2, 'V.X', 'km/s')
    ...     VY = (3, 'V.Y', 'km/s')
    ...

    >>> print(Coordinate['PY'])
    Coordinate.PY

    >>> print(Coordinate(3))
    Coordinate.VY

## Ejemplos interesantes

Si bien se espera que `Enum`, `IntEnum`, `IntFlag`, y `Flag` cubran la mayoría de los casos de uso, no pueden cubrirlos a todos. Aquí hay recetas para algunos tipos diferentes de enumeraciones que puede usarse directamente, o como ejemplos para crear los propios.

### Omitir valores

En muchos casos de uso, a uno no le importa cuál es el valor real de una enumeración. Hay varias formas de definir este tipo de enumeración simple:

- use instancias de `auto` para el valor

- use instancias de `object` como el valor

- use a descriptive string as the value

- use una tupla como valor y un `__new__()` personalizado para reemplazar la tupla con un valor `int`

El uso de cualquiera de estos métodos significa para el usuario que estos valores no son importantes y también permite agregar, eliminar o reordenar miembros sin tener que volver a numerar los miembros restantes.

Cualquiera que sea el método que elijas, debe proporcionar un `repr()` que también oculte el valor (sin importancia):

    >>> class NoValue(Enum):
    ...     def __repr__(self):
    ...         return '<%s.%s>' % (self.__class__.__name__, self.name)
    ...

#### Usando `auto`

Usando `auto` se vería como:

    >>> class Color(NoValue):
    ...     RED = auto()
    ...     BLUE = auto()
    ...     GREEN = auto()
    ...
    >>> Color.GREEN
    <Color.GREEN>

#### Usando `object`

Usando `object` se vería como:

    >>> class Color(NoValue):
    ...     RED = object()
    ...     GREEN = object()
    ...     BLUE = object()
    ...
    >>> Color.GREEN
    <Color.GREEN>

#### Usando una cadena descriptiva

Usar una cadena como valor se vería así:

    >>> class Color(NoValue):
    ...     RED = 'stop'
    ...     GREEN = 'go'
    ...     BLUE = 'too fast!'
    ...
    >>> Color.GREEN
    <Color.GREEN>
    >>> Color.GREEN.value
    'go'

#### Usando `__new__()` personalizados

Usando una numeración automática `__new__()` se vería como:

    >>> class AutoNumber(NoValue):
    ...     def __new__(cls):
    ...         value = len(cls.__members__) + 1
    ...         obj = object.__new__(cls)
    ...         obj._value_ = value
    ...         return obj
    ...
    >>> class Color(AutoNumber):
    ...     RED = ()
    ...     GREEN = ()
    ...     BLUE = ()
    ...
    >>> Color.GREEN
    <Color.GREEN>
    >>> Color.GREEN.value
    2

Para hacer un `AutoNumber` de propósito más general, agregue `*args` a la firma:

    >>> class AutoNumber(NoValue):
    ...     def __new__(cls, *args):      # this is the only change from above
    ...         value = len(cls.__members__) + 1
    ...         obj = object.__new__(cls)
    ...         obj._value_ = value
    ...         return obj
    ...

Luego, cuando hereda de `AutoNumber`, puede escribir su propio `__init__` para manejar cualquier argumento adicional:

    >>> class Swatch(AutoNumber):
    ...     def __init__(self, pantone='unknown'):
    ...         self.pantone = pantone
    ...     AUBURN = '3497'
    ...     SEA_GREEN = '1246'
    ...     BLEACHED_CORAL = () # New color, no Pantone code yet!
    ...
    >>> Swatch.SEA_GREEN
    <Swatch.SEA_GREEN>
    >>> Swatch.SEA_GREEN.pantone
    '1246'
    >>> Swatch.BLEACHED_CORAL.pantone
    'unknown'

Nota

El método `__new__()`, está definido, se usa durante la creación de los miembros Enum; se remplaza entonces por el Enum `__new__()` que se utiliza después de la creación de la clase para buscar miembros existentes.

### OrderedEnum

Una enumeración ordenada que no se basa en `IntEnum` y, por lo tanto mantiene los invariantes normales de `Enum` (como no ser comparables con otras enumeraciones):

    >>> 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):
    ...     A = 5
    ...     B = 4
    ...     C = 3
    ...     D = 2
    ...     F = 1
    ...
    >>> Grade.C < Grade.A
    True

### DuplicateFreeEnum

Levanta un error si se encuentra un nombre de miembro duplicado en lugar de crear un alias:

    >>> class DuplicateFreeEnum(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 DuplicateFreeEnum:  %r --> %r"
    ...                 % (a, e))
    ...
    >>> class Color(DuplicateFreeEnum):
    ...     RED = 1
    ...     GREEN = 2
    ...     BLUE = 3
    ...     GRENE = 2
    ...
    Traceback (most recent call last):
    ...
    ValueError: aliases not allowed in DuplicateFreeEnum:  'GRENE' --> 'GREEN'

Nota

Este es un ejemplo útil para subclasificar Enum para agregar o cambiar otros comportamientos, así como no permitir alias. Si el único cambio deseado es no permitir alias, el decorador `unique()` puede usarse en su lugar.

### Planeta

Si `__new__()` o `__init__()` se definen el valor del miembro enum se pasará a estos métodos:

    >>> 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

### Periodo de tiempo

Un ejemplo para mostrar el atributo `ignore` en uso:

    >>> from datetime import timedelta
    >>> class Period(timedelta, Enum):
    ...     "different lengths of time"
    ...     _ignore_ = 'Period i'
    ...     Period = vars()
    ...     for i in range(367):
    ...         Period['day_%d' % i] = i
    ...
    >>> list(Period)[:2]
    [<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
    >>> list(Period)[-2:]
    [<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]

## ¿Cómo son diferentes las Enums?

Los Enums tienen una metaclase personalizada que afecta muchos aspectos, tanto de las clases derivadas Enum como de sus instancias (miembros).

### Clases Enum

La meta clase `EnumMeta` es responsable de proveer los métodos `__contains__()`, `__dir__()`, `__iter__()` y cualquier otro que permita hacer cosas con una clase `Enum` que falla en una clase típica, como list(Color) o some_enum_var in Color. `EnumMeta` es responsable de asegurar que los otro varios métodos en la clase final `Enum` sean correctos (como `__new__()`, `__getnewargs__()`, `__str__()` y `__repr__()`).

### Miembros de Enum (también conocidos como instancias)

Lo más interesante de los miembros de Enum es que son únicos. `Enum` los crea todos mientras está creando la clase `Enum` misma, y después un `__new__()` personalizado para garantizar que nunca se creen instancias nuevas retornando solo las instancias de miembros existentes.

### Puntos más finos

#### Nombres soportados `__dunder__`

`__members__` es una asignación ordenada de solo lectura de artículos `member_name`:`member`. Solo está disponible en la clase.

`__new__()`, si se especifica, debe crear y retornar los miembros de enumeración; también es una muy buena idea establecer el `_value_` del miembro apropiadamente. Una vez que se crean todos los miembros, ya no se usa.

#### Nombres `_sunder_` compatibles

- `_name_`— nombre del miembro

- `_value_` — valor del miembro; se puede definir / modificar en `__new__`

- `_missing_` — una función de búsqueda utilizada cuando no se encuentra un valor; puede ser anulado

- `_ignore_` – una lista de nombres, ya sea como una `list()` o una `str()` que no será transformada en miembros, y que se eliminará de la clase final

- `_order_` — usado en código Python 2/3 para asegurar que el orden de los miembros sea consistente (atributo de clase, eliminado durante la creación de la clase)

- `_generate_next_value_` — usado por la Funcional API y por `auto` para obtener un valor apropiado para un miembro enum; puede ser anulado

Nuevo en la versión 3.6: `_missing_`, `_order_`, `_generate_next_value_`

Nuevo en la versión 3.7: `_ignore_`

Para ayudar a mantener sincronizado el código Python 2 / Python 3 se puede proporcionar un atributo `_order_`. Se verificará con el orden real de la enumeración y lanzará un error si los dos no coinciden:

    >>> class Color(Enum):
    ...     _order_ = 'RED GREEN BLUE'
    ...     RED = 1
    ...     BLUE = 3
    ...     GREEN = 2
    ...
    Traceback (most recent call last):
    ...
    TypeError: member order does not match _order_

Nota

En código Python 2 el atributo `_order_` es necesario ya que el orden de definición se pierde antes de que se pueda registrar.

#### _Private__names

Private names will be normal attributes in Python 3.11 instead of either an error or a member (depending on if the name ends with an underscore). Using these names in 3.10 will issue a `DeprecationWarning`.

#### Tipo de miembro `Enum`

Los miembros `Enum` son instancias de su clase `Enum`, y normalmente se accede a ellos como `EnumClass.member`. Bajo ciertas circunstancias también se puede acceder como `EnumClass.member.member`, pero nunca se debe hacer esto ya que esa búsqueda puede fallar, o peor aún, retornar algo además del miembro `Enum` que está buscando (esta es otra buena razón para usar solo mayúsculas en los nombres para los miembros):

    >>> class FieldTypes(Enum):
    ...     name = 0
    ...     value = 1
    ...     size = 2
    ...
    >>> FieldTypes.value.size
    <FieldTypes.size: 2>
    >>> FieldTypes.size.value
    2

Nota

This behavior is deprecated and will be removed in 3.11.

Distinto en la versión 3.5.

#### Valor booleano de las clases y miembros `Enum`

Lo miembros `Enum` que están mezclados con tipos sin-`Enum` (como `int`, `str`, etc.) se evalúan de acuerdo con las reglas de tipo mixto; de lo contrario, todos los miembros evalúan como `True`. Para hacer que tu propia evaluación booleana de Enum dependa del valor del miembro, agregue lo siguiente a su clase:

    def __bool__(self):
        return bool(self.value)

las clases `Enum` siempre evalúan como `True`.

#### `Enum` clases con métodos

Si le da a su subclase `Enum` métodos adicionales, como la clase Planet anterior, esos métodos aparecerán en una `dir()` del miembro, pero no de la clase

    >>> dir(Planet)
    ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
    >>> dir(Planet.EARTH)
    ['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', 'surface_gravity', 'value']

#### Combinando miembros de``Flag``

Si no se nombra una combinación de miembros de Flag, el `repr()` incluirá todos los flags con nombre y todas las combinaciones de flags con nombre que estén en el valor

    >>> class Color(Flag):
    ...     RED = auto()
    ...     GREEN = auto()
    ...     BLUE = auto()
    ...     MAGENTA = RED | BLUE
    ...     YELLOW = RED | GREEN
    ...     CYAN = GREEN | BLUE
    ...
    >>> Color(3)  # named combination
    <Color.YELLOW: 3>
    >>> Color(7)      # not named combination
    <Color.CYAN|MAGENTA|BLUE|YELLOW|GREEN|RED: 7>

Nota

In 3.11 unnamed combinations of flags will only produce the canonical flag members (aka single-value flags). So `Color(7)` will produce something like `<Color.BLUE|GREEN|RED: 7>`.