[Python-checkins] [3.10] More minor fixes to C API docs (GH-31525) (GH-32258)
JelleZijlstra
webhook-mailer at python.org
Sat Apr 2 19:00:56 EDT 2022
https://github.com/python/cpython/commit/11f5fd1135065908c281ddfe767daa357c61e598
commit: 11f5fd1135065908c281ddfe767daa357c61e598
branch: 3.10
author: Jelle Zijlstra <jelle.zijlstra at gmail.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-04-02T16:00:51-07:00
summary:
[3.10] More minor fixes to C API docs (GH-31525) (GH-32258)
* wording fixes in type.rst
* grammar and punctuation in sys.rst
* set: grammar fixes
* structures: capitalization fix
* grammar fixes for sequence
* objects: point to Py_TYPE instead of direct object access
* numbers: add more explicit Python equivalences
* method: add missing period
* memory: grammar fix
* mapping: grammar fixes
* long: grammar fix
* iter: fix grammar for PyAIter_Check
* init: grammar fix.
(cherry picked from commit 897bc6f9282238d5fb32d232ab62d30675244736)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>
files:
M Doc/c-api/init.rst
M Doc/c-api/iter.rst
M Doc/c-api/long.rst
M Doc/c-api/mapping.rst
M Doc/c-api/memory.rst
M Doc/c-api/method.rst
M Doc/c-api/number.rst
M Doc/c-api/object.rst
M Doc/c-api/sequence.rst
M Doc/c-api/set.rst
M Doc/c-api/structures.rst
M Doc/c-api/sys.rst
M Doc/c-api/type.rst
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 9ac3039d02ec3..a522790446001 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1725,7 +1725,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`.
diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst
index 3e388bb917a02..434d2021cea8e 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
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 4201490286b82..620344e71373b 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.
diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst
index 682160d1475c1..3c9d282c6d0ab 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)
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 0746d9ac52a7b..ced7ca79ca590 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 <customize-memory-allocators>` section.
diff --git a/Doc/c-api/method.rst b/Doc/c-api/method.rst
index 23852251dfe02..6e7e1e21aa93f 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.
diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst
index 37979bb506bcf..11c9c67d36a67 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.
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 41a3affcf9842..9dcfd769c64a0 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.
diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst
index 6581885904117..c78d273f9f149 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.
diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst
index eca19c4d81647..f0d905bae8ae4 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
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index 05c54ccc8dab5..839c889a6c8a7 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -494,7 +494,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 |
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 97717f5fc1923..350d4e1de41ba 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:
@@ -338,7 +338,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.
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index c472e8df9cf43..01d00bede544d 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -272,7 +272,7 @@ 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.
.. c:member:: void *PyType_Slot.pfunc
More information about the Python-checkins
mailing list