Add EnumMeta.__new__ & EnumMeta.__call__ (#6572)

stdlib/enum.pyi

@@ -2,17 +2,49 @@ import sys
 import types
 from abc import ABCMeta
 from builtins import property as _builtins_property
-from typing import Any, Iterator, Type, TypeVar
+from collections.abc import Iterable, Iterator, Mapping
+from typing import Any, Dict, Tuple, Type, TypeVar, Union, overload
 
 _T = TypeVar("_T")
 _S = TypeVar("_S", bound=Type[Enum])
 
+# The following all work:
+# >>> from enum import Enum
+# >>> from string import ascii_lowercase
+# >>> Enum('Foo', names='RED YELLOW GREEN')
+# <enum 'Foo'>
+# >>> Enum('Foo', names=[('RED', 1), ('YELLOW, 2)])
+# <enum 'Foo'>
+# >>> Enum('Foo', names=((x for x in (ascii_lowercase[i], i)) for i in range(5)))
+# <enum 'Foo'>
+# >>> Enum('Foo', names={'RED': 1, 'YELLOW': 2})
+# <enum 'Foo'>
+_EnumNames = Union[str, Iterable[str], Iterable[Iterable[Union[str, Any]]], Mapping[str, Any]]
+
+class _EnumDict(Dict[str, Any]):
+    def __init__(self) -> None: ...
+
 # Note: EnumMeta actually subclasses type directly, not ABCMeta.
 # This is a temporary workaround to allow multiple creation of enums with builtins
 # such as str as mixins, which due to the handling of ABCs of builtin types, cause
 # spurious inconsistent metaclass structure. See #1595.
 # Structurally: Iterable[T], Reversible[T], Container[T] where T is the enum itself
 class EnumMeta(ABCMeta):
+    if sys.version_info >= (3, 11):
+        def __new__(
+            metacls: Type[_T],
+            cls: str,
+            bases: Tuple[type, ...],
+            classdict: _EnumDict,
+            *,
+            boundary: FlagBoundary | None = ...,
+            _simple: bool = ...,
+            **kwds: Any,
+        ) -> _T: ...
+    elif sys.version_info >= (3, 9):
+        def __new__(metacls: Type[_T], cls: str, bases: Tuple[type, ...], classdict: _EnumDict, **kwds: Any) -> _T: ...  # type: ignore
+    else:
+        def __new__(metacls: Type[_T], cls: str, bases: Tuple[type, ...], classdict: _EnumDict) -> _T: ...  # type: ignore
     def __iter__(self: Type[_T]) -> Iterator[_T]: ...
     def __reversed__(self: Type[_T]) -> Iterator[_T]: ...
     def __contains__(self: Type[Any], member: object) -> bool: ...
@@ -20,6 +52,37 @@ class EnumMeta(ABCMeta):
     @_builtins_property
     def __members__(self: Type[_T]) -> types.MappingProxyType[str, _T]: ...
     def __len__(self) -> int: ...
+    if sys.version_info >= (3, 11):
+        # Simple value lookup
+        @overload  # type: ignore[override]
+        def __call__(cls: Type[_T], value: Any, names: None = ...) -> _T: ...
+        # Functional Enum API
+        @overload
+        def __call__(
+            cls,
+            value: str,
+            names: _EnumNames,
+            *,
+            module: str | None = ...,
+            qualname: str | None = ...,
+            type: type | None = ...,
+            start: int = ...,
+            boundary: FlagBoundary | None = ...,
+        ) -> Type[Enum]: ...
+    else:
+        @overload  # type: ignore[override]
+        def __call__(cls: Type[_T], value: Any, names: None = ...) -> _T: ...
+        @overload
+        def __call__(
+            cls,
+            value: str,
+            names: _EnumNames,
+            *,
+            module: str | None = ...,
+            qualname: str | None = ...,
+            type: type | None = ...,
+            start: int = ...,
+        ) -> Type[Enum]: ...
     _member_names_: list[str]  # undocumented
     _member_map_: dict[str, Enum]  # undocumented
     _value2member_map_: dict[Any, Enum]  # undocumented

tests/stubtest_allowlists/py3_common.txt

@@ -83,8 +83,6 @@ distutils.command.bdist_packager  # It exists in docs as package name but not in
 distutils.version.Version._cmp  # class should have declared this
 distutils.version.Version.parse  # class should have declared this
 email.headerregistry.BaseHeader.max_count  # docs say subclasses should have this property
-enum.EnumMeta.__call__
-enum.EnumMeta.__new__
 http.HTTPStatus.description  # set in __new__
 http.HTTPStatus.phrase  # set in __new__
 http.client.HTTPConnection.response_class  # the actual type at runtime is abc.ABCMeta