From f253cf469dfd65237882fcb51854d750bf80df13 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Fri, 13 May 2022 07:10:10 -0700 Subject: Document Py_ssize_t. (GH-92512) It fixes 252 errors from a Sphinx nitpicky run (sphinx-build -n). But there's 8182 errors left. Co-authored-by: Ezio Melotti (cherry picked from commit 664aa94b570a4a8f3535efb2e3d638a4ab655943) Co-authored-by: Julien Palard --- Doc/c-api/arg.rst | 4 ++-- Doc/c-api/bytes.rst | 4 ++-- Doc/c-api/intro.rst | 7 +++++++ Doc/c-api/number.rst | 4 ++-- Doc/c-api/object.rst | 2 +- Doc/c-api/sys.rst | 4 ++-- Doc/c-api/typeobj.rst | 18 +++++++++--------- Doc/c-api/unicode.rst | 8 ++++---- Doc/howto/clinic.rst | 2 +- Doc/whatsnew/3.8.rst | 2 +- 10 files changed, 31 insertions(+), 24 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 7a31880..6b60344 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -288,7 +288,7 @@ Numbers Convert a Python integer to a C :c:type:`unsigned long long` without overflow checking. -``n`` (:class:`int`) [Py_ssize_t] +``n`` (:class:`int`) [:c:type:`Py_ssize_t`] Convert a Python integer to a C :c:type:`Py_ssize_t`. ``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char] @@ -614,7 +614,7 @@ Building values ``K`` (:class:`int`) [unsigned long long] Convert a C :c:type:`unsigned long long` to a Python integer object. - ``n`` (:class:`int`) [Py_ssize_t] + ``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] diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index 32c7b80..ffbfb5a 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -84,8 +84,8 @@ called with a non-bytes parameter. | :attr:`%lu` | unsigned long | Equivalent to | | | | ``printf("%lu")``. [1]_ | +-------------------+---------------+--------------------------------+ - | :attr:`%zd` | Py_ssize_t | Equivalent to | - | | | ``printf("%zd")``. [1]_ | + | :attr:`%zd` | :c:type:`\ | Equivalent to | + | | Py_ssize_t` | ``printf("%zd")``. [1]_ | +-------------------+---------------+--------------------------------+ | :attr:`%zu` | size_t | Equivalent to | | | | ``printf("%zu")``. [1]_ | diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 7ca8693..ac1024c 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -502,6 +502,13 @@ 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 use them. +.. c:type:: Py_ssize_t + + A signed integral type such that ``sizeof(Py_ssize_t) == sizeof(size_t)``. + C99 doesn't define such a thing directly (size_t is an unsigned integral type). + See :pep:`353` for details. ``PY_SSIZE_T_MAX`` is the largest positive value + of type :c:type:`Py_ssize_t`. + .. _api-exceptions: diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst index 1058b2c..47033a3 100644 --- a/Doc/c-api/number.rst +++ b/Doc/c-api/number.rst @@ -269,11 +269,11 @@ Number Protocol .. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc) - Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an + Returns *o* converted to a :c:type:`Py_ssize_t` value if *o* can be interpreted as an integer. If the call fails, an exception is raised and ``-1`` is returned. If *o* can be converted to a Python int but the attempt to - convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the + convert to a :c:type:`Py_ssize_t` value would raise an :exc:`OverflowError`, then the *exc* argument is the type of exception that will be raised (usually :exc:`IndexError` or :exc:`OverflowError`). If *exc* is ``NULL``, then the exception is cleared and the value is clipped to ``PY_SSIZE_T_MIN`` for a negative diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 43ccb44..3e4f61a 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -258,7 +258,7 @@ Object Protocol .. versionchanged:: 3.2 The return type is now Py_hash_t. This is a signed integer the same size - as Py_ssize_t. + as :c:type:`Py_ssize_t`. .. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 37591a4..0a5c8d7 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -321,7 +321,7 @@ accessible to C code. They all work with the current interpreter thread's leaks.) Note that ``#`` format characters should always be treated as - ``Py_ssize_t``, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined. + :c:type:`Py_ssize_t`, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined. :func:`sys.audit` performs the same function from Python code. @@ -329,7 +329,7 @@ accessible to C code. They all work with the current interpreter thread's .. versionchanged:: 3.8.2 - Require ``Py_ssize_t`` for ``#`` format characters. Previously, an + Require :c:type:`Py_ssize_t` for ``#`` format characters. Previously, an unavoidable deprecation warning was raised. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index d49f3ff..eedefd7 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -43,13 +43,13 @@ Quick Reference +================================================+===================================+===================+===+===+===+===+ | :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X | + | :c:member:`~PyTypeObject.tp_basicsize` | :c:type:`Py_ssize_t` | | X | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | | X | | X | + | :c:member:`~PyTypeObject.tp_itemsize` | :c:type:`Py_ssize_t` | | | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_vectorcall_offset` | Py_ssize_t | | | X | | X | + | :c:member:`~PyTypeObject.tp_vectorcall_offset` | :c:type:`Py_ssize_t` | | | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G | | | | __getattr__ | | | | | @@ -96,7 +96,7 @@ Quick Reference | | | __gt__, | | | | | | | | __ge__ | | | | | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | | X | | ? | + | :c:member:`~PyTypeObject.tp_weaklistoffset` | :c:type:`Py_ssize_t` | | | X | | ? | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | __iter__ | | | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ @@ -117,7 +117,7 @@ Quick Reference | :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | __set__, | | | | X | | | | __delete__ | | | | | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | | X | | ? | + | :c:member:`~PyTypeObject.tp_dictoffset` | :c:type:`Py_ssize_t` | | | X | | ? | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ | :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | __init__ | X | X | | X | +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ @@ -331,7 +331,7 @@ slot typedefs | :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * | | | | | | | :c:type:`PyTypeObject` * | | -| | Py_ssize_t | | +| | :c:type:`Py_ssize_t` | | +-----------------------------+-----------------------------+----------------------+ | :c:type:`destructor` | void * | void | +-----------------------------+-----------------------------+----------------------+ @@ -403,7 +403,7 @@ slot typedefs +-----------------------------+-----------------------------+----------------------+ | :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | +-----------------------------+-----------------------------+----------------------+ -| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t | +| :c:type:`lenfunc` | :c:type:`PyObject` * | :c:type:`Py_ssize_t` | +-----------------------------+-----------------------------+----------------------+ | :c:type:`getbufferproc` | .. line-block:: | int | | | | | @@ -436,12 +436,12 @@ slot typedefs | :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * | | | | | | | :c:type:`PyObject` * | | -| | Py_ssize_t | | +| | :c:type:`Py_ssize_t` | | +-----------------------------+-----------------------------+----------------------+ | :c:type:`ssizeobjargproc` | .. line-block:: | int | | | | | | | :c:type:`PyObject` * | | -| | Py_ssize_t | | +| | :c:type:`Py_ssize_t` | | +-----------------------------+-----------------------------+----------------------+ | :c:type:`objobjproc` | .. line-block:: | int | | | | | diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 8bdcad6..4129c61 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -490,11 +490,11 @@ APIs: | :attr:`%llu` | unsigned long long | Equivalent to | | | | ``printf("%llu")``. [1]_ | +-------------------+---------------------+----------------------------------+ - | :attr:`%zd` | Py_ssize_t | Equivalent to | - | | | ``printf("%zd")``. [1]_ | + | :attr:`%zd` | :c:type:`\ | Equivalent to | + | | Py_ssize_t` | ``printf("%zd")``. [1]_ | +-------------------+---------------------+----------------------------------+ - | :attr:`%zi` | Py_ssize_t | Equivalent to | - | | | ``printf("%zi")``. [1]_ | + | :attr:`%zi` | :c:type:`\ | Equivalent to | + | | Py_ssize_t` | ``printf("%zi")``. [1]_ | +-------------------+---------------------+----------------------------------+ | :attr:`%zu` | size_t | Equivalent to | | | | ``printf("%zu")``. [1]_ | diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 5004182..145febe 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -1288,7 +1288,7 @@ Here's the simplest example of a custom converter, from ``Modules/zlibmodule.c`` /*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/ This block adds a converter to Argument Clinic named ``ssize_t``. Parameters -declared as ``ssize_t`` will be declared as type ``Py_ssize_t``, and will +declared as ``ssize_t`` will be declared as type :c:type:`Py_ssize_t`, and will be parsed by the ``'O&'`` format unit, which will call the ``ssize_t_converter`` converter function. ``ssize_t`` variables automatically support default values. diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 1b3bb15..92bdb45 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -1489,7 +1489,7 @@ Optimizations first introduced in Python 3.4. It offers better performance and smaller size compared to Protocol 3 available since Python 3.0. -* Removed one ``Py_ssize_t`` member from ``PyGC_Head``. All GC tracked +* Removed one :c:type:`Py_ssize_t` member from ``PyGC_Head``. All GC tracked objects (e.g. tuple, list, dict) size is reduced 4 or 8 bytes. (Contributed by Inada Naoki in :issue:`33597`.) -- cgit v0.12