diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/howto/enum.rst | 272 | ||||
| -rw-r--r-- | Doc/library/enum.rst | 265 | ||||
| -rw-r--r-- | Doc/library/ssl.rst | 4 |
3 files changed, 240 insertions, 301 deletions
diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index fa0e228..6c09b99 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -2,10 +2,15 @@ Enum HOWTO ========== +:Author: Ethan Furman <ethan at stoneleaf dot us> + .. _enum-basic-tutorial: .. currentmodule:: enum +Basic Enum Tutorial +------------------- + An :class:`Enum` is a set of symbolic names bound to unique values. They are similar to global variables, but they offer a more useful :func:`repr()`, grouping, type-safety, and a few other features. @@ -23,14 +28,6 @@ selection of values. For example, the days of the week:: ... SATURDAY = 6 ... SUNDAY = 7 - Or perhaps the RGB primary colors:: - - >>> from enum import Enum - >>> class Color(Enum): - ... RED = 1 - ... GREEN = 2 - ... BLUE = 3 - As you can see, creating an :class:`Enum` is as simple as writing a class that inherits from :class:`Enum` itself. @@ -44,14 +41,13 @@ important, but either way that value can be used to get the corresponding member:: >>> Weekday(3) - <Weekday.WEDNESDAY: 3> + Weekday.WEDNESDAY -As you can see, the ``repr()`` of a member shows the enum name, the member name, -and the value. The ``str()`` of a member shows only the enum name and member -name:: +As you can see, the ``repr()`` of a member shows the enum name and the +member name. The ``str()`` on a member shows only its name:: >>> print(Weekday.THURSDAY) - Weekday.THURSDAY + THURSDAY The *type* of an enumeration member is the enum it belongs to:: @@ -101,8 +97,8 @@ The complete :class:`Weekday` enum now looks like this:: Now we can find out what today is! Observe:: >>> from datetime import date - >>> Weekday.from_date(date.today()) # doctest: +SKIP - <Weekday.TUESDAY: 2> + >>> Weekday.from_date(date.today()) + Weekday.TUESDAY Of course, if you're reading this on some other day, you'll see that day instead. @@ -128,21 +124,21 @@ Just like the original :class:`Weekday` enum above, we can have a single selecti >>> first_week_day = Weekday.MONDAY >>> first_week_day - <Weekday.MONDAY: 1> + Weekday.MONDAY But :class:`Flag` also allows us to combine several members into a single variable:: >>> weekend = Weekday.SATURDAY | Weekday.SUNDAY >>> weekend - <Weekday.SATURDAY|SUNDAY: 96> + Weekday.SATURDAY|Weekday.SUNDAY You can even iterate over a :class:`Flag` variable:: >>> for day in weekend: ... print(day) - Weekday.SATURDAY - Weekday.SUNDAY + SATURDAY + SUNDAY Okay, let's get some chores set up:: @@ -177,7 +173,6 @@ yourself some work and use :func:`auto()` for the values:: .. _enum-advanced-tutorial: - Programmatic access to enumeration members and their attributes --------------------------------------------------------------- @@ -186,16 +181,16 @@ situations where ``Color.RED`` won't do because the exact color is not known at program-writing time). ``Enum`` allows such access:: >>> Color(1) - <Color.RED: 1> + Color.RED >>> Color(3) - <Color.BLUE: 3> + Color.BLUE If you want to access enum members by *name*, use item access:: >>> Color['RED'] - <Color.RED: 1> + Color.RED >>> Color['GREEN'] - <Color.GREEN: 2> + Color.GREEN If you have an enum member and need its :attr:`name` or :attr:`value`:: @@ -217,7 +212,7 @@ Having two enum members with the same name is invalid:: ... Traceback (most recent call last): ... - TypeError: 'SQUARE' already defined as 2 + TypeError: 'SQUARE' already defined as: 2 However, an enum member can have other names associated with it. Given two entries ``A`` and ``B`` with the same value (and ``A`` defined first), ``B`` @@ -232,11 +227,11 @@ By-name lookup of ``B`` will also return the member ``A``:: ... ALIAS_FOR_SQUARE = 2 ... >>> Shape.SQUARE - <Shape.SQUARE: 2> + Shape.SQUARE >>> Shape.ALIAS_FOR_SQUARE - <Shape.SQUARE: 2> + Shape.SQUARE >>> Shape(2) - <Shape.SQUARE: 2> + Shape.SQUARE .. note:: @@ -304,7 +299,7 @@ Iteration Iterating over the members of an enum does not provide the aliases:: >>> list(Shape) - [<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>] + [Shape.SQUARE, Shape.DIAMOND, Shape.CIRCLE] The special attribute ``__members__`` is a read-only ordered mapping of names to members. It includes all names defined in the enumeration, including the @@ -313,10 +308,10 @@ aliases:: >>> 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>) + ('SQUARE', Shape.SQUARE) + ('DIAMOND', Shape.DIAMOND) + ('CIRCLE', Shape.CIRCLE) + ('ALIAS_FOR_SQUARE', Shape.SQUARE) The ``__members__`` attribute can be used for detailed programmatic access to the enumeration members. For example, finding all the aliases:: @@ -365,8 +360,8 @@ below):: Allowed members and attributes of enumerations ---------------------------------------------- -Most of the examples above use integers for enumeration values. Using integers -is short and handy (and provided by default by the `Functional API`_), but not +Most of the examples above use integers for enumeration values. Using integers is +short and handy (and provided by default by the `Functional API`_), but not strictly enforced. In the vast majority of use-cases, one doesn't care what the actual value of an enumeration is. But if the value *is* important, enumerations can have arbitrary values. @@ -394,7 +389,7 @@ usual. If we have this enumeration:: Then:: >>> Mood.favorite_mood() - <Mood.HAPPY: 3> + Mood.HAPPY >>> Mood.HAPPY.describe() ('HAPPY', 3) >>> str(Mood.FUNKY) @@ -430,7 +425,7 @@ any members. So this is forbidden:: ... Traceback (most recent call last): ... - TypeError: <enum 'MoreColor'> cannot extend <enum 'Color'> + TypeError: MoreColor: cannot extend enumeration 'Color' But this is allowed:: @@ -481,9 +476,11 @@ The :class:`Enum` class is callable, providing the following functional API:: >>> Animal <enum 'Animal'> >>> Animal.ANT - <Animal.ANT: 1> + Animal.ANT + >>> Animal.ANT.value + 1 >>> list(Animal) - [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>] + [Animal.ANT, Animal.BEE, Animal.CAT, Animal.DOG] The semantics of this API resemble :class:`~collections.namedtuple`. The first argument of the call to :class:`Enum` is the name of the enumeration. @@ -628,7 +625,16 @@ StrEnum The second variation of :class:`Enum` that is provided is also a subclass of :class:`str`. Members of a :class:`StrEnum` can be compared to strings; by extension, string enumerations of different types can also be compared -to each other. +to each other. :class:`StrEnum` exists to help avoid the problem of getting +an incorrect member:: + + >>> from enum import StrEnum + >>> class Directions(StrEnum): + ... NORTH = 'north', # notice the trailing comma + ... SOUTH = 'south' + +Before :class:`StrEnum`, ``Directions.NORTH`` would have been the :class:`tuple` +``('north',)``. .. versionadded:: 3.11 @@ -639,8 +645,9 @@ IntFlag The next variation of :class:`Enum` provided, :class:`IntFlag`, is also based on :class:`int`. The difference being :class:`IntFlag` members can be combined using the bitwise operators (&, \|, ^, ~) and the result is still an -:class:`IntFlag` member, if possible. Like :class:`IntEnum`, :class:`IntFlag` -members are also integers and can be used wherever an :class:`int` is used. +:class:`IntFlag` member, if possible. However, as the name implies, :class:`IntFlag` +members also subclass :class:`int` and can be used wherever an :class:`int` is +used. .. note:: @@ -663,7 +670,7 @@ Sample :class:`IntFlag` class:: ... X = 1 ... >>> Perm.R | Perm.W - <Perm.R|W: 6> + Perm.R|Perm.W >>> Perm.R + Perm.W 6 >>> RW = Perm.R | Perm.W @@ -678,11 +685,11 @@ It is also possible to name the combinations:: ... X = 1 ... RWX = 7 >>> Perm.RWX - <Perm.RWX: 7> + Perm.RWX >>> ~Perm.RWX - <Perm: 0> + Perm(0) >>> Perm(7) - <Perm.RWX: 7> + Perm.RWX .. note:: @@ -695,7 +702,7 @@ Another important difference between :class:`IntFlag` and :class:`Enum` is that if no flags are set (the value is 0), its boolean evaluation is :data:`False`:: >>> Perm.R & Perm.X - <Perm: 0> + Perm(0) >>> bool(Perm.R & Perm.X) False @@ -703,7 +710,7 @@ Because :class:`IntFlag` members are also subclasses of :class:`int` they can be combined with them (but may lose :class:`IntFlag` membership:: >>> Perm.X | 4 - <Perm.R|X: 5> + Perm.R|Perm.X >>> Perm.X | 8 9 @@ -719,7 +726,7 @@ be combined with them (but may lose :class:`IntFlag` membership:: :class:`IntFlag` members can also be iterated over:: >>> list(RW) - [<Perm.R: 4>, <Perm.W: 2>] + [Perm.R, Perm.W] .. versionadded:: 3.11 @@ -746,7 +753,7 @@ flags being set, the boolean evaluation is :data:`False`:: ... GREEN = auto() ... >>> Color.RED & Color.GREEN - <Color: 0> + Color(0) >>> bool(Color.RED & Color.GREEN) False @@ -760,7 +767,7 @@ while combinations of flags won't:: ... WHITE = RED | BLUE | GREEN ... >>> Color.WHITE - <Color.WHITE: 7> + Color.WHITE Giving a name to the "no flags set" condition does not change its boolean value:: @@ -772,7 +779,7 @@ value:: ... GREEN = auto() ... >>> Color.BLACK - <Color.BLACK: 0> + Color.BLACK >>> bool(Color.BLACK) False @@ -780,7 +787,7 @@ value:: >>> purple = Color.RED | Color.BLUE >>> list(purple) - [<Color.RED: 1>, <Color.BLUE: 2>] + [Color.RED, Color.BLUE] .. versionadded:: 3.11 @@ -805,16 +812,16 @@ simple to implement independently:: pass This demonstrates how similar derived enumerations can be defined; for example -a :class:`FloatEnum` that mixes in :class:`float` instead of :class:`int`. +a :class:`StrEnum` that mixes in :class:`str` instead of :class:`int`. Some rules: 1. When subclassing :class:`Enum`, mix-in types must appear before :class:`Enum` itself in the sequence of bases, as in the :class:`IntEnum` example above. -2. Mix-in types must be subclassable. For example, :class:`bool` and - :class:`range` are not subclassable and will throw an error during Enum - creation if used as the mix-in type. +2. Mix-in types must be subclassable. For example, + :class:`bool` and :class:`range` are not subclassable + and will throw an error during Enum creation if used as the mix-in type. 3. While :class:`Enum` can have members of any type, once you mix in an additional type, all the members must have values of that type, e.g. :class:`int` above. This restriction does not apply to mix-ins which only @@ -822,18 +829,15 @@ Some rules: 4. When another data type is mixed in, the :attr:`value` attribute is *not the same* as the enum member itself, although it is equivalent and will compare equal. -5. %-style formatting: ``%s`` and ``%r`` call the :class:`Enum` class's +5. %-style formatting: `%s` and `%r` call the :class:`Enum` class's :meth:`__str__` and :meth:`__repr__` respectively; other codes (such as - ``%i`` or ``%h`` for IntEnum) treat the enum member as its mixed-in type. + `%i` or `%h` for IntEnum) treat the enum member as its mixed-in type. 6. :ref:`Formatted string literals <f-strings>`, :meth:`str.format`, - and :func:`format` will use the enum's :meth:`__str__` method. - -.. note:: - - Because :class:`IntEnum`, :class:`IntFlag`, and :class:`StrEnum` are - designed to be drop-in replacements for existing constants, their - :meth:`__str__` method has been reset to their data types - :meth:`__str__` method. + and :func:`format` will use the mixed-in type's :meth:`__format__` + unless :meth:`__str__` or :meth:`__format__` is overridden in the subclass, + in which case the overridden methods or :class:`Enum` methods will be used. + Use the !s and !r format codes to force usage of the :class:`Enum` class's + :meth:`__str__` and :meth:`__repr__` methods. When to use :meth:`__new__` vs. :meth:`__init__` ------------------------------------------------ @@ -862,10 +866,10 @@ want one of them to be the value:: ... >>> print(Coordinate['PY']) - Coordinate.PY + PY >>> print(Coordinate(3)) - Coordinate.VY + VY Finer Points @@ -923,8 +927,8 @@ and raise an error if the two do not match:: Traceback (most recent call last): ... TypeError: member order does not match _order_: - ['RED', 'BLUE', 'GREEN'] - ['RED', 'GREEN', 'BLUE'] + ['RED', 'BLUE', 'GREEN'] + ['RED', 'GREEN', 'BLUE'] .. note:: @@ -945,36 +949,35 @@ but remain normal attributes. """""""""""""""""""" Enum members are instances of their enum class, and are normally accessed as -``EnumClass.member``. In Python versions ``3.5`` to ``3.10`` you could access -members from other members -- this practice was discouraged, and in ``3.11`` -:class:`Enum` returns to not allowing it:: +``EnumClass.member``. In Python versions ``3.5`` to ``3.9`` you could access +members from other members -- this practice was discouraged, and in ``3.12`` +:class:`Enum` will return to not allowing it, while in ``3.10`` and ``3.11`` +it will raise a :exc:`DeprecationWarning`:: >>> class FieldTypes(Enum): ... name = 0 ... value = 1 ... size = 2 ... - >>> FieldTypes.value.size - Traceback (most recent call last): - ... - AttributeError: <enum 'FieldTypes'> member has no attribute 'size' - + >>> FieldTypes.value.size # doctest: +SKIP + DeprecationWarning: accessing one member from another is not supported, + and will be disabled in 3.12 + <FieldTypes.size: 2> .. versionchanged:: 3.5 -.. versionchanged:: 3.11 Creating members that are mixed with other data types """"""""""""""""""""""""""""""""""""""""""""""""""""" When subclassing other data types, such as :class:`int` or :class:`str`, with -an :class:`Enum`, all values after the ``=`` are passed to that data type's +an :class:`Enum`, all values after the `=` are passed to that data type's constructor. For example:: - >>> class MyEnum(IntEnum): # help(int) -> int(x, base=10) -> integer - ... example = '11', 16 # so x='11' and base=16 - ... - >>> MyEnum.example.value # and hex(11) is... + >>> class MyEnum(IntEnum): + ... example = '11', 16 # '11' will be interpreted as a hexadecimal + ... # number + >>> MyEnum.example.value 17 @@ -997,12 +1000,13 @@ Plain :class:`Enum` classes always evaluate as :data:`True`. """"""""""""""""""""""""""""" If you give your enum subclass extra methods, like the `Planet`_ -class below, those methods will show up in a :func:`dir` of the member, -but not of the class:: +class below, those methods will show up in a :func:`dir` of the member and the +class. Attributes defined in an :func:`__init__` method will only show up in a +:func:`dir` of the member:: - >>> dir(Planet) # doctest: +SKIP - ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__'] - >>> dir(Planet.EARTH) # doctest: +SKIP + >>> dir(Planet) + ['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__init__', '__members__', '__module__', 'surface_gravity'] + >>> dir(Planet.EARTH) ['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', 'surface_gravity', 'value'] @@ -1021,10 +1025,19 @@ are comprised of a single bit:: ... CYAN = GREEN | BLUE ... >>> Color(3) # named combination - <Color.YELLOW: 3> + Color.YELLOW >>> Color(7) # not named combination - <Color.RED|GREEN|BLUE: 7> + Color.RED|Color.GREEN|Color.BLUE +``StrEnum`` and :meth:`str.__str__` +""""""""""""""""""""""""""""""""""" + +An important difference between :class:`StrEnum` and other Enums is the +:meth:`__str__` method; because :class:`StrEnum` members are strings, some +parts of Python will read the string data directly, while others will call +:meth:`str()`. To make those two operations have the same result, +:meth:`StrEnum.__str__` will be the same as :meth:`str.__str__` so that +``str(StrEnum.member) == StrEnum.member`` is true. ``Flag`` and ``IntFlag`` minutia """""""""""""""""""""""""""""""" @@ -1047,16 +1060,16 @@ the following are true: - only canonical flags are returned during iteration:: >>> list(Color.WHITE) - [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>] + [Color.RED, Color.GREEN, Color.BLUE] - negating a flag or flag set returns a new flag/flag set with the corresponding positive integer value:: >>> Color.BLUE - <Color.BLUE: 4> + Color.BLUE >>> ~Color.BLUE - <Color.RED|GREEN: 3> + Color.RED|Color.GREEN - names of pseudo-flags are constructed from their members' names:: @@ -1066,29 +1079,25 @@ the following are true: - multi-bit flags, aka aliases, can be returned from operations:: >>> Color.RED | Color.BLUE - <Color.PURPLE: 5> + Color.PURPLE >>> Color(7) # or Color(-1) - <Color.WHITE: 7> + Color.WHITE >>> Color(0) - <Color.BLACK: 0> + Color.BLACK -- membership / containment checking: zero-valued flags are always considered - to be contained:: +- membership / containment checking has changed slightly -- zero-valued flags + are never considered to be contained:: >>> Color.BLACK in Color.WHITE - True + False - otherwise, only if all bits of one flag are in the other flag will True - be returned:: + otherwise, if all bits of one flag are in the other flag, True is returned:: >>> Color.PURPLE in Color.WHITE True - >>> Color.GREEN in Color.PURPLE - False - There is a new boundary mechanism that controls how out-of-range / invalid bits are handled: ``STRICT``, ``CONFORM``, ``EJECT``, and ``KEEP``: @@ -1172,7 +1181,7 @@ Using :class:`auto` would look like:: ... GREEN = auto() ... >>> Color.GREEN - <Color.GREEN: 3> + <Color.GREEN> Using :class:`object` @@ -1185,24 +1194,10 @@ Using :class:`object` would look like:: ... GREEN = object() ... BLUE = object() ... - >>> Color.GREEN # doctest: +SKIP - <Color.GREEN: <object object at 0x...>> - -This is also a good example of why you might want to write your own -:meth:`__repr__`:: - - >>> class Color(Enum): - ... RED = object() - ... GREEN = object() - ... BLUE = object() - ... def __repr__(self): - ... return "<%s.%s>" % (self.__class__.__name__, self._name_) - ... >>> Color.GREEN <Color.GREEN> - Using a descriptive string """""""""""""""""""""""""" @@ -1214,7 +1209,9 @@ Using a string as the value would look like:: ... BLUE = 'too fast!' ... >>> Color.GREEN - <Color.GREEN: 'go'> + <Color.GREEN> + >>> Color.GREEN.value + 'go' Using a custom :meth:`__new__` @@ -1235,7 +1232,9 @@ Using an auto-numbering :meth:`__new__` would look like:: ... BLUE = () ... >>> Color.GREEN - <Color.GREEN: 2> + <Color.GREEN> + >>> Color.GREEN.value + 2 To make a more general purpose ``AutoNumber``, add ``*args`` to the signature:: @@ -1258,7 +1257,7 @@ to handle any extra arguments:: ... BLEACHED_CORAL = () # New color, no Pantone code yet! ... >>> Swatch.SEA_GREEN - <Swatch.SEA_GREEN: 2> + <Swatch.SEA_GREEN> >>> Swatch.SEA_GREEN.pantone '1246' >>> Swatch.BLEACHED_CORAL.pantone @@ -1385,9 +1384,30 @@ An example to show the :attr:`_ignore_` attribute in use:: ... Period['day_%d' % i] = i ... >>> list(Period)[:2] - [<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>] + [Period.day_0, Period.day_1] >>> list(Period)[-2:] - [<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>] + [Period.day_365, Period.day_366] + + +Conforming input to Flag +^^^^^^^^^^^^^^^^^^^^^^^^ + +To create a :class:`Flag` enum that is more resilient to out-of-bounds results +from mathematical operations, you can use the :attr:`FlagBoundary.CONFORM` +setting:: + + >>> from enum import Flag, CONFORM, auto + >>> class Weekday(Flag, boundary=CONFORM): + ... MONDAY = auto() + ... TUESDAY = auto() + ... WEDNESDAY = auto() + ... THURSDAY = auto() + ... FRIDAY = auto() + ... SATURDAY = auto() + ... SUNDAY = auto() + >>> today = Weekday.TUESDAY + >>> Weekday(today + 22) # what day is three weeks from tomorrow? + >>> Weekday.WEDNESDAY .. _enumtype-examples: diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 906c60b..8bb19dc 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -31,7 +31,7 @@ An enumeration: * uses *call* syntax to return members by value * uses *index* syntax to return members by name -Enumerations are created either by using :keyword:`class` syntax, or by +Enumerations are created either by using the :keyword:`class` syntax, or by using function-call syntax:: >>> from enum import Enum @@ -45,7 +45,7 @@ using function-call syntax:: >>> # functional syntax >>> Color = Enum('Color', ['RED', 'GREEN', 'BLUE']) -Even though we can use :keyword:`class` syntax to create Enums, Enums +Even though we can use the :keyword:`class` syntax to create Enums, Enums are not normal Python classes. See :ref:`How are Enums different? <enum-class-differences>` for more details. @@ -53,7 +53,7 @@ are not normal Python classes. See - The class :class:`Color` is an *enumeration* (or *enum*) - The attributes :attr:`Color.RED`, :attr:`Color.GREEN`, etc., are - *enumeration members* (or *members*) and are functionally constants. + *enumeration members* (or *enum members*) and are functionally constants. - The enum members have *names* and *values* (the name of :attr:`Color.RED` is ``RED``, the value of :attr:`Color.BLUE` is ``3``, etc.) @@ -110,10 +110,15 @@ Module Contents :class:`StrEnum` defaults to the lower-cased version of the member name, while other Enums default to 1 and increase from there. - :func:`property` + :func:`global_enum` + + :class:`Enum` class decorator to apply the appropriate global `__repr__`, + and export its members into the global name space. + + :func:`.property` Allows :class:`Enum` members to have attributes without conflicting with - member names. + other members' names. :func:`unique` @@ -126,7 +131,7 @@ Module Contents .. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto`` -.. versionadded:: 3.11 ``StrEnum``, ``EnumCheck``, ``FlagBoundary``, ``property`` +.. versionadded:: 3.11 ``StrEnum``, ``EnumCheck``, ``FlagBoundary`` --------------- @@ -140,11 +145,6 @@ Data Types to subclass *EnumType* -- see :ref:`Subclassing EnumType <enumtype-examples>` for details. - *EnumType* is responsible for setting the correct :meth:`__repr__`, - :meth:`__str__`, :meth:`__format__`, and :meth:`__reduce__` methods on the - final *enum*, as well as creating the enum members, properly handling - duplicates, providing iteration over the enum class, etc. - .. method:: EnumType.__contains__(cls, member) Returns ``True`` if member belongs to the ``cls``:: @@ -162,31 +162,32 @@ Data Types .. method:: EnumType.__dir__(cls) Returns ``['__class__', '__doc__', '__members__', '__module__']`` and the - names of the members in *cls*:: + names of the members in ``cls``. User-defined methods and methods from + mixin classes will also be included:: >>> dir(Color) - ['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__'] + ['BLUE', 'GREEN', 'RED', '__class__', '__doc__', '__members__', '__module__'] .. method:: EnumType.__getattr__(cls, name) Returns the Enum member in *cls* matching *name*, or raises an :exc:`AttributeError`:: >>> Color.GREEN - <Color.GREEN: 2> + Color.GREEN .. method:: EnumType.__getitem__(cls, name) - Returns the Enum member in *cls* matching *name*, or raises an :exc:`KeyError`:: + Returns the Enum member in *cls* matching *name*, or raises a :exc:`KeyError`:: >>> Color['BLUE'] - <Color.BLUE: 3> + Color.BLUE .. method:: EnumType.__iter__(cls) Returns each member in *cls* in definition order:: >>> list(Color) - [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>] + [Color.RED, Color.GREEN, Color.BLUE] .. method:: EnumType.__len__(cls) @@ -200,7 +201,7 @@ Data Types Returns each member in *cls* in reverse definition order:: >>> list(reversed(Color)) - [<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>] + [Color.BLUE, Color.GREEN, Color.RED] .. class:: Enum @@ -231,7 +232,7 @@ Data Types .. attribute:: Enum._ignore_ ``_ignore_`` is only used during creation and is removed from the - enumeration once creation is complete. + enumeration once that is complete. ``_ignore_`` is a list of names that will not become members, and whose names will also be removed from the completed enumeration. See @@ -260,7 +261,7 @@ Data Types .. method:: Enum.__dir__(self) Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and - any public methods defined on *self.__class__*:: + any public methods defined on ``self.__class__`` or a mixin class:: >>> from datetime import date >>> class Weekday(Enum): @@ -275,7 +276,7 @@ Data Types ... def today(cls): ... print('today is %s' % cls(date.today().isoweekday()).name) >>> dir(Weekday.SATURDAY) - ['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value'] + ['__class__', '__doc__', '__module__', 'name', 'today', 'value'] .. method:: Enum._generate_next_value_(name, start, count, last_values) @@ -297,11 +298,6 @@ Data Types >>> PowersOfThree.SECOND.value 6 - .. method:: Enum.__init_subclass__(cls, \**kwds) - - A *classmethod* that is used to further configure subsequent subclasses. - By default, does nothing. - .. method:: Enum._missing_(cls, value) A *classmethod* for looking up values not found in *cls*. By default it @@ -321,55 +317,42 @@ Data Types >>> Build.DEBUG.value 'debug' >>> Build('deBUG') - <Build.DEBUG: 'debug'> + Build.DEBUG .. method:: Enum.__repr__(self) Returns the string used for *repr()* calls. By default, returns the - *Enum* name, member name, and value, but can be overridden:: + *Enum* name and the member name, but can be overridden:: - >>> class OtherStyle(Enum): - ... ALTERNATE = auto() - ... OTHER = auto() - ... SOMETHING_ELSE = auto() + >>> class OldStyle(Enum): + ... RETRO = auto() + ... OLD_SCHOOl = auto() + ... YESTERYEAR = 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') + ... return f'<{cls_name}.{self.name}: {self.value}>' + >>> OldStyle.RETRO + <OldStyle.RETRO: 1> .. method:: Enum.__str__(self) Returns the string used for *str()* calls. By default, returns the - *Enum* name and member name, but can be overridden:: + member name, but can be overridden:: - >>> class OtherStyle(Enum): - ... ALTERNATE = auto() - ... OTHER = auto() - ... SOMETHING_ELSE = auto() + >>> class OldStyle(Enum): + ... RETRO = auto() + ... OLD_SCHOOl = auto() + ... YESTERYEAR = auto() ... def __str__(self): - ... return f'{self.name}' - >>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"{OtherStyle.ALTERNATE}" - (<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE') - - .. method:: Enum.__format__(self) - - Returns the string used for *format()* and *f-string* calls. By default, - returns :meth:`__str__` returns, but can be overridden:: - - >>> 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') + ... cls_name = self.__class__.__name__ + ... return f'{cls_name}.{self.name}' + >>> OldStyle.RETRO + OldStyle.RETRO - .. note:: +.. note:: - Using :class:`auto` with :class:`Enum` results in integers of increasing value, - starting with ``1``. + Using :class:`auto` with :class:`Enum` results in integers of increasing value, + starting with ``1``. .. class:: IntEnum @@ -384,7 +367,7 @@ Data Types ... TWO = 2 ... THREE = 3 >>> Numbers.THREE - <Numbers.THREE: 3> + Numbers.THREE >>> Numbers.ONE + Numbers.TWO 3 >>> Numbers.THREE + 5 @@ -392,14 +375,10 @@ Data Types >>> Numbers.THREE == 3 True - .. note:: +.. note:: - Using :class:`auto` with :class:`IntEnum` results in integers of increasing - value, starting with ``1``. - - .. versionchanged:: 3.11 :meth:`__str__` is now :func:`int.__str__` to - better support the *replacement of existing constants* use-case. - :meth:`__format__` was already :func:`int.__format__` for that same reason. + Using :class:`auto` with :class:`IntEnum` results in integers of increasing value, + starting with ``1``. .. class:: StrEnum @@ -413,16 +392,13 @@ Data Types instead of ``isinstance(str, unknown)``), and in those locations you will need to use ``str(StrEnum.member)``. - .. note:: - Using :class:`auto` with :class:`StrEnum` results in the lower-cased member - name as the value. +.. note:: - .. note:: :meth:`__str__` is :func:`str.__str__` to better support the - *replacement of existing constants* use-case. :meth:`__format__` is likewise - :func:`int.__format__` for that same reason. + Using :class:`auto` with :class:`StrEnum` results in values of the member name, + lower-cased. - .. versionadded:: 3.11 +.. versionadded:: 3.11 .. class:: Flag @@ -455,9 +431,9 @@ Data Types Returns all contained members:: >>> list(Color.RED) - [<Color.RED: 1>] + [Color.RED] >>> list(purple) - [<Color.RED: 1>, <Color.BLUE: 4>] + [Color.RED, Color.BLUE] .. method:: __len__(self): @@ -485,52 +461,42 @@ Data Types Returns current flag binary or'ed with other:: >>> Color.RED | Color.GREEN - <Color.RED|GREEN: 3> + Color.RED|Color.GREEN .. method:: __and__(self, other) Returns current flag binary and'ed with other:: >>> purple & white - <Color.RED|BLUE: 5> + Color.RED|Color.BLUE >>> purple & Color.GREEN - <Color: 0> + 0x0 .. method:: __xor__(self, other) Returns current flag binary xor'ed with other:: >>> purple ^ white - <Color.GREEN: 2> + Color.GREEN >>> purple ^ Color.GREEN - <Color.RED|GREEN|BLUE: 7> + Color.RED|Color.GREEN|Color.BLUE .. method:: __invert__(self): Returns all the flags in *type(self)* that are not in self:: >>> ~white - <Color: 0> + 0x0 >>> ~purple - <Color.GREEN: 2> + Color.GREEN >>> ~Color.RED - <Color.GREEN|BLUE: 6> - - .. method:: _numeric_repr_ - - Function used to format any remaining unnamed numeric values. Default is - the value's repr; common choices are :func:`hex` and :func:`oct`. - - .. note:: + Color.GREEN|Color.BLUE - Using :class:`auto` with :class:`Flag` results in integers that are powers - of two, starting with ``1``. +.. note:: - .. versionchanged:: 3.11 The *repr()* of zero-valued flags has changed. It - is now:: + Using :class:`auto` with :class:`Flag` results in integers that are powers + of two, starting with ``1``. - >>> Color(0) - <Color: 0> .. class:: IntFlag @@ -543,9 +509,9 @@ Data Types ... GREEN = auto() ... BLUE = auto() >>> Color.RED & 2 - <Color: 0> + 0x0 >>> Color.RED | 2 - <Color.RED|GREEN: 3> + Color.RED|Color.GREEN If any integer operation is performed with an *IntFlag* member, the result is not an *IntFlag*:: @@ -558,25 +524,15 @@ Data Types * the result is a valid *IntFlag*: an *IntFlag* is returned * the result is not a valid *IntFlag*: the result depends on the *FlagBoundary* setting - The *repr()* of unnamed zero-valued flags has changed. It is now: - - >>> Color(0) - <Color: 0> - - .. note:: - - Using :class:`auto` with :class:`IntFlag` results in integers that are powers - of two, starting with ``1``. - - .. versionchanged:: 3.11 :meth:`__str__` is now :func:`int.__str__` to - better support the *replacement of existing constants* use-case. - :meth:`__format__` was already :func:`int.__format__` for that same reason. +.. note:: + Using :class:`auto` with :class:`IntFlag` results in integers that are powers + of two, starting with ``1``. .. class:: EnumCheck *EnumCheck* contains the options used by the :func:`verify` decorator to ensure - various constraints; failed constraints result in a :exc:`ValueError`. + various constraints; failed constraints result in a :exc:`TypeError`. .. attribute:: UNIQUE @@ -626,11 +582,11 @@ Data Types ... ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details] - .. note:: +.. note:: - CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members. + CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members. - .. versionadded:: 3.11 +.. versionadded:: 3.11 .. class:: FlagBoundary @@ -650,7 +606,7 @@ Data Types >>> StrictFlag(2**2 + 2**4) Traceback (most recent call last): ... - ValueError: <flag 'StrictFlag'> invalid value 20 + ValueError: StrictFlag: invalid value: 20 given 0b0 10100 allowed 0b0 00111 @@ -665,7 +621,7 @@ Data Types ... GREEN = auto() ... BLUE = auto() >>> ConformFlag(2**2 + 2**4) - <ConformFlag.BLUE: 4> + ConformFlag.BLUE .. attribute:: EJECT @@ -691,52 +647,12 @@ Data Types ... GREEN = auto() ... BLUE = auto() >>> KeepFlag(2**2 + 2**4) - <KeepFlag.BLUE|16: 20> + KeepFlag.BLUE|0x10 .. versionadded:: 3.11 --------------- -Supported ``__dunder__`` names -"""""""""""""""""""""""""""""" - -:attr:`__members__` is a read-only ordered mapping of ``member_name``:``member`` -items. It is only available on the class. - -:meth:`__new__`, if specified, must create and return the enum members; it is -also a very good idea to set the member's :attr:`_value_` appropriately. Once -all the members are created it is no longer used. - - -Supported ``_sunder_`` names -"""""""""""""""""""""""""""" - -- ``_name_`` -- name of the member -- ``_value_`` -- value of the member; can be set / modified in ``__new__`` - -- ``_missing_`` -- a lookup function used when a value is not found; may be - overridden -- ``_ignore_`` -- a list of names, either as a :class:`list` or a :class:`str`, - that will not be transformed into members, and will be removed from the final - class -- ``_order_`` -- used in Python 2/3 code to ensure member order is consistent - (class attribute, removed during class creation) -- ``_generate_next_value_`` -- used to get an appropriate value for an enum - member; may be overridden - - .. note:: - - For standard :class:`Enum` classes the next value chosen is the last value seen - incremented by one. - - For :class:`Flag` classes the next value chosen will be the next highest - power-of-two, regardless of the last value seen. - -.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_`` -.. versionadded:: 3.7 ``_ignore_`` - ---------------- - Utilities and Decorators ------------------------ @@ -752,6 +668,15 @@ Utilities and Decorators ``_generate_next_value_`` can be overridden to customize the values used by *auto*. +.. decorator:: global_enum + + A :keyword:`class` decorator specifically for enumerations. It replaces the + :meth:`__repr__` method with one that shows *module_name*.*member_name*. It + also injects the members, and their aliases, into the global namespace they + were defined in. + +.. versionadded:: 3.11 + .. decorator:: property A decorator similar to the built-in *property*, but specifically for @@ -763,7 +688,7 @@ Utilities and Decorators *Enum* class, and *Enum* subclasses can define members with the names ``value`` and ``name``. - .. versionadded:: 3.11 +.. versionadded:: 3.11 .. decorator:: unique @@ -789,7 +714,7 @@ Utilities and Decorators :class:`EnumCheck` are used to specify which constraints should be checked on the decorated enumeration. - .. versionadded:: 3.11 +.. versionadded:: 3.11 --------------- @@ -801,20 +726,14 @@ Notes These three enum types are designed to be drop-in replacements for existing integer- and string-based values; as such, they have extra limitations: - - ``__str__`` uses the value and not the name of the enum member + - ``format()`` will use the value of the enum member, unless ``__str__`` + has been overridden - - ``__format__``, because it uses ``__str__``, will also use the value of - the enum member instead of its name + - ``StrEnum.__str__`` uses the value and not the name of the enum member - If you do not need/want those limitations, you can either create your own - base class by mixing in the ``int`` or ``str`` type yourself:: + If you do not need/want those limitations, you can create your own base + class by mixing in the ``int`` or ``str`` type yourself:: >>> from enum import Enum >>> class MyIntEnum(int, Enum): ... pass - - or you can reassign the appropriate :meth:`str`, etc., in your enum:: - - >>> from enum import IntEnum - >>> class MyIntEnum(IntEnum): - ... __str__ = IntEnum.__str__ diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 4d8488a..eb33d7e 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -2070,7 +2070,7 @@ to speed up repeated connections from the same clients. :attr:`SSLContext.verify_flags` returns :class:`VerifyFlags` flags: >>> ssl.create_default_context().verify_flags # doctest: +SKIP - <VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768> + ssl.VERIFY_X509_TRUSTED_FIRST .. attribute:: SSLContext.verify_mode @@ -2082,7 +2082,7 @@ to speed up repeated connections from the same clients. :attr:`SSLContext.verify_mode` returns :class:`VerifyMode` enum: >>> ssl.create_default_context().verify_mode - <VerifyMode.CERT_REQUIRED: 2> + ssl.CERT_REQUIRED .. index:: single: certificates |