Nota

¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.

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

  • se puede iterar para retornar sus miembros en orden de definición

  • usa la sintaxis call para retornar miembros por valor

  • usa la sintaxis index para retornar miembros por nombre

Las enumeraciones se crean mediante la sintaxis class o mediante la sintaxis de llamadas a funciones:

>>> from enum import Enum

>>> # class syntax
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3

>>> # functional syntax
>>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE'])

Aunque podemos usar la sintaxis class para crear enumeraciones, las enumeraciones no son clases normales de Python. Ver ¿En qué se diferencian las enumeraciones? para más detalles.

Nota

Nomenclatura

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

  • Los atributos Color.RED, Color.GREEN, etc., son enumeraciones miembros (o miembros) 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. )


Contenido del Módulo

EnumType

El type para Enum y sus subclases.

Enum

Clase base para crear constantes enumeradas.

IntEnum

Clase base para crear constantes enumeradas que también son subclases de int. (Notes)

StrEnum

Clase base para crear constantes enumeradas que también son subclases de str. (Notes)

Flag

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

IntFlag

Clase base para crear constantes enumeradas que se pueden combinar mediante los operadores bit a bit sin perder su pertenencia a IntFlag. Los miembros IntFlag también son subclases de int. (Notes)

ReprEnum

Usado por IntEnum, StrEnum y IntFlag para mantener el str() del tipo mixto.

EnumCheck

Una enumeración con los valores CONTINUOUS, NAMED_FLAGS y UNIQUE, para usar con verify() para garantizar que una enumeración determinada cumpla varias restricciones.

FlagBoundary

Una enumeración con los valores STRICT, CONFORM, EJECT y KEEP que permite un control más detallado sobre cómo se tratan los valores no válidos en una enumeración.

auto

Las instancias se reemplazan con un valor apropiado para los miembros de Enum. StrEnum usa de manera predeterminada la versión en minúsculas del nombre del miembro, mientras que otras enumeraciones tienen el valor predeterminado de 1 y aumentan a partir de ahí.

property()

Permite que los miembros Enum tengan atributos sin entrar en conflicto con los nombres de los miembros.

unique()

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

verify()

Decorador de clase Enum que verifica las restricciones seleccionables por el usuario en una enumeración.

member()

Convierta a obj en miembro. Se puede utilizar como decorador.

nonmember()

No convierta a obj en miembro. Se puede utilizar como decorador.

global_enum()

Modifique str() y repr() de una enumeración para mostrar sus miembros como pertenecientes al módulo en lugar de a su clase. Solo debe usarse si los miembros de la enumeración se exportarán al espacio de nombres global del módulo.

show_flag_values()

Retorna una lista de todos los enteros de potencia de dos contenidos en una bandera.

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

Nuevo en la versión 3.11: StrEnum, EnumCheck, ReprEnum, FlagBoundary, property, member, nonmember, global_enum, show_flag_values


Tipos de datos

class enum.EnumType

EnumType es el metaclass para enumeraciones enum. Es posible subclasificar EnumType; consulte Subclassing EnumType para obtener más detalles.

EnumType es responsable de configurar los métodos __repr__(), __str__(), __format__() y __reduce__() correctos en el enum final, así como de crear los miembros de enumeración, manejar correctamente los duplicados, proporcionar iteración sobre la clase de enumeración, etc.

__contains__(cls, member)

Retorna True si el miembro pertenece a cls:

>>> some_var = Color.RED
>>> some_var in Color
True

Nota

En Python 3.12, será posible verificar los valores de los miembros y no solo los miembros; hasta entonces, se generará un TypeError si se usa un miembro que no sea Enum en una verificación de contención.

__dir__(cls)

Retorna ['__class__', '__doc__', '__members__', '__module__'] y los nombres de los miembros en cls:

>>> dir(Color)
['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']
__getattr__(cls, name)

Retorna el miembro Enum en cls que coincide con name, o genera un AttributeError:

>>> Color.GREEN
<Color.GREEN: 2>
__getitem__(cls, name)

Retorna el miembro Enum en cls que coincide con name, o genera un KeyError:

>>> Color['BLUE']
<Color.BLUE: 3>
__iter__(cls)

Retorna cada miembro en cls en orden de definición:

>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]
__len__(cls)

Retorna el número de miembro en cls:

>>> len(Color)
3
__reversed__(cls)

Retorna cada miembro en cls en orden de definición inverso:

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

Enum es la clase base para todas las enumeraciones enum.

name

El nombre utilizado para definir el miembro Enum:

>>> Color.BLUE.name
'BLUE'
value

El valor dado al miembro Enum:

>>> Color.RED.value
1

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.

_ignore_

_ignore_ solo se usa durante la creación y se elimina de la enumeración una vez que se completa la creación.

_ignore_ es una lista de nombres que no se convertirán en miembros y cuyos nombres también se eliminarán de la enumeración completa. Consulte TimePeriod para ver un ejemplo.

__call__(cls, value, names=None, \*, module=None, qualname=None, type=None, start=1, boundary=None)

Este método se llama de dos maneras diferentes:

  • para buscar un miembro existente:

    cls

    La clase de enumeración que se llama.

    value

    El valor a buscar.

  • para usar la enumeración cls para crear una nueva enumeración:

    cls

    La clase de enumeración que se llama.

    value

    El nombre del nuevo Enum para crear.

    names

    Los nombres/valores de los miembros para el nuevo Enum.

    module

    El nombre del módulo en el que se crea el nuevo Enum.

    qualname

    La ubicación real en el módulo donde se puede encontrar este Enum.

    type

    Un tipo de mezcla para el nuevo Enum.

    start

    El primer valor entero para Enum (usado por auto)

    boundary

    Cómo manejar valores fuera de rango de operaciones de bits (solo Flag)

__dir__(self)

Retorna ['__class__', '__doc__', '__module__', 'name', 'value'] y cualquier método público definido en self.__class__:

>>> from datetime import date
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     @classmethod
...     def today(cls):
...         print('today is %s' % cls(date.today().isoweekday()).name)
>>> dir(Weekday.SATURDAY)
['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']
_generate_next_value_(name, start, count, last_values)
name

El nombre del miembro que se está definiendo (por ejemplo, “RED”).

start

El valor inicial de Enum; el valor predeterminado es 1.

count

El número de miembros actualmente definidos, sin incluir este.

last_values

Una lista de los valores anteriores.

Un staticmethod que se usa para determinar el siguiente valor retornado por auto:

>>> from enum import auto
>>> class PowersOfThree(Enum):
...     @staticmethod
...     def _generate_next_value_(name, start, count, last_values):
...         return (count + 1) * 3
...     FIRST = auto()
...     SECOND = auto()
>>> PowersOfThree.SECOND.value
6
__init_subclass__(cls, \**kwds)

Un classmethod que se usa para configurar más subclases subsiguientes. Por defecto, no hace nada.

_missing_(cls, value)

Un classmethod para buscar valores que no se encuentran en cls. De forma predeterminada, no hace nada, pero se puede anular para implementar un comportamiento de búsqueda personalizado:

>>> from enum import StrEnum
>>> class Build(StrEnum):
...     DEBUG = auto()
...     OPTIMIZED = auto()
...     @classmethod
...     def _missing_(cls, value):
...         value = value.lower()
...         for member in cls:
...             if member.value == value:
...                 return member
...         return None
>>> Build.DEBUG.value
'debug'
>>> Build('deBUG')
<Build.DEBUG: 'debug'>
__repr__(self)

Retorna la cadena utilizada para las llamadas repr(). De forma predeterminada, retorna el nombre Enum, el nombre del miembro y el valor, pero se puede anular:

>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __repr__(self):
...         cls_name = self.__class__.__name__
...         return f'{cls_name}.{self.name}'
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')
__str__(self)

Retorna la cadena utilizada para las llamadas str(). De forma predeterminada, retorna el nombre Enum y el nombre del miembro, pero se puede anular:

>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __str__(self):
...         return f'{self.name}'
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')
__format__(self)

Retorna la cadena utilizada para las llamadas format() y f-string. De forma predeterminada, retorna __str__(), pero se puede anular:

>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __format__(self, spec):
...         return f'{self.name}'
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}"
(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')

Nota

El uso de auto con Enum da como resultado números enteros de valor creciente, comenzando con 1.

class enum.IntEnum

IntEnum es lo mismo que Enum, pero sus miembros también son números enteros y se pueden usar en cualquier lugar donde se pueda usar un número entero. Si se realiza alguna operación con enteros con un miembro IntEnum, el valor resultante pierde su estado de enumeración.

>>> from enum import IntEnum
>>> class Numbers(IntEnum):
...     ONE = 1
...     TWO = 2
...     THREE = 3
>>> Numbers.THREE
<Numbers.THREE: 3>
>>> Numbers.ONE + Numbers.TWO
3
>>> Numbers.THREE + 5
8
>>> Numbers.THREE == 3
True

Nota

El uso de auto con IntEnum da como resultado números enteros de valor creciente, comenzando con 1.

Distinto en la versión 3.11: __str__() ahora es int.__str__() para admitir mejor el caso de uso de replacement of existing constants. __format__() ya era int.__format__() por la misma razón.

class enum.StrEnum

StrEnum es lo mismo que Enum, pero sus miembros también son cadenas y se pueden usar en la mayoría de los mismos lugares en los que se puede usar una cadena. El resultado de cualquier operación de cadena realizada en o con un miembro StrEnum no forma parte de la enumeración.

Nota

Hay lugares en stdlib que buscan un str exacto en lugar de una subclase str (es decir, type(unknown) == str en lugar de isinstance(unknown, str)), y en esos lugares necesitará usar str(StrEnum.member).

Nota

El uso de auto con StrEnum da como resultado el nombre de miembro en minúsculas como valor.

Nota

__str__() es str.__str__() para admitir mejor el caso de uso de replacement of existing constants. __format__() también es str.__format__() por la misma razón.

Nuevo en la versión 3.11.

class enum.Flag

Los miembros Flag admiten los operadores bit a bit & (AND), | (OR), ^ (XOR) y ~ (INVERT); los resultados de esos operadores son miembros de la enumeración.

__contains__(self, value)

Retorna True si el valor está en sí mismo:

>>> from enum import Flag, auto
>>> class Color(Flag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
>>> purple = Color.RED | Color.BLUE
>>> white = Color.RED | Color.GREEN | Color.BLUE
>>> Color.GREEN in purple
False
>>> Color.GREEN in white
True
>>> purple in white
True
>>> white in purple
False
__iter__(self):

Retorna todos los miembros contenidos:

>>> list(Color.RED)
[<Color.RED: 1>]
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 4>]
__len__(self):

Retorna el número de miembros en la bandera:

>>> len(Color.GREEN)
1
>>> len(white)
3
__bool__(self):

Retorna True si hay algún miembro en la bandera, False de lo contrario:

>>> bool(Color.GREEN)
True
>>> bool(white)
True
>>> black = Color(0)
>>> bool(black)
False
__or__(self, other)

Retorna la bandera actual binaria o con otra:

>>> Color.RED | Color.GREEN
<Color.RED|GREEN: 3>
__and__(self, other)

Retorna el binario de la bandera actual y se combina con otro:

>>> purple & white
<Color.RED|BLUE: 5>
>>> purple & Color.GREEN
<Color: 0>
__xor__(self, other)

Retorna la bandera actual binaria xor’ed con otra:

>>> purple ^ white
<Color.GREEN: 2>
>>> purple ^ Color.GREEN
<Color.RED|GREEN|BLUE: 7>
__invert__(self):

Retorna todas las banderas en type(self) que no están en uno mismo:

>>> ~white
<Color: 0>
>>> ~purple
<Color.GREEN: 2>
>>> ~Color.RED
<Color.GREEN|BLUE: 6>
_numeric_repr_()

Función utilizada para dar formato a los valores numéricos restantes sin nombre. El valor predeterminado es la repr del valor; las opciones comunes son hex() y oct().

Nota

El uso de auto con Flag da como resultado números enteros que son potencias de dos, comenzando con 1.

Distinto en la versión 3.11: El repr() de las banderas de valor cero ha cambiado. Esto es ahora:

>>> Color(0) 
<Color: 0>
class enum.IntFlag

IntFlag es lo mismo que Flag, pero sus miembros también son números enteros y se pueden usar en cualquier lugar donde se pueda usar un número entero.

>>> from enum import IntFlag, auto
>>> class Color(IntFlag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
>>> Color.RED & 2
<Color: 0>
>>> Color.RED | 2
<Color.RED|GREEN: 3>

Si se realiza alguna operación con enteros con un miembro IntFlag, el resultado no es un IntFlag:

>>> Color.RED + 2
3

Si se realiza una operación Flag con un miembro IntFlag y:

  • el resultado es un IntFlag válido: se retorna un IntFlag

  • el resultado no es un IntFlag válido: el resultado depende de la configuración de FlagBoundary

El repr() de indicadores de valor cero sin nombre ha cambiado. Esto es ahora:

>>> Color(0)
<Color: 0>

Nota

El uso de auto con IntFlag da como resultado números enteros que son potencias de dos, comenzando con 1.

Distinto en la versión 3.11: __str__() ahora es int.__str__() para admitir mejor el caso de uso de replacement of existing constants. __format__() ya era int.__format__() por la misma razón.

class enum.ReprEnum

ReprEum usa el repr() de Enum, pero el str() del tipo de datos mixto:

Heredar de ReprEnum para mantener str() <str> / :func:`format del tipo de datos mixto en lugar de utilizar el Enum por defecto str().

Nuevo en la versión 3.11.

class enum.EnumCheck

EnumCheck contiene las opciones utilizadas por el decorador verify() para garantizar diversas restricciones; las restricciones fallidas dan como resultado un ValueError.

UNIQUE

Asegúrese de que cada valor tenga un solo nombre:

>>> from enum import Enum, verify, UNIQUE
>>> @verify(UNIQUE)
... class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
...     CRIMSON = 1
Traceback (most recent call last):
...
ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED
CONTINUOUS

Asegúrese de que no falten valores entre el miembro de menor valor y el miembro de mayor valor:

>>> from enum import Enum, verify, CONTINUOUS
>>> @verify(CONTINUOUS)
... class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 5
Traceback (most recent call last):
...
ValueError: invalid enum 'Color': missing values 3, 4
NAMED_FLAGS

Asegúrese de que los grupos/máscaras de banderas contengan solo banderas con nombre, lo cual es útil cuando se especifican valores en lugar de generarlos auto().

>>> from enum import Flag, verify, NAMED_FLAGS
>>> @verify(NAMED_FLAGS)
... class Color(Flag):
...     RED = 1
...     GREEN = 2
...     BLUE = 4
...     WHITE = 15
...     NEON = 31
Traceback (most recent call last):
...
ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]

Nota

CONTINUOUS y NAMED_FLAGS están diseñados para funcionar con miembros con valores enteros.

Nuevo en la versión 3.11.

class enum.FlagBoundary

FlagBoundary controla cómo se manejan los valores fuera de rango en Flag y sus subclases.

STRICT

Los valores fuera de rango hacen que se genere un ValueError. Este es el valor predeterminado para Flag:

>>> from enum import Flag, STRICT
>>> class StrictFlag(Flag, boundary=STRICT):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
>>> StrictFlag(2**2 + 2**4)
Traceback (most recent call last):
...
ValueError: <flag 'StrictFlag'> invalid value 20
    given 0b0 10100
  allowed 0b0 00111
CONFORM

Los valores fuera de rango tienen valores no válidos eliminados, dejando un valor Flag válido:

>>> from enum import Flag, CONFORM
>>> class ConformFlag(Flag, boundary=CONFORM):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
>>> ConformFlag(2**2 + 2**4)
<ConformFlag.BLUE: 4>
EJECT

Los valores fuera de rango pierden su pertenencia a Flag y vuelven a int. Este es el valor predeterminado para IntFlag:

>>> from enum import Flag, EJECT
>>> class EjectFlag(Flag, boundary=EJECT):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
>>> EjectFlag(2**2 + 2**4)
20
KEEP

Se mantienen los valores fuera de rango y se mantiene la pertenencia a Flag. Esto se usa para algunas banderas stdlib:

>>> from enum import Flag, KEEP
>>> class KeepFlag(Flag, boundary=KEEP):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
>>> KeepFlag(2**2 + 2**4)
<KeepFlag.BLUE|16: 20>

Nuevo en la versión 3.11.


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_: se usa para obtener un valor apropiado para un miembro de enumeración; puede ser anulado

    Nota

    Para las clases Enum estándar, el siguiente valor elegido es el último valor visto incrementado en uno.

    Para las clases Flag, el siguiente valor elegido será la siguiente potencia de dos más alta, independientemente del último valor visto.

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

Nuevo en la versión 3.7: _ignore_


Utilidades y decoradores

class enum.auto

auto se puede utilizar en lugar de un valor. Si se usa, la maquinaria Enum llamará a _generate_next_value_() de Enum para obtener un valor apropiado. Para Enum y IntEnum, ese valor apropiado será el último valor más uno; para Flag y IntFlag será la primera potencia de dos mayor que el último valor; para StrEnum será la versión en minúsculas del nombre del miembro.

_generate_next_value_ se puede anular para personalizar los valores utilizados por auto.

Nota

en 3.13, el "generate_next_value_ predeterminado siempre retornará el valor de miembro más alto incrementado en 1 y fallará si algún miembro es de un tipo incompatible.

@enum.property

Un decorador similar al property integrado, pero específico para enumeraciones. Permite que los atributos de los miembros tengan los mismos nombres que los propios miembros.

Nota

el property y el miembro deben definirse en clases separadas; por ejemplo, los atributos value y name se definen en la clase Enum y las subclases Enum pueden definir miembros con los nombres value y name.

Nuevo en la versión 3.11.

@enum.unique

Un decorador class específicamente para enumeraciones. Busca el __members__ de una enumeración, recopilando cualquier alias que encuentre; si se encuentra alguno, se genera 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
@enum.verify

Un decorador class específicamente para enumeraciones. Los miembros de EnumCheck se utilizan para especificar qué restricciones deben verificarse en la enumeración decorada.

Nuevo en la versión 3.11.

@enum.member

Un decorador para usar en enumeraciones: su objetivo se convertirá en miembro.

Nuevo en la versión 3.11.

@enum.nonmember

Un decorador para usar en enumeraciones: su destino no se convertirá en miembro.

Nuevo en la versión 3.11.

@enum.global_enum

Un decorador para cambiar el str() y repr() de una enumeración para mostrar sus miembros como pertenecientes al módulo en lugar de a su clase. Solo debe usarse cuando los miembros de la enumeración se exportan al espacio de nombres global del módulo (consulte re.RegexFlag para ver un ejemplo).

Nuevo en la versión 3.11.

enum.show_flag_values(value)

Retorna una lista de todos los enteros de potencia de dos contenidos en un indicador value.

Nuevo en la versión 3.11.


Notas

IntEnum, StrEnum y IntFlag

Estos tres tipos de enumeración están diseñados para ser reemplazos directos de los valores existentes basados ​​en cadenas y enteros; como tales, tienen limitaciones adicionales:

  • __str__ usa el valor y no el nombre del miembro de enumeración

  • __format__, debido a que usa __str__, también usará el valor del miembro de enumeración en lugar de su nombre

Si no necesita/quiere esas limitaciones, puede crear su propia clase base mezclando el tipo int o str usted mismo:

>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     pass

o puede reasignar el str() apropiado, etc., en su enumeración:

>>> from enum import IntEnum
>>> class MyIntEnum(IntEnum):
...     __str__ = IntEnum.__str__