__init_subclass__ method is called after __new__ and __init__ methods in Enum classes

[espdev]

Bug report

Bug description:

Hello,

The documentation says:

__init_subclass__(cls, **kwds)
A classmethod that is used to further configure subsequent subclasses. By default, does nothing.

This would be useful for configuring Enum subclasses and enum members, but it doesn't work as I expected. This method is called after the __new__ or __init__ methods are called, which makes it practically useless for Enum classes.

Even if this is expected behavior, there are questions:

1. The documentation does not mention this, or it is written too vaguely (used to further configure).
2. This contradicts how this method works in normal classes. It is clear that in normal classes, the __new__ and __init__ methods are called when instances are created, and in this respect their behavior also differs from Enum classes. However, the order of __init_subclass__ method calls in Enum classes still does not seem logical.

Here is a minimal example what I mean:

from enum import Enum

class Foo(Enum):
    def __init_subclass__(cls, /, **kwargs):
        super().__init_subclass__(**kwargs)
        print('222:', cls)
        
    def __init__(self, value):
        print('111:', value)

class Bar(Foo):
    a = 1
    b = 2

For this code, we get:

111: 1
111: 2
222: <enum 'Bar'>

Therefore, I cannot use __init_subclass__ method before the Enum class and its members are configured.

For example, I would like to do something like that:

class Foo(Enum):
    def __init_subclass__(cls, /, prefix, **kwargs):
        super().__init_subclass__(**kwargs)
        cls._prefix = prefix
        
    def __init__(self, value):
        self._value_ = f'{type(self)._prefix}{value}'

class Bar(Foo, prefix='bar/'):
    a = 'a'
    b = 'b'

print(Bar.a)
<Bar.a: 'bar/a'>
print(Bar.a.value)
'bar/a'

I am currently implementing similar logic through nonmember.

CPython versions tested on:

3.13

Operating systems tested on:

No response

[picnixz]

cc @ethanfurman

[johnslavik]

The documentation would definitely benefit from an example usage of __init_subclass__. CC @ZeroIntensity (mentorship), I'd add a docs label as well.

[ZeroIntensity]

Let's make a new issue for the documentation.

[ethanfurman]

Enum classes are not normal classes. Enum members are both attributes of the class, and instances of the class. To make that happen, the members are created when the class is created, which means that __new__ and __init__ will be called once for each member as it is created.

When __init_subclass__ is called, the class it receives should be finished -- i.e. all methods defined, all data structures defined, etc. In the case of an enum, that also means all members defined.

Here are some valid uses of __init_subclass__ for an enum:

• add validation
• share enums between Python and another language
• add dynamic data structures based on members

---

NB: Ignore the following -- I confused myself.

The way you are modifying _value_ will result in an inconsistent member:

print(Bar.a)
<Bar.a: 'bar/a'>
print(Bar.a.value)
'bar/a'

but

Bar['bar/a']

will result in a ValueError.

[espdev]

@ethanfurman
Thank you for the explanation. In any case, it seems to me that the documentation is not complete enough. Your add validation example seems like a good candidate for inclusion in the documentation.

---

NB: The way you are modifying value will result in an inconsistent member:

Yes, I know. We will get the same state even if we use the __new__ method:

class Foo(StrEnum):
    def __new__(cls, value):
        new_value = f'bar/{value}'
        obj = str.__new__(cls, new_value)
        obj._value_ = new_value
        return obj

class Bar(Foo):
    a = 'a'
    b = 'b'

Bar['bar/a']
KeyError

It seems that this only does not work with __getitem__, because, for example, __contains__ works correctly:

'a' in Bar
False

'bar/a' in Bar
True

[ethanfurman]

Ignore my inconsistent comment -- I confused myself.

Bar['a'] (a name lookup) gives Bar.a, and
Bar('bar/a') (a value lookup) gives Bar.a -- which is how it's supposed to work.