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
esROJO
, el valor deColor.BLUE
es3
, etc. )
Contenido del Módulo¶
El
type
para Enum y sus subclases.Clase base para crear constantes enumeradas.
Clase base para crear constantes enumeradas que se pueden combinar utilizando las operaciones bitwise sin perder su membresía
Flag
.Una enumeración con los valores
CONTINUOUS
,NAMED_FLAGS
yUNIQUE
, para usar converify()
para garantizar que una enumeración determinada cumpla varias restricciones.Una enumeración con los valores
STRICT
,CONFORM
,EJECT
yKEEP
que permite un control más detallado sobre cómo se tratan los valores no válidos en una enumeración.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í.Permite que los miembros
Enum
tengan atributos sin entrar en conflicto con los nombres de los miembros.El decorador de clase Enum que garantiza que solo un nombre esté vinculado a cualquier valor.
Decorador de clase Enum que verifica las restricciones seleccionables por el usuario en una enumeración.
Convierta a
obj
en miembro. Se puede utilizar como decorador.No convierta a
obj
en miembro. Se puede utilizar como decorador.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 acls
:>>> 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
- _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')
- 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
conIntEnum
da como resultado números enteros de valor creciente, comenzando con1
.Distinto en la versión 3.11:
__str__()
ahora esint.__str__()
para admitir mejor el caso de uso de replacement of existing constants.__format__()
ya eraint.__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 subclasestr
(es decir,type(unknown) == str
en lugar deisinstance(unknown, str)
), y en esos lugares necesitará usarstr(StrEnum.member)
.Nota
__str__()
esstr.__str__()
para admitir mejor el caso de uso de replacement of existing constants.__format__()
también esstr.__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()
yoct()
.
Nota
El uso de
auto
conFlag
da como resultado números enteros que son potencias de dos, comenzando con1
.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
conIntFlag
da como resultado números enteros que son potencias de dos, comenzando con1
.Distinto en la versión 3.11:
__str__()
ahora esint.__str__()
para admitir mejor el caso de uso de replacement of existing constants.__format__()
ya eraint.__format__()
por la misma razón.
- class enum.ReprEnum¶
ReprEum
usa elrepr()
deEnum
, pero elstr()
del tipo de datos mixto:Heredar de
ReprEnum
para mantenerstr() <str> / :func:`format
del tipo de datos mixto en lugar de utilizar elEnum
por defectostr()
.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 unValueError
.- 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 paraFlag
:>>> 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 paraIntFlag
:>>> 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 unalist()
o unastr()
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
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
yname
.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 generaValueError
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 deEnumCheck
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()
yrepr()
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 (consultere.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¶
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 nombreSi no necesita/quiere esas limitaciones, puede crear su propia clase base mezclando el tipo
int
ostr
usted mismo:>>> from enum import Enum >>> class MyIntEnum(int, Enum): ... passo puede reasignar el
str()
apropiado, etc., en su enumeración:>>> from enum import IntEnum >>> class MyIntEnum(IntEnum): ... __str__ = IntEnum.__str__