@@ -3,6 +3,8 @@ Constructors
33
44Calls to constructors require special handling within type checkers.
55
6+ .. _`constructor-calls` :
7+
68Constructor Calls
79-----------------
810
@@ -488,3 +490,289 @@ callable.
488490 def __init__[V](self, x: T, y: list[V], z: V) -> None: ...
489491
490492 reveal_type(accepts_callable(MyClass)) # ``def [T, V] (x: T, y: list[V], z: V) -> MyClass[T]``
493+
494+
495+ Metaclass Constructors
496+ ----------------------
497+
498+ A class object is itself an instance of its :term: `python:metaclass `, so the
499+ creation of a class is also a constructor call, one made on the metaclass. While
500+ the sections above describe how a metaclass participates in the construction of
501+ *instances * of a class, the following sections describe the construction of class objects
502+ themselves.
503+
504+ A metaclass constructor is invoked in one of two ways:
505+
506+ 1. Directly, by calling the metaclass with a class name, a tuple of base
507+ classes, and a namespace dictionary (for example,
508+ ``Meta(name, bases, namespace) ``), optionally along with additional keyword
509+ arguments.
510+ 2. Implicitly, by a :keyword: `python:class ` statement, which assembles these
511+ three arguments from the statement and the class body and then calls the metaclass.
512+
513+ In both cases, the metaclass call should be evaluated using the same rules
514+ described in the sections above: the :meth: `!__call__ ` method of the metaclass's
515+ own metaclass (typically :meth: `!type.__call__ `) is invoked, which in turn calls
516+ the :meth: `!__new__ ` and :meth: `!__init__ ` methods of the metaclass. These methods are
517+ typically inherited from :class: `type `, whose type definitions require special
518+ handling by type checkers, as described below.
519+
520+ The following example illustrates these rules applied to metaclass calls:
521+
522+ ::
523+
524+ class MetaMeta(type):
525+ def __call__(cls, *args, **kwargs) -> Never:
526+ raise TypeError("Classes cannot be created with this metaclass")
527+
528+ class Meta1(type, metaclass=MetaMeta):
529+ pass
530+
531+ # The __call__() method of the metaclass's own metaclass is evaluated first:
532+ assert_type(Meta1("A", (), {}), Never)
533+
534+ class Meta2(type):
535+ def __new__(
536+ mcls,
537+ name: str,
538+ bases: tuple[type, ...],
539+ namespace: dict[str, Any],
540+ *,
541+ key: int,
542+ ):
543+ return super().__new__(mcls, name, bases, namespace)
544+
545+ # Then, the __new__ and __init__ methods of the metaclass are evaluated:
546+ Meta2("B", (), {}, key=1) # OK, evaluates to an instance of Meta2
547+ Meta2("B", (), {}) # Type error: missing argument "key"
548+
549+ class Meta3(type):
550+ def __new__(
551+ mcls, name: str, bases: tuple[type, ...], namespace: dict[str, Any]
552+ ) -> int:
553+ return 0
554+
555+ # Not evaluated, as __new__ does not return an instance of Meta3:
556+ def __init__(cls, x: str) -> None:
557+ pass
558+
559+ assert_type(Meta3("C", (), {}), int)
560+
561+
562+ The ``type `` Constructor
563+ ------------------------
564+
565+ In addition to being the default metaclass, :class: `type ` serves a second purpose:
566+ when called with a single argument, it returns the type of that argument rather than
567+ creating a new class. :class: `type ` therefore supports two distinct call forms,
568+ which are distinguished by the number of positional arguments:
569+
570+ * ``type(obj, /) `` returns the class of ``obj ``.
571+ * ``type(name, bases, dict, /, **kwds) `` creates and returns a new class.
572+
573+ These two forms are typically declared as overloads of the :meth: `!__new__ ` and
574+ :meth: `!__init__ ` methods in the type definition of :class: `type `. Both forms require
575+ special-case handling by type checkers.
576+
577+ Although the single-argument form is typically declared with a return type of
578+ ``type ``, type checkers should special-case this form and evaluate its result
579+ as ``type[T] ``, where ``T `` is the type of the argument.
580+
581+ ::
582+
583+ def func(x: int, y: int | str) -> None:
584+ assert_type(type(x), type[int])
585+ assert_type(type(y), type[int] | type[str])
586+
587+ At runtime, the single-argument form applies only when the class being called
588+ is :class: `type ` itself, and is not inherited by metaclasses: a single-argument call
589+ to a subclass of :class: `type ` raises a :exc: `TypeError `.
590+
591+ ::
592+
593+ class Meta(type):
594+ pass
595+
596+ assert_type(type(1), type[int]) # OK, uses the single-argument form
597+ Meta(1) # Type error: single-argument form does not apply to subclasses
598+
599+ Meta("A", (), {}) # OK, uses the three-argument form
600+
601+ This special-casing applies only to the :meth: `!__new__ ` and :meth: `!__init__ `
602+ methods inherited from :class: `type `. If a metaclass defines its own :meth: `!__new__ `
603+ method that accepts a single argument, calls to it should be evaluated
604+ using the rules for regular constructor calls described earlier in this
605+ chapter.
606+
607+ The evaluated return type of the three-argument form is an instance of the
608+ metaclass being called, consistent with the return type definition of
609+ :meth: `!type.__new__ `. Type checkers may infer a more precise type for the returned
610+ class object, for example, one equivalent to a class defined by a :keyword: `class `
611+ statement with the given name, base classes, and namespace.
612+
613+
614+ Class Statements
615+ ----------------
616+
617+ When a :keyword: `class ` statement is executed, the runtime performs the following
618+ steps to create the new class object (see :ref: `python:metaclasses `):
619+
620+ 1. The metaclass is determined. If a ``metaclass `` keyword argument is present
621+ in the class statement's argument list, it is used as a candidate;
622+ otherwise, :class: `type ` is. The most derived metaclass among the candidate and
623+ the metaclasses of all base classes is selected. If no candidate is a
624+ (non-strict) subclass of all of the others, a :exc: `TypeError ` is raised
625+ (see :ref: `py315:metaclass-determination `).
626+ 2. The class namespace is prepared. If the metaclass has a :attr: `!__prepare__ `
627+ attribute, it is called as ``Meta.__prepare__(name, bases, **kwds) ``, and
628+ its result is used as the namespace object.
629+ 3. The class body is executed within this namespace.
630+ 4. The metaclass is called as ``Meta(name, bases, namespace, **kwds) ``, where
631+ ``kwds `` consists of the keyword arguments that appear in the class
632+ statement's argument list, excluding ``metaclass `` itself.
633+
634+ Type checkers may report an error for a class statement whose base classes
635+ have incompatible metaclasses.
636+
637+ Type checkers should validate keyword arguments in a class statement's
638+ argument list (other than ``metaclass ``) by evaluating the implied metaclass
639+ call using the constructor call rules described in :ref: `constructor-calls `.
640+
641+ ::
642+
643+ class Meta(type):
644+ def __new__(
645+ mcls,
646+ name: str,
647+ bases: tuple[type, ...],
648+ namespace: dict[str, Any],
649+ *,
650+ key: int,
651+ ):
652+ return super().__new__(mcls, name, bases, namespace)
653+
654+ class MyClass1(metaclass=Meta, key=3): # OK
655+ pass
656+
657+ class MyClass2(metaclass=Meta, key=""): # Type error: wrong type for "key"
658+ pass
659+
660+ class MyClass3(metaclass=Meta): # Type error: missing argument "key"
661+ pass
662+
663+ Meta("MyClass4", (), {}, key=3) # OK
664+ Meta("MyClass5", (), {}, key="") # Type error: wrong type for "key"
665+
666+ Keyword arguments in a direct metaclass call (such as the last two calls in the
667+ example above) require no special handling: they are validated as part of
668+ evaluating the call using the standard constructor call rules.
669+
670+ Regardless of the evaluated return type of the implied metaclass call, a
671+ :keyword: `class ` statement defines a class, and type checkers should evaluate the
672+ type of the bound name accordingly (``type[MyClass1] `` in the example above).
673+ The implied metaclass call is evaluated only for the purpose of validating
674+ its arguments.
675+
676+ Type checkers may validate the implied call to :attr: `!__prepare__ `:
677+
678+ ::
679+
680+ class Meta(type):
681+ @classmethod
682+ def __prepare__(mcls, name: str, bases: tuple[type, ...]): # No **kwds
683+ return {}
684+
685+ def __new__(
686+ mcls,
687+ name: str,
688+ bases: tuple[type, ...],
689+ namespace: dict[str, Any],
690+ *,
691+ key: int,
692+ ):
693+ return super().__new__(mcls, name, bases, namespace)
694+
695+ # The 'key' argument may result in a type checker error:
696+ class MyClass6(metaclass=Meta, key=3):
697+ pass
698+
699+ The ``metaclass `` argument can also be an arbitrary callable that is not a subclass
700+ of :class: `type `. Support for this pattern is currently unspecified.
701+
702+
703+ The ``__init_subclass__() `` Method
704+ ----------------------------------
705+
706+ :meth: `!type.__new__ ` invokes the :meth: `~object.__init_subclass__ `
707+ method of the parent class (the class that follows the newly created class in
708+ its :term: `python:method resolution order `) passing the newly created class as
709+ ``cls `` along with the keyword arguments supplied to the metaclass constructor
710+ (see :ref: `python:class-customization `).
711+
712+ :meth: `~object.__init_subclass__ ` is implicitly a class method: it is converted to
713+ a :class: `classmethod ` even when it is not explicitly decorated as one, and it is
714+ not called for the class that defines it, only for its subclasses. Type checkers
715+ should treat it as a classmethod if it isn't explicitly defined as one.
716+
717+ If the metaclass of the class being defined does not define its own
718+ :meth: `!__new__ ` method (including when no explicit metaclass
719+ is specified), type checkers should validate the keyword arguments in a
720+ class statement's argument list against the :meth: `~object.__init_subclass__ ` method of
721+ the parent class.
722+
723+ ::
724+
725+ class Base:
726+ def __init_subclass__(cls, *, flag: bool = False) -> None:
727+ super().__init_subclass__()
728+
729+ class MyClass1(Base, flag=True): # OK
730+ pass
731+
732+ class MyClass2(Base, flag=""): # Type error: wrong type for "flag"
733+ pass
734+
735+ class MyClass3(Base, other=1): # Type error: Base.__init_subclass__() got an unexpected keyword argument 'other'
736+ pass
737+
738+ class MyClass4(other=1): # Type error: MyClass4.__init_subclass__() takes no keyword arguments
739+ pass
740+
741+ A metaclass :meth: `!__init__ ` method has no effect on this rule: when the
742+ metaclass does not define its own :meth: `!__new__ ` method, :meth: `!type.__new__ `
743+ still forwards the keyword arguments to :meth: `~object.__init_subclass__ `, so
744+ the keyword arguments should satisfy both the metaclass :meth: `!__init__ `
745+ method (as part of validating the implied metaclass call) and the
746+ :meth: `~object.__init_subclass__ ` method of the parent class.
747+
748+ ::
749+
750+ class MetaInit(type):
751+ def __init__(
752+ cls,
753+ name: str,
754+ bases: tuple[type, ...],
755+ namespace: dict[str, Any],
756+ *,
757+ key: int,
758+ ) -> None:
759+ super().__init__(name, bases, namespace)
760+
761+ # Type error: "key" is accepted by MetaInit.__init__(), but type.__new__()
762+ # forwards it to Base.__init_subclass__(), which does not accept it:
763+ class MyClass5(Base, metaclass=MetaInit, key=1):
764+ pass
765+
766+ The same forwarding occurs when the metaclass is called directly:
767+ ``type("D", (Base,), {}, flag=True) `` passes ``flag `` to
768+ :meth: `!Base.__init_subclass__ `. Type checkers may validate keyword
769+ arguments in such calls against the :meth: `~object.__init_subclass__ ` method of
770+ the parent class when the base classes can be statically determined.
771+
772+ If the metaclass defines its own :meth: `!__new__ ` method that accepts keyword
773+ arguments only through a ``**kwargs `` parameter, whether these arguments are
774+ forwarded to :meth: `!type.__new__ ` (and from there to
775+ :meth: `~object.__init_subclass__ `) cannot generally be determined statically.
776+ In this situation, type checkers may additionally validate the keyword
777+ arguments against the :meth: `~object.__init_subclass__ ` method of the parent
778+ class.
0 commit comments