diff options
| -rw-r--r-- | Doc/c-api/concrete.rst | 1 | ||||
| -rw-r--r-- | Doc/c-api/typehints.rst | 47 | ||||
| -rw-r--r-- | Doc/data/stable_abi.dat | 2 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2021-06-16-18-09-49.bpo-44392.6RF1Sc.rst | 2 | ||||
| -rw-r--r-- | Misc/stable_abi.txt | 2 | ||||
| -rwxr-xr-x | PC/python3dll.c | 2 |
6 files changed, 53 insertions, 3 deletions
diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index c1d9fa1..84224dc 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -115,3 +115,4 @@ Other Objects coro.rst contextvars.rst datetime.rst + typehints.rst diff --git a/Doc/c-api/typehints.rst b/Doc/c-api/typehints.rst new file mode 100644 index 0000000..dfda96a --- /dev/null +++ b/Doc/c-api/typehints.rst @@ -0,0 +1,47 @@ +.. highlight:: c + +.. _typehintobjects: + +Objects for Type Hinting +------------------------ + +Various built-in types for type hinting are provided. Currently, +two types exist -- :ref:`GenericAlias <types-genericalias>` and +:ref:`Union <types-union>`. Only ``GenericAlias`` is exposed to C. + +.. c:function:: PyObject* Py_GenericAlias(PyObject *origin, PyObject *args) + + Create a :ref:`GenericAlias <types-genericalias>` object. + Equivalent to calling the Python class + :class:`types.GenericAlias`. The *origin* and *args* arguments set the + ``GenericAlias``\ 's ``__origin__`` and ``__args__`` attributes respectively. + *origin* should be a :c:type:`PyTypeObject*`, and *args* can be a + :c:type:`PyTupleObject*` or any ``PyObject*``. If *args* passed is + not a tuple, a 1-tuple is automatically constructed and ``__args__`` is set + to ``(args,)``. + Minimal checking is done for the arguments, so the function will succeed even + if *origin* is not a type. + The ``GenericAlias``\ 's ``__parameters__`` attribute is constructed lazily + from ``__args__``. On failure, an exception is raised and ``NULL`` is + returned. + + Here's an example of how to make an extension type generic:: + + ... + static PyMethodDef my_obj_methods[] = { + // Other methods. + ... + {"__class_getitem__", (PyCFunction)Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"} + ... + } + + .. seealso:: The data model method :meth:`__class_getitem__`. + + .. versionadded:: 3.9 + +.. c:var:: PyTypeObject Py_GenericAliasType + + The C type of the object returned by :c:func:`Py_GenericAlias`. Equivalent to + :class:`types.GenericAlias` in Python. + + .. versionadded:: 3.9 diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat index 5f4955b..e373e23 100644 --- a/Doc/data/stable_abi.dat +++ b/Doc/data/stable_abi.dat @@ -785,7 +785,7 @@ var,Py_FileSystemDefaultEncoding,3.2, function,Py_Finalize,3.2, function,Py_FinalizeEx,3.6, function,Py_GenericAlias,3.9, -function,Py_GenericAliasType,3.9, +var,Py_GenericAliasType,3.9, function,Py_GetBuildInfo,3.2, function,Py_GetCompiler,3.2, function,Py_GetCopyright,3.2, diff --git a/Misc/NEWS.d/next/Documentation/2021-06-16-18-09-49.bpo-44392.6RF1Sc.rst b/Misc/NEWS.d/next/Documentation/2021-06-16-18-09-49.bpo-44392.6RF1Sc.rst new file mode 100644 index 0000000..ac197f2 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-06-16-18-09-49.bpo-44392.6RF1Sc.rst @@ -0,0 +1,2 @@ +Added a new section in the C API documentation for types used in type +hinting. Documented ``Py_GenericAlias`` and ``Py_GenericAliasType``. diff --git a/Misc/stable_abi.txt b/Misc/stable_abi.txt index 168e81d..24c71d1 100644 --- a/Misc/stable_abi.txt +++ b/Misc/stable_abi.txt @@ -2043,7 +2043,7 @@ function Py_LeaveRecursiveCall added 3.9 function Py_GenericAlias added 3.9 -function Py_GenericAliasType +data Py_GenericAliasType added 3.9 function PyCMethod_New added 3.9 # Windows: 3.10 & 3.9.2 -- https://bugs.python.org/issue43155 diff --git a/PC/python3dll.c b/PC/python3dll.c index be85f27..378669c 100755 --- a/PC/python3dll.c +++ b/PC/python3dll.c @@ -56,7 +56,6 @@ EXPORT_FUNC(Py_FatalError) EXPORT_FUNC(Py_Finalize) EXPORT_FUNC(Py_FinalizeEx) EXPORT_FUNC(Py_GenericAlias) -EXPORT_FUNC(Py_GenericAliasType) EXPORT_FUNC(Py_GetArgcArgv) EXPORT_FUNC(Py_GetBuildInfo) EXPORT_FUNC(Py_GetCompiler) @@ -722,6 +721,7 @@ EXPORT_DATA(_PyWeakref_ProxyType) EXPORT_DATA(_PyWeakref_RefType) EXPORT_DATA(Py_FileSystemDefaultEncodeErrors) EXPORT_DATA(Py_FileSystemDefaultEncoding) +EXPORT_DATA(Py_GenericAliasType) EXPORT_DATA(Py_HasFileSystemDefaultEncoding) EXPORT_DATA(Py_UTF8Mode) EXPORT_DATA(PyBaseObject_Type) |