From 382e3b3d10937cda04397d2f509687b3f1287063 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 22 Apr 2022 09:17:53 +0200 Subject: [PATCH 1/6] Update weakref docs --- Doc/c-api/weakref.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/c-api/weakref.rst b/Doc/c-api/weakref.rst index 98ebe711adaeb4..7b32e17a239729 100644 --- a/Doc/c-api/weakref.rst +++ b/Doc/c-api/weakref.rst @@ -66,5 +66,4 @@ as much as it can. .. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref) - Similar to :c:func:`PyWeakref_GetObject`, but implemented as a macro that does no - error checking. + Similar to :c:func:`PyWeakref_GetObject`, but does no error checking. From 8f935b4f65340163301bb45f2defe3f74244e412 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 22 Apr 2022 09:19:02 +0200 Subject: [PATCH 2/6] Update list docs --- Doc/c-api/list.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst index f338e2ae066895..f9e65354a259f4 100644 --- a/Doc/c-api/list.rst +++ b/Doc/c-api/list.rst @@ -53,7 +53,7 @@ List Objects .. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list) - Macro form of :c:func:`PyList_Size` without error checking. + Similar to :c:func:`PyList_Size`, but without error checking. .. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index) @@ -66,7 +66,7 @@ List Objects .. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i) - Macro form of :c:func:`PyList_GetItem` without error checking. + Similar to :c:func:`PyList_GetItem`, but without error checking. .. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item) From 155141242b5d3332608fc6bd4f81d8ec79a7e459 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 22 Apr 2022 09:31:27 +0200 Subject: [PATCH 3/6] Update unicode docs --- Doc/c-api/unicode.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 11aa751cdad153..38270f0e21ba91 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -84,8 +84,8 @@ Python: is exposed to Python code as ``str``. -The following APIs are really C macros and can be used to do fast checks and to -access internal read-only data of Unicode objects: +The following APIs are C macros and static inlined functions for fast checks and +access to internal read-only data of Unicode objects: .. c:function:: int PyUnicode_Check(PyObject *o) @@ -172,9 +172,9 @@ access internal read-only data of Unicode objects: Py_UCS4 value) Write into a canonical representation *data* (as obtained with - :c:func:`PyUnicode_DATA`). This macro does not do any sanity checks and is + :c:func:`PyUnicode_DATA`). This function performs no sanity checks, and is intended for usage in loops. The caller should cache the *kind* value and - *data* pointer as obtained from other macro calls. *index* is the index in + *data* pointer as obtained from other calls. *index* is the index in the string (starts at 0) and *value* is the new code point value which should be written to that location. @@ -198,7 +198,7 @@ access internal read-only data of Unicode objects: .. versionadded:: 3.3 -.. c:macro:: PyUnicode_MAX_CHAR_VALUE(o) +.. c:function:: PyUnicode_MAX_CHAR_VALUE(o) Return the maximum code point that is suitable for creating another string based on *o*, which must be in the "canonical" representation. This is @@ -239,7 +239,7 @@ access internal read-only data of Unicode objects: a Unicode object (not checked). .. versionchanged:: 3.3 - This macro is now inefficient -- because in many cases the + This function is now inefficient -- because in many cases the :c:type:`Py_UNICODE` representation does not exist and needs to be created -- and can fail (return ``NULL`` with an exception set). Try to port the code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use @@ -642,8 +642,8 @@ APIs: .. c:function:: Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index) Read a character from a string. This function checks that *unicode* is a - Unicode object and the index is not out of bounds, in contrast to the macro - version :c:func:`PyUnicode_READ_CHAR`. + Unicode object and the index is not out of bounds, in contrast to + :c:func:`PyUnicode_READ_CHAR`, which performs no error checking. .. versionadded:: 3.3 From 0eccc8719b896f2386c090583985904b72335321 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 22 Apr 2022 09:37:07 +0200 Subject: [PATCH 4/6] Update tuple docs --- Doc/c-api/tuple.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index 6919e61022788f..9b85522600d4e7 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -91,7 +91,7 @@ Tuple Objects .. note:: - This macro "steals" a reference to *o*, and, unlike + This function "steals" a reference to *o*, and, unlike :c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that is being replaced; any reference in the tuple at position *pos* will be leaked. @@ -215,7 +215,8 @@ type. .. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o) - Macro equivalent of :c:func:`PyStructSequence_SetItem`. + Similar to :c:func:`PyStructSequence_SetItem`, but implemented as a static + inlined function. .. note:: From 85b8a68a9501c4d5396ba7821e623e8e1c2848cd Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 22 Apr 2022 10:54:42 +0200 Subject: [PATCH 5/6] Fix PyUnicode_MAX_CHAR_VALUE --- 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 38270f0e21ba91..5984123aadf55d 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -198,7 +198,7 @@ access to internal read-only data of Unicode objects: .. versionadded:: 3.3 -.. c:function:: PyUnicode_MAX_CHAR_VALUE(o) +.. c:function:: Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *o) Return the maximum code point that is suitable for creating another string based on *o*, which must be in the "canonical" representation. This is From 95daf2625f33eda37c876819e9fdf5f7b10e5e19 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 22 Apr 2022 14:37:40 +0200 Subject: [PATCH 6/6] Address review: fix unicode argument type --- 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 5984123aadf55d..00faac5b69abdb 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -168,8 +168,8 @@ access to internal read-only data of Unicode objects: .. versionadded:: 3.3 -.. c:function:: void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, \ - Py_UCS4 value) +.. c:function:: void PyUnicode_WRITE(unsigned int kind, void *data, \ + Py_ssize_t index, Py_UCS4 value) Write into a canonical representation *data* (as obtained with :c:func:`PyUnicode_DATA`). This function performs no sanity checks, and is @@ -181,7 +181,8 @@ access to internal read-only data of Unicode objects: .. versionadded:: 3.3 -.. c:function:: Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index) +.. c:function:: Py_UCS4 PyUnicode_READ(unsigned int kind, void *data, \ + Py_ssize_t index) Read a code point from a canonical representation *data* (as obtained with :c:func:`PyUnicode_DATA`). No checks or ready calls are performed.