diff options
| author | Ethan Furman <ethan@stoneleaf.us> | 2023-08-31 19:45:12 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-08-31 19:45:12 (GMT) |
| commit | d48760b2f1e28dd3c1a35721939f400a8ab619b8 (patch) | |
| tree | cf8dbe4f3bf0019e5359918e92fee16827a6b93a /Doc/howto | |
| parent | 13a00078b81776b23b0b6add69b848382240d1f2 (diff) | |
| download | cpython-d48760b2f1e28dd3c1a35721939f400a8ab619b8.zip cpython-d48760b2f1e28dd3c1a35721939f400a8ab619b8.tar.gz cpython-d48760b2f1e28dd3c1a35721939f400a8ab619b8.tar.bz2 | |
gh-108682: [Enum] raise TypeError if super().__new__ called in custom __new__ (GH-108704)
When overriding the `__new__` method of an enum, the underlying data type should be created directly; i.e. .
member = object.__new__(cls)
member = int.__new__(cls, value)
member = str.__new__(cls, value)
Calling `super().__new__()` finds the lookup version of `Enum.__new__`, and will now raise an exception when detected.
Diffstat (limited to 'Doc/howto')
| -rw-r--r-- | Doc/howto/enum.rst | 23 |
1 files changed, 22 insertions, 1 deletions
diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index 4312b4c..2874975 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -426,10 +426,17 @@ enumeration, with the exception of special methods (:meth:`__str__`, :meth:`__add__`, etc.), descriptors (methods are also descriptors), and variable names listed in :attr:`_ignore_`. -Note: if your enumeration defines :meth:`__new__` and/or :meth:`__init__` then +Note: if your enumeration defines :meth:`__new__` and/or :meth:`__init__`, any value(s) given to the enum member will be passed into those methods. See `Planet`_ for an example. +.. note:: + + The :meth:`__new__` method, if defined, is used during creation of the Enum + members; it is then replaced by Enum's :meth:`__new__` which is used after + class creation for lookup of existing members. See :ref:`new-vs-init` for + more details. + Restricted Enum subclassing --------------------------- @@ -895,6 +902,8 @@ Some rules: :meth:`__str__` method has been reset to their data types' :meth:`__str__` method. +.. _new-vs-init: + When to use :meth:`__new__` vs. :meth:`__init__` ------------------------------------------------ @@ -927,6 +936,11 @@ want one of them to be the value:: >>> print(Coordinate(3)) Coordinate.VY +.. warning:: + + *Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the one + that is found; instead, use the data type directly. + Finer Points ^^^^^^^^^^^^ @@ -1353,6 +1367,13 @@ to handle any extra arguments:: members; it is then replaced by Enum's :meth:`__new__` which is used after class creation for lookup of existing members. +.. warning:: + + *Do not* call ``super().__new__()``, as the lookup-only ``__new__`` is the one + that is found; instead, use the data type directly -- e.g.:: + + obj = int.__new__(cls, value) + OrderedEnum ^^^^^^^^^^^ |