From 31d4b1ef7317e63d426744011b5b3ffd67a0dcd3 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Wed, 18 Jan 2023 11:27:39 +0300 Subject: [PATCH 1/4] gh-101100: Fix sphinx warnings in `enum` module --- Doc/library/enum.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index b9cc802e752eb0..6ae3f2e795dc94 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -52,11 +52,11 @@ are not normal Python classes. See .. note:: Nomenclature - - The class :class:`Color` is an *enumeration* (or *enum*) - - The attributes :attr:`Color.RED`, :attr:`Color.GREEN`, etc., are + - The class ``Color`` is an *enumeration* (or *enum*) + - The attributes ``Color.RED``, ``Color.GREEN``, etc., are *enumeration members* (or *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 + ``Color.RED`` is ``RED``, the value of ``Color.BLUE`` is ``3``, etc.) --------------- @@ -165,8 +165,8 @@ Data Types to subclass *EnumType* -- see :ref:`Subclassing EnumType ` for details. - *EnumType* is responsible for setting the correct :meth:`__repr__`, - :meth:`__str__`, :meth:`__format__`, and :meth:`__reduce__` methods on the + *EnumType* is responsible for setting the correct *__repr__*, + *__str__*, *__format__*, and *__reduce__* methods on the final *enum*, as well as creating the enum members, properly handling duplicates, providing iteration over the enum class, etc. @@ -424,9 +424,9 @@ Data Types 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 + .. versionchanged:: 3.11 *__str__* is now ``int.__str__`` to better support the *replacement of existing constants* use-case. - :meth:`__format__` was already :func:`int.__format__` for that same reason. + *__format__* was already ``int.__format__`` for that same reason. .. class:: StrEnum @@ -761,11 +761,11 @@ Data Types Supported ``__dunder__`` names """""""""""""""""""""""""""""" -:attr:`__members__` is a read-only ordered mapping of ``member_name``:``member`` +:attr:`!EnumType.__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 +``__new__``, if specified, must create and return the enum members; it is +also a very good idea to set the member's ``_value_`` appropriately. Once all the members are created it is no longer used. @@ -804,7 +804,7 @@ Utilities and Decorators .. class:: auto *auto* can be used in place of a value. If used, the *Enum* machinery will - call an *Enum*'s :meth:`_generate_next_value_` to get an appropriate value. + call an *Enum*'s :meth:`!Enum._generate_next_value_` to get an appropriate value. For *Enum* and *IntEnum* that appropriate value will be the last value plus one; for *Flag* and *IntFlag* it will be the first power-of-two greater than the highest value; for *StrEnum* it will be the lower-cased version of @@ -847,7 +847,7 @@ Utilities and Decorators .. decorator:: unique A :keyword:`class` decorator specifically for enumerations. It searches an - enumeration's :attr:`__members__`, gathering any aliases it finds; if any are + enumeration's :attr:`!EnumType.__members__`, gathering any aliases it finds; if any are found :exc:`ValueError` is raised with the details:: >>> from enum import Enum, unique From 52eb7987e74b6241841ff75948f0dd9e4b7df92c Mon Sep 17 00:00:00 2001 From: sobolevn Date: Thu, 19 Jan 2023 10:04:11 +0300 Subject: [PATCH 2/4] Address review --- Doc/library/enum.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 6ae3f2e795dc94..99d04e9c297072 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -52,11 +52,11 @@ are not normal Python classes. See .. note:: Nomenclature - - The class ``Color`` is an *enumeration* (or *enum*) - - The attributes ``Color.RED``, ``Color.GREEN``, etc., are + - The class :class:`!Color` (or *enum*) + - The attributes :attr:`!Color.RED`, :attr:`!Color.GREEN`, etc., are *enumeration members* (or *members*) and are functionally constants. - The enum members have *names* and *values* (the name of - ``Color.RED`` is ``RED``, the value of ``Color.BLUE`` is + :attr:`!Color.RED` is ``RED``, the value of :attr:`!Color.BLUE` is ``3``, etc.) --------------- @@ -165,8 +165,8 @@ Data Types to subclass *EnumType* -- see :ref:`Subclassing EnumType ` for details. - *EnumType* is responsible for setting the correct *__repr__*, - *__str__*, *__format__*, and *__reduce__* methods on the + *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. @@ -424,9 +424,9 @@ Data Types Using :class:`auto` with :class:`IntEnum` results in integers of increasing value, starting with ``1``. - .. versionchanged:: 3.11 *__str__* is now ``int.__str__`` to + .. versionchanged:: 3.11 :meth:`!__str__` is now :meth:`!int.__str__` to better support the *replacement of existing constants* use-case. - *__format__* was already ``int.__format__`` for that same reason. + :meth:`!__format__` was already :meth:`!int.__format__` for that same reason. .. class:: StrEnum @@ -761,11 +761,11 @@ Data Types Supported ``__dunder__`` names """""""""""""""""""""""""""""" -:attr:`!EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member`` +:attr:`!__members__` is a read-only ordered mapping of ``member_name``:``member`` items. It is only available on the class. -``__new__``, if specified, must create and return the enum members; it is -also a very good idea to set the member's ``_value_`` appropriately. Once +: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. @@ -804,7 +804,7 @@ Utilities and Decorators .. class:: auto *auto* can be used in place of a value. If used, the *Enum* machinery will - call an *Enum*'s :meth:`!Enum._generate_next_value_` to get an appropriate value. + call an *Enum*'s :meth:`~Enum._generate_next_value_` to get an appropriate value. For *Enum* and *IntEnum* that appropriate value will be the last value plus one; for *Flag* and *IntFlag* it will be the first power-of-two greater than the highest value; for *StrEnum* it will be the lower-cased version of @@ -847,7 +847,7 @@ Utilities and Decorators .. decorator:: unique A :keyword:`class` decorator specifically for enumerations. It searches an - enumeration's :attr:`!EnumType.__members__`, gathering any aliases it finds; if any are + enumeration's :attr:`!__members__`, gathering any aliases it finds; if any are found :exc:`ValueError` is raised with the details:: >>> from enum import Enum, unique From 440385f64c6977571f8cf22a758dcd8af44f7123 Mon Sep 17 00:00:00 2001 From: Ethan Furman Date: Thu, 19 Jan 2023 18:07:43 -0800 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/enum.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 99d04e9c297072..dc5337dd071c04 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -424,9 +424,9 @@ Data Types Using :class:`auto` with :class:`IntEnum` results in integers of increasing value, starting with ``1``. - .. versionchanged:: 3.11 :meth:`!__str__` is now :meth:`!int.__str__` to + .. versionchanged:: 3.11 :meth:`~object.__str__` is now :meth:`!int.__str__` to better support the *replacement of existing constants* use-case. - :meth:`!__format__` was already :meth:`!int.__format__` for that same reason. + :meth:`~object.__format__` was already :meth:`!int.__format__` for that same reason. .. class:: StrEnum @@ -761,10 +761,10 @@ Data Types Supported ``__dunder__`` names """""""""""""""""""""""""""""" -:attr:`!__members__` is a read-only ordered mapping of ``member_name``:``member`` +:attr:`~EnumType.__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 +:meth:`~object.__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. @@ -847,7 +847,7 @@ Utilities and Decorators .. decorator:: unique A :keyword:`class` decorator specifically for enumerations. It searches an - enumeration's :attr:`!__members__`, gathering any aliases it finds; if any are + enumeration's :attr:`~EnumType.__members__`, gathering any aliases it finds; if any are found :exc:`ValueError` is raised with the details:: >>> from enum import Enum, unique From 8f5716e3a0ca6514abe4573aab13e17e206911f9 Mon Sep 17 00:00:00 2001 From: Ethan Furman Date: Thu, 19 Jan 2023 18:08:05 -0800 Subject: [PATCH 4/4] Update Doc/library/enum.rst Co-authored-by: C.A.M. Gerlach --- Doc/library/enum.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index dc5337dd071c04..cfe4fbeb0698e7 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -52,7 +52,7 @@ are not normal Python classes. See .. note:: Nomenclature - - The class :class:`!Color` (or *enum*) + - 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. - The enum members have *names* and *values* (the name of