Skip to content

Commit 48f2d8d

Browse files
miss-islingtonJulienPalard
miss-islington
and
JulienPalard
authored
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 <ezio.melotti@gmail.com> (cherry picked from commit 664aa94) Co-authored-by: Julien Palard <julien@palard.fr>
1 parent a24e676 commit 48f2d8d

File tree

10 files changed

+31
-24
lines changed

10 files changed

+31
-24
lines changed

‎Doc/c-api/arg.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -286,7 +286,7 @@ Numbers
286286
Convert a Python integer to a C :c:type:`unsigned long long`
287287
without overflow checking.
288288

289-
``n`` (:class:`int`) [Py_ssize_t]
289+
``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
290290
Convert a Python integer to a C :c:type:`Py_ssize_t`.
291291

292292
``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
@@ -613,7 +613,7 @@ Building values
613613
``K`` (:class:`int`) [unsigned long long]
614614
Convert a C :c:type:`unsigned long long` to a Python integer object.
615615
616-
``n`` (:class:`int`) [Py_ssize_t]
616+
``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
617617
Convert a C :c:type:`Py_ssize_t` to a Python integer.
618618
619619
``c`` (:class:`bytes` of length 1) [char]

‎Doc/c-api/bytes.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,8 @@ called with a non-bytes parameter.
8484
| :attr:`%lu` | unsigned long | Equivalent to |
8585
| | | ``printf("%lu")``. [1]_ |
8686
+-------------------+---------------+--------------------------------+
87-
| :attr:`%zd` | Py_ssize_t | Equivalent to |
88-
| | | ``printf("%zd")``. [1]_ |
87+
| :attr:`%zd` | :c:type:`\ | Equivalent to |
88+
| | Py_ssize_t` | ``printf("%zd")``. [1]_ |
8989
+-------------------+---------------+--------------------------------+
9090
| :attr:`%zu` | size_t | Equivalent to |
9191
| | | ``printf("%zu")``. [1]_ |

‎Doc/c-api/intro.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -502,6 +502,13 @@ data attributes of a new object type, and another is used to describe the value
502502
of a complex number. These will be discussed together with the functions that
503503
use them.
504504

505+
.. c:type:: Py_ssize_t
506+
507+
A signed integral type such that ``sizeof(Py_ssize_t) == sizeof(size_t)``.
508+
C99 doesn't define such a thing directly (size_t is an unsigned integral type).
509+
See :pep:`353` for details. ``PY_SSIZE_T_MAX`` is the largest positive value
510+
of type :c:type:`Py_ssize_t`.
511+
505512

506513
.. _api-exceptions:
507514

‎Doc/c-api/number.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -273,11 +273,11 @@ Number Protocol
273273
274274
.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
275275
276-
Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
276+
Returns *o* converted to a :c:type:`Py_ssize_t` value if *o* can be interpreted as an
277277
integer. If the call fails, an exception is raised and ``-1`` is returned.
278278
279279
If *o* can be converted to a Python int but the attempt to
280-
convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
280+
convert to a :c:type:`Py_ssize_t` value would raise an :exc:`OverflowError`, then the
281281
*exc* argument is the type of exception that will be raised (usually
282282
:exc:`IndexError` or :exc:`OverflowError`). If *exc* is ``NULL``, then the
283283
exception is cleared and the value is clipped to ``PY_SSIZE_T_MIN`` for a negative

‎Doc/c-api/object.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -258,7 +258,7 @@ Object Protocol
258258
259259
.. versionchanged:: 3.2
260260
The return type is now Py_hash_t. This is a signed integer the same size
261-
as Py_ssize_t.
261+
as :c:type:`Py_ssize_t`.
262262
263263
264264
.. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)

‎Doc/c-api/sys.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -323,15 +323,15 @@ accessible to C code. They all work with the current interpreter thread's
323323
leaks.)
324324
325325
Note that ``#`` format characters should always be treated as
326-
``Py_ssize_t``, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined.
326+
:c:type:`Py_ssize_t`, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined.
327327
328328
:func:`sys.audit` performs the same function from Python code.
329329
330330
.. versionadded:: 3.8
331331
332332
.. versionchanged:: 3.8.2
333333
334-
Require ``Py_ssize_t`` for ``#`` format characters. Previously, an
334+
Require :c:type:`Py_ssize_t` for ``#`` format characters. Previously, an
335335
unavoidable deprecation warning was raised.
336336
337337

‎Doc/c-api/typeobj.rst‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,13 @@ Quick Reference
4343
+================================================+===================================+===================+===+===+===+===+
4444
| <R> :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | |
4545
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
46-
| :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X |
46+
| :c:member:`~PyTypeObject.tp_basicsize` | :c:type:`Py_ssize_t` | | X | X | | X |
4747
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
48-
| :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | | X | | X |
48+
| :c:member:`~PyTypeObject.tp_itemsize` | :c:type:`Py_ssize_t` | | | X | | X |
4949
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
5050
| :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X |
5151
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
52-
| :c:member:`~PyTypeObject.tp_vectorcall_offset` | Py_ssize_t | | | X | | X |
52+
| :c:member:`~PyTypeObject.tp_vectorcall_offset` | :c:type:`Py_ssize_t` | | | X | | X |
5353
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
5454
| (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G |
5555
| | | __getattr__ | | | | |
@@ -96,7 +96,7 @@ Quick Reference
9696
| | | __gt__, | | | | |
9797
| | | __ge__ | | | | |
9898
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
99-
| :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | | X | | ? |
99+
| :c:member:`~PyTypeObject.tp_weaklistoffset` | :c:type:`Py_ssize_t` | | | X | | ? |
100100
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
101101
| :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | __iter__ | | | | X |
102102
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
@@ -117,7 +117,7 @@ Quick Reference
117117
| :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | __set__, | | | | X |
118118
| | | __delete__ | | | | |
119119
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
120-
| :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | | X | | ? |
120+
| :c:member:`~PyTypeObject.tp_dictoffset` | :c:type:`Py_ssize_t` | | | X | | ? |
121121
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
122122
| :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | __init__ | X | X | | X |
123123
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
@@ -333,7 +333,7 @@ slot typedefs
333333
| :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * |
334334
| | | |
335335
| | :c:type:`PyTypeObject` * | |
336-
| | Py_ssize_t | |
336+
| | :c:type:`Py_ssize_t` | |
337337
+-----------------------------+-----------------------------+----------------------+
338338
| :c:type:`destructor` | void * | void |
339339
+-----------------------------+-----------------------------+----------------------+
@@ -405,7 +405,7 @@ slot typedefs
405405
+-----------------------------+-----------------------------+----------------------+
406406
| :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * |
407407
+-----------------------------+-----------------------------+----------------------+
408-
| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t |
408+
| :c:type:`lenfunc` | :c:type:`PyObject` * | :c:type:`Py_ssize_t` |
409409
+-----------------------------+-----------------------------+----------------------+
410410
| :c:type:`getbufferproc` | .. line-block:: | int |
411411
| | | |
@@ -438,12 +438,12 @@ slot typedefs
438438
| :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * |
439439
| | | |
440440
| | :c:type:`PyObject` * | |
441-
| | Py_ssize_t | |
441+
| | :c:type:`Py_ssize_t` | |
442442
+-----------------------------+-----------------------------+----------------------+
443443
| :c:type:`ssizeobjargproc` | .. line-block:: | int |
444444
| | | |
445445
| | :c:type:`PyObject` * | |
446-
| | Py_ssize_t | |
446+
| | :c:type:`Py_ssize_t` | |
447447
+-----------------------------+-----------------------------+----------------------+
448448
| :c:type:`objobjproc` | .. line-block:: | int |
449449
| | | |

‎Doc/c-api/unicode.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -490,11 +490,11 @@ APIs:
490490
| :attr:`%llu` | unsigned long long | Equivalent to |
491491
| | | ``printf("%llu")``. [1]_ |
492492
+-------------------+---------------------+----------------------------------+
493-
| :attr:`%zd` | Py_ssize_t | Equivalent to |
494-
| | | ``printf("%zd")``. [1]_ |
493+
| :attr:`%zd` | :c:type:`\ | Equivalent to |
494+
| | Py_ssize_t` | ``printf("%zd")``. [1]_ |
495495
+-------------------+---------------------+----------------------------------+
496-
| :attr:`%zi` | Py_ssize_t | Equivalent to |
497-
| | | ``printf("%zi")``. [1]_ |
496+
| :attr:`%zi` | :c:type:`\ | Equivalent to |
497+
| | Py_ssize_t` | ``printf("%zi")``. [1]_ |
498498
+-------------------+---------------------+----------------------------------+
499499
| :attr:`%zu` | size_t | Equivalent to |
500500
| | | ``printf("%zu")``. [1]_ |

‎Doc/howto/clinic.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1350,7 +1350,7 @@ Here's the simplest example of a custom converter, from ``Modules/zlibmodule.c``
13501350
/*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/
13511351

13521352
This block adds a converter to Argument Clinic named ``ssize_t``. Parameters
1353-
declared as ``ssize_t`` will be declared as type ``Py_ssize_t``, and will
1353+
declared as ``ssize_t`` will be declared as type :c:type:`Py_ssize_t`, and will
13541354
be parsed by the ``'O&'`` format unit, which will call the
13551355
``ssize_t_converter`` converter function. ``ssize_t`` variables
13561356
automatically support default values.

‎Doc/whatsnew/3.8.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1490,7 +1490,7 @@ Optimizations
14901490
first introduced in Python 3.4. It offers better performance and smaller
14911491
size compared to Protocol 3 available since Python 3.0.
14921492

1493-
* Removed one ``Py_ssize_t`` member from ``PyGC_Head``. All GC tracked
1493+
* Removed one :c:type:`Py_ssize_t` member from ``PyGC_Head``. All GC tracked
14941494
objects (e.g. tuple, list, dict) size is reduced 4 or 8 bytes.
14951495
(Contributed by Inada Naoki in :issue:`33597`.)
14961496

0 commit comments

Comments
 (0)