10000 bpo-44392: Add Py_GenericAlias to C API docs (GH-26724) · python/cpython@84ce737 · GitHub
[go: up one dir, main page]
Skip to content

Commit 84ce737

Browse files
miss-islingtonFidget-Spinner
miss-islington
and
Fidget-Spinner
authored
bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)
Also fix stable ABI type definitions (cherry picked from commit 6773c3e) Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>
1 parent 7fd4010 commit 84ce737

File tree

6 files changed

+53
-3
lines changed

6 files changed

+53
-3
lines changed

‎Doc/c-api/concrete.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,3 +115,4 @@ Other Objects
115115
coro.rst
116116
contextvars.rst
117117
datetime.rst
118+
typehints.rst

‎Doc/c-api/typehints.rst

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
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:type:`PyTypeObject*`, and *args* can be a
19+
:c:type:`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__", (PyCFunction)Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"}
35+
...
36+
}
37+
38+
.. seealso:: The data model method :meth:`__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

‎Doc/data/stable_abi.dat

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -785,7 +785,7 @@ var,Py_FileSystemDefaultEncoding,3.2,
785785
function,Py_Finalize,3.2,
786786
function,Py_FinalizeEx,3.6,
787787
function,Py_GenericAlias,3.9,
788-
function,Py_GenericAliasType,3.9,
788+
var,Py_GenericAliasType,3.9,
789789
function,Py_GetBuildInfo,3.2,
790790
function,Py_GetCompiler,3.2,
791791
function,Py_GetCopyright,3.2,

‎Misc/NEWS.d/next/Documentation/2021-06-16-18-09-49.bpo-44392.6RF1Sc.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Added a new section in the C API documentation for types used in type
2+
hinting. Documented ``Py_GenericAlias`` and ``Py_GenericAliasType``.

‎Misc/stable_abi.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2043,7 +2043,7 @@ function Py_LeaveRecursiveCall
20432043
added 3.9
20442044
function Py_GenericAlias
20452045
added 3.9
2046-
function Py_GenericAliasType
2046+
data Py_GenericAliasType
20472047
added 3.9
20482048
function PyCMethod_New
20492049
added 3.9 # Windows: 3.10 & 3.9.2 -- https://bugs.python.org/issue43155

‎PC/python3dll.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,6 @@ EXPORT_FUNC(Py_FatalError)
5656
EXPORT_FUNC(Py_Finalize)
5757
EXPORT_FUNC(Py_FinalizeEx)
5858
EXPORT_FUNC(Py_GenericAlias)
59-
EXPORT_FUNC(Py_GenericAliasType)
6059
EXPORT_FUNC(Py_GetArgcArgv)
6160
EXPORT_FUNC(Py_GetBuildInfo)
6261
EXPORT_FUNC(Py_GetCompiler)
@@ -722,6 +721,7 @@ EXPORT_DATA(_PyWeakref_ProxyType)
722721
EXPORT_DATA(_PyWeakref_RefType)
723722
EXPORT_DATA(Py_FileSystemDefaultEncodeErrors)
724723
EXPORT_DATA(Py_FileSystemDefaultEncoding)
724+
EXPORT_DATA(Py_GenericAliasType)
725725
EXPORT_DATA(Py_HasFileSystemDefaultEncoding)
726726
EXPORT_DATA(Py_UTF8Mode)
727727
EXPORT_DATA(PyBaseObject_Type)

0 commit comments

Comments
 (0)
0