mirror of
https://github.com/python/cpython.git
synced 2025-10-04 22:20:46 +00:00
[3.11] gh-93738: Documentation C syntax (:c:type:<C type> -> :c:expr:<C type>) (GH-97768) (#97924)
:c:type:`<C type>` -> :c:expr:`<C type>`
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
(cherry picked from commit 0031e62973)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
This commit is contained in:
Łukasz Langa
Pablo Galindo
parent
82f663b7f0
commit
e48d6dfbcd
34 changed files with 240 additions and 240 deletions
|
|
@ -194,10 +194,10 @@ which disallows mutable objects such as :class:`bytearray`.
|
|||
It only works for encoded data without embedded NUL bytes.
|
||||
|
||||
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.
|
||||
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.
|
||||
The text will be encoded in the encoding specified by the first argument.
|
||||
|
||||
|
|
@ -217,10 +217,10 @@ which disallows mutable objects such as :class:`bytearray`.
|
|||
characters.
|
||||
|
||||
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.
|
||||
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.
|
||||
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
|
||||
|
|
@ -252,38 +252,38 @@ Numbers
|
|||
|
||||
``b`` (:class:`int`) [unsigned char]
|
||||
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]
|
||||
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]
|
||||
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]
|
||||
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.
|
||||
|
||||
``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]
|
||||
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.
|
||||
|
||||
``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]
|
||||
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.
|
||||
|
||||
``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]
|
||||
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.
|
||||
|
||||
``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
|
||||
|
|
@ -291,20 +291,20 @@ Numbers
|
|||
|
||||
``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
|
||||
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
|
||||
Allow :class:`bytearray` objects.
|
||||
|
||||
``C`` (:class:`str` of length 1) [int]
|
||||
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]
|
||||
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]
|
||||
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]
|
||||
Convert a Python complex number to a C :c:type:`Py_complex` structure.
|
||||
|
|
@ -329,13 +329,13 @@ Other objects
|
|||
``O&`` (object) [*converter*, *anything*]
|
||||
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
|
||||
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::
|
||||
|
||||
status = converter(object, address);
|
||||
|
||||
where *object* is the Python object to be converted and *address* is the
|
||||
:c:type:`void*` argument that was passed to the :c:func:`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 conversion has failed. When the conversion fails, the *converter* function
|
||||
should raise an exception and leave the content of *address* unmodified.
|
||||
|
|
@ -568,7 +568,7 @@ Building values
|
|||
Same as ``s#``.
|
||||
|
||||
``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``,
|
||||
``None`` is returned.
|
||||
|
||||
|
|
@ -584,51 +584,51 @@ Building values
|
|||
Same as ``s#``.
|
||||
|
||||
``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]
|
||||
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]
|
||||
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]
|
||||
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]
|
||||
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]
|
||||
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]
|
||||
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]
|
||||
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]
|
||||
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]
|
||||
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`]
|
||||
Convert a C :c:type:`Py_ssize_t` to a Python integer.
|
||||
|
||||
``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.
|
||||
|
||||
``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.
|
||||
|
||||
``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]
|
||||
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 \*]
|
||||
Convert a C :c:type:`Py_complex` structure to a Python complex number.
|
||||
|
|
@ -651,7 +651,7 @@ Building values
|
|||
|
||||
``O&`` (object) [*converter*, *anything*]
|
||||
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
|
||||
error occurred.
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
|
|||
.. c:type:: PyCapsule
|
||||
|
||||
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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -115,12 +115,12 @@ Complex Numbers as Python Objects
|
|||
|
||||
.. 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)
|
||||
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
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
|
||||
the set of strings accepted by Python's :func:`float` constructor,
|
||||
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)
|
||||
|
||||
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* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
|
||||
|
|
|
|||
|
|
@ -73,7 +73,7 @@ Dictionary Objects
|
|||
.. index:: single: PyUnicode_FromString()
|
||||
|
||||
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
|
||||
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)
|
||||
|
||||
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
|
||||
:c:type:`const char*`, rather than a :c:type:`PyObject*`.
|
||||
:c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
|
||||
|
||||
Note that exceptions which occur while calling :meth:`__hash__` and
|
||||
:meth:`__eq__` methods and creating a temporary string object
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ the :mod:`io` APIs instead.
|
|||
|
||||
.. 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's :meth:`~io.IOBase.fileno` method is called if it exists; the
|
||||
method must return an integer, which is returned as the file descriptor
|
||||
|
|
|
|||
|
|
@ -44,7 +44,7 @@ Floating Point Objects
|
|||
|
||||
.. 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__`
|
||||
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__`.
|
||||
|
|
@ -57,7 +57,7 @@ Floating Point Objects
|
|||
|
||||
.. 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.
|
||||
|
||||
|
||||
|
|
@ -70,12 +70,12 @@ Floating Point Objects
|
|||
|
||||
.. 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()
|
||||
|
||||
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
|
||||
|
|
@ -83,8 +83,8 @@ Pack and Unpack functions
|
|||
|
||||
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
|
||||
string from a C :c:type:`double`, and the Unpack routines produce a C
|
||||
:c:type:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the
|
||||
string from a C :c:expr:`double`, and the Unpack routines produce a C
|
||||
:c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the
|
||||
number of bytes in the bytes string.
|
||||
|
||||
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
|
||||
: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
|
||||
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
|
||||
|
|
@ -138,7 +138,7 @@ Unpack functions
|
|||
----------------
|
||||
|
||||
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 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``
|
||||
|
|
|
|||
|
|
@ -376,7 +376,7 @@ Process-wide parameters
|
|||
interpreter will change the contents of this storage.
|
||||
|
||||
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
|
||||
:c:type:`wchar_*` string.
|
||||
:c:expr:`wchar_*` string.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
|
|
@ -527,7 +527,7 @@ Process-wide parameters
|
|||
if required after calling :c:func:`Py_Initialize`.
|
||||
|
||||
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
|
||||
call completes.
|
||||
|
|
@ -642,7 +642,7 @@ Process-wide parameters
|
|||
directory (``"."``).
|
||||
|
||||
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`
|
||||
members of the :ref:`Python Initialization Configuration <init-config>`.
|
||||
|
|
@ -678,7 +678,7 @@ Process-wide parameters
|
|||
:option:`-I`.
|
||||
|
||||
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`
|
||||
members of the :ref:`Python Initialization Configuration <init-config>`.
|
||||
|
|
@ -704,7 +704,7 @@ Process-wide parameters
|
|||
this storage.
|
||||
|
||||
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
|
||||
:c:type:`wchar_*` string.
|
||||
:c:expr:`wchar_*` string.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
|
|
@ -1291,8 +1291,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.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
The type of the *id* parameter changed from :c:type:`long` to
|
||||
:c:type:`unsigned long`.
|
||||
The type of the *id* parameter changed from :c:expr:`long` to
|
||||
:c:expr:`unsigned long`.
|
||||
|
||||
.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
|
||||
|
||||
|
|
@ -1730,7 +1730,7 @@ The Python interpreter provides low-level support for thread-local storage
|
|||
(TLS) which wraps the underlying native TLS implementation to support the
|
||||
Python-level thread local storage API (:class:`threading.local`). The
|
||||
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.
|
||||
|
||||
The GIL does *not* need to be held when calling these functions; they supply
|
||||
|
|
@ -1741,8 +1741,8 @@ you need to include :file:`pythread.h` to use thread-local storage.
|
|||
|
||||
.. note::
|
||||
None of these API functions handle memory management on behalf of the
|
||||
:c:type:`void*` values. You need to allocate and deallocate them yourself.
|
||||
If the :c:type:`void*` values happen to be :c:type:`PyObject*`, these
|
||||
:c:expr:`void*` values. You need to allocate and deallocate them yourself.
|
||||
If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these
|
||||
functions don't do refcount operations on them either.
|
||||
|
||||
.. _thread-specific-storage-api:
|
||||
|
|
@ -1752,7 +1752,7 @@ Thread Specific Storage (TSS) API
|
|||
|
||||
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
|
||||
:c:type:`int` to represent thread keys.
|
||||
:c:expr:`int` to represent thread keys.
|
||||
|
||||
.. versionadded:: 3.7
|
||||
|
||||
|
|
@ -1838,14 +1838,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)
|
||||
|
||||
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
|
||||
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)
|
||||
|
||||
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
|
||||
current thread.
|
||||
|
||||
|
|
|
|||
|
|
@ -530,8 +530,8 @@ Types
|
|||
-----
|
||||
|
||||
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`,
|
||||
:c:type:`double` and :c:type:`char*`. A few structure types are used to
|
||||
API; most are simple C types such as :c:expr:`int`, :c:expr:`long`,
|
||||
: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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
|
||||
.. 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.
|
||||
|
||||
|
||||
|
|
@ -65,13 +65,13 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
|
||||
.. 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.
|
||||
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
|
|
@ -115,12 +115,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
single: LONG_MAX
|
||||
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
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -133,7 +133,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
|
||||
.. 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__`
|
||||
method (if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
|
|
@ -156,12 +156,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
.. index::
|
||||
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
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -174,7 +174,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
|
||||
.. 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
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
|
|
@ -215,11 +215,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
single: ULONG_MAX
|
||||
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`.
|
||||
|
||||
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.
|
||||
Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
|
@ -246,11 +246,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
.. index::
|
||||
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`.
|
||||
|
||||
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.
|
||||
Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
|
@ -261,11 +261,11 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
|
||||
.. 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__`
|
||||
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``.
|
||||
|
||||
Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to
|
||||
|
|
@ -280,12 +280,12 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
|
||||
.. 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
|
||||
:meth:`__index__` 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 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``.
|
||||
|
||||
Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred`
|
||||
|
|
@ -300,20 +300,20 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
|
|||
|
||||
.. 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`.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. 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
|
||||
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`.
|
||||
|
||||
Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
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
|
||||
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)
|
||||
|
|
@ -43,9 +43,9 @@ The following functions allow marshalled values to be read back in.
|
|||
|
||||
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
|
||||
|
||||
Return a C :c:type:`long` from the data stream in a :c:type:`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,
|
||||
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
|
||||
``-1``.
|
||||
|
|
@ -53,9 +53,9 @@ The following functions allow marshalled values to be read back in.
|
|||
|
||||
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
|
||||
|
||||
Return a C :c:type:`short` from the data stream in a :c:type:`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,
|
||||
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
|
||||
``-1``.
|
||||
|
|
|
|||
|
|
@ -141,7 +141,7 @@ zero bytes.
|
|||
|
||||
.. 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.
|
||||
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
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)
|
||||
|
||||
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.
|
||||
|
||||
Requesting zero elements or elements of size zero bytes returns a distinct
|
||||
|
|
|
|||
|
|
@ -105,7 +105,7 @@ Operating System Utilities
|
|||
|
||||
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
|
||||
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)`.
|
||||
|
||||
|
||||
|
|
@ -114,7 +114,7 @@ Operating System Utilities
|
|||
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
|
||||
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)
|
||||
|
||||
|
|
@ -377,7 +377,7 @@ accessible to C code. They all work with the current interpreter thread's
|
|||
silently abort the operation by raising an error subclassed from
|
||||
: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
|
||||
:c:type:`PyTupleObject`. The hook function is always called with the GIL
|
||||
held by the Python interpreter that raised the event.
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ Python:
|
|||
|
||||
.. 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.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
|
|
@ -935,11 +935,11 @@ conversion function:
|
|||
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)
|
||||
|
||||
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,
|
||||
using wcslen.
|
||||
Return ``NULL`` on failure.
|
||||
|
|
@ -947,13 +947,13 @@ wchar_t Support
|
|||
|
||||
.. 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
|
||||
*size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
|
||||
null termination character). Return the number of :c:type:`wchar_t` characters
|
||||
copied or ``-1`` in case of an error. Note that the resulting :c:type:`wchar_t*`
|
||||
Copy the Unicode object contents into the :c:expr:`wchar_t` buffer *w*. At most
|
||||
*size* :c:expr:`wchar_t` characters are copied (excluding a possibly trailing
|
||||
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:expr:`wchar_t*`
|
||||
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
|
||||
required by the application. Also, note that the :c:type:`wchar_t*` string
|
||||
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:expr:`wchar_t*` string
|
||||
might contain null characters, which would cause the string to be truncated
|
||||
when used with most C functions.
|
||||
|
||||
|
|
@ -963,9 +963,9 @@ wchar_t Support
|
|||
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
|
||||
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
|
||||
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.
|
||||
|
||||
Returns a buffer allocated by :c:func:`PyMem_Alloc` (use
|
||||
|
|
@ -976,7 +976,7 @@ wchar_t Support
|
|||
.. versionadded:: 3.2
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue