enum — Stöd för uppräkningar

Tillagd i version 3.4.

Källkod: Lib/enum.py

En uppräkning:

  • är en uppsättning symboliska namn (medlemmar) som är bundna till unika värden

  • kan itereras över för att returnera dess kanoniska (dvs. icke-alias) medlemmar i definitionsordning

  • använder call-syntax för att returnera medlemmar med värde

  • använder index-syntax för att returnera medlemmar efter namn

Uppräkningar skapas antingen med hjälp av syntaxen class eller med hjälp av syntaxen för funktionsanrop:

>>> from enum import Enum

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

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

Även om vi kan använda class syntax för att skapa Enums, är Enums inte vanliga Python-klasser. Se Hur är Enums annorlunda? för mer information.

Anteckning

Nomenklatur

  • Klassen Color är en enumeration (eller enum)

  • Attributen Color.RED, Color.GREEN, etc., är enumerationsmedlemmar (eller medlemmar) och är funktionellt konstanter.

  • Enum-medlemmarna har namn och värden (namnet på Color.RED är RED, värdet på Color.BLUE är 3, etc.)

Modulens innehåll

EnumType

typ för Enum och dess underklasser.

Enum

Basklass för att skapa uppräknade konstanter.

IntEnum

Basklass för att skapa uppräknade konstanter som också är underklasser till int. (Noter)

StrEnum

Basklass för att skapa uppräknade konstanter som också är underklasser till str. (Noter)

Flagga

Basklass för att skapa uppräknade konstanter som kan kombineras med bitvisa operationer utan att förlora sitt medlemskap i Flag.

IntFlag

Basklass för att skapa uppräknade konstanter som kan kombineras med bitvisa operatorer utan att förlora sitt medlemskap i IntFlag. Medlemmar i IntFlag är också underklasser till int. (Noter)

ReprEnum

Används av IntEnum, StrEnum och IntFlag för att hålla str() av typen mixed-in.

EnumCheck

En uppräkning med värdena CONTINUOUS, NAMED_FLAGS och UNIQUE, för användning med verify() för att säkerställa att olika begränsningar uppfylls av en given uppräkning.

FlaggBegränsning

En uppräkning med värdena STRICT, CONFORM, EJECT och KEEP som ger möjlighet till mer finkornig kontroll över hur ogiltiga värden hanteras i en uppräkning.

EnumDict

En underklass av dict för användning vid underklassning av EnumType.

auto

Instanser ersätts med ett lämpligt värde för Enum-medlemmar. StrEnum har som standard den gemena versionen av medlemsnamnet, medan andra Enum har som standard 1 och ökar därifrån.

property()

Tillåter Enum-medlemmar att ha attribut utan att det står i konflikt med medlemsnamnen. Attributen value och name är implementerade på detta sätt.

unique()

Enum-klassdekorator som säkerställer att endast ett namn är bundet till ett värde.

verifiera()

Enum-klassdekorator som kontrollerar användarvalbara begränsningar för en uppräkning.

medlem()

Gör obj till en medlem. Kan användas som dekorator.

icke-medlem()

Gör inte obj till en medlem. Kan användas som dekorator.

global_enum()

Modifiera str() och repr() för en enum så att dess medlemmar visas som tillhörande modulen istället för klassen, och exportera enum-medlemmarna till det globala namnrymden.

visa_flagg_värden()

Returnerar en lista över alla tvåpotenstal som ingår i en flagga.

Tillagd i version 3.6: Flag, IntFlag, auto

Tillagd i version 3.11: StrEnum, EnumCheck, ReprEnum, FlagBoundary, property, member, nonmember, global_enum, show_flag_values

Tillagd i version 3.13: EnumDict

Datatyper

class enum.EnumType

EnumType är metaklass för enum uppräkningar. Det är möjligt att subklassa EnumType – se Subclassing EnumType för detaljer.

EnumType är ansvarig för att ställa in rätt __repr__(), __str__(), __format__(), och __reduce__() metoder på den slutliga enum, samt skapa enum medlemmar, korrekt hantering av dubbletter, tillhandahålla iteration över enum klassen, etc.

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

Denna metod kan användas på två olika sätt:

  • för att söka upp en befintlig medlem:

    cls:

    Den enumklass som anropas.

    värde:

    Det värde som ska sökas upp.

  • för att använda cls enum för att skapa en ny enum (endast om den befintliga enum inte har några medlemmar):

    cls:

    Den enumklass som anropas.

    värde:

    Namnet på den nya Enum som ska skapas.

    namn:

    Namnen/värdena på medlemmarna för det nya Enum.

    modul:

    Namnet på den modul som det nya Enum skapas i.

    kvalitetsnamn:

    Den faktiska platsen i modulen där denna Enum finns.

    typ:

    En mix-in-typ för det nya Enum.

    börja:

    Det första heltalsvärdet för Enum (används av auto).

    avgränsning:

    Hur man hanterar värden utanför intervallet från bitoperationer (Flag only).

__contains__(cls, member)

Returnerar True om medlemmen tillhör cls:

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

Ändrad i version 3.12: Före Python 3.12 uppstår ett TypeError om en icke-Enum-medlem används i en kontroll av inneslutning.

__dir__(cls)

Returnerar ['__class__', '__doc__', '__members__', '__module__'] och namnen på medlemmarna i cls:

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

Returnerar Enum-medlemmen i cls som matchar namn, eller ger upphov till ett KeyError:

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

Returnerar varje medlem i cls i definitionsordning:

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

Returnerar antalet medlemmar i cls:

>>> len(Color)
3
__members__

Returnerar en mappning av varje enumnamn till dess medlem, inklusive alias

__reversed__(cls)

Returnerar varje medlem i cls i omvänd definitionsordning:

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

Lägger till ett nytt namn som alias till en befintlig medlem. Utlöser ett NameError om namnet redan är tilldelat en annan medlem.

_add_value_alias_()

Lägger till ett nytt värde som ett alias till en befintlig medlem. Utlöser ett ValueError om värdet redan är länkat till en annan medlem.

Tillagd i version 3.11: Före 3.11 hette EnumType EnumMeta, vilket fortfarande finns som alias.

class enum.Enum

Enum är basklassen för alla enum-uppräkningar.

name

Det namn som används för att definiera medlemmen Enum:

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

Det värde som ges till Enum-medlemmen:

>>> Color.RED.value
1

Värde för medlemmen, kan ställas in i __new__().

Anteckning

Enum-medlemsvärden

Medlemsvärden kan vara vad som helst: int, str, etc. Om det exakta värdet är oviktigt kan du använda auto-instanser och ett lämpligt värde kommer att väljas åt dig. Se auto för mer information.

Även om muterbara/ohashbara värden, som dict, list eller en muterbar dataclass, kan användas, kommer de att ha en kvadratisk prestandapåverkan under skapandet i förhållande till det totala antalet muterbara/ohashbara värden i enum.

_name_

Ledamotens namn.

_value_

Värde för medlemmen, kan ställas in i __new__().

_order_

Används inte längre, men behålls för bakåtkompatibilitet. (klassattribut, tas bort när klassen skapas).

_ignore_

_ignore_ används endast under skapandet och tas bort från uppräkningen när skapandet är klart.

_ignore_ är en lista med namn som inte kommer att bli medlemmar, och vars namn också kommer att tas bort från den färdiga uppräkningen. Se TimePeriod för ett exempel.

__dir__(self)

Returnerar ['__class__', '__doc__', '__module__', 'name', 'value'] och alla offentliga metoder som definieras på 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)
namn:

Namnet på den medlem som ska definieras (t.ex. ”RED”).

börja:

Startvärdet för Enum; standardvärdet är 1.

antal:

Antalet medlemmar som för närvarande är definierade, exklusive denna.

senaste_värden:

En lista över tidigare värden.

En statisk metod som används för att bestämma nästa värde som returneras av auto:

>>> from enum import auto
>>> class PowersOfThree(Enum):
...     @staticmethod
...     def _generate_next_value_(name, start, count, last_values):
...         return 3 ** (count + 1)
...     FIRST = auto()
...     SECOND = auto()
...
>>> PowersOfThree.SECOND.value
9
__init__(self, *args, **kwds)

Som standard gör den ingenting. Om flera värden anges i medlemstilldelningen, blir dessa värden separata argument till __init__; t.ex.

>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1, 'Mon'

Weekday.__init__() skulle kallas som Weekday.__init__(self, 1, 'Mon')

__init_subclass__(cls, **kwds)

En klassmetod som används för att ytterligare konfigurera efterföljande underklasser. Som standard gör den ingenting.

_missing_(cls, value)

En klassmetod för att leta upp värden som inte finns i cls. Som standard gör den ingenting, men kan åsidosättas för att implementera anpassat sökbeteende:

>>> 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'>
__new__(cls, *args, **kwds)

Existerar inte som standard. Om det anges, antingen i enum-klassdefinitionen eller i en mixin-klass (t.ex. int), kommer alla värden som anges i medlemstilldelningen att skickas; t.ex.

>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     TWENTYSIX = '1a', 16

resulterar i anropet int('1a', 16) och ett värde på 26 för medlemmen.

Anteckning

När du skriver en egen __new__ ska du inte använda super().__new__ - anropa istället lämplig __new__.

__repr__(self)

Returnerar den sträng som används för repr()-anrop. Som standard returneras Enum-namnet, medlemsnamnet och värdet, men kan åsidosättas:

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

Returnerar den sträng som används för str()-anrop. Som standard returneras Enum-namnet och medlemsnamnet, men kan åsidosättas:

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

Returnerar strängen som används för format() och f-string-anrop. Returnerar som standard __str__() returvärde, men kan åsidosättas:

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

Anteckning

Att använda auto med Enum resulterar i heltal med ökande värde, med början på 1.

Ändrad i version 3.12: Lagt till Stöd för dataklasser

class enum.IntEnum

IntEnum är samma sak som Enum, men dess medlemmar är också heltal och kan användas var som helst där ett heltal kan användas. Om någon heltalsoperation utförs med en IntEnum-medlem förlorar det resulterande värdet sin uppräkningsstatus.

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

Anteckning

Att använda auto med IntEnum resulterar i heltal med ökande värde, med början på 1.

Ändrad i version 3.11: __str__() är nu int.__str__() för att bättre stödja användningsfallet ersättning av befintliga konstanter. __format__() var redan int.__format__() av samma anledning.

class enum.StrEnum

StrEnum är samma sak som Enum, men dess medlemmar är också strängar och kan användas på de flesta av de ställen där en sträng kan användas. Resultatet av en strängoperation som utförs på eller med en StrEnum-medlem är inte en del av uppräkningen.

>>> from enum import StrEnum, auto
>>> class Color(StrEnum):
...     RED = 'r'
...     GREEN = 'g'
...     BLUE = 'b'
...     UNKNOWN = auto()
...
>>> Color.RED
<Color.RED: 'r'>
>>> Color.UNKNOWN
<Color.UNKNOWN: 'unknown'>
>>> str(Color.UNKNOWN)
'unknown'

Anteckning

Det finns ställen i stdlib som kontrollerar för en exakt str istället för en str underklass (t.ex. type(unknown) == str istället för isinstance(unknown, str)), och på dessa ställen måste du använda str(MyStrEnum.MY_MEMBER).

Anteckning

Om du använder auto med StrEnum får du det gemena medlemsnamnet som värde.

Anteckning

__str__() är str.__str__() för att bättre stödja användningsfallet ersättning av befintliga konstanter. __format__() är likaså str.__format__() av samma anledning.

Tillagd i version 3.11.

class enum.Flag

Flag är samma sak som Enum, men dess medlemmar stöder de bitvisa operatorerna & (AND), | (OR), ^ (XOR) och ~ (INVERT); resultaten av dessa operationer är (alias för) medlemmar i uppräkningen.

__contains__(self, value)

Returnerar True om värdet finns i self:

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

Returnerar alla ingående icke-alias-medlemmar:

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

Tillagd i version 3.11.

__len__(self):

Returnerar antalet medlemmar i flag:

>>> len(Color.GREEN)
1
>>> len(white)
3

Tillagd i version 3.11.

__bool__(self):

Returnerar True om några medlemmar i flaggan, False annars:

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

Returnerar aktuell flagga binärt eller’ed med andra:

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

Returnerar aktuell flagga binärt och’ed med andra:

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

Returnerar aktuell flagga binärt xor’ed med andra:

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

Returnerar alla flaggor i type(self) som inte finns i self:

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

Funktion som används för att formatera eventuella återstående icke namngivna numeriska värden. Standard är värdets repr; vanliga val är hex() och oct().

Anteckning

Om du använder auto med Flag får du heltal som är potenser av två, med början på 1.

Ändrad i version 3.11: repr() för nollvärdesflaggor har ändrats. Det är det nu:

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

IntFlag är samma sak som Flag, men dess medlemmar är också heltal och kan användas överallt där ett heltal kan användas.

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

Om en heltalsoperation utförs med en IntFlag-medlem är resultatet inte en IntFlag:

>>> Color.RED + 2
3

Om en Flag-operation utförs med en IntFlag-medlem och:

  • resultatet är en giltig IntFlag: en IntFlag returneras

  • resultatet är inte en giltig IntFlag: resultatet beror på inställningen FlagBoundary

repr() av icke namngivna nollvärderade flaggor har ändrats. Den är nu:

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

Anteckning

Om du använder auto med IntFlag får du heltal som är potenser av två, med början på 1.

Ändrad i version 3.11: __str__() är nu int.__str__() för att bättre stödja användningsfallet ersättning av befintliga konstanter. __format__() var redan int.__format__() av samma anledning.

Inversion av en IntFlag returnerar nu ett positivt värde som är en sammanslagning av alla flaggor som inte ingår i den givna flaggan, istället för ett negativt värde. Detta matchar det befintliga Flag-beteendet.

class enum.ReprEnum

ReprEnum använder repr() av Enum, men str() av den blandade datatypen:

Ärv från ReprEnum för att behålla str() / format() för den blandade datatypen istället för att använda Enum-standard str().

Tillagd i version 3.11.

class enum.EnumCheck

EnumCheck innehåller de alternativ som används av verify()-dekoratorn för att säkerställa olika begränsningar; misslyckade begränsningar resulterar i ett ValueError.

UNIQUE

Se till att varje värde bara har ett namn:

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

Se till att det inte saknas några värden mellan den lägst värderade medlemmen och den högst värderade medlemmen:

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

Se till att alla flagggrupper/masker endast innehåller namngivna flaggor – användbart när värden anges istället för att genereras av 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]

Anteckning

CONTINUOUS och NAMED_FLAGS är utformade för att fungera med heltalsvärderade medlemmar.

Tillagd i version 3.11.

class enum.FlagBoundary

FlagBoundary styr hur värden utanför intervallet hanteras i Flag och dess underklasser.

STRICT

Värden utanför intervallet ger upphov till ett ValueError. Detta är standardvärdet för Flag:

>>> from enum import Flag, STRICT, auto
>>> 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

Värden utanför intervallet har ogiltiga värden borttagna, vilket lämnar ett giltigt Flag-värde:

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

Värden utanför intervallet förlorar sitt medlemskap i Flag och återgår till int.

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

Värden utanför intervallet behålls och medlemskapet i Flag behålls. Detta är standardinställningen för IntFlag:

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

Tillagd i version 3.11.

class enum.EnumDict

EnumDict är en subklass av dict som används som namnrymd för att definiera enumklasser (se Förbereda klassens namnrymd). Den är exponerad för att tillåta subklasser av EnumType med avancerat beteende som att ha flera värden per medlem. Den bör anropas med namnet på den enumklass som skapas, annars kommer privata namn och interna klasser inte att hanteras korrekt.

Observera att endast gränssnittet MutableMapping (__setitem__() och update()) åsidosätts. Det kan vara möjligt att kringgå kontrollerna genom att använda andra dict-operationer som |=.

member_names

En lista med medlemmarnas namn.

Tillagd i version 3.13.

Namn som stöds för __dunder__

__members__ är en skrivskyddad ordnad mappning av member_name:member objekt. Den är endast tillgänglig för klassen.

__new__(), om det anges, måste skapa och returnera enum-medlemmarna; det är också en mycket bra idé att ställa in medlemmens _value_ på lämpligt sätt. När alla medlemmar är skapade används den inte längre.

Namn med stöd för _sunder_

  • _add_alias_() – lägger till ett nytt namn som alias till en befintlig medlem.

  • _add_value_alias_() – lägger till ett nytt värde som ett alias till en befintlig medlem.

  • _name_ – namnet på medlemmen

  • _value_ – medlemmens värde; kan ställas in i __new__

  • _missing_() – en uppslagningsfunktion som används när ett värde inte hittas; kan åsidosättas

  • _ignore_ – en lista med namn, antingen som en list eller en str, som inte kommer att omvandlas till medlemmar och som kommer att tas bort från den slutliga klassen

  • _order_ – används inte längre, behålls för bakåtkompatibilitet (klassattribut, tas bort när klassen skapas)

  • _generate_next_value_() – används för att få ett lämpligt värde för en enum-medlem; kan åsidosättas

    Anteckning

    För standardklasserna Enum är nästa värde som väljs det högsta värde som setts, ökat med ett.

    För klasserna Flag kommer nästa värde som väljs att vara den näst högsta tvåpotensen.

  • Även om _sunder_-namn i allmänhet är reserverade för vidareutveckling av klassen Enum och inte kan användas, är vissa uttryckligen tillåtna:

Tillagd i version 3.6: _missing_, _order_, _generate_next_value_

Tillagd i version 3.7: _ignore_

Tillagd i version 3.13: _add_alias_, _add_value_alias_, _repr_*

Verktyg och dekoratörer

class enum.auto

auto kan användas i stället för ett värde. Om det används kommer Enum-maskineriet att anropa Enum:s _generate_next_value_() för att få ett lämpligt värde. För Enum och IntEnum kommer det lämpliga värdet att vara det sista värdet plus ett; för Flag och IntFlag kommer det att vara den första tvåpotensen större än det högsta värdet; för StrEnum kommer det att vara den gemena versionen av medlemmens namn. Försiktighet måste iakttas om auto() blandas med manuellt angivna värden.

auto-instanser löses endast när de befinner sig på den högsta nivån i ett uppdrag:

  • FIRST = auto() kommer att fungera (auto() ersätts med 1);

  • SECOND = auto(), -2 kommer att fungera (auto ersätts med 2, så 2, -2 används för att skapa enummedlemmen SECOND;

  • THREE = [auto(), -3] kommer inte att fungera (<auto instance>, -3 används för att skapa enummedlemmen THREE)

Ändrad i version 3.11.1: I tidigare versioner var auto() tvungen att vara det enda på tilldelningsraden för att fungera korrekt.

_generate_next_value_ kan åsidosättas för att anpassa de värden som används av auto.

Anteckning

i 3.13 kommer standardinställningen _generate_next_value_ alltid att returnera det högsta medlemsvärdet ökat med 1, och kommer att misslyckas om någon medlem är en inkompatibel typ.

@enum.property

En dekorator som liknar den inbyggda property, men som är specifik för uppräkningar. Den gör det möjligt för medlemsattribut att ha samma namn som medlemmarna själva.

Anteckning

egenskapen och medlemmen måste definieras i separata klasser; till exempel definieras attributen värde och namn i klassen Enum, och underklasser till Enum kan definiera medlemmar med namnen värde och namn.

Tillagd i version 3.11.

@enum.unique

En class-dekorator speciellt för uppräkningar. Den söker igenom en uppräknings __members__ och samlar in alla alias som den hittar; om några hittas ValueError skapas med detaljerna:

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

En class-dekorator speciellt för uppräkningar. Medlemmar från EnumCheck används för att ange vilka begränsningar som ska kontrolleras på den dekorerade uppräkningen.

Tillagd i version 3.11.

@enum.member

En dekorator för användning i enumer: dess mål blir en medlem.

Tillagd i version 3.11.

@enum.nonmember

En dekorator för användning i enumer: dess mål kommer inte att bli medlem.

Tillagd i version 3.11.

@enum.global_enum

En dekorator för att ändra str() och repr() för ett enum så att dess medlemmar visas som tillhörande modulen istället för dess klass. Bör endast användas när enum-medlemmarna exporteras till modulens globala namnrymd (se re.RegexFlag för ett exempel).

Tillagd i version 3.11.

enum.show_flag_values(value)

Returnerar en lista med alla tvåpotenstal som ingår i flaggan value.

Tillagd i version 3.11.

Anteckningar

IntEnum, StrEnum, och IntFlag

Dessa tre enumtyper är utformade för att ersätta befintliga heltals- och strängbaserade värden, och de har därför extra begränsningar:

  • __str__ använder värdet och inte namnet på enum-medlemmen

  • eftersom __format__ använder __str__ använder den också värdet på enum-medlemmen i stället för dess namn

Om du inte behöver/vill ha dessa begränsningar kan du antingen skapa din egen basklass genom att själv blanda in typen int eller str:

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

eller så kan du omfördela lämplig str(), etc., i din enum:

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