# `enum` — Énumerations

Nouveau dans la version 3.4.

Code source : Lib/enum.py

Une énumération est un ensemble de noms symboliques, appelés membres, liés à des valeurs constantes et uniques. Au sein d'une énumération, les membres peuvent être comparés entre eux et il est possible d'itérer sur l'énumération elle-même.

Note

Convention de nommage pour les membres d'une Enum

Puisque les Enums sont utilisées pour représenter des constantes, il est recommandé d'utiliser des majuscules (format `MAJUSCULE_AVEC_SOULIGNÉS`) pour leurs membres. Cette convention de style sera utilisée dans les exemples.

## Contenu du module

Ce module définit quatre classes d'énumération qui permettent de définir des ensembles uniques de noms et de valeurs : `Enum`, `IntEnum`, `Flag` et `IntFlag`. Il fournit également un décorateur, `unique()`, ainsi qu'une classe utilitaire, `auto`.

class `enum.``Enum`

  Classe de base pour créer une énumération de constantes. Voir la section API par fonction pour une syntaxe alternative de construction.

class `enum.``IntEnum`

  Classe de base pour créer une énumération de constantes qui sont également des sous-classes de `int`.

class `enum.``IntFlag`

  Classe de base pour créer une énumération de constantes pouvant être combinées avec des opérateurs de comparaison bit-à-bit, sans perdre leur qualité de `IntFlag`. Les membres de `IntFlag` sont aussi des sous-classes de `int`.

class `enum.``Flag`

  Classe de base pour créer une énumération de constantes pouvant être combinées avec des opérateurs de comparaison bit-à-bit, sans perdre leur qualité de `Flag`.

`enum.``unique`()

  Décorateur de classe qui garantit qu'une valeur ne puisse être associée qu'à un seul nom.

class `enum.``auto`

  Instances are replaced with an appropriate value for Enum members. By default, the initial value starts at 1.

Nouveau dans la version 3.6: `Flag`, `IntFlag`, `auto`

## Création d'une Enum

Une énumération est créée comme une `class`, ce qui la rend facile à lire et à écrire. Une autre méthode de création est décrite dans API par fonction. Pour définir une énumération, il faut hériter de `Enum` de la manière suivante :

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

Note

Valeurs des membres d'une Enum

La valeur d'un membre peut être de n'importe quel type : `int`, `str`, etc. Si la valeur exacte n'a pas d'importance, utilisez des instances de `auto` et une valeur appropriée sera choisie pour vous. Soyez vigilant si vous mélangez `auto` avec d'autres valeurs.

Note

Nomenclature

- La classe `Color` est une énumération (ou un enum).

- Les attributs `Color.RED`, `Color.GREEN`, etc., sont les membres de l'énumération (ou les membres de l'enum) et sont fonctionnellement des constantes.

- Les membres de l'enum ont chacun un nom et une valeur ; le nom de `Color.RED` est `RED`, la valeur de `Color.BLUE` est `3`, etc.

Note

Même si on utilise la syntaxe en `class` pour créer des énumérations, les Enums ne sont pas des vraies classes Python. Voir En quoi les Enums sont différentes ? pour plus de détails.

Les membres d'une énumération ont une représentation en chaîne de caractères compréhensible par un humain :

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

… tandis que leur `repr` contient plus d'informations :

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

Le type d'un membre est l'énumération auquel ce membre appartient :

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

Les membres ont également un attribut qui contient leur nom :

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

Les énumérations sont itérables, l'ordre d'itération est celui dans lequel les membres sont déclarés :

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

Les membres d'une énumération sont hachables, ils peuvent ainsi être utilisés dans des dictionnaires ou des ensembles :

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

## Accès dynamique aux membres et à leurs attributs

Il est parfois utile de pouvoir accéder dynamiquement aux membres d'une énumération (p. ex. dans des situations où il ne suffit pas d'utiliser `Color.RED` car la couleur précise n'est pas connue à l'écriture du programme). `Enum` permet de tels accès :

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

Pour accéder aux membres par leur nom, utilisez l'accès par indexation :

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

Pour obtenir l'attribut `name` ou `value` d'un membre :

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

## Duplication de membres et de valeurs

Il n'est pas possible d'avoir deux membres du même nom dans un enum :

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

Cependant deux membres peuvent avoir la même valeur. Si deux membres A et B ont la même valeur (et que A est défini en premier), B sera un alias de A. Un accès par valeur avec la valeur commune à A et B renverra A. Un accès à B par nom renverra aussi 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>

Note

Il est interdit de créer un membre avec le même nom qu'un attribut déjà défini (un autre membre, une méthode, etc.) ou de créer un attribut avec le nom d'un membre.

## Coercition d'unicité des valeurs d'une énumération

Par défaut, les énumérations autorisent les alias de nom pour une même valeur. Quand ce comportement n'est pas désiré, il faut utiliser le décorateur suivant pour s'assurer que chaque valeur n'est utilisée qu'une seule fois au sein de l'énumération :

`@``enum.``unique`

Un décorateur de `class` spécifique aux énumérations. Il examine l'attribut `__members__` d'une énumération et recherche des alias ; s'il en trouve, l'exception `ValueError` est levée avec des détails :

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

## Valeurs automatiques

Si la valeur exacte n'a pas d'importance, vous pouvez utiliser `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>]

Les valeurs sont déterminées par `_generate_next_value_()`, qui peut être redéfinie :

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

Note

La méthode `_generate_next_value_()` doit renvoyer le prochain `int` de la séquence à partir du dernier `int` fourni, mais l'implémentation de cette fonction peut changer.

Note

La méthode `_generate_next_value_()` doit être définie avant tout membre.

## Itération

Itérer sur les membres d'une énumération ne parcourt pas les alias :

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

L'attribut spécial `__members__` est un dictionnaire en lecture seule ordonné qui fait correspondre les noms aux membres. Il inclut tous les noms définis dans l'énumération, alias compris :

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

L'attribut `__members__` peut servir à accéder dynamiquement aux membres de l'énumération. Par exemple, pour trouver tous les alias :

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

## Comparaisons

Les membres d'une énumération sont comparés par identité :

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

Les comparaisons d'ordre entre les valeurs d'une énumération n'existent pas ; les membres d'un enum ne sont pas des entiers (voir cependant IntEnum ci-dessous) :

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

A contrario, les comparaisons d'égalité existent :

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

Les comparaisons avec des valeurs ne provenant pas d'énumérations sont toujours fausses (ici encore, `IntEnum` a été conçue pour fonctionner différemment, voir ci-dessous) :

    >>> Color.BLUE == 2
    False

## Membres et attributs autorisés dans une énumération

Les exemples précédents utilisent des entiers pour énumérer les valeurs. C'est un choix concis et pratique (et implémenté par défaut dans l'API par fonction), mais ce n'est pas une obligation. Dans la majorité des cas, il importe peu de connaître la valeur réelle d'une énumération. Il est toutefois possible de donner une valeur arbitraire aux énumérations, si cette valeur est vraiment significative.

Les énumérations sont des classes Python et peuvent donc avoir des méthodes et des méthodes spéciales. L'énumération suivante :

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

amène :

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

Les règles pour ce qui est autorisé sont les suivantes : les noms qui commencent et finissent avec un seul tiret bas sont réservés par enum et ne peuvent pas être utilisés ; tous les autres attributs définis dans l'énumération en deviendront des membres, à l'exception des méthodes spéciales (`__str__()`, `__add__()`, etc.), des descripteurs (les méthodes sont aussi des descripteurs) et des noms de variable listés dans `_ignore_`.

Remarque : si votre énumération définit `__new__()` ou `__init__()`, alors les valeurs affectées aux membres seront passées à ces méthodes. Voir Planet pour exemple.

## Restrictions sur l'héritage

Une nouvelle classe `Enum` doit avoir une classe Enum de base, au plus un type de données concret et autant de classes de mélange (basées sur `object`) que nécessaire. L'ordre de ces classes de base est le suivant :

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

Hériter d'une énumération n'est permis que si cette énumération ne définit aucun membre. Le code suivant n'est pas autorisé :

    >>> class MoreColor(Color):
    ...     PINK = 17
    ...
    Traceback (most recent call last):
    ...
    TypeError: Cannot extend enumerations

Mais celui-ci est correct :

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

Autoriser l'héritage d'enums définissant des membres violerait des invariants sur les types et les instances. D'un autre côté, il est logique d'autoriser un groupe d'énumérations à partager un comportement commun (voir par exemple OrderedEnum).

## Sérialisation

Les énumérations peuvent être sérialisées et déserialisées :

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

Les restrictions habituelles de sérialisation s'appliquent : les enums à sérialiser doivent être déclarés dans l'espace de nom de haut niveau du module car la déserialisation nécessite que ces enums puissent être importés depuis ce module.

Note

Depuis la version 4 du protocole de pickle, il est possible de sérialiser facilement des enums imbriqués dans d'autres classes.

Redéfinir la méthode `__reduce_ex__()` permet de modifier la sérialisation ou la dé-sérialisation des membres d'une énumération.

## API par fonction

La `Enum` est appelable et implémente l'API par fonction suivante :

    >>> 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 sémantique de cette API est similaire à `namedtuple`. Le premier argument de l'appel à `Enum` est le nom de l'énumération.

Le second argument est la source des noms des membres de l'énumération. Il peut être une chaîne de caractères contenant les noms séparés par des espaces, une séquence de noms, une séquence de couples clé / valeur ou un dictionnaire (p. ex. un dict) de valeurs indexées par des noms. Les deux dernières options permettent d'affecter des valeurs arbitraires aux énumérations ; les autres affectent automatiquement des entiers en commençant par 1 (le paramètre `start` permet de changer la valeur de départ). Ceci renvoie une nouvelle classe dérivée de `Enum`. En d'autres termes, la déclaration de `Animal` ci-dessus équivaut à :

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

La valeur de départ par défaut est `1` et non `0` car `0` au sens booléen vaut `False` alors que tous les membres d'une enum valent `True`.

La sérialisation d'énumérations créées avec l'API en fonction peut être source de problèmes, car celle-ci repose sur des détails d'implémentation de l'affichage de la pile d'appel pour tenter de déterminer dans quel module l'énumération est créée (p. ex. elle échouera avec les fonctions utilitaires provenant d'un module séparé et peut ne pas fonctionner avec IronPython ou Jython). La solution consiste à préciser explicitement le nom du module comme ceci :

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

Avertissement

Si `module` n'est pas fourni et que Enum ne peut pas le deviner, les nouveaux membres de l'Enum ne seront pas déserialisables ; pour garder les erreurs au plus près de leur origine, la sérialisation sera désactivée.

Le nouveau protocole version 4 de pickle se base lui aussi, dans certains cas, sur le fait que `__qualname__` pointe sur l'endroit où pickle peut trouver la classe. Par exemple, si la classe était disponible depuis la classe SomeData dans l'espace de nom de plus haut niveau :

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

La signature complète est la suivante :

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

value

  Le nom de la la nouvelle classe Enum.

names

  Les membres de l'énumération. Une chaîne de caractères séparés par des espaces ou des virgules (la valeur de départ est fixée à 1, sauf si spécifiée autrement) :

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

  ou un itérateur sur les noms :

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

  ou un itérateur sur les n-uplets (nom, valeur) :

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

  ou une correspondance :

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

module

  nom du module dans lequel la classe Enum se trouve.

qualname

  localisation de la nouvelle classe Enum dans le module.

type

  le type à mélanger dans la nouvelle classe Enum.

start

  index de départ si uniquement des noms sont passés.

Modifié dans la version 3.5: Ajout du paramètre start.

## Énumérations dérivées

### IntEnum

La première version dérivée de `Enum` qui existe est aussi une sous-classe de `int`. Les membres de `IntEnum` peuvent être comparés à des entiers et, par extension, les comparaisons entre des énumérations entières de type différent sont possibles :

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

Elles ne peuvent cependant toujours pas être comparées à des énumérations standards de `Enum` :

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

Les valeurs de `IntEnum` se comportent comme des entiers, comme on pouvait s'y attendre :

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

### IntFlag

La version dérivée suivante de `Enum` est `IntFlag`. Elle est aussi basée sur `int`, à la différence près que les membres de `IntFlag` peuvent être combinés en utilisant les opérateurs bit-à-bit (&, |, ^, ~) et que le résultat reste un membre de `IntFlag`. Cependant, comme le nom l'indique, les membres d'une classe `IntFlag` héritent aussi de `int` et peuvent être utilisés là où un `int` est utilisé. Toute opération sur un membre d'une classe `IntFlag`, autre qu'un opérateur bit-à-bit lui fait perdre sa qualité de `IntFlag`.

Nouveau dans la version 3.6.

Exemple d'une classe `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

Il est aussi possible de nommer les combinaisons :

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

Une autre différence importante entre `IntFlag` et `Enum` est que, si aucune option n'est activée (la valeur vaut 0), son évaluation booléenne est `False` :

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

Comme les membres d'une classe `IntFlag` héritent aussi de `int`, ils peuvent être combinés avec eux :

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

### Option

La dernière version dérivée est la classe `Flag`. Comme `IntFlag`, les membres d'une classe `Flag` peuvent être combinés en utilisant les opérateurs de comparaison bit-à-bit. Cependant, à la différence de `IntFlag`, ils ne peuvent ni être combinés, ni être comparés avec une autre énumération `Flag`, ni avec `int`. Bien qu'il soit possible de définir directement les valeurs, il est recommandé d'utiliser `auto` comme valeur et de laisser `Flag` choisir une valeur appropriée.

Nouveau dans la version 3.6.

Comme avec `IntFlag`, si une combinaison de membres d'une classe `Flag` n'active aucune option, l'évaluation booléenne de la comparaison est `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

Les options de base doivent avoir des puissances de deux pour valeurs (1, 2, 4, 8, ...) mais pas les combinaisons :

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

Donner un nom à la valeur « aucune option activée » ne change pas sa valeur booléenne :

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

Note

Dans la plupart des cas, il est fortement recommandé d'utiliser `Enum` et `Flag` pour écrire du code nouveau, car `IntEnum` et `IntFlag` violent certains principes sémantiques d'une énumération (en pouvant être comparées à des entiers et donc, par transitivité, à d'autres énumérations). `IntEnum` et `IntFlag` ne doivent être utilisées que dans les cas où `Enum` et `Flag` ne suffisent pas ; par exemple quand des constantes entières sont remplacées par des énumérations, ou pour l’interopérabilité avec d'autres systèmes.

### Autres

Bien que `IntEnum` fasse partie du module `enum`, elle serait très simple à implémenter hors de ce module :

    class IntEnum(int, Enum):
        pass

Ceci montre comment définir des énumérations dérivées similaires ; par exemple une classe `StrEnum` qui dériverait de `str` au lieu de `int`.

Quelques règles :

1. Pour hériter de `Enum`, les types de mélange doivent être placés avant la classe `Enum` elle-même dans la liste des classes de base, comme dans l'exemple de `IntEnum` ci-dessus.

2. Même si une classe `Enum` peut avoir des membres de n'importe quel type, dès qu'un type est spécifié à la déclaration de la classe, alors tous les membres doivent être de ce type, p. ex. `int` ci-dessus. Cette restriction ne s'applique pas aux classes dérivées qui n'ajoutent que des méthodes supplémentaires sans spécifier un type de données.

3. Quand un autre type de données est mélangé, l'attribut `value` n'est pas identique au membre de l'énumération lui-même, bien qu'ils soient équivalents et égaux en comparaison.

4. Formatage de style % : %s et %r appellent respectivement les méthodes `__str__()` et `__repr__()` de la classe `Enum` ; les autres codes, comme %i ou %h pour IntEnum, s'appliquent au membre comme si celui-ci était converti en son type de mélange.

5. Les chaînes littérales formatées : `str.format()` et `format()` appellent la méthode `__format__()` du type dérivé à moins que `__str__()` ou `__format__()` soit surchargée dans la sous-classe, auquel cas les méthodes surchargées ou celles de la classe `Enum` seront utilisées. Pour appeler les méthodes `__str__()` ou `__repr__()` de la classe `Enum`, il faut utiliser les codes de formatage `!s` ou `!r`.

## Quand utiliser `__new__()` ou `__init__()`

`__new__()` doit être utilisé dès que vous souhaitez personnaliser la valeur effective des membres d'un `Enum`. Tout autre modification peut autant aller dans `__new__()` que dans `__init__()`, mais l'usage de `__init__()` est recommandé.

Par exemple, si vous voulez passer plusieurs éléments au constructeur, mais qu'un seul d'entre eux soit la valeur :

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

## Exemples intéressants

Bien que `Enum`, `IntEnum`, `IntFlag` et `Flag` soient conçues pour répondre à la majorité des besoins, elles ne peuvent répondre à tous. Voici quelques recettes d'énumération qui peuvent être réutilisées telles quelles, ou peuvent servir d'exemple pour développer vos propres énumérations.

### Omettre les valeurs

Dans de nombreux cas, la valeur réelle de l'énumération n'a pas d'importance. Il y a plusieurs façons de définir ce type d'énumération simple :

- affecter des instances de `auto` aux valeurs

- affecter des instances de `object` aux valeurs

- affecter des chaînes de caractères aux valeurs pour les décrire

- affecter un n-uplet aux valeurs et définir une méthode `__new__()` pour remplacer les n-uplets avec un `int`

Utiliser une de ces méthodes indique à l'utilisateur que les valeurs n'ont pas d'importance. Cela permet aussi d'ajouter, de supprimer ou de ré-ordonner les membres sans avoir à ré-énumérer les membres existants.

Quelle que soit la méthode choisie, il faut fournir une méthode `repr()` qui masque les valeurs (pas importantes de toute façon) :

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

#### Avec `auto`

On utilise `auto` de la manière suivante :

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

#### Avec `object`

On utilise `object` de la manière suivante :

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

#### Avec une chaîne de caractères de description

On utilise une chaîne de caractères de la manière suivante :

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

#### Avec une méthode ad-hoc `__new__()`

On utilise une méthode `__new__()` d'énumération de la manière suivante :

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

Pour définir un `AutoNumber` plus générique, ajoutez `*args` à la signature :

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

Ainsi, quand vous héritez d'`AutoNumber`, vous pouvez définir `__init__` pour gérer tout argument supplémentaire :

    >>> 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: 2>
    >>> Swatch.SEA_GREEN.pantone
    '1246'
    >>> Swatch.BLEACHED_CORAL.pantone
    'unknown'

Note

La méthode `__new__()`, si définie, est appelée à la création des membres de l'énumération ; elle est ensuite remplacée par la méthode `__new__()` de Enum, qui est utilisée après la création de la classe pour la recherche des membres existants.

### OrderedEnum

Une énumération ordonnée qui n'est pas basée sur `IntEnum` et qui, par conséquent, respecte les invariants classiques de `Enum` (comme par exemple l'impossibilité de pouvoir être comparée à d'autres énumérations) :

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

Lève une erreur si un membre est dupliqué, plutôt que de créer 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'

Note

Cet exemple d'héritage de Enum est intéressant pour ajouter ou modifier des comportements comme interdire les alias. Si vous ne souhaitez qu'interdire les alias, il suffit d'utiliser le décorateur `unique()`.

### Planet

Si `__new__()` ou `__init__()` sont définies, la valeur du membre de l'énumération sera passée à ces méthodes :

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

### TimePeriod

Exemple d'utilisation de l'attribut `_ignore_` :

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

## En quoi les Enums sont différentes ?

Les enums ont une métaclasse spéciale qui affecte de nombreux aspects des classes dérivées de Enum et de leur instances (membres).

### Classes Enum

La métaclasse `EnumMeta` se charge de fournir les méthodes `__contains__()`, `__dir__()`, `__iter__()` etc. qui permettent de faire des opérations sur une classe `Enum` qui ne fonctionneraient pas sur une classe standard, comme list(Color) ou some_enum_var in Color. `EnumMeta` garantit que les autres méthodes de la classe finale `Enum` sont correctes (comme `__new__()`, `__getnewargs__()`, `__str__()` et `__repr__()`).

### Membres d'Enum (c.-à-d. instances)

Il est intéressant de souligner que les membres d'une Enum sont des singletons. La classe `EnumMeta` les crée tous au moment de la création de la classe `Enum` elle-même et implémente une méthode `__new__()` spécifique. Cette méthode renvoie toujours les instances de membres déjà existantes pour être sûr de ne jamais en instancier de nouvelles.

### Aspects approfondis

#### Noms de la forme `__dunder__` disponibles

`__members__` est un dictionnaire en lecture seule ordonné d'éléments `nom_du_membre` / `membre`. Il n'est disponible que depuis la classe.

La méthode `__new__()`, si elle est définie, doit créer et renvoyer les membres de l'énumération ; affecter correctement l'attribut `_value_` du membre est également conseillé. Une fois que tous les membres ont été créés, cette méthode n'est plus utilisée.

#### Noms de la forme `_sunder_` disponibles

- `_name_` -- nom du membre

- `_value_` -- valeur du membre ; il est possible d'y accéder ou de la muer dans `__new__`

- `_missing_` -- une fonction de recherche qui est appelée quand la valeur n'est pas trouvée ; elle peut être redéfinie

- `_ignore_` — liste de noms, sous la forme d'une `list()` ou d'une `str()`, qui ne sont pas convertis en membres et sont supprimés de la classe résultante

- `_order_` -- utilisé en Python 2 ou 3 pour s'assurer que l'ordre des membres est cohérent (attribut de classe, supprimé durant la création de la classe)

- `_generate_next_value_` -- utilisée par l' API par fonction et par `auto` pour obtenir une valeur appropriée à affecter à un membre de l'enum ; elle peut être redéfinie

Nouveau dans la version 3.6: `_missing_`, `_order_`, `_generate_next_value_`

Nouveau dans la version 3.7: `_ignore_`

Pour faciliter la transition de Python 2 en Python 3, l'attribut `_order_` peut être défini. Il sera comparé au véritable ordre de l'énumération et lève une erreur si les deux ne correspondent pas :

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

Note

En Python 2, l'attribut `_order_` est indispensable car l'ordre de la définition est perdu avant de pouvoir être enregistré.

#### _Noms__privés

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.9 and 3.10 will issue a `DeprecationWarning`.

#### Type des membres de `Enum`

Les membres de `Enum` sont des instances de leur classe `Enum`. On y accède normalement par `ClasseEnum.membre`. Dans certains cas, on peut également y accéder par `ClasseEnum.membre.membre`, mais ceci est fortement déconseillé car cette indirection est susceptible d'échouer, ou pire, de ne pas renvoyer le membre de la classe `Enum` désiré (c'est une autre bonne raison pour définir tous les noms des membres en majuscules) :

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

Note

Ce comportement est obsolète et sera retiré en 3.11.

Modifié dans la version 3.5.

#### Valeur booléenne des classes `Enum` et de leurs membres

Les membres d'une classe `Enum` mélangée avec un type non dérivé de `Enum` (comme `int`, `str`, etc.) sont évalués selon les règles du type de mélange. Sinon, tous les membres valent `True`. Pour faire dépendre l'évaluation booléenne de votre propre Enum de la valeur du membre, il faut ajouter le code suivant à votre classe :

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

Les classes `Enum` valent toujours `True`.

#### Classes `Enum` avec des méthodes

Si votre classe `Enum` contient des méthodes supplémentaires, comme la classe Planet ci-dessus, elles s'afficheront avec un appel à `dir()` sur le membre, mais pas avec un appel sur la classe :

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

#### Combinaison de membres de `Flag`

Si une valeur issue de la combinaison de membres de Flag n'est pas associée explicitement à un membre, la fonction `repr()` inclut tous les membres et toutes les combinaisons de membres présents dans cette valeur :

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

Note

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