From aff021ba5e5027a666d337324915295f60f7f982 Mon Sep 17 00:00:00 2001 From: Max Bachmann Date: Thu, 21 Jul 2022 02:32:36 +0200 Subject: [PATCH 1/5] GH-95079: add missing documentation of error behavior --- Doc/c-api/unicode.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 5d420bfa93cb27..0d8cf0abdf5ee2 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -345,6 +345,8 @@ APIs: This is the recommended way to allocate a new Unicode object. Objects created using this function are not resizable. + On failure returns ``NULL`` and sets an exception. + .. versionadded:: 3.3 @@ -529,6 +531,10 @@ APIs: Return the length of the Unicode object, in code points. + This function checks that *unicode* is a Unicode object, in contrast to + :c:func:`PyUnicode_GET_LENGTH`, which performs no error checking. On error + returns ``-1`` and sets an exception. + .. versionadded:: 3.3 @@ -572,6 +578,8 @@ APIs: not out of bounds, and that the object can be modified safely (i.e. that it its reference count is one). + Return ``0`` on success, ``-1`` on error with an exception set. + .. versionadded:: 3.3 @@ -581,6 +589,8 @@ APIs: Unicode object and the index is not out of bounds, in contrast to :c:func:`PyUnicode_READ_CHAR`, which performs no error checking. + Return character on success, ``-1`` on error with an exception set. + .. versionadded:: 3.3 @@ -589,6 +599,7 @@ APIs: Return a substring of *str*, from character index *start* (included) to character index *end* (excluded). Negative indices are not supported. + Returns ``NULL`` and sets an exception on error. .. versionadded:: 3.3 From 9d948feec259f79ce6ed7901c72998228adaca39 Mon Sep 17 00:00:00 2001 From: Max Bachmann Date: Tue, 16 Jul 2024 14:30:14 +0200 Subject: [PATCH 2/5] use imperative mood --- Doc/c-api/unicode.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 557ba2a5d181f1..dc8d56ac6d7e58 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -345,7 +345,7 @@ APIs: This is the recommended way to allocate a new Unicode object. Objects created using this function are not resizable. - On failure returns ``NULL`` and sets an exception. + On error, set an exception and return ``NULL``. .. versionadded:: 3.3 @@ -534,8 +534,9 @@ APIs: Return the length of the Unicode object, in code points. This function checks that *unicode* is a Unicode object, in contrast to - :c:func:`PyUnicode_GET_LENGTH`, which performs no error checking. On error - returns ``-1`` and sets an exception. + :c:func:`PyUnicode_GET_LENGTH`, which performs no error checking. + + On error, set an exception and return ``-1``. .. versionadded:: 3.3 From ba9d1fcd57e921d4d2cd17c02a8189e38d95026f Mon Sep 17 00:00:00 2001 From: Max Bachmann Date: Tue, 16 Jul 2024 14:32:12 +0200 Subject: [PATCH 3/5] Use imperative mood --- Doc/c-api/unicode.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index dc8d56ac6d7e58..afa21d121822f6 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -602,7 +602,7 @@ APIs: Return a substring of *str*, from character index *start* (included) to character index *end* (excluded). Negative indices are not supported. - Returns ``NULL`` and sets an exception on error. + On error, set an exception and return ``NULL``. .. versionadded:: 3.3 From fdfc8a14a1a95b6f9fff510730619103f9819307 Mon Sep 17 00:00:00 2001 From: Max Bachmann Date: Tue, 16 Jul 2024 14:40:53 +0200 Subject: [PATCH 4/5] Update unicode.rst --- Doc/c-api/unicode.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 220daf66e3e7ae..de77d9279d5fc0 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -616,8 +616,8 @@ APIs: Return the length of the Unicode object, in code points. - This function checks that *unicode* is a Unicode object, in contrast to - :c:func:`PyUnicode_GET_LENGTH`, which performs no error checking. + Check that *unicode* is a Unicode object, unlike :c:func:`PyUnicode_GET_LENGTH`, + which performs no error checking. On error, set an exception and return ``-1``. From 75f7f5f64312be2864cf67fe10af9ca83be45a45 Mon Sep 17 00:00:00 2001 From: Max Bachmann Date: Wed, 4 Sep 2024 15:43:14 +0200 Subject: [PATCH 5/5] Update Doc/c-api/unicode.rst Co-authored-by: Erlend E. Aasland --- Doc/c-api/unicode.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 9e2d9cbdc8d2b1..7d3e7a21a32477 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -616,9 +616,6 @@ APIs: Return the length of the Unicode object, in code points. - Check that *unicode* is a Unicode object, unlike :c:func:`PyUnicode_GET_LENGTH`, - which performs no error checking. - On error, set an exception and return ``-1``. .. versionadded:: 3.3