From f21fd019e904de1d58e2e6ebbfb349232bdc9883 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 3 Jan 2025 20:09:09 +0200 Subject: [PATCH 1/3] gh-77214: Update outdated documentation for numeric PyArg_Parse formats --- 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 3201bdc82691f4..2d3cba8152012c 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 to represent 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 format, :exc:`OverflowError` is raised if the value +is out of range for the C type. +For unsigned integer format, no proper 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: From 7c7aaa3c5b1540de1e0ccbd0a951b448bffbc37e Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 3 Jan 2025 20:54:20 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/c-api/arg.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 2d3cba8152012c..d5b971f51f2f41 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -235,9 +235,9 @@ 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 format, :exc:`OverflowError` is raised if the value +For signed integer formats, :exc:`OverflowError` is raised if the value is out of range for the C type. -For unsigned integer format, no proper range checking is done --- the +For unsigned integer formats, no proper range checking is done --- the most significant bits are silently truncated when the receiving field is too small to receive the value. From 848d0effe847b395430b89e7ed257805bf734be0 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 6 Jan 2025 11:48:22 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Petr Viktorin --- Doc/c-api/arg.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index d5b971f51f2f41..41c0366d205086 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -229,7 +229,7 @@ There are three ways strings and buffers can be converted to C: Numbers ------- -These formats allow to represent Python numbers or single characters as 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 @@ -237,7 +237,7 @@ 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 proper range checking is done --- the +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.