From 4d6eff2d9cdd4ac884582e49465af6fa5c4ad33d Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 18:40:10 -0800 Subject: [PATCH 01/13] wording fixes in type.rst --- Doc/c-api/type.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index e6a5a0ea9c121b..d740e4eb0897e5 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -296,12 +296,12 @@ The following functions and structs are used to create .. versionchanged:: 3.9 - Slots in :c:type:`PyBufferProcs` in may be set in the unlimited API. + Slots in :c:type:`PyBufferProcs` may be set in the unlimited API. .. versionchanged:: 3.11 :c:member:`~PyBufferProcs.bf_getbuffer` and :c:member:`~PyBufferProcs.bf_releasebuffer` are now available - under limited API. + under the limited API. .. c:member:: void *PyType_Slot.pfunc From 298807aaa1cbc49bcb5b38812447717cfea6755f Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 18:53:02 -0800 Subject: [PATCH 02/13] grammar and punctuation in sys.rst --- Doc/c-api/sys.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index cca8b7bb6d6448..de94e3f0180f0a 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -177,7 +177,7 @@ Operating System Utilities Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free` to free the memory. Return ``NULL`` on encoding error or memory allocation - error + error. If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on success, or set to the index of the invalid character on encoding error. @@ -207,7 +207,7 @@ Operating System Utilities .. versionchanged:: 3.8 The function now uses the UTF-8 encoding on Windows if - :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero; + :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero. .. _systemfunctions: @@ -356,7 +356,7 @@ accessible to C code. They all work with the current interpreter thread's .. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData) Append the callable *hook* to the list of active auditing hooks. - Return zero for success + Return zero on success and non-zero on failure. If the runtime has been initialized, also set an error on failure. Hooks added through this API are called for all interpreters created by the runtime. From 6f465cb1192fdb35a28b8c9c39c4f20395b90927 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 19:09:49 -0800 Subject: [PATCH 03/13] set: grammar fixes --- Doc/c-api/set.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index eca19c4d816474..f0d905bae8ae44 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -13,7 +13,7 @@ Set Objects object: frozenset This section details the public API for :class:`set` and :class:`frozenset` -objects. Any functionality not listed below is best accessed using the either +objects. Any functionality not listed below is best accessed using either the abstract object protocol (including :c:func:`PyObject_CallMethod`, :c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`, :c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and @@ -31,7 +31,7 @@ the abstract object protocol (including :c:func:`PyObject_CallMethod`, in that it is a fixed size for small sets (much like tuple storage) and will point to a separate, variable sized block of memory for medium and large sized sets (much like list storage). None of the fields of this structure should be - considered public and are subject to change. All access should be done through + considered public and all are subject to change. All access should be done through the documented API rather than by manipulating the values in the structure. @@ -131,7 +131,7 @@ or :class:`frozenset` or instances of their subtypes. .. c:function:: int PySet_Add(PyObject *set, PyObject *key) Add *key* to a :class:`set` instance. Also works with :class:`frozenset` - instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values + instances (like :c:func:`PyTuple_SetItem` it can be used to fill in the values of brand new frozensets before they are exposed to other code). Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a From 92124583a0adb2d8ab30cb33ee9094acf2c51bfb Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 19:09:58 -0800 Subject: [PATCH 04/13] structures: capitalization fix --- Doc/c-api/structures.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index 49f2a614e3507e..f811c95eaa3153 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -501,7 +501,7 @@ Accessing attributes of extension types +=============+==================+===================================+ | name | const char \* | attribute name | +-------------+------------------+-----------------------------------+ - | get | getter | C Function to get the attribute | + | get | getter | C function to get the attribute | +-------------+------------------+-----------------------------------+ | set | setter | optional C function to set or | | | | delete the attribute, if omitted | From 5e4e84ea787b752aad9b946a3e71af7d7aec1c8f Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 19:15:37 -0800 Subject: [PATCH 05/13] grammar fixes for sequence --- Doc/c-api/sequence.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index 65818859041179..c78d273f9f149f 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -8,10 +8,10 @@ Sequence Protocol .. c:function:: int PySequence_Check(PyObject *o) - Return ``1`` if the object provides sequence protocol, and ``0`` otherwise. + Return ``1`` if the object provides the sequence protocol, and ``0`` otherwise. Note that it returns ``1`` for Python classes with a :meth:`__getitem__` - method unless they are :class:`dict` subclasses since in general case it - is impossible to determine what the type of keys it supports. This + method, unless they are :class:`dict` subclasses, since in general it + is impossible to determine what type of keys the class supports. This function always succeeds. @@ -69,7 +69,7 @@ Sequence Protocol is the equivalent of the Python statement ``o[i] = v``. This function *does not* steal a reference to *v*. - If *v* is ``NULL``, the element is deleted, however this feature is + If *v* is ``NULL``, the element is deleted, but this feature is deprecated in favour of using :c:func:`PySequence_DelItem`. @@ -147,7 +147,7 @@ Sequence Protocol Returns the length of *o*, assuming that *o* was returned by :c:func:`PySequence_Fast` and that *o* is not ``NULL``. The size can also be - gotten by calling :c:func:`PySequence_Size` on *o*, but + retrieved by calling :c:func:`PySequence_Size` on *o*, but :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list or tuple. From 255012933412182e8add2322cae39bdf9e82f9de Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 19:26:40 -0800 Subject: [PATCH 06/13] objects: point to Py_TYPE instead of direct object access --- Doc/c-api/object.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 41a3affcf9842a..9dcfd769c64a05 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -93,7 +93,7 @@ Object Protocol return ``0`` on success. This is the equivalent of the Python statement ``o.attr_name = v``. - If *v* is ``NULL``, the attribute is deleted, however this feature is + If *v* is ``NULL``, the attribute is deleted, but this feature is deprecated in favour of using :c:func:`PyObject_DelAttrString`. @@ -291,7 +291,7 @@ Object Protocol of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``. This is equivalent to the Python expression ``type(o)``. This function increments the reference count of the return value. There's really no reason to use this - function instead of the common expression ``o->ob_type``, which returns a + function instead of the :c:func:`Py_TYPE()` function, which returns a pointer of type :c:type:`PyTypeObject*`, except when the incremented reference count is needed. From 3929c97a9f361d5290ce961b4d3811e24511f091 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 19:33:29 -0800 Subject: [PATCH 07/13] numbers: add more explicit Python equivalences --- Doc/c-api/number.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst index 37979bb506bcfa..11c9c67d36a678 100644 --- a/Doc/c-api/number.rst +++ b/Doc/c-api/number.rst @@ -44,7 +44,7 @@ Number Protocol .. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2) Return the floor of *o1* divided by *o2*, or ``NULL`` on failure. This is - equivalent to the "classic" division of integers. + the equivalent of the Python expression ``o1 // o2``. .. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2) @@ -53,7 +53,7 @@ Number Protocol *o2*, or ``NULL`` on failure. The return value is "approximate" because binary floating point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating point value when - passed two integers. + passed two integers. This is the equivalent of the Python expression ``o1 / o2``. .. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2) @@ -180,6 +180,7 @@ Number Protocol floating point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating point value when passed two integers. The operation is done *in-place* when *o1* supports it. + This is the equivalent of the Python statement ``o1 /= o2``. .. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2) @@ -285,6 +286,6 @@ Number Protocol .. c:function:: int PyIndex_Check(PyObject *o) - Returns ``1`` if *o* is an index integer (has the nb_index slot of the - tp_as_number structure filled in), and ``0`` otherwise. + Returns ``1`` if *o* is an index integer (has the ``nb_index`` slot of the + ``tp_as_number`` structure filled in), and ``0`` otherwise. This function always succeeds. From a7399edd4967cee8b28d0dbb555c38b549cd30ce Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 19:44:05 -0800 Subject: [PATCH 08/13] method: add missing period --- Doc/c-api/method.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/method.rst b/Doc/c-api/method.rst index 23852251dfe020..6e7e1e21aa93f2 100644 --- a/Doc/c-api/method.rst +++ b/Doc/c-api/method.rst @@ -27,7 +27,7 @@ to bind a :c:data:`PyCFunction` to a class object. It replaces the former call .. c:function:: PyObject* PyInstanceMethod_New(PyObject *func) - Return a new instance method object, with *func* being any callable object + Return a new instance method object, with *func* being any callable object. *func* is the function that will be called when the instance method is called. From fc4f6381f6fb1f01a3fe4608dda43e933e8bf702 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 19:59:41 -0800 Subject: [PATCH 09/13] memory: grammar fix --- Doc/c-api/memory.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 01b646c226e6d9..e81a246cb75cca 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -306,7 +306,7 @@ memory from the Python heap. .. note:: There is no guarantee that the memory returned by these allocators can be - successfully casted to a Python object when intercepting the allocating + successfully cast to a Python object when intercepting the allocating functions in this domain by the methods described in the :ref:`Customize Memory Allocators ` section. From e9a0a2ecc0144a535b3b20c3892c43c107e36e9a Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 20:03:06 -0800 Subject: [PATCH 10/13] mapping: grammar fixes --- Doc/c-api/mapping.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index 682160d1475c1c..3c9d282c6d0ab0 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -11,10 +11,10 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and .. c:function:: int PyMapping_Check(PyObject *o) - Return ``1`` if the object provides mapping protocol or supports slicing, + Return ``1`` if the object provides the mapping protocol or supports slicing, and ``0`` otherwise. Note that it returns ``1`` for Python classes with - a :meth:`__getitem__` method since in general case it is impossible to - determine what type of keys it supports. This function always succeeds. + a :meth:`__getitem__` method, since in general it is impossible to + determine what type of keys the class supports. This function always succeeds. .. c:function:: Py_ssize_t PyMapping_Size(PyObject *o) From a299539827b4ac9f96278fc05a99188da0e9cc70 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 20:09:42 -0800 Subject: [PATCH 11/13] long: grammar fix --- Doc/c-api/long.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 4201490286b82f..620344e71373b2 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -41,7 +41,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. Return a new :c:type:`PyLongObject` object from *v*, or ``NULL`` on failure. The current implementation keeps an array of integer objects for all integers - between ``-5`` and ``256``, when you create an int in that range you actually + between ``-5`` and ``256``. When you create an int in that range you actually just get back a reference to the existing object. From 41626fd4e02d4a7121a9c8632f792da6b1b0e7f0 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 20:11:08 -0800 Subject: [PATCH 12/13] iter: fix grammar for PyAIter_Check --- Doc/c-api/iter.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst index 3e388bb917a029..434d2021cea8e6 100644 --- a/Doc/c-api/iter.rst +++ b/Doc/c-api/iter.rst @@ -14,8 +14,8 @@ There are two functions specifically for working with iterators. .. c:function:: int PyAIter_Check(PyObject *o) - Returns non-zero if the object 'obj' provides :class:`AsyncIterator` - protocols, and ``0`` otherwise. This function always succeeds. + Return non-zero if the object *o* provides the :class:`AsyncIterator` + protocol, and ``0`` otherwise. This function always succeeds. .. versionadded:: 3.10 From 296a766ee2255f2812c7e31ff7ec68dd5004a147 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 22 Feb 2022 20:39:53 -0800 Subject: [PATCH 13/13] init: grammar fix --- Doc/c-api/init.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 322b9e4d251e76..3fda9c3af4d2a5 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1783,7 +1783,7 @@ is not possible due to its implementation being opaque at build time. argument is `NULL`. .. note:: - A freed key becomes a dangling pointer, you should reset the key to + A freed key becomes a dangling pointer. You should reset the key to `NULL`.