Skip to content

Document Py_ssize_t. #92512

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 13, 2022
Merged

Document Py_ssize_t. #92512

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
68f35b5
Document Py_ssize_t.
JulienPalard May 8, 2022
e4c2e12
Fix a couple of minor markup errors.
ezio-melotti May 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Doc/c-api/arg.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -286,7 +286,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]
Expand Down Expand Up @@ -613,7 +613,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]
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/bytes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]_ |
Expand Down
7 changes: 7 additions & 0 deletions Doc/c-api/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -537,6 +537,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:

Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/number.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,11 +273,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
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/object.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/sys.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,15 +348,15 @@ 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.

.. versionadded:: 3.8

.. 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.


Expand Down
18 changes: 9 additions & 9 deletions Doc/c-api/typeobj.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,13 @@ Quick Reference
+================================================+===================================+===================+===+===+===+===+
| <R> :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__ | | | | |
Expand Down Expand Up @@ -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 |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
Expand All @@ -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 |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
Expand Down Expand Up @@ -333,7 +333,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 |
+-----------------------------+-----------------------------+----------------------+
Expand Down Expand Up @@ -405,7 +405,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 |
| | | |
Expand Down Expand Up @@ -438,12 +438,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 |
| | | |
Expand Down
8 changes: 4 additions & 4 deletions Doc/c-api/unicode.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -497,11 +497,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]_ |
Expand Down
2 changes: 1 addition & 1 deletion Doc/howto/clinic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1347,7 +1347,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.
Expand Down
2 changes: 1 addition & 1 deletion Doc/whatsnew/3.8.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1490,7 +1490,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`.)

Expand Down