Skip to content

Commit bb24c61

Browse files
committed
Add section about metaclass constructors
1 parent 39164cd commit bb24c61

2 files changed

Lines changed: 292 additions & 1 deletion

File tree

‎docs/conf.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,4 +52,7 @@
5252
html_static_path = []
5353

5454
extensions = ['sphinx.ext.intersphinx']
55-
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
55+
intersphinx_mapping = {
56+
'python': ('https://docs.python.org/3', None),
57+
'py315': ('https://docs.python.org/3.15', None),
58+
}

‎docs/spec/constructors.rst‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ Constructors
33

44
Calls to constructors require special handling within type checkers.
55

6+
.. _`constructor-calls`:
7+
68
Constructor 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

Comments
 (0)