More minor fixes to C API docs (GH-31525)

* 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
This commit is contained in:
Jelle Zijlstra 2022-04-02 12:31:05 -07:00 committed by GitHub
parent 6066739ff7
commit 897bc6f928
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 30 additions and 29 deletions

View File

@ -1792,7 +1792,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`.

View File

@ -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

View File

@ -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.

View File

@ -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)

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -504,7 +504,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 |

View File

@ -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.

View File

@ -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