bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)

Also fix stable ABI type definitions
(cherry picked from commit 6773c3eaa735b5061b4a97f2c730703a32d8c9ff)

Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>

diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst
index c1d9fa1b41a3feee74e711d6b9bd3eddf7421934..84224dcca523b9ee0eb6c44c39b8cbf8c01e5ced 100644 (file)
--- 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 (file)
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 5f4955bb35bcbf6c8bfcd7fb5af085e6e90eac12..e373e2314a65171e688ff685c50571adf56bf89b 100644 (file)
--- 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 (file)
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 168e81db42d05a45942cb3e0061273521acf8710..24c71d12e3ba759844a0d91cdb0f973636c98dd0 100644 (file)
--- 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 be85f27e72ac81c201f758b72afb5cbc20261eb8..378669c27f0544cf5f26f0aac15c799ea708a18a 100755 (executable)
--- 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)