mirror of
https://github.com/python/cpython
synced 2024-09-05 16:38:56 +00:00
bpo-44392: Add Py_GenericAlias to C API docs (GH-26724)
Also fix stable ABI type definitions
This commit is contained in:
parent
ab030d6f9d
commit
6773c3eaa7
|
@ -115,3 +115,4 @@ Other Objects
|
||||||
coro.rst
|
coro.rst
|
||||||
contextvars.rst
|
contextvars.rst
|
||||||
datetime.rst
|
datetime.rst
|
||||||
|
typehints.rst
|
||||||
|
|
47
Doc/c-api/typehints.rst
Normal file
47
Doc/c-api/typehints.rst
Normal file
|
@ -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
|
|
@ -785,7 +785,7 @@ var,Py_FileSystemDefaultEncoding,3.2,
|
||||||
function,Py_Finalize,3.2,
|
function,Py_Finalize,3.2,
|
||||||
function,Py_FinalizeEx,3.6,
|
function,Py_FinalizeEx,3.6,
|
||||||
function,Py_GenericAlias,3.9,
|
function,Py_GenericAlias,3.9,
|
||||||
function,Py_GenericAliasType,3.9,
|
var,Py_GenericAliasType,3.9,
|
||||||
function,Py_GetBuildInfo,3.2,
|
function,Py_GetBuildInfo,3.2,
|
||||||
function,Py_GetCompiler,3.2,
|
function,Py_GetCompiler,3.2,
|
||||||
function,Py_GetCopyright,3.2,
|
function,Py_GetCopyright,3.2,
|
||||||
|
|
|
@ -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``.
|
|
@ -2043,7 +2043,7 @@ function Py_LeaveRecursiveCall
|
||||||
added 3.9
|
added 3.9
|
||||||
function Py_GenericAlias
|
function Py_GenericAlias
|
||||||
added 3.9
|
added 3.9
|
||||||
function Py_GenericAliasType
|
data Py_GenericAliasType
|
||||||
added 3.9
|
added 3.9
|
||||||
function PyCMethod_New
|
function PyCMethod_New
|
||||||
added 3.9 # Windows: 3.10 & 3.9.2 -- https://bugs.python.org/issue43155
|
added 3.9 # Windows: 3.10 & 3.9.2 -- https://bugs.python.org/issue43155
|
||||||
|
|
|
@ -56,7 +56,6 @@ EXPORT_FUNC(Py_FatalError)
|
||||||
EXPORT_FUNC(Py_Finalize)
|
EXPORT_FUNC(Py_Finalize)
|
||||||
EXPORT_FUNC(Py_FinalizeEx)
|
EXPORT_FUNC(Py_FinalizeEx)
|
||||||
EXPORT_FUNC(Py_GenericAlias)
|
EXPORT_FUNC(Py_GenericAlias)
|
||||||
EXPORT_FUNC(Py_GenericAliasType)
|
|
||||||
EXPORT_FUNC(Py_GetArgcArgv)
|
EXPORT_FUNC(Py_GetArgcArgv)
|
||||||
EXPORT_FUNC(Py_GetBuildInfo)
|
EXPORT_FUNC(Py_GetBuildInfo)
|
||||||
EXPORT_FUNC(Py_GetCompiler)
|
EXPORT_FUNC(Py_GetCompiler)
|
||||||
|
@ -722,6 +721,7 @@ EXPORT_DATA(_PyWeakref_ProxyType)
|
||||||
EXPORT_DATA(_PyWeakref_RefType)
|
EXPORT_DATA(_PyWeakref_RefType)
|
||||||
EXPORT_DATA(Py_FileSystemDefaultEncodeErrors)
|
EXPORT_DATA(Py_FileSystemDefaultEncodeErrors)
|
||||||
EXPORT_DATA(Py_FileSystemDefaultEncoding)
|
EXPORT_DATA(Py_FileSystemDefaultEncoding)
|
||||||
|
EXPORT_DATA(Py_GenericAliasType)
|
||||||
EXPORT_DATA(Py_HasFileSystemDefaultEncoding)
|
EXPORT_DATA(Py_HasFileSystemDefaultEncoding)
|
||||||
EXPORT_DATA(Py_UTF8Mode)
|
EXPORT_DATA(Py_UTF8Mode)
|
||||||
EXPORT_DATA(PyBaseObject_Type)
|
EXPORT_DATA(PyBaseObject_Type)
|
||||||
|
|
Loading…
Reference in a new issue