diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 152d4c8e503..82c4acebf1b 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -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`. diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst index 3e388bb917a..434d2021cea 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 4201490286b..620344e7137 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 682160d1475..3c9d282c6d0 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 01b646c226e..e81a246cb75 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. diff --git a/Doc/c-api/method.rst b/Doc/c-api/method.rst index 23852251dfe..6e7e1e21aa9 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 37979bb506b..11c9c67d36a 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 41a3affcf98..9dcfd769c64 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 65818859041..c78d273f9f1 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 eca19c4d816..f0d905bae8a 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 3270d7d8fba..aa74f6cce1a 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -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 | diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index cca8b7bb6d6..de94e3f0180 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. diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index e6a5a0ea9c1..d740e4eb089 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