Debian Codegraph @

Doc/c-api/typehints.rst

raw
1 .. highlight:: c
2
3 .. _typehintobjects:
4
5 Objects for Type Hinting
6 ------------------------
7
8 Various built-in types for type hinting are provided. Currently,
9 two types exist -- :ref:`GenericAlias <types-genericalias>` and
10 :ref:`Union <types-union>`. Only ``GenericAlias`` is exposed to C.
11
12 .. c:function:: PyObject* Py_GenericAlias(PyObject *origin, PyObject *args)
13
14 Create a :ref:`GenericAlias <types-genericalias>` object.
15 Equivalent to calling the Python class
16 :class:`types.GenericAlias`. The *origin* and *args* arguments set the
17 ``GenericAlias``\ 's ``__origin__`` and ``__args__`` attributes respectively.
18 *origin* should be a :c:expr:`PyTypeObject*`, and *args* can be a
19 :c:expr:`PyTupleObject*` or any ``PyObject*``. If *args* passed is
20 not a tuple, a 1-tuple is automatically constructed and ``__args__`` is set
21 to ``(args,)``.
22 Minimal checking is done for the arguments, so the function will succeed even
23 if *origin* is not a type.
24 The ``GenericAlias``\ 's ``__parameters__`` attribute is constructed lazily
25 from ``__args__``. On failure, an exception is raised and ``NULL`` is
26 returned.
27
28 Here's an example of how to make an extension type generic::
29
30 ...
31 static PyMethodDef my_obj_methods[] = {
32 // Other methods.
33 ...
34 {"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "my_obj is generic over its contained type"}
35 ...
36 }
37
38 .. seealso:: The data model method :meth:`~object.__class_getitem__`.
39
40 .. versionadded:: 3.9
41
42 .. c:var:: PyTypeObject Py_GenericAliasType
43
44 The C type of the object returned by :c:func:`Py_GenericAlias`. Equivalent to
45 :class:`types.GenericAlias` in Python.
46
47 .. versionadded:: 3.9