From 8d15058d61681e98579cf3fbd3c6fd13b3df6a72 Mon Sep 17 00:00:00 2001
From: Serhiy Storchaka <storchaka@gmail.com>
Date: Mon, 6 Jan 2025 12:50:28 +0200
Subject: gh-77214: Update outdated documentation for numeric PyArg_Parse
formats (GH-128454)
---
Doc/c-api/arg.rst | 22 ++++++++++++++--------
1 file changed, 14 insertions(+), 8 deletions(-)
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 3201bdc..41c0366 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -229,12 +229,24 @@ There are three ways strings and buffers can be converted to C:
Numbers
-------
+These formats allow representing Python numbers or single characters as C numbers.
+Formats that require :class:`int`, :class:`float` or :class:`complex` can
+also use the corresponding special methods :meth:`~object.__index__`,
+:meth:`~object.__float__` or :meth:`~object.__complex__` to convert
+the Python object to the required type.
+
+For signed integer formats, :exc:`OverflowError` is raised if the value
+is out of range for the C type.
+For unsigned integer formats, no range checking is done --- the
+most significant bits are silently truncated when the receiving field is too
+small to receive the value.
+
``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 integer, stored in a C
:c:expr:`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 integer without overflow checking, stored in a C
:c:expr:`unsigned char`.
``h`` (:class:`int`) [short int]
@@ -344,12 +356,6 @@ Other objects
in *items*. The C arguments must correspond to the individual format units in
*items*. Format units for sequences may be nested.
-It is possible to pass "long" integers (integers whose value exceeds the
-platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
-most significant bits are silently truncated when the receiving field is too
-small to receive the value (actually, the semantics are inherited from downcasts
-in C --- your mileage may vary).
-
A few other characters have a meaning in a format string. These may not occur
inside nested parentheses. They are:
--
cgit v0.12