Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-93738: Documentation C syntax (:c:type:<C type> -> :c:expr:<C type>) (#97768) 

:c:type:`<C type>` -> :c:expr:`<C type>`

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
This commit is contained in:
Adam Turner 2022-10-05 19:01:14 +01:00 committed by GitHub
parent aeb28f5130
commit 0031e62973
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
34 changed files with 241 additions and 241 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
Doc/c-api/arg.rst
View File

@ -152,10 +152,10 @@ which disallows mutable objects such as :class:`bytearray`.
It only works for encoded data without embedded NUL bytes. It only works for encoded data without embedded NUL bytes.
This format requires two arguments. The first is only used as input, and This format requires two arguments. The first is only used as input, and
must be a :c:type:`const char*` which points to the name of an encoding as a must be a :c:expr:`const char*` which points to the name of an encoding as a
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used. NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char**`; the value of the pointer it second argument must be a :c:expr:`char**`; the value of the pointer it
references will be set to a buffer with the contents of the argument text. references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument. The text will be encoded in the encoding specified by the first argument.
@ -175,10 +175,10 @@ which disallows mutable objects such as :class:`bytearray`.
characters. characters.
It requires three arguments. The first is only used as input, and must be a It requires three arguments. The first is only used as input, and must be a
:c:type:`const char*` which points to the name of an encoding as a :c:expr:`const char*` which points to the name of an encoding as a
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used. NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char**`; the value of the pointer it second argument must be a :c:expr:`char**`; the value of the pointer it
references will be set to a buffer with the contents of the argument text. references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument. The text will be encoded in the encoding specified by the first argument.
The third argument must be a pointer to an integer; the referenced integer The third argument must be a pointer to an integer; the referenced integer
@ -215,38 +215,38 @@ Numbers
``b`` (:class:`int`) [unsigned char] ``b`` (:class:`int`) [unsigned char]
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
:c:type:`unsigned char`. :c:expr:`unsigned char`.
``B`` (:class:`int`) [unsigned char] ``B`` (:class:`int`) [unsigned char]
Convert a Python integer to a tiny int without overflow checking, stored in a C Convert a Python integer to a tiny int without overflow checking, stored in a C
:c:type:`unsigned char`. :c:expr:`unsigned char`.
``h`` (:class:`int`) [short int] ``h`` (:class:`int`) [short int]
Convert a Python integer to a C :c:type:`short int`. Convert a Python integer to a C :c:expr:`short int`.
``H`` (:class:`int`) [unsigned short int] ``H`` (:class:`int`) [unsigned short int]
Convert a Python integer to a C :c:type:`unsigned short int`, without overflow Convert a Python integer to a C :c:expr:`unsigned short int`, without overflow
checking. checking.
``i`` (:class:`int`) [int] ``i`` (:class:`int`) [int]
Convert a Python integer to a plain C :c:type:`int`. Convert a Python integer to a plain C :c:expr:`int`.
``I`` (:class:`int`) [unsigned int] ``I`` (:class:`int`) [unsigned int]
Convert a Python integer to a C :c:type:`unsigned int`, without overflow Convert a Python integer to a C :c:expr:`unsigned int`, without overflow
checking. checking.
``l`` (:class:`int`) [long int] ``l`` (:class:`int`) [long int]
Convert a Python integer to a C :c:type:`long int`. Convert a Python integer to a C :c:expr:`long int`.
``k`` (:class:`int`) [unsigned long] ``k`` (:class:`int`) [unsigned long]
Convert a Python integer to a C :c:type:`unsigned long` without Convert a Python integer to a C :c:expr:`unsigned long` without
overflow checking. overflow checking.
``L`` (:class:`int`) [long long] ``L`` (:class:`int`) [long long]
Convert a Python integer to a C :c:type:`long long`. Convert a Python integer to a C :c:expr:`long long`.
``K`` (:class:`int`) [unsigned long long] ``K`` (:class:`int`) [unsigned long long]
Convert a Python integer to a C :c:type:`unsigned long long` Convert a Python integer to a C :c:expr:`unsigned long long`
without overflow checking. without overflow checking.
``n`` (:class:`int`) [:c:type:`Py_ssize_t`] ``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
@ -254,20 +254,20 @@ Numbers
``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char] ``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
Convert a Python byte, represented as a :class:`bytes` or Convert a Python byte, represented as a :class:`bytes` or
:class:`bytearray` object of length 1, to a C :c:type:`char`. :class:`bytearray` object of length 1, to a C :c:expr:`char`.
.. versionchanged:: 3.3 .. versionchanged:: 3.3
Allow :class:`bytearray` objects. Allow :class:`bytearray` objects.
``C`` (:class:`str` of length 1) [int] ``C`` (:class:`str` of length 1) [int]
Convert a Python character, represented as a :class:`str` object of Convert a Python character, represented as a :class:`str` object of
length 1, to a C :c:type:`int`. length 1, to a C :c:expr:`int`.
``f`` (:class:`float`) [float] ``f`` (:class:`float`) [float]
Convert a Python floating point number to a C :c:type:`float`. Convert a Python floating point number to a C :c:expr:`float`.
``d`` (:class:`float`) [double] ``d`` (:class:`float`) [double]
Convert a Python floating point number to a C :c:type:`double`. Convert a Python floating point number to a C :c:expr:`double`.
``D`` (:class:`complex`) [Py_complex] ``D`` (:class:`complex`) [Py_complex]
Convert a Python complex number to a C :c:type:`Py_complex` structure. Convert a Python complex number to a C :c:type:`Py_complex` structure.
@ -292,13 +292,13 @@ Other objects
``O&`` (object) [*converter*, *anything*] ``O&`` (object) [*converter*, *anything*]
Convert a Python object to a C variable through a *converter* function. This Convert a Python object to a C variable through a *converter* function. This
takes two arguments: the first is a function, the second is the address of a C takes two arguments: the first is a function, the second is the address of a C
variable (of arbitrary type), converted to :c:type:`void *`. The *converter* variable (of arbitrary type), converted to :c:expr:`void *`. The *converter*
function in turn is called as follows:: function in turn is called as follows::
status = converter(object, address); status = converter(object, address);
where *object* is the Python object to be converted and *address* is the where *object* is the Python object to be converted and *address* is the
:c:type:`void*` argument that was passed to the ``PyArg_Parse*`` function. :c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` function.
The returned *status* should be ``1`` for a successful conversion and ``0`` if The returned *status* should be ``1`` for a successful conversion and ``0`` if
the conversion has failed. When the conversion fails, the *converter* function the conversion has failed. When the conversion fails, the *converter* function
should raise an exception and leave the content of *address* unmodified. should raise an exception and leave the content of *address* unmodified.
@ -531,7 +531,7 @@ Building values
Same as ``s#``. Same as ``s#``.
``u`` (:class:`str`) [const wchar_t \*] ``u`` (:class:`str`) [const wchar_t \*]
Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4) Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``, data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
``None`` is returned. ``None`` is returned.
@ -547,51 +547,51 @@ Building values
Same as ``s#``. Same as ``s#``.
``i`` (:class:`int`) [int] ``i`` (:class:`int`) [int]
Convert a plain C :c:type:`int` to a Python integer object. Convert a plain C :c:expr:`int` to a Python integer object.
``b`` (:class:`int`) [char] ``b`` (:class:`int`) [char]
Convert a plain C :c:type:`char` to a Python integer object. Convert a plain C :c:expr:`char` to a Python integer object.
``h`` (:class:`int`) [short int] ``h`` (:class:`int`) [short int]
Convert a plain C :c:type:`short int` to a Python integer object. Convert a plain C :c:expr:`short int` to a Python integer object.
``l`` (:class:`int`) [long int] ``l`` (:class:`int`) [long int]
Convert a C :c:type:`long int` to a Python integer object. Convert a C :c:expr:`long int` to a Python integer object.
``B`` (:class:`int`) [unsigned char] ``B`` (:class:`int`) [unsigned char]
Convert a C :c:type:`unsigned char` to a Python integer object. Convert a C :c:expr:`unsigned char` to a Python integer object.
``H`` (:class:`int`) [unsigned short int] ``H`` (:class:`int`) [unsigned short int]
Convert a C :c:type:`unsigned short int` to a Python integer object. Convert a C :c:expr:`unsigned short int` to a Python integer object.
``I`` (:class:`int`) [unsigned int] ``I`` (:class:`int`) [unsigned int]
Convert a C :c:type:`unsigned int` to a Python integer object. Convert a C :c:expr:`unsigned int` to a Python integer object.
``k`` (:class:`int`) [unsigned long] ``k`` (:class:`int`) [unsigned long]
Convert a C :c:type:`unsigned long` to a Python integer object. Convert a C :c:expr:`unsigned long` to a Python integer object.
``L`` (:class:`int`) [long long] ``L`` (:class:`int`) [long long]
Convert a C :c:type:`long long` to a Python integer object. Convert a C :c:expr:`long long` to a Python integer object.
``K`` (:class:`int`) [unsigned long long] ``K`` (:class:`int`) [unsigned long long]
Convert a C :c:type:`unsigned long long` to a Python integer object. Convert a C :c:expr:`unsigned long long` to a Python integer object.
``n`` (:class:`int`) [:c:type:`Py_ssize_t`] ``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
Convert a C :c:type:`Py_ssize_t` to a Python integer. Convert a C :c:type:`Py_ssize_t` to a Python integer.
``c`` (:class:`bytes` of length 1) [char] ``c`` (:class:`bytes` of length 1) [char]
Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of Convert a C :c:expr:`int` representing a byte to a Python :class:`bytes` object of
length 1. length 1.
``C`` (:class:`str` of length 1) [int] ``C`` (:class:`str` of length 1) [int]
Convert a C :c:type:`int` representing a character to Python :class:`str` Convert a C :c:expr:`int` representing a character to Python :class:`str`
object of length 1. object of length 1.
``d`` (:class:`float`) [double] ``d`` (:class:`float`) [double]
Convert a C :c:type:`double` to a Python floating point number. Convert a C :c:expr:`double` to a Python floating point number.
``f`` (:class:`float`) [float] ``f`` (:class:`float`) [float]
Convert a C :c:type:`float` to a Python floating point number. Convert a C :c:expr:`float` to a Python floating point number.
``D`` (:class:`complex`) [Py_complex \*] ``D`` (:class:`complex`) [Py_complex \*]
Convert a C :c:type:`Py_complex` structure to a Python complex number. Convert a C :c:type:`Py_complex` structure to a Python complex number.
@ -614,7 +614,7 @@ Building values
``O&`` (object) [*converter*, *anything*] ``O&`` (object) [*converter*, *anything*]
Convert *anything* to a Python object through a *converter* function. The Convert *anything* to a Python object through a *converter* function. The
function is called with *anything* (which should be compatible with :c:type:`void*`) function is called with *anything* (which should be compatible with :c:expr:`void*`)
as its argument and should return a "new" Python object, or ``NULL`` if an as its argument and should return a "new" Python object, or ``NULL`` if an
error occurred. error occurred.

2
Doc/c-api/capsule.rst
View File

@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
.. c:type:: PyCapsule .. c:type:: PyCapsule
This subtype of :c:type:`PyObject` represents an opaque value, useful for C This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`void*` extension modules who need to pass an opaque value (as a :c:expr:`void*`
pointer) through Python code to other C code. It is often used to make a C pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically regular import mechanism can be used to access C APIs defined in dynamically

4
Doc/c-api/complex.rst
View File

@ -115,12 +115,12 @@ Complex Numbers as Python Objects
.. c:function:: double PyComplex_RealAsDouble(PyObject *op) .. c:function:: double PyComplex_RealAsDouble(PyObject *op)
Return the real part of *op* as a C :c:type:`double`. Return the real part of *op* as a C :c:expr:`double`.
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op) .. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
Return the imaginary part of *op* as a C :c:type:`double`. Return the imaginary part of *op* as a C :c:expr:`double`.
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op) .. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)

4
Doc/c-api/conversion.rst
View File

@ -49,7 +49,7 @@ The following functions provide locale-independent string to number conversions.
.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception) .. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
Convert a string ``s`` to a :c:type:`double`, raising a Python Convert a string ``s`` to a :c:expr:`double`, raising a Python
exception on failure. The set of accepted strings corresponds to exception on failure. The set of accepted strings corresponds to
the set of strings accepted by Python's :func:`float` constructor, the set of strings accepted by Python's :func:`float` constructor,
except that ``s`` must not have leading or trailing whitespace. except that ``s`` must not have leading or trailing whitespace.
@ -83,7 +83,7 @@ The following functions provide locale-independent string to number conversions.
.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype) .. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
Convert a :c:type:`double` *val* to a string using supplied Convert a :c:expr:`double` *val* to a string using supplied
*format_code*, *precision*, and *flags*. *format_code*, *precision*, and *flags*.
*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``, *format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,

4
Doc/c-api/dict.rst
View File

@ -73,7 +73,7 @@ Dictionary Objects
.. index:: single: PyUnicode_FromString() .. index:: single: PyUnicode_FromString()
Insert *val* into the dictionary *p* using *key* as a key. *key* should Insert *val* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`const char*`. The key object is created using be a :c:expr:`const char*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on ``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure. This function *does not* steal a reference to *val*. failure. This function *does not* steal a reference to *val*.
@ -118,7 +118,7 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key) .. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
:c:type:`const char*`, rather than a :c:expr:`PyObject*`. :c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
Note that exceptions which occur while calling :meth:`__hash__` and Note that exceptions which occur while calling :meth:`__hash__` and
:meth:`__eq__` methods and creating a temporary string object :meth:`__eq__` methods and creating a temporary string object

2
Doc/c-api/file.rst
View File

@ -38,7 +38,7 @@ the :mod:`io` APIs instead.
.. c:function:: int PyObject_AsFileDescriptor(PyObject *p) .. c:function:: int PyObject_AsFileDescriptor(PyObject *p)
Return the file descriptor associated with *p* as an :c:type:`int`. If the Return the file descriptor associated with *p* as an :c:expr:`int`. If the
object is an integer, its value is returned. If not, the object is an integer, its value is returned. If not, the
object's :meth:`~io.IOBase.fileno` method is called if it exists; the object's :meth:`~io.IOBase.fileno` method is called if it exists; the
method must return an integer, which is returned as the file descriptor method must return an integer, which is returned as the file descriptor

16
Doc/c-api/float.rst
View File

@ -44,7 +44,7 @@ Floating Point Objects
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat) .. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
Return a C :c:type:`double` representation of the contents of *pyfloat*. If Return a C :c:expr:`double` representation of the contents of *pyfloat*. If
*pyfloat* is not a Python floating point object but has a :meth:`__float__` *pyfloat* is not a Python floating point object but has a :meth:`__float__`
method, this method will first be called to convert *pyfloat* into a float. method, this method will first be called to convert *pyfloat* into a float.
If ``__float__()`` is not defined then it falls back to :meth:`__index__`. If ``__float__()`` is not defined then it falls back to :meth:`__index__`.
@ -57,7 +57,7 @@ Floating Point Objects
.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat) .. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
Return a C :c:type:`double` representation of the contents of *pyfloat*, but Return a C :c:expr:`double` representation of the contents of *pyfloat*, but
without error checking. without error checking.
@ -70,12 +70,12 @@ Floating Point Objects
.. c:function:: double PyFloat_GetMax() .. c:function:: double PyFloat_GetMax()
Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`. Return the maximum representable finite float *DBL_MAX* as C :c:expr:`double`.
.. c:function:: double PyFloat_GetMin() .. c:function:: double PyFloat_GetMin()
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`. Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`.
Pack and Unpack functions Pack and Unpack functions
@ -83,8 +83,8 @@ Pack and Unpack functions
The pack and unpack functions provide an efficient platform-independent way to The pack and unpack functions provide an efficient platform-independent way to
store floating-point values as byte strings. The Pack routines produce a bytes store floating-point values as byte strings. The Pack routines produce a bytes
string from a C :c:type:`double`, and the Unpack routines produce a C string from a C :c:expr:`double`, and the Unpack routines produce a C
:c:type:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the :c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the
number of bytes in the bytes string. number of bytes in the bytes string.
On platforms that appear to use IEEE 754 formats these functions work by On platforms that appear to use IEEE 754 formats these functions work by
@ -107,7 +107,7 @@ Pack functions
-------------- --------------
The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
:c:type:`int` argument, non-zero if you want the bytes string in little-endian :c:expr:`int` argument, non-zero if you want the bytes string in little-endian
format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you
want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN`
constant can be used to use the native endian: it is equal to ``1`` on big constant can be used to use the native endian: it is equal to ``1`` on big
@ -138,7 +138,7 @@ Unpack functions
---------------- ----------------
The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an
:c:type:`int` argument, non-zero if the bytes string is in little-endian format :c:expr:`int` argument, non-zero if the bytes string is in little-endian format
(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian (exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
(exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to
use the native endian: it is equal to ``1`` on big endian processor, or ``0`` use the native endian: it is equal to ``1`` on big endian processor, or ``0``

28
Doc/c-api/init.rst
View File

@ -485,7 +485,7 @@ Process-wide parameters
interpreter will change the contents of this storage. interpreter will change the contents of this storage.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
:c:type:`wchar_*` string. :c:expr:`wchar_*` string.
.. deprecated:: 3.11 .. deprecated:: 3.11
@ -636,7 +636,7 @@ Process-wide parameters
if required after calling :c:func:`Py_Initialize`. if required after calling :c:func:`Py_Initialize`.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
:c:type:`wchar_*` string. :c:expr:`wchar_*` string.
The path argument is copied internally, so the caller may free it after the The path argument is copied internally, so the caller may free it after the
call completes. call completes.
@ -751,7 +751,7 @@ Process-wide parameters
directory (``"."``). directory (``"."``).
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
:c:type:`wchar_*` string. :c:expr:`wchar_*` string.
See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv` See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
members of the :ref:`Python Initialization Configuration <init-config>`. members of the :ref:`Python Initialization Configuration <init-config>`.
@ -787,7 +787,7 @@ Process-wide parameters
:option:`-I`. :option:`-I`.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
:c:type:`wchar_*` string. :c:expr:`wchar_*` string.
See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv` See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
members of the :ref:`Python Initialization Configuration <init-config>`. members of the :ref:`Python Initialization Configuration <init-config>`.
@ -813,7 +813,7 @@ Process-wide parameters
this storage. this storage.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
:c:type:`wchar_*` string. :c:expr:`wchar_*` string.
.. deprecated:: 3.11 .. deprecated:: 3.11
@ -1400,8 +1400,8 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
exception (if any) for the thread is cleared. This raises no exceptions. exception (if any) for the thread is cleared. This raises no exceptions.
.. versionchanged:: 3.7 .. versionchanged:: 3.7
The type of the *id* parameter changed from :c:type:`long` to The type of the *id* parameter changed from :c:expr:`long` to
:c:type:`unsigned long`. :c:expr:`unsigned long`.
.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate) .. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
@ -1863,7 +1863,7 @@ The Python interpreter provides low-level support for thread-local storage
(TLS) which wraps the underlying native TLS implementation to support the (TLS) which wraps the underlying native TLS implementation to support the
Python-level thread local storage API (:class:`threading.local`). The Python-level thread local storage API (:class:`threading.local`). The
CPython C level APIs are similar to those offered by pthreads and Windows: CPython C level APIs are similar to those offered by pthreads and Windows:
use a thread key and functions to associate a :c:type:`void*` value per use a thread key and functions to associate a :c:expr:`void*` value per
thread. thread.
The GIL does *not* need to be held when calling these functions; they supply The GIL does *not* need to be held when calling these functions; they supply
@ -1874,8 +1874,8 @@ you need to include :file:`pythread.h` to use thread-local storage.
.. note:: .. note::
None of these API functions handle memory management on behalf of the None of these API functions handle memory management on behalf of the
:c:type:`void*` values. You need to allocate and deallocate them yourself. :c:expr:`void*` values. You need to allocate and deallocate them yourself.
If the :c:type:`void*` values happen to be :c:expr:`PyObject*`, these If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these
functions don't do refcount operations on them either. functions don't do refcount operations on them either.
.. _thread-specific-storage-api: .. _thread-specific-storage-api:
@ -1885,7 +1885,7 @@ Thread Specific Storage (TSS) API
TSS API is introduced to supersede the use of the existing TLS API within the TSS API is introduced to supersede the use of the existing TLS API within the
CPython interpreter. This API uses a new type :c:type:`Py_tss_t` instead of CPython interpreter. This API uses a new type :c:type:`Py_tss_t` instead of
:c:type:`int` to represent thread keys. :c:expr:`int` to represent thread keys.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -1971,14 +1971,14 @@ undefined if the given :c:type:`Py_tss_t` has not been initialized by
.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value) .. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value)
Return a zero value to indicate successfully associating a :c:type:`void*` Return a zero value to indicate successfully associating a :c:expr:`void*`
value with a TSS key in the current thread. Each thread has a distinct value with a TSS key in the current thread. Each thread has a distinct
mapping of the key to a :c:type:`void*` value. mapping of the key to a :c:expr:`void*` value.
.. c:function:: void* PyThread_tss_get(Py_tss_t *key) .. c:function:: void* PyThread_tss_get(Py_tss_t *key)
Return the :c:type:`void*` value associated with a TSS key in the current Return the :c:expr:`void*` value associated with a TSS key in the current
thread. This returns ``NULL`` if no value is associated with the key in the thread. This returns ``NULL`` if no value is associated with the key in the
current thread. current thread.

4
Doc/c-api/intro.rst
View File

@ -530,8 +530,8 @@ Types
----- -----
There are few other data types that play a significant role in the Python/C There are few other data types that play a significant role in the Python/C
API; most are simple C types such as :c:type:`int`, :c:type:`long`, API; most are simple C types such as :c:expr:`int`, :c:expr:`long`,
:c:type:`double` and :c:type:`char*`. A few structure types are used to :c:expr:`double` and :c:expr:`char*`. A few structure types are used to
describe static tables used to list the functions exported by a module or the describe static tables used to list the functions exported by a module or the
data attributes of a new object type, and another is used to describe the value data attributes of a new object type, and another is used to describe the value
of a complex number. These will be discussed together with the functions that of a complex number. These will be discussed together with the functions that

42
Doc/c-api/long.rst
View File

@ -47,7 +47,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v) .. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long`, or
``NULL`` on failure. ``NULL`` on failure.
@ -65,13 +65,13 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: PyObject* PyLong_FromLongLong(long long v) .. c:function:: PyObject* PyLong_FromLongLong(long long v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or ``NULL`` Return a new :c:type:`PyLongObject` object from a C :c:expr:`long long`, or ``NULL``
on failure. on failure.
.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v) .. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`, Return a new :c:type:`PyLongObject` object from a C :c:expr:`unsigned long long`,
or ``NULL`` on failure. or ``NULL`` on failure.
@ -116,12 +116,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
single: LONG_MAX single: LONG_MAX
single: OverflowError (built-in exception) single: OverflowError (built-in exception)
Return a C :c:type:`long` representation of *obj*. If *obj* is not an Return a C :c:expr:`long` representation of *obj*. If *obj* is not an
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
(if present) to convert it to a :c:type:`PyLongObject`. (if present) to convert it to a :c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *obj* is out of range for a Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long`. :c:expr:`long`.
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
@ -134,7 +134,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow) .. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
Return a C :c:type:`long` representation of *obj*. If *obj* is not an Return a C :c:expr:`long` representation of *obj*. If *obj* is not an
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
method (if present) to convert it to a :c:type:`PyLongObject`. method (if present) to convert it to a :c:type:`PyLongObject`.
@ -157,12 +157,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. index:: .. index::
single: OverflowError (built-in exception) single: OverflowError (built-in exception)
Return a C :c:type:`long long` representation of *obj*. If *obj* is not an Return a C :c:expr:`long long` representation of *obj*. If *obj* is not an
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
(if present) to convert it to a :c:type:`PyLongObject`. (if present) to convert it to a :c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *obj* is out of range for a Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long long`. :c:expr:`long long`.
Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
@ -175,7 +175,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow) .. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
Return a C :c:type:`long long` representation of *obj*. If *obj* is not an Return a C :c:expr:`long long` representation of *obj*. If *obj* is not an
instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method instance of :c:type:`PyLongObject`, first call its :meth:`__index__` method
(if present) to convert it to a :c:type:`PyLongObject`. (if present) to convert it to a :c:type:`PyLongObject`.
@ -216,11 +216,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
single: ULONG_MAX single: ULONG_MAX
single: OverflowError (built-in exception) single: OverflowError (built-in exception)
Return a C :c:type:`unsigned long` representation of *pylong*. *pylong* Return a C :c:expr:`unsigned long` representation of *pylong*. *pylong*
must be an instance of :c:type:`PyLongObject`. must be an instance of :c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
:c:type:`unsigned long`. :c:expr:`unsigned long`.
Returns ``(unsigned long)-1`` on error. Returns ``(unsigned long)-1`` on error.
Use :c:func:`PyErr_Occurred` to disambiguate. Use :c:func:`PyErr_Occurred` to disambiguate.
@ -247,11 +247,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. index:: .. index::
single: OverflowError (built-in exception) single: OverflowError (built-in exception)
Return a C :c:type:`unsigned long long` representation of *pylong*. *pylong* Return a C :c:expr:`unsigned long long` representation of *pylong*. *pylong*
must be an instance of :c:type:`PyLongObject`. must be an instance of :c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *pylong* is out of range for an Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
:c:type:`unsigned long long`. :c:expr:`unsigned long long`.
Returns ``(unsigned long long)-1`` on error. Returns ``(unsigned long long)-1`` on error.
Use :c:func:`PyErr_Occurred` to disambiguate. Use :c:func:`PyErr_Occurred` to disambiguate.
@ -262,11 +262,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj) .. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
Return a C :c:type:`unsigned long` representation of *obj*. If *obj* is not Return a C :c:expr:`unsigned long` representation of *obj*. If *obj* is not
an instance of :c:type:`PyLongObject`, first call its :meth:`__index__` an instance of :c:type:`PyLongObject`, first call its :meth:`__index__`
method (if present) to convert it to a :c:type:`PyLongObject`. method (if present) to convert it to a :c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:type:`unsigned long`, If the value of *obj* is out of range for an :c:expr:`unsigned long`,
return the reduction of that value modulo ``ULONG_MAX + 1``. return the reduction of that value modulo ``ULONG_MAX + 1``.
Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to
@ -281,12 +281,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj) .. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
Return a C :c:type:`unsigned long long` representation of *obj*. If *obj* Return a C :c:expr:`unsigned long long` representation of *obj*. If *obj*
is not an instance of :c:type:`PyLongObject`, first call its is not an instance of :c:type:`PyLongObject`, first call its
:meth:`__index__` method (if present) to convert it to a :meth:`__index__` method (if present) to convert it to a
:c:type:`PyLongObject`. :c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:type:`unsigned long long`, If the value of *obj* is out of range for an :c:expr:`unsigned long long`,
return the reduction of that value modulo ``ULLONG_MAX + 1``. return the reduction of that value modulo ``ULLONG_MAX + 1``.
Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred` Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred`
@ -301,20 +301,20 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: double PyLong_AsDouble(PyObject *pylong) .. c:function:: double PyLong_AsDouble(PyObject *pylong)
Return a C :c:type:`double` representation of *pylong*. *pylong* must be Return a C :c:expr:`double` representation of *pylong*. *pylong* must be
an instance of :c:type:`PyLongObject`. an instance of :c:type:`PyLongObject`.
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
:c:type:`double`. :c:expr:`double`.
Returns ``-1.0`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. Returns ``-1.0`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong) .. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
Convert a Python integer *pylong* to a C :c:type:`void` pointer. Convert a Python integer *pylong* to a C :c:expr:`void` pointer.
If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
is only assured to produce a usable :c:type:`void` pointer for values created is only assured to produce a usable :c:expr:`void` pointer for values created
with :c:func:`PyLong_FromVoidPtr`. with :c:func:`PyLong_FromVoidPtr`.
Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.

12
Doc/c-api/marshal.rst
View File

@ -21,9 +21,9 @@ unmarshalling. Version 2 uses a binary format for floating point numbers.
.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version) .. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
Marshal a :c:type:`long` integer, *value*, to *file*. This will only write Marshal a :c:expr:`long` integer, *value*, to *file*. This will only write
the least-significant 32 bits of *value*; regardless of the size of the the least-significant 32 bits of *value*; regardless of the size of the
native :c:type:`long` type. *version* indicates the file format. native :c:expr:`long` type. *version* indicates the file format.
.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version) .. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
@ -43,9 +43,9 @@ The following functions allow marshalled values to be read back in.
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file) .. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
Return a C :c:type:`long` from the data stream in a :c:expr:`FILE*` opened Return a C :c:expr:`long` from the data stream in a :c:expr:`FILE*` opened
for reading. Only a 32-bit value can be read in using this function, for reading. Only a 32-bit value can be read in using this function,
regardless of the native size of :c:type:`long`. regardless of the native size of :c:expr:`long`.
On error, sets the appropriate exception (:exc:`EOFError`) and returns On error, sets the appropriate exception (:exc:`EOFError`) and returns
``-1``. ``-1``.
@ -53,9 +53,9 @@ The following functions allow marshalled values to be read back in.
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file) .. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
Return a C :c:type:`short` from the data stream in a :c:expr:`FILE*` opened Return a C :c:expr:`short` from the data stream in a :c:expr:`FILE*` opened
for reading. Only a 16-bit value can be read in using this function, for reading. Only a 16-bit value can be read in using this function,
regardless of the native size of :c:type:`short`. regardless of the native size of :c:expr:`short`.
On error, sets the appropriate exception (:exc:`EOFError`) and returns On error, sets the appropriate exception (:exc:`EOFError`) and returns
``-1``. ``-1``.

12
Doc/c-api/memory.rst
View File

@ -141,7 +141,7 @@ zero bytes.
.. c:function:: void* PyMem_RawMalloc(size_t n) .. c:function:: void* PyMem_RawMalloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the
allocated memory, or ``NULL`` if the request fails. allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -152,7 +152,7 @@ zero bytes.
.. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize) .. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros. request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct Requesting zero elements or elements of size zero bytes returns a distinct
@ -212,7 +212,7 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
.. c:function:: void* PyMem_Malloc(size_t n) .. c:function:: void* PyMem_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the
allocated memory, or ``NULL`` if the request fails. allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -223,7 +223,7 @@ The :ref:`default memory allocator <default-memory-allocators>` uses the
.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize) .. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros. request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct Requesting zero elements or elements of size zero bytes returns a distinct
@ -320,7 +320,7 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
.. c:function:: void* PyObject_Malloc(size_t n) .. c:function:: void* PyObject_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void*` to the Allocates *n* bytes and returns a pointer of type :c:expr:`void*` to the
allocated memory, or ``NULL`` if the request fails. allocated memory, or ``NULL`` if the request fails.
Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as Requesting zero bytes returns a distinct non-``NULL`` pointer if possible, as
@ -331,7 +331,7 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize) .. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
Allocates *nelem* elements each whose size in bytes is *elsize* and returns Allocates *nelem* elements each whose size in bytes is *elsize* and returns
a pointer of type :c:type:`void*` to the allocated memory, or ``NULL`` if the a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the
request fails. The memory is initialized to zeros. request fails. The memory is initialized to zeros.
Requesting zero elements or elements of size zero bytes returns a distinct Requesting zero elements or elements of size zero bytes returns a distinct

6
Doc/c-api/sys.rst
View File

@ -107,7 +107,7 @@ Operating System Utilities
Return the current signal handler for signal *i*. This is a thin wrapper around Return the current signal handler for signal *i*. This is a thin wrapper around
either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void
(\*)(int)`. (\*)(int)`.
@ -116,7 +116,7 @@ Operating System Utilities
Set the signal handler for signal *i* to be *h*; return the old signal handler. Set the signal handler for signal *i* to be *h*; return the old signal handler.
This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
alias for :c:type:`void (\*)(int)`. alias for :c:expr:`void (\*)(int)`.
.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size) .. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
@ -379,7 +379,7 @@ accessible to C code. They all work with the current interpreter thread's
silently abort the operation by raising an error subclassed from silently abort the operation by raising an error subclassed from
:class:`Exception` (other errors will not be silenced). :class:`Exception` (other errors will not be silenced).
The hook function is of type :c:type:`int (*)(const char *event, PyObject The hook function is of type :c:expr:`int (*)(const char *event, PyObject
*args, void *userData)`, where *args* is guaranteed to be a *args, void *userData)`, where *args* is guaranteed to be a
:c:type:`PyTupleObject`. The hook function is always called with the GIL :c:type:`PyTupleObject`. The hook function is always called with the GIL
held by the Python interpreter that raised the event. held by the Python interpreter that raised the event.

24
Doc/c-api/unicode.rst
View File

@ -44,7 +44,7 @@ Python:
.. c:type:: Py_UNICODE .. c:type:: Py_UNICODE
This is a typedef of :c:type:`wchar_t`, which is a 16-bit type or 32-bit type This is a typedef of :c:expr:`wchar_t`, which is a 16-bit type or 32-bit type
depending on the platform. depending on the platform.
.. versionchanged:: 3.3 .. versionchanged:: 3.3
@ -788,11 +788,11 @@ conversion function:
wchar_t Support wchar_t Support
""""""""""""""" """""""""""""""
:c:type:`wchar_t` support for platforms which support it: :c:expr:`wchar_t` support for platforms which support it:
.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size) .. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*. Create a Unicode object from the :c:expr:`wchar_t` buffer *w* of the given *size*.
Passing ``-1`` as the *size* indicates that the function must itself compute the length, Passing ``-1`` as the *size* indicates that the function must itself compute the length,
using wcslen. using wcslen.
Return ``NULL`` on failure. Return ``NULL`` on failure.
@ -800,13 +800,13 @@ wchar_t Support
.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size) .. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)
Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most Copy the Unicode object contents into the :c:expr:`wchar_t` buffer *w*. At most
*size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing *size* :c:expr:`wchar_t` characters are copied (excluding a possibly trailing
null termination character). Return the number of :c:type:`wchar_t` characters null termination character). Return the number of :c:expr:`wchar_t` characters
copied or ``-1`` in case of an error. Note that the resulting :c:type:`wchar_t*` copied or ``-1`` in case of an error. Note that the resulting :c:expr:`wchar_t*`
string may or may not be null-terminated. It is the responsibility of the caller string may or may not be null-terminated. It is the responsibility of the caller
to make sure that the :c:type:`wchar_t*` string is null-terminated in case this is to make sure that the :c:expr:`wchar_t*` string is null-terminated in case this is
required by the application. Also, note that the :c:type:`wchar_t*` string required by the application. Also, note that the :c:expr:`wchar_t*` string
might contain null characters, which would cause the string to be truncated might contain null characters, which would cause the string to be truncated
when used with most C functions. when used with most C functions.
@ -816,9 +816,9 @@ wchar_t Support
Convert the Unicode object to a wide character string. The output string Convert the Unicode object to a wide character string. The output string
always ends with a null character. If *size* is not ``NULL``, write the number always ends with a null character. If *size* is not ``NULL``, write the number
of wide characters (excluding the trailing null termination character) into of wide characters (excluding the trailing null termination character) into
*\*size*. Note that the resulting :c:type:`wchar_t` string might contain *\*size*. Note that the resulting :c:expr:`wchar_t` string might contain
null characters, which would cause the string to be truncated when used with null characters, which would cause the string to be truncated when used with
most C functions. If *size* is ``NULL`` and the :c:type:`wchar_t*` string most C functions. If *size* is ``NULL`` and the :c:expr:`wchar_t*` string
contains null characters a :exc:`ValueError` is raised. contains null characters a :exc:`ValueError` is raised.
Returns a buffer allocated by :c:func:`PyMem_New` (use Returns a buffer allocated by :c:func:`PyMem_New` (use
@ -829,7 +829,7 @@ wchar_t Support
.. versionadded:: 3.2 .. versionadded:: 3.2
.. versionchanged:: 3.7 .. versionchanged:: 3.7
Raises a :exc:`ValueError` if *size* is ``NULL`` and the :c:type:`wchar_t*` Raises a :exc:`ValueError` if *size* is ``NULL`` and the :c:expr:`wchar_t*`
string contains null characters. string contains null characters.

8
Doc/extending/extending.rst
View File

@ -298,7 +298,7 @@ In this case, it will return an integer object. (Yes, even integers are objects
on the heap in Python!) on the heap in Python!)
If you have a C function that returns no useful argument (a function returning If you have a C function that returns no useful argument (a function returning
:c:type:`void`), the corresponding Python function must return ``None``. You :c:expr:`void`), the corresponding Python function must return ``None``. You
need this idiom to do so (which is implemented by the :c:macro:`Py_RETURN_NONE` need this idiom to do so (which is implemented by the :c:macro:`Py_RETURN_NONE`
macro):: macro)::
@ -1171,7 +1171,7 @@ other extension modules must be exported in a different way.
Python provides a special mechanism to pass C-level information (pointers) from Python provides a special mechanism to pass C-level information (pointers) from
one extension module to another one: Capsules. A Capsule is a Python data type one extension module to another one: Capsules. A Capsule is a Python data type
which stores a pointer (:c:type:`void \*`). Capsules can only be created and which stores a pointer (:c:expr:`void \*`). Capsules can only be created and
accessed via their C API, but they can be passed around like any other Python accessed via their C API, but they can be passed around like any other Python
object. In particular, they can be assigned to a name in an extension module's object. In particular, they can be assigned to a name in an extension module's
namespace. Other extension modules can then import this module, retrieve the namespace. Other extension modules can then import this module, retrieve the
@ -1185,7 +1185,7 @@ different ways between the module providing the code and the client modules.
Whichever method you choose, it's important to name your Capsules properly. Whichever method you choose, it's important to name your Capsules properly.
The function :c:func:`PyCapsule_New` takes a name parameter The function :c:func:`PyCapsule_New` takes a name parameter
(:c:type:`const char \*`); you're permitted to pass in a ``NULL`` name, but (:c:expr:`const char \*`); you're permitted to pass in a ``NULL`` name, but
we strongly encourage you to specify a name. Properly named Capsules provide we strongly encourage you to specify a name. Properly named Capsules provide
a degree of runtime type-safety; there is no feasible way to tell one unnamed a degree of runtime type-safety; there is no feasible way to tell one unnamed
Capsule from another. Capsule from another.
@ -1203,7 +1203,7 @@ of certainty that the Capsule they load contains the correct C API.
The following example demonstrates an approach that puts most of the burden on The following example demonstrates an approach that puts most of the burden on
the writer of the exporting module, which is appropriate for commonly used the writer of the exporting module, which is appropriate for commonly used
library modules. It stores all C API pointers (just one in the example!) in an library modules. It stores all C API pointers (just one in the example!) in an
array of :c:type:`void` pointers which becomes the value of a Capsule. The header array of :c:expr:`void` pointers which becomes the value of a Capsule. The header
file corresponding to the module provides a macro that takes care of importing file corresponding to the module provides a macro that takes care of importing
the module and retrieving its C API pointers; client modules only have to call the module and retrieving its C API pointers; client modules only have to call
this macro before accessing the C API. this macro before accessing the C API.

6
Doc/extending/newtypes.rst
View File

@ -207,7 +207,7 @@ a special case, for which the new value passed to the handler is ``NULL``.
Python supports two pairs of attribute handlers; a type that supports attributes Python supports two pairs of attribute handlers; a type that supports attributes
only needs to implement the functions for one pair. The difference is that one only needs to implement the functions for one pair. The difference is that one
pair takes the name of the attribute as a :c:type:`char\*`, while the other pair takes the name of the attribute as a :c:expr:`char\*`, while the other
accepts a :c:type:`PyObject\*`. Each type can use whichever pair makes more accepts a :c:type:`PyObject\*`. Each type can use whichever pair makes more
sense for the implementation's convenience. :: sense for the implementation's convenience. ::
@ -339,8 +339,8 @@ of ``NULL`` is required.
Type-specific Attribute Management Type-specific Attribute Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For simplicity, only the :c:type:`char\*` version will be demonstrated here; the For simplicity, only the :c:expr:`char\*` version will be demonstrated here; the
type of the name parameter is the only difference between the :c:type:`char\*` type of the name parameter is the only difference between the :c:expr:`char\*`
and :c:type:`PyObject\*` flavors of the interface. This example effectively does and :c:type:`PyObject\*` flavors of the interface. This example effectively does
the same thing as the generic example above, but does not use the generic the same thing as the generic example above, but does not use the generic
support added in Python 2.2. It explains how the handler functions are support added in Python 2.2. It explains how the handler functions are

120
Doc/library/ctypes.rst
View File

@ -196,9 +196,9 @@ calls).
``None``, integers, bytes objects and (unicode) strings are the only native ``None``, integers, bytes objects and (unicode) strings are the only native
Python objects that can directly be used as parameters in these function calls. Python objects that can directly be used as parameters in these function calls.
``None`` is passed as a C ``NULL`` pointer, bytes objects and strings are passed ``None`` is passed as a C ``NULL`` pointer, bytes objects and strings are passed
as pointer to the memory block that contains their data (:c:type:`char *` or as pointer to the memory block that contains their data (:c:expr:`char *` or
:c:type:`wchar_t *`). Python integers are passed as the platforms default C :c:expr:`wchar_t *`). Python integers are passed as the platforms default C
:c:type:`int` type, their value is masked to fit into the C type. :c:expr:`int` type, their value is masked to fit into the C type.
Before we move on calling functions with other parameter types, we have to learn Before we move on calling functions with other parameter types, we have to learn
more about :mod:`ctypes` data types. more about :mod:`ctypes` data types.
@ -214,51 +214,51 @@ Fundamental data types
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| ctypes type | C type | Python type | | ctypes type | C type | Python type |
+======================+==========================================+============================+ +======================+==========================================+============================+
| :class:`c_bool` | :c:type:`_Bool` | bool (1) | | :class:`c_bool` | :c:expr:`_Bool` | bool (1) |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_char` | :c:type:`char` | 1-character bytes object | | :class:`c_char` | :c:expr:`char` | 1-character bytes object |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_wchar` | :c:type:`wchar_t` | 1-character string | | :class:`c_wchar` | :c:expr:`wchar_t` | 1-character string |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_byte` | :c:type:`char` | int | | :class:`c_byte` | :c:expr:`char` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_ubyte` | :c:type:`unsigned char` | int | | :class:`c_ubyte` | :c:expr:`unsigned char` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_short` | :c:type:`short` | int | | :class:`c_short` | :c:expr:`short` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_ushort` | :c:type:`unsigned short` | int | | :class:`c_ushort` | :c:expr:`unsigned short` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_int` | :c:type:`int` | int | | :class:`c_int` | :c:expr:`int` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_uint` | :c:type:`unsigned int` | int | | :class:`c_uint` | :c:expr:`unsigned int` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_long` | :c:type:`long` | int | | :class:`c_long` | :c:expr:`long` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_ulong` | :c:type:`unsigned long` | int | | :class:`c_ulong` | :c:expr:`unsigned long` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_longlong` | :c:type:`__int64` or :c:type:`long long` | int | | :class:`c_longlong` | :c:expr:`__int64` or :c:expr:`long long` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_ulonglong` | :c:type:`unsigned __int64` or | int | | :class:`c_ulonglong` | :c:expr:`unsigned __int64` or | int |
| | :c:type:`unsigned long long` | | | | :c:expr:`unsigned long long` | |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_size_t` | :c:type:`size_t` | int | | :class:`c_size_t` | :c:expr:`size_t` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_ssize_t` | :c:type:`ssize_t` or | int | | :class:`c_ssize_t` | :c:expr:`ssize_t` or | int |
| | :c:type:`Py_ssize_t` | | | | :c:expr:`Py_ssize_t` | |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_time_t` | :c:type:`time_t` | int | | :class:`c_time_t` | :c:type:`time_t` | int |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_float` | :c:type:`float` | float | | :class:`c_float` | :c:expr:`float` | float |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_double` | :c:type:`double` | float | | :class:`c_double` | :c:expr:`double` | float |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_longdouble`| :c:type:`long double` | float | | :class:`c_longdouble`| :c:expr:`long double` | float |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_char_p` | :c:type:`char *` (NUL terminated) | bytes object or ``None`` | | :class:`c_char_p` | :c:expr:`char *` (NUL terminated) | bytes object or ``None`` |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_wchar_p` | :c:type:`wchar_t *` (NUL terminated) | string or ``None`` | | :class:`c_wchar_p` | :c:expr:`wchar_t *` (NUL terminated) | string or ``None`` |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
| :class:`c_void_p` | :c:type:`void *` | int or ``None`` | | :class:`c_void_p` | :c:expr:`void *` | int or ``None`` |
+----------------------+------------------------------------------+----------------------------+ +----------------------+------------------------------------------+----------------------------+
(1) (1)
@ -333,7 +333,7 @@ property::
The :func:`create_string_buffer` function replaces the old :func:`c_buffer` The :func:`create_string_buffer` function replaces the old :func:`c_buffer`
function (which is still available as an alias). To create a mutable memory function (which is still available as an alias). To create a mutable memory
block containing unicode characters of the C type :c:type:`wchar_t`, use the block containing unicode characters of the C type :c:expr:`wchar_t`, use the
:func:`create_unicode_buffer` function. :func:`create_unicode_buffer` function.
@ -444,7 +444,7 @@ integer, string, bytes, a :mod:`ctypes` instance, or an object with an
Return types Return types
^^^^^^^^^^^^ ^^^^^^^^^^^^
By default functions are assumed to return the C :c:type:`int` type. Other By default functions are assumed to return the C :c:expr:`int` type. Other
return types can be specified by setting the :attr:`restype` attribute of the return types can be specified by setting the :attr:`restype` attribute of the
function object. function object.
@ -1337,7 +1337,7 @@ way is to instantiate one of the following classes:
Instances of this class represent loaded shared libraries. Functions in these Instances of this class represent loaded shared libraries. Functions in these
libraries use the standard C calling convention, and are assumed to return libraries use the standard C calling convention, and are assumed to return
:c:type:`int`. :c:expr:`int`.
On Windows creating a :class:`CDLL` instance may fail even if the DLL name On Windows creating a :class:`CDLL` instance may fail even if the DLL name
exists. When a dependent DLL of the loaded DLL is not found, a exists. When a dependent DLL of the loaded DLL is not found, a
@ -1372,7 +1372,7 @@ way is to instantiate one of the following classes:
Windows only: Instances of this class represent loaded shared libraries, Windows only: Instances of this class represent loaded shared libraries,
functions in these libraries use the ``stdcall`` calling convention, and are functions in these libraries use the ``stdcall`` calling convention, and are
assumed to return :c:type:`int` by default. assumed to return :c:expr:`int` by default.
The Python :term:`global interpreter lock` is released before calling any The Python :term:`global interpreter lock` is released before calling any
function exported by these libraries, and reacquired afterwards. function exported by these libraries, and reacquired afterwards.
@ -1528,7 +1528,7 @@ object is available:
An instance of :class:`PyDLL` that exposes Python C API functions as An instance of :class:`PyDLL` that exposes Python C API functions as
attributes. Note that all these functions are assumed to return C attributes. Note that all these functions are assumed to return C
:c:type:`int`, which is of course not always the truth, so you have to assign :c:expr:`int`, which is of course not always the truth, so you have to assign
the correct :attr:`restype` attribute to use these functions. the correct :attr:`restype` attribute to use these functions.
.. audit-event:: ctypes.dlopen name ctypes.LibraryLoader .. audit-event:: ctypes.dlopen name ctypes.LibraryLoader
@ -1574,10 +1574,10 @@ They are instances of a private class:
.. attribute:: restype .. attribute:: restype
Assign a ctypes type to specify the result type of the foreign function. Assign a ctypes type to specify the result type of the foreign function.
Use ``None`` for :c:type:`void`, a function not returning anything. Use ``None`` for :c:expr:`void`, a function not returning anything.
It is possible to assign a callable Python object that is not a ctypes It is possible to assign a callable Python object that is not a ctypes
type, in this case the function is assumed to return a C :c:type:`int`, and type, in this case the function is assumed to return a C :c:expr:`int`, and
the callable will be called with this integer, allowing further the callable will be called with this integer, allowing further
processing or error checking. Using this is deprecated, for more flexible processing or error checking. Using this is deprecated, for more flexible
post processing or error checking use a ctypes data type as post processing or error checking use a ctypes data type as
@ -2190,21 +2190,21 @@ These are the fundamental ctypes data types:
.. class:: c_byte .. class:: c_byte
Represents the C :c:type:`signed char` datatype, and interprets the value as Represents the C :c:expr:`signed char` datatype, and interprets the value as
small integer. The constructor accepts an optional integer initializer; no small integer. The constructor accepts an optional integer initializer; no
overflow checking is done. overflow checking is done.
.. class:: c_char .. class:: c_char
Represents the C :c:type:`char` datatype, and interprets the value as a single Represents the C :c:expr:`char` datatype, and interprets the value as a single
character. The constructor accepts an optional string initializer, the character. The constructor accepts an optional string initializer, the
length of the string must be exactly one character. length of the string must be exactly one character.
.. class:: c_char_p .. class:: c_char_p
Represents the C :c:type:`char *` datatype when it points to a zero-terminated Represents the C :c:expr:`char *` datatype when it points to a zero-terminated
string. For a general character pointer that may also point to binary data, string. For a general character pointer that may also point to binary data,
``POINTER(c_char)`` must be used. The constructor accepts an integer ``POINTER(c_char)`` must be used. The constructor accepts an integer
address, or a bytes object. address, or a bytes object.
@ -2212,68 +2212,68 @@ These are the fundamental ctypes data types:
.. class:: c_double .. class:: c_double
Represents the C :c:type:`double` datatype. The constructor accepts an Represents the C :c:expr:`double` datatype. The constructor accepts an
optional float initializer. optional float initializer.
.. class:: c_longdouble .. class:: c_longdouble
Represents the C :c:type:`long double` datatype. The constructor accepts an Represents the C :c:expr:`long double` datatype. The constructor accepts an
optional float initializer. On platforms where ``sizeof(long double) == optional float initializer. On platforms where ``sizeof(long double) ==
sizeof(double)`` it is an alias to :class:`c_double`. sizeof(double)`` it is an alias to :class:`c_double`.
.. class:: c_float .. class:: c_float
Represents the C :c:type:`float` datatype. The constructor accepts an Represents the C :c:expr:`float` datatype. The constructor accepts an
optional float initializer. optional float initializer.
.. class:: c_int .. class:: c_int
Represents the C :c:type:`signed int` datatype. The constructor accepts an Represents the C :c:expr:`signed int` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done. On platforms optional integer initializer; no overflow checking is done. On platforms
where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`. where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`.
.. class:: c_int8 .. class:: c_int8
Represents the C 8-bit :c:type:`signed int` datatype. Usually an alias for Represents the C 8-bit :c:expr:`signed int` datatype. Usually an alias for
:class:`c_byte`. :class:`c_byte`.
.. class:: c_int16 .. class:: c_int16
Represents the C 16-bit :c:type:`signed int` datatype. Usually an alias for Represents the C 16-bit :c:expr:`signed int` datatype. Usually an alias for
:class:`c_short`. :class:`c_short`.
.. class:: c_int32 .. class:: c_int32
Represents the C 32-bit :c:type:`signed int` datatype. Usually an alias for Represents the C 32-bit :c:expr:`signed int` datatype. Usually an alias for
:class:`c_int`. :class:`c_int`.
.. class:: c_int64 .. class:: c_int64
Represents the C 64-bit :c:type:`signed int` datatype. Usually an alias for Represents the C 64-bit :c:expr:`signed int` datatype. Usually an alias for
:class:`c_longlong`. :class:`c_longlong`.
.. class:: c_long .. class:: c_long
Represents the C :c:type:`signed long` datatype. The constructor accepts an Represents the C :c:expr:`signed long` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done. optional integer initializer; no overflow checking is done.
.. class:: c_longlong .. class:: c_longlong
Represents the C :c:type:`signed long long` datatype. The constructor accepts Represents the C :c:expr:`signed long long` datatype. The constructor accepts
an optional integer initializer; no overflow checking is done. an optional integer initializer; no overflow checking is done.
.. class:: c_short .. class:: c_short
Represents the C :c:type:`signed short` datatype. The constructor accepts an Represents the C :c:expr:`signed short` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done. optional integer initializer; no overflow checking is done.
@ -2298,83 +2298,83 @@ These are the fundamental ctypes data types:
.. class:: c_ubyte .. class:: c_ubyte
Represents the C :c:type:`unsigned char` datatype, it interprets the value as Represents the C :c:expr:`unsigned char` datatype, it interprets the value as
small integer. The constructor accepts an optional integer initializer; no small integer. The constructor accepts an optional integer initializer; no
overflow checking is done. overflow checking is done.
.. class:: c_uint .. class:: c_uint
Represents the C :c:type:`unsigned int` datatype. The constructor accepts an Represents the C :c:expr:`unsigned int` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done. On platforms optional integer initializer; no overflow checking is done. On platforms
where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`. where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`.
.. class:: c_uint8 .. class:: c_uint8
Represents the C 8-bit :c:type:`unsigned int` datatype. Usually an alias for Represents the C 8-bit :c:expr:`unsigned int` datatype. Usually an alias for
:class:`c_ubyte`. :class:`c_ubyte`.
.. class:: c_uint16 .. class:: c_uint16
Represents the C 16-bit :c:type:`unsigned int` datatype. Usually an alias for Represents the C 16-bit :c:expr:`unsigned int` datatype. Usually an alias for
:class:`c_ushort`. :class:`c_ushort`.
.. class:: c_uint32 .. class:: c_uint32
Represents the C 32-bit :c:type:`unsigned int` datatype. Usually an alias for Represents the C 32-bit :c:expr:`unsigned int` datatype. Usually an alias for
:class:`c_uint`. :class:`c_uint`.
.. class:: c_uint64 .. class:: c_uint64
Represents the C 64-bit :c:type:`unsigned int` datatype. Usually an alias for Represents the C 64-bit :c:expr:`unsigned int` datatype. Usually an alias for
:class:`c_ulonglong`. :class:`c_ulonglong`.
.. class:: c_ulong .. class:: c_ulong
Represents the C :c:type:`unsigned long` datatype. The constructor accepts an Represents the C :c:expr:`unsigned long` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done. optional integer initializer; no overflow checking is done.
.. class:: c_ulonglong .. class:: c_ulonglong
Represents the C :c:type:`unsigned long long` datatype. The constructor Represents the C :c:expr:`unsigned long long` datatype. The constructor
accepts an optional integer initializer; no overflow checking is done. accepts an optional integer initializer; no overflow checking is done.
.. class:: c_ushort .. class:: c_ushort
Represents the C :c:type:`unsigned short` datatype. The constructor accepts Represents the C :c:expr:`unsigned short` datatype. The constructor accepts
an optional integer initializer; no overflow checking is done. an optional integer initializer; no overflow checking is done.
.. class:: c_void_p .. class:: c_void_p
Represents the C :c:type:`void *` type. The value is represented as integer. Represents the C :c:expr:`void *` type. The value is represented as integer.
The constructor accepts an optional integer initializer. The constructor accepts an optional integer initializer.
.. class:: c_wchar .. class:: c_wchar
Represents the C :c:type:`wchar_t` datatype, and interprets the value as a Represents the C :c:expr:`wchar_t` datatype, and interprets the value as a
single character unicode string. The constructor accepts an optional string single character unicode string. The constructor accepts an optional string
initializer, the length of the string must be exactly one character. initializer, the length of the string must be exactly one character.
.. class:: c_wchar_p .. class:: c_wchar_p
Represents the C :c:type:`wchar_t *` datatype, which must be a pointer to a Represents the C :c:expr:`wchar_t *` datatype, which must be a pointer to a
zero-terminated wide character string. The constructor accepts an integer zero-terminated wide character string. The constructor accepts an integer
address, or a string. address, or a string.
.. class:: c_bool .. class:: c_bool
Represent the C :c:type:`bool` datatype (more accurately, :c:type:`_Bool` from Represent the C :c:expr:`bool` datatype (more accurately, :c:expr:`_Bool` from
C99). Its value can be ``True`` or ``False``, and the constructor accepts any object C99). Its value can be ``True`` or ``False``, and the constructor accepts any object
that has a truth value. that has a truth value.

4
Doc/library/posix.rst
View File

@ -39,12 +39,12 @@ Large File Support
Several operating systems (including AIX and Solaris) provide Several operating systems (including AIX and Solaris) provide
support for files that are larger than 2 GiB from a C programming model where support for files that are larger than 2 GiB from a C programming model where
:c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished :c:expr:`int` and :c:expr:`long` are 32-bit values. This is typically accomplished
by defining the relevant size and offset types as 64-bit values. Such files are by defining the relevant size and offset types as 64-bit values. Such files are
sometimes referred to as :dfn:`large files`. sometimes referred to as :dfn:`large files`.
Large file support is enabled in Python when the size of an :c:type:`off_t` is Large file support is enabled in Python when the size of an :c:type:`off_t` is
larger than a :c:type:`long` and the :c:type:`long long` is at least as large larger than a :c:expr:`long` and the :c:expr:`long long` is at least as large
as an :c:type:`off_t`. as an :c:type:`off_t`.
It may be necessary to configure and compile Python with certain compiler flags It may be necessary to configure and compile Python with certain compiler flags
to enable this mode. For example, with Solaris 2.6 and 2.7 you need to do to enable this mode. For example, with Solaris 2.6 and 2.7 you need to do

2
Doc/library/socket.rst
View File

@ -1612,7 +1612,7 @@ to sockets.
ancillary data, items of the form ``(socket.SOL_SOCKET, ancillary data, items of the form ``(socket.SOL_SOCKET,
socket.SCM_RIGHTS, fds)``, where *fds* is a :class:`bytes` object socket.SCM_RIGHTS, fds)``, where *fds* is a :class:`bytes` object
representing the new file descriptors as a binary array of the representing the new file descriptors as a binary array of the
native C :c:type:`int` type. If :meth:`recvmsg` raises an native C :c:expr:`int` type. If :meth:`recvmsg` raises an
exception after the system call returns, it will first attempt to exception after the system call returns, it will first attempt to
close any file descriptors received via this mechanism. close any file descriptors received via this mechanism.

2
Doc/library/stdtypes.rst
View File

@ -215,7 +215,7 @@ Numeric Types --- :class:`int`, :class:`float`, :class:`complex`
There are three distinct numeric types: :dfn:`integers`, :dfn:`floating There are three distinct numeric types: :dfn:`integers`, :dfn:`floating
point numbers`, and :dfn:`complex numbers`. In addition, Booleans are a point numbers`, and :dfn:`complex numbers`. In addition, Booleans are a
subtype of integers. Integers have unlimited precision. Floating point subtype of integers. Integers have unlimited precision. Floating point
numbers are usually implemented using :c:type:`double` in C; information numbers are usually implemented using :c:expr:`double` in C; information
about the precision and internal representation of floating point about the precision and internal representation of floating point
numbers for the machine on which your program is running is available numbers for the machine on which your program is running is available
in :data:`sys.float_info`. Complex numbers have a real and imaginary in :data:`sys.float_info`. Complex numbers have a real and imaginary

42
Doc/library/struct.rst
View File

@ -196,46 +196,46 @@ platform-dependent.
+========+==========================+====================+================+============+ +========+==========================+====================+================+============+
| ``x`` | pad byte | no value | | | | ``x`` | pad byte | no value | | |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``c`` | :c:type:`char` | bytes of length 1 | 1 | | | ``c`` | :c:expr:`char` | bytes of length 1 | 1 | |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``b`` | :c:type:`signed char` | integer | 1 | \(1), \(2) | | ``b`` | :c:expr:`signed char` | integer | 1 | \(1), \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``B`` | :c:type:`unsigned char` | integer | 1 | \(2) | | ``B`` | :c:expr:`unsigned char` | integer | 1 | \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``?`` | :c:type:`_Bool` | bool | 1 | \(1) | | ``?`` | :c:expr:`_Bool` | bool | 1 | \(1) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``h`` | :c:type:`short` | integer | 2 | \(2) | | ``h`` | :c:expr:`short` | integer | 2 | \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``H`` | :c:type:`unsigned short` | integer | 2 | \(2) | | ``H`` | :c:expr:`unsigned short` | integer | 2 | \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``i`` | :c:type:`int` | integer | 4 | \(2) | | ``i`` | :c:expr:`int` | integer | 4 | \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``I`` | :c:type:`unsigned int` | integer | 4 | \(2) | | ``I`` | :c:expr:`unsigned int` | integer | 4 | \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``l`` | :c:type:`long` | integer | 4 | \(2) | | ``l`` | :c:expr:`long` | integer | 4 | \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``L`` | :c:type:`unsigned long` | integer | 4 | \(2) | | ``L`` | :c:expr:`unsigned long` | integer | 4 | \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``q`` | :c:type:`long long` | integer | 8 | \(2) | | ``q`` | :c:expr:`long long` | integer | 8 | \(2) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``Q`` | :c:type:`unsigned long | integer | 8 | \(2) | | ``Q`` | :c:expr:`unsigned long | integer | 8 | \(2) |
| | long` | | | | | | long` | | | |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``n`` | :c:type:`ssize_t` | integer | | \(3) | | ``n`` | :c:expr:`ssize_t` | integer | | \(3) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``N`` | :c:type:`size_t` | integer | | \(3) | | ``N`` | :c:expr:`size_t` | integer | | \(3) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``e`` | \(6) | float | 2 | \(4) | | ``e`` | \(6) | float | 2 | \(4) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``f`` | :c:type:`float` | float | 4 | \(4) | | ``f`` | :c:expr:`float` | float | 4 | \(4) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``d`` | :c:type:`double` | float | 8 | \(4) | | ``d`` | :c:expr:`double` | float | 8 | \(4) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``s`` | :c:type:`char[]` | bytes | | | | ``s`` | :c:expr:`char[]` | bytes | | |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``p`` | :c:type:`char[]` | bytes | | | | ``p`` | :c:expr:`char[]` | bytes | | |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
| ``P`` | :c:type:`void \*` | integer | | \(5) | | ``P`` | :c:expr:`void \*` | integer | | \(5) |
+--------+--------------------------+--------------------+----------------+------------+ +--------+--------------------------+--------------------+----------------+------------+
.. versionchanged:: 3.3 .. versionchanged:: 3.3
@ -250,8 +250,8 @@ Notes:
(1) (1)
.. index:: single: ? (question mark); in struct format strings .. index:: single: ? (question mark); in struct format strings
The ``'?'`` conversion code corresponds to the :c:type:`_Bool` type defined by The ``'?'`` conversion code corresponds to the :c:expr:`_Bool` type defined by
C99. If this type is not available, it is simulated using a :c:type:`char`. In C99. If this type is not available, it is simulated using a :c:expr:`char`. In
standard mode, it is always represented by one byte. standard mode, it is always represented by one byte.
(2) (2)

2
Doc/reference/datamodel.rst
View File

@ -316,7 +316,7 @@ Sequences
A string is a sequence of values that represent Unicode code points. A string is a sequence of values that represent Unicode code points.
All the code points in the range ``U+0000 - U+10FFFF`` can be All the code points in the range ``U+0000 - U+10FFFF`` can be
represented in a string. Python doesn't have a :c:type:`char` type; represented in a string. Python doesn't have a :c:expr:`char` type;
instead, every code point in the string is represented as a string instead, every code point in the string is represented as a string
object with length ``1``. The built-in function :func:`ord` object with length ``1``. The built-in function :func:`ord`
converts a code point from its string form to an integer in the converts a code point from its string form to an integer in the

2
Doc/whatsnew/2.2.rst
View File

@ -983,7 +983,7 @@ New and Improved Modules
Jun-ichiro "itojun" Hagino.) Jun-ichiro "itojun" Hagino.)
* Two new format characters were added to the :mod:`struct` module for 64-bit * Two new format characters were added to the :mod:`struct` module for 64-bit
integers on platforms that support the C :c:type:`long long` type. ``q`` is for integers on platforms that support the C :c:expr:`long long` type. ``q`` is for
a signed 64-bit integer, and ``Q`` is for an unsigned one. The value is a signed 64-bit integer, and ``Q`` is for an unsigned one. The value is
returned in Python's long integer type. (Contributed by Tim Peters.) returned in Python's long integer type. (Contributed by Tim Peters.)

4
Doc/whatsnew/2.3.rst
View File

@ -1905,8 +1905,8 @@ Changes to Python's build process and to the C API include:
"")`` instead, but this will be slower than using :const:`METH_NOARGS`. "")`` instead, but this will be slower than using :const:`METH_NOARGS`.
* :c:func:`PyArg_ParseTuple` accepts new format characters for various sizes of * :c:func:`PyArg_ParseTuple` accepts new format characters for various sizes of
unsigned integers: ``B`` for :c:type:`unsigned char`, ``H`` for :c:type:`unsigned unsigned integers: ``B`` for :c:expr:`unsigned char`, ``H`` for :c:expr:`unsigned
short int`, ``I`` for :c:type:`unsigned int`, and ``K`` for :c:type:`unsigned short int`, ``I`` for :c:expr:`unsigned int`, and ``K`` for :c:expr:`unsigned
long long`. long long`.
* A new function, ``PyObject_DelItemString(mapping, char *key)`` was added * A new function, ``PyObject_DelItemString(mapping, char *key)`` was added

8
Doc/whatsnew/2.4.rst
View File

@ -472,7 +472,7 @@ PEP 327: Decimal Data Type
========================== ==========================
Python has always supported floating-point (FP) numbers, based on the underlying Python has always supported floating-point (FP) numbers, based on the underlying
C :c:type:`double` type, as a data type. However, while most programming C :c:expr:`double` type, as a data type. However, while most programming
languages provide a floating-point type, many people (even programmers) are languages provide a floating-point type, many people (even programmers) are
unaware that floating-point numbers don't represent certain decimal fractions unaware that floating-point numbers don't represent certain decimal fractions
accurately. The new :class:`Decimal` type can represent these fractions accurately. The new :class:`Decimal` type can represent these fractions
@ -501,7 +501,7 @@ mantissa is multiplied by 4 (2 to the power of the exponent 2); 1.25 \* 4 equals
5. 5.
Modern systems usually provide floating-point support that conforms to a Modern systems usually provide floating-point support that conforms to a
standard called IEEE 754. C's :c:type:`double` type is usually implemented as a standard called IEEE 754. C's :c:expr:`double` type is usually implemented as a
64-bit IEEE 754 number, which uses 52 bits of space for the mantissa. This 64-bit IEEE 754 number, which uses 52 bits of space for the mantissa. This
means that numbers can only be specified to 52 bits of precision. If you're means that numbers can only be specified to 52 bits of precision. If you're
trying to represent numbers whose expansion repeats endlessly, the expansion is trying to represent numbers whose expansion repeats endlessly, the expansion is
@ -750,10 +750,10 @@ The solution described in the PEP is to add three new functions to the Python
API that perform ASCII-only conversions, ignoring the locale setting: API that perform ASCII-only conversions, ignoring the locale setting:
* ``PyOS_ascii_strtod(str, ptr)`` and ``PyOS_ascii_atof(str, ptr)`` * ``PyOS_ascii_strtod(str, ptr)`` and ``PyOS_ascii_atof(str, ptr)``
both convert a string to a C :c:type:`double`. both convert a string to a C :c:expr:`double`.
* ``PyOS_ascii_formatd(buffer, buf_len, format, d)`` converts a * ``PyOS_ascii_formatd(buffer, buf_len, format, d)`` converts a
:c:type:`double` to an ASCII string. :c:expr:`double` to an ASCII string.
The code for these functions came from the GLib library The code for these functions came from the GLib library
(https://developer.gnome.org/glib/stable/), whose developers kindly (https://developer.gnome.org/glib/stable/), whose developers kindly

20
Doc/whatsnew/2.5.rst
View File

@ -872,18 +872,18 @@ PEP 353: Using ssize_t as the index type
======================================== ========================================
A wide-ranging change to Python's C API, using a new :c:type:`Py_ssize_t` type A wide-ranging change to Python's C API, using a new :c:type:`Py_ssize_t` type
definition instead of :c:type:`int`, will permit the interpreter to handle more definition instead of :c:expr:`int`, will permit the interpreter to handle more
data on 64-bit platforms. This change doesn't affect Python's capacity on 32-bit data on 64-bit platforms. This change doesn't affect Python's capacity on 32-bit
platforms. platforms.
Various pieces of the Python interpreter used C's :c:type:`int` type to store Various pieces of the Python interpreter used C's :c:expr:`int` type to store
sizes or counts; for example, the number of items in a list or tuple were stored sizes or counts; for example, the number of items in a list or tuple were stored
in an :c:type:`int`. The C compilers for most 64-bit platforms still define in an :c:expr:`int`. The C compilers for most 64-bit platforms still define
:c:type:`int` as a 32-bit type, so that meant that lists could only hold up to :c:expr:`int` as a 32-bit type, so that meant that lists could only hold up to
``2**31 - 1`` = 2147483647 items. (There are actually a few different ``2**31 - 1`` = 2147483647 items. (There are actually a few different
programming models that 64-bit C compilers can use -- see programming models that 64-bit C compilers can use -- see
https://unix.org/version2/whatsnew/lp64_wp.html for a discussion -- but the https://unix.org/version2/whatsnew/lp64_wp.html for a discussion -- but the
most commonly available model leaves :c:type:`int` as 32 bits.) most commonly available model leaves :c:expr:`int` as 32 bits.)
A limit of 2147483647 items doesn't really matter on a 32-bit platform because A limit of 2147483647 items doesn't really matter on a 32-bit platform because
you'll run out of memory before hitting the length limit. Each list item you'll run out of memory before hitting the length limit. Each list item
@ -895,7 +895,7 @@ It's possible to address that much memory on a 64-bit platform, however. The
pointers for a list that size would only require 16 GiB of space, so it's not pointers for a list that size would only require 16 GiB of space, so it's not
unreasonable that Python programmers might construct lists that large. unreasonable that Python programmers might construct lists that large.
Therefore, the Python interpreter had to be changed to use some type other than Therefore, the Python interpreter had to be changed to use some type other than
:c:type:`int`, and this will be a 64-bit type on 64-bit platforms. The change :c:expr:`int`, and this will be a 64-bit type on 64-bit platforms. The change
will cause incompatibilities on 64-bit machines, so it was deemed worth making will cause incompatibilities on 64-bit machines, so it was deemed worth making
the transition now, while the number of 64-bit users is still relatively small. the transition now, while the number of 64-bit users is still relatively small.
(In 5 or 10 years, we may *all* be on 64-bit machines, and the transition would (In 5 or 10 years, we may *all* be on 64-bit machines, and the transition would
@ -909,7 +909,7 @@ may therefore need to have some variables changed to :c:type:`Py_ssize_t`.
The :c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` functions have a new The :c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` functions have a new
conversion code, ``n``, for :c:type:`Py_ssize_t`. :c:func:`PyArg_ParseTuple`'s conversion code, ``n``, for :c:type:`Py_ssize_t`. :c:func:`PyArg_ParseTuple`'s
``s#`` and ``t#`` still output :c:type:`int` by default, but you can define the ``s#`` and ``t#`` still output :c:expr:`int` by default, but you can define the
macro :c:macro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h` to make macro :c:macro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h` to make
them return :c:type:`Py_ssize_t`. them return :c:type:`Py_ssize_t`.
@ -1695,7 +1695,7 @@ attributes of the :class:`CDLL` object. ::
result = libc.printf("Line of output\n") result = libc.printf("Line of output\n")
Type constructors for the various C types are provided: :func:`c_int`, Type constructors for the various C types are provided: :func:`c_int`,
:func:`c_float`, :func:`c_double`, :func:`c_char_p` (equivalent to :c:type:`char :func:`c_float`, :func:`c_double`, :func:`c_char_p` (equivalent to :c:expr:`char
\*`), and so forth. Unlike Python's types, the C versions are all mutable; you \*`), and so forth. Unlike Python's types, the C versions are all mutable; you
can assign to their :attr:`value` attribute to change the wrapped value. Python can assign to their :attr:`value` attribute to change the wrapped value. Python
integers and strings will be automatically converted to the corresponding C integers and strings will be automatically converted to the corresponding C
@ -2093,7 +2093,7 @@ Changes to Python's build process and to the C API include:
* The largest change to the C API came from :pep:`353`, which modifies the * The largest change to the C API came from :pep:`353`, which modifies the
interpreter to use a :c:type:`Py_ssize_t` type definition instead of interpreter to use a :c:type:`Py_ssize_t` type definition instead of
:c:type:`int`. See the earlier section :ref:`pep-353` for a discussion of this :c:expr:`int`. See the earlier section :ref:`pep-353` for a discussion of this
change. change.
* The design of the bytecode compiler has changed a great deal, no longer * The design of the bytecode compiler has changed a great deal, no longer
@ -2264,7 +2264,7 @@ code:
Setting :attr:`rpc_paths` to ``None`` or an empty tuple disables this path Setting :attr:`rpc_paths` to ``None`` or an empty tuple disables this path
checking. checking.
* C API: Many functions now use :c:type:`Py_ssize_t` instead of :c:type:`int` to * C API: Many functions now use :c:type:`Py_ssize_t` instead of :c:expr:`int` to
allow processing more data on 64-bit machines. Extension code may need to make allow processing more data on 64-bit machines. Extension code may need to make
the same change to avoid warnings and to support 64-bit machines. See the the same change to avoid warnings and to support 64-bit machines. See the
earlier section :ref:`pep-353` for a discussion of this change. earlier section :ref:`pep-353` for a discussion of this change.

2
Doc/whatsnew/2.6.rst
View File

@ -2389,7 +2389,7 @@ changes, or look through the Subversion logs for all the details.
has been updated from version 2.3.2 in Python 2.5 to has been updated from version 2.3.2 in Python 2.5 to
version 2.4.1. version 2.4.1.
* The :mod:`struct` module now supports the C99 :c:type:`_Bool` type, * The :mod:`struct` module now supports the C99 :c:expr:`_Bool` type,
using the format character ``'?'``. using the format character ``'?'``.
(Contributed by David Remahl.) (Contributed by David Remahl.)

4
Doc/whatsnew/2.7.rst
View File

@ -2144,7 +2144,7 @@ Changes to Python's build process and to the C API include:
* New functions: :c:func:`PyLong_AsLongAndOverflow` and * New functions: :c:func:`PyLong_AsLongAndOverflow` and
:c:func:`PyLong_AsLongLongAndOverflow` approximates a Python long :c:func:`PyLong_AsLongLongAndOverflow` approximates a Python long
integer as a C :c:type:`long` or :c:type:`long long`. integer as a C :c:expr:`long` or :c:expr:`long long`.
If the number is too large to fit into If the number is too large to fit into
the output type, an *overflow* flag is set and returned to the caller. the output type, an *overflow* flag is set and returned to the caller.
(Contributed by Case Van Horsen; :issue:`7528` and :issue:`7767`.) (Contributed by Case Van Horsen; :issue:`7528` and :issue:`7767`.)
@ -2202,7 +2202,7 @@ Changes to Python's build process and to the C API include:
* New format codes: the :c:func:`PyFormat_FromString`, * New format codes: the :c:func:`PyFormat_FromString`,
:c:func:`PyFormat_FromStringV`, and :c:func:`PyErr_Format` functions now :c:func:`PyFormat_FromStringV`, and :c:func:`PyErr_Format` functions now
accept ``%lld`` and ``%llu`` format codes for displaying accept ``%lld`` and ``%llu`` format codes for displaying
C's :c:type:`long long` types. C's :c:expr:`long long` types.
(Contributed by Mark Dickinson; :issue:`7228`.) (Contributed by Mark Dickinson; :issue:`7228`.)
* The complicated interaction between threads and process forking has * The complicated interaction between threads and process forking has

2
Doc/whatsnew/3.3.rst
View File

@ -932,7 +932,7 @@ it can now be used as a class decorator (:issue:`10868`).
array array
----- -----
The :mod:`array` module supports the :c:type:`long long` type using ``q`` and The :mod:`array` module supports the :c:expr:`long long` type using ``q`` and
``Q`` type codes. ``Q`` type codes.
(Contributed by Oren Tirosh and Hirokazu Yamamoto in :issue:`1172711`.) (Contributed by Oren Tirosh and Hirokazu Yamamoto in :issue:`1172711`.)

14
Doc/whatsnew/3.7.rst
View File

@ -290,21 +290,21 @@ PEP 539: New C API for Thread-Local Storage
While Python provides a C API for thread-local storage support; the existing While Python provides a C API for thread-local storage support; the existing
:ref:`Thread Local Storage (TLS) API <thread-local-storage-api>` has used :ref:`Thread Local Storage (TLS) API <thread-local-storage-api>` has used
:c:type:`int` to represent TLS keys across all platforms. This has not :c:expr:`int` to represent TLS keys across all platforms. This has not
generally been a problem for officially support platforms, but that is neither generally been a problem for officially support platforms, but that is neither
POSIX-compliant, nor portable in any practical sense. POSIX-compliant, nor portable in any practical sense.
:pep:`539` changes this by providing a new :ref:`Thread Specific Storage (TSS) :pep:`539` changes this by providing a new :ref:`Thread Specific Storage (TSS)
API <thread-specific-storage-api>` to CPython which supersedes use of the API <thread-specific-storage-api>` to CPython which supersedes use of the
existing TLS API within the CPython interpreter, while deprecating the existing existing TLS API within the CPython interpreter, while deprecating the existing
API. The TSS API uses a new type :c:type:`Py_tss_t` instead of :c:type:`int` API. The TSS API uses a new type :c:type:`Py_tss_t` instead of :c:expr:`int`
to represent TSS keys--an opaque type the definition of which may depend on to represent TSS keys--an opaque type the definition of which may depend on
the underlying TLS implementation. Therefore, this will allow to build CPython the underlying TLS implementation. Therefore, this will allow to build CPython
on platforms where the native TLS key is defined in a way that cannot be safely on platforms where the native TLS key is defined in a way that cannot be safely
cast to :c:type:`int`. cast to :c:expr:`int`.
Note that on platforms where the native TLS key is defined in a way that cannot Note that on platforms where the native TLS key is defined in a way that cannot
be safely cast to :c:type:`int`, all functions of the existing TLS API will be be safely cast to :c:expr:`int`, all functions of the existing TLS API will be
no-op and immediately return failure. This indicates clearly that the old API no-op and immediately return failure. This indicates clearly that the old API
is not supported on platforms where it cannot be used reliably, and that no is not supported on platforms where it cannot be used reliably, and that no
effort will be made to add such support. effort will be made to add such support.
@ -1708,12 +1708,12 @@ Contributed by Paul Ganssle in :issue:`10381`.
The type of results of :c:func:`PyThread_start_new_thread` and The type of results of :c:func:`PyThread_start_new_thread` and
:c:func:`PyThread_get_thread_ident`, and the *id* parameter of :c:func:`PyThread_get_thread_ident`, and the *id* parameter of
:c:func:`PyThreadState_SetAsyncExc` changed from :c:type:`long` to :c:func:`PyThreadState_SetAsyncExc` changed from :c:expr:`long` to
:c:type:`unsigned long`. :c:expr:`unsigned long`.
(Contributed by Serhiy Storchaka in :issue:`6532`.) (Contributed by Serhiy Storchaka in :issue:`6532`.)
:c:func:`PyUnicode_AsWideCharString` now raises a :exc:`ValueError` if the :c:func:`PyUnicode_AsWideCharString` now raises a :exc:`ValueError` if the
second argument is ``NULL`` and the :c:type:`wchar_t*` string contains null second argument is ``NULL`` and the :c:expr:`wchar_t*` string contains null
characters. (Contributed by Serhiy Storchaka in :issue:`30708`.) characters. (Contributed by Serhiy Storchaka in :issue:`30708`.)
Changes to the startup sequence and the management of dynamic memory Changes to the startup sequence and the management of dynamic memory

2
Doc/whatsnew/3.9.rst
View File

@ -773,7 +773,7 @@ Optimizations
Stinner in :issue:`38061`.) Stinner in :issue:`38061`.)
* :c:func:`PyLong_FromDouble` is now up to 1.87x faster for values that * :c:func:`PyLong_FromDouble` is now up to 1.87x faster for values that
fit into :c:type:`long`. fit into :c:expr:`long`.
(Contributed by Sergey Fedoseev in :issue:`37986`.) (Contributed by Sergey Fedoseev in :issue:`37986`.)
* A number of Python builtins (:class:`range`, :class:`tuple`, :class:`set`, * A number of Python builtins (:class:`range`, :class:`tuple`, :class:`set`,

2
Misc/NEWS.d/3.5.0a1.rst
View File

@ -3034,7 +3034,7 @@ by Phil Elson.
.. nonce: LK_5S1 .. nonce: LK_5S1
.. section: Library .. section: Library
os.read() now uses a :c:func:`Py_ssize_t` type instead of :c:type:`int` for os.read() now uses a :c:func:`Py_ssize_t` type instead of :c:expr:`int` for
the size to support reading more than 2 GB at once. On Windows, the size is the size to support reading more than 2 GB at once. On Windows, the size is
truncated to INT_MAX. As any call to os.read(), the OS may read less bytes truncated to INT_MAX. As any call to os.read(), the OS may read less bytes
than the number of requested bytes. than the number of requested bytes.

2
Misc/NEWS.d/3.9.0a1.rst
View File

@ -1510,7 +1510,7 @@ asynchronous magic methods on a MagicMock now return an AsyncMock.
.. section: Library .. section: Library
Update the *length* parameter of :func:`os.pread` to accept Update the *length* parameter of :func:`os.pread` to accept
:c:type:`Py_ssize_t` instead of :c:type:`int`. :c:type:`Py_ssize_t` instead of :c:expr:`int`.
.. ..

2
Misc/NEWS.d/3.9.0b1.rst
View File

@ -191,7 +191,7 @@ internal subinterpreters module.
.. section: Core and Builtins .. section: Core and Builtins
Improve performance of :c:func:`PyLong_FromDouble` for values that fit into Improve performance of :c:func:`PyLong_FromDouble` for values that fit into
:c:type:`long`. :c:expr:`long`.
.. ..