Mailman 3 April 2022 - Python-checkins

[3.10] More minor fixes to C API docs (GH-31525) (GH-32258)
by JelleZijlstra April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/11f5fd1135065908c281ddfe767daa357c… commit: 11f5fd1135065908c281ddfe767daa357c61e598 branch: 3.10 author: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)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(a)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

1 0

[3.9] More minor fixes to C API docs (GH-31525) (GH-32259)
by JelleZijlstra April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/6eff004b96ae9cdca1b36600fe10984982… commit: 6eff004b96ae9cdca1b36600fe1098498228f66d branch: 3.9 author: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-02T16:00:36-07:00 summary: [3.9] More minor fixes to C API docs (GH-31525) (GH-32259) * 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(a)gmail.com> files: M Doc/c-api/init.rst M Doc/c-api/long.rst M Doc/c-api/mapping.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 9d7876e055981..8f1382e008c1e 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1688,7 +1688,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/long.rst b/Doc/c-api/long.rst index 60e1791df9a45..95796e0fa506a 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/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 620204ca8e229..1058b2c77f308 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) @@ -281,6 +282,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 9f874382e85bb..43ccb44c35ba0 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 84f34e7dae80b..9e3045e796eec 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. @@ -125,7 +125,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 1e30d408ab6d1..1599b88e4aa27 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -461,7 +461,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 9ac9179097892..37591a495fd4d 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -185,7 +185,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. @@ -205,7 +205,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: @@ -336,7 +336,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 cc2d8fdaa513c..119a908171eb3 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -266,7 +266,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

1 0

[3.9] More minor fixes to C API docs (GH-31714) (GH-32260)
by JelleZijlstra April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/74138ac954f6ee04aefcfbb96240a5185b… commit: 74138ac954f6ee04aefcfbb96240a5185bd944c9 branch: 3.9 author: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-02T16:00:13-07:00 summary: [3.9] More minor fixes to C API docs (GH-31714) (GH-32260) * init_config: wording fixes * bytearray: remove XXX, there is a good link to the buffer docs * bytes, call, exceptions: minor wording fixes. (cherry picked from commit 677a87946630c5fbd9998969669b4dd4f4b32545) Co-authored-by: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> files: M Doc/c-api/bytearray.rst M Doc/c-api/bytes.rst M Doc/c-api/call.rst M Doc/c-api/exceptions.rst M Doc/c-api/init_config.rst diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst index 30bcfc7cf9f50..85a7d1373c2a8 100644 --- a/Doc/c-api/bytearray.rst +++ b/Doc/c-api/bytearray.rst @@ -42,8 +42,6 @@ Direct API functions Return a new bytearray object from any object, *o*, that implements the :ref:`buffer protocol <bufferobjects>`. - .. XXX expand about the buffer protocol, at least somewhere - .. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len) diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index de65701037a7c..32c7b80dc7ac6 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -5,7 +5,7 @@ Bytes Objects ------------- -These functions raise :exc:`TypeError` when expecting a bytes parameter and are +These functions raise :exc:`TypeError` when expecting a bytes parameter and called with a non-bytes parameter. .. index:: object: bytes diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst index 739b5e97d1515..cdf72bc1f4714 100644 --- a/Doc/c-api/call.rst +++ b/Doc/c-api/call.rst @@ -26,7 +26,7 @@ This convention is not only used by *tp_call*: :c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init` also pass arguments this way. -To call an object, use :c:func:`PyObject_Call` or other +To call an object, use :c:func:`PyObject_Call` or another :ref:`call API <capi-call>`. diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index df38ba43ec431..646dc5a543473 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -281,7 +281,7 @@ For convenience, some of these functions will always return a .. c:function:: void PyErr_SyntaxLocation(const char *filename, int lineno) - Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is + Like :c:func:`PyErr_SyntaxLocationEx`, but the *col_offset* parameter is omitted. @@ -333,7 +333,7 @@ an error value). Issue a warning message with explicit control over all warning attributes. This is a straightforward wrapper around the Python function - :func:`warnings.warn_explicit`, see there for more information. The *module* + :func:`warnings.warn_explicit`; see there for more information. The *module* and *registry* arguments may be set to ``NULL`` to get the default effect described there. @@ -441,7 +441,7 @@ Querying the error indicator error indicator. -.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) +.. c:function:: void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb) Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index 23009e4191f88..f44c7bb5cd5a8 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -823,7 +823,7 @@ Isolated Configuration isolate Python from the system. For example, to embed Python into an application. -This configuration ignores global configuration variables, environments +This configuration ignores global configuration variables, environment variables, command line arguments (:c:member:`PyConfig.argv` is not parsed) and user site directory. The C standard streams (ex: ``stdout``) and the LC_CTYPE locale are left unchanged. Signal handlers are not installed. @@ -1000,7 +1000,7 @@ Multi-Phase Initialization Private Provisional API -------------------------------------------------- This section is a private provisional API introducing multi-phase -initialization, the core feature of the :pep:`432`: +initialization, the core feature of :pep:`432`: * "Core" initialization phase, "bare minimum Python":

1 0

[3.9] Document func parameter of locale.atof (GH-18183) (GH-32261)
by JelleZijlstra April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/62da258a455974014ddc3a40466724bb81… commit: 62da258a455974014ddc3a40466724bb815f862d branch: 3.9 author: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-02T15:59:57-07:00 summary: [3.9] Document func parameter of locale.atof (GH-18183) (GH-32261) The second parameter (named `func`) has been present since the `locale` module was introduced in eef1d4e8b1, but has never been documented. This commit updates the documentation for `locale.atof` to clarify the behavior of the function and how the `func` parameter is used. Signed-off-by: Kevin Locke <kevin(a)kevinlocke.name>. (cherry picked from commit 208da6d508bb2683732151f4ae288dfc8001267c) Co-authored-by: Kevin Locke <kevin(a)kevinlocke.name> files: M Doc/library/locale.rst diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst index bf57a08355916..5b5a0c7552323 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -423,10 +423,10 @@ The :mod:`locale` module defines the following exception and functions: .. versionadded:: 3.5 -.. function:: atof(string) +.. function:: atof(string, func=float) - Converts a string to a floating point number, following the :const:`LC_NUMERIC` - settings. + Converts a string to a number, following the :const:`LC_NUMERIC` settings, + by calling *func* on the result of calling :func:`delocalize` on *string*. .. function:: atoi(string)

1 0

[3.10] Document func parameter of locale.atof (GH-18183) (GH-32262)
by JelleZijlstra April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/a930062d257b066705c9a681aa6c7f0f34… commit: a930062d257b066705c9a681aa6c7f0f342dea11 branch: 3.10 author: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-02T15:59:41-07:00 summary: [3.10] Document func parameter of locale.atof (GH-18183) (GH-32262) The second parameter (named `func`) has been present since the `locale` module was introduced in eef1d4e8b1, but has never been documented. This commit updates the documentation for `locale.atof` to clarify the behavior of the function and how the `func` parameter is used. Signed-off-by: Kevin Locke <kevin(a)kevinlocke.name> (cherry picked from commit 208da6d508bb2683732151f4ae288dfc8001267c) Co-authored-by: Kevin Locke <kevin(a)kevinlocke.name> files: M Doc/library/locale.rst diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst index 60d0c59d017c7..dd14a379b0c6c 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -435,10 +435,10 @@ The :mod:`locale` module defines the following exception and functions: .. versionadded:: 3.10 -.. function:: atof(string) +.. function:: atof(string, func=float) - Converts a string to a floating point number, following the :const:`LC_NUMERIC` - settings. + Converts a string to a number, following the :const:`LC_NUMERIC` settings, + by calling *func* on the result of calling :func:`delocalize` on *string*. .. function:: atoi(string)

1 0

bpo-45584: Clarify `math.trunc` documentation (GH-29183)
by miss-islington April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/694425817ba2b3a796acb3413a7111f6de… commit: 694425817ba2b3a796acb3413a7111f6de4bd086 branch: 3.9 author: Miss Islington (bot) <31488909+miss-islington(a)users.noreply.github.com> committer: miss-islington <31488909+miss-islington(a)users.noreply.github.com> date: 2022-04-02T15:36:33-07:00 summary: bpo-45584: Clarify `math.trunc` documentation (GH-29183) While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious) Co-authored-by: Alex Waygood <Alex.Waygood(a)Gmail.com> Co-authored-by: Éric Araujo <merwok(a)netwok.org> Co-authored-by: Terry Jan Reedy <tjreedy(a)udel.edu> Co-authored-by: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> (cherry picked from commit ebbdbbff5d6840807e46ec61b8a323e94ee88de2) Co-authored-by: Arthur Milchior <arthur(a)milchior.fr> files: M Doc/library/math.rst diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 9783e9ef825d50..ad9116b63e6066 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -32,8 +32,8 @@ Number-theoretic and representation functions .. function:: ceil(x) Return the ceiling of *x*, the smallest integer greater than or equal to *x*. - If *x* is not a float, delegates to ``x.__ceil__()``, which should return an - :class:`~numbers.Integral` value. + If *x* is not a float, delegates to :meth:`x.__ceil__ <object.__ceil__>`, + which should return an :class:`~numbers.Integral` value. .. function:: comb(n, k) @@ -77,9 +77,9 @@ Number-theoretic and representation functions .. function:: floor(x) - Return the floor of *x*, the largest integer less than or equal to *x*. - If *x* is not a float, delegates to ``x.__floor__()``, which should return an - :class:`~numbers.Integral` value. + Return the floor of *x*, the largest integer less than or equal to *x*. If + *x* is not a float, delegates to :meth:`x.__floor__ <object.__floor__>`, which + should return an :class:`~numbers.Integral` value. .. function:: fmod(x, y) @@ -298,9 +298,11 @@ Number-theoretic and representation functions .. function:: trunc(x) - Return the :class:`~numbers.Real` value *x* truncated to an - :class:`~numbers.Integral` (usually an integer). Delegates to - :meth:`x.__trunc__() <object.__trunc__>`. + Return *x* with the fractional part + removed, leaving the integer part. This rounds toward 0: ``trunc()`` is + equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` + for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__ + <object.__trunc__>`, which should return an :class:`~numbers.Integral` value. .. function:: ulp(x)

1 0

bpo-45584: Clarify `math.trunc` documentation (GH-29183)
by miss-islington April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/3031b867531009d270d5d7d3e53e739c4c… commit: 3031b867531009d270d5d7d3e53e739c4cba8816 branch: 3.10 author: Miss Islington (bot) <31488909+miss-islington(a)users.noreply.github.com> committer: miss-islington <31488909+miss-islington(a)users.noreply.github.com> date: 2022-04-02T15:30:59-07:00 summary: bpo-45584: Clarify `math.trunc` documentation (GH-29183) While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious) Co-authored-by: Alex Waygood <Alex.Waygood(a)Gmail.com> Co-authored-by: Éric Araujo <merwok(a)netwok.org> Co-authored-by: Terry Jan Reedy <tjreedy(a)udel.edu> Co-authored-by: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> (cherry picked from commit ebbdbbff5d6840807e46ec61b8a323e94ee88de2) Co-authored-by: Arthur Milchior <arthur(a)milchior.fr> files: M Doc/library/math.rst diff --git a/Doc/library/math.rst b/Doc/library/math.rst index d485ae5c2706a..7ba5fa4a0b4e7 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -32,8 +32,8 @@ Number-theoretic and representation functions .. function:: ceil(x) Return the ceiling of *x*, the smallest integer greater than or equal to *x*. - If *x* is not a float, delegates to ``x.__ceil__()``, which should return an - :class:`~numbers.Integral` value. + If *x* is not a float, delegates to :meth:`x.__ceil__ <object.__ceil__>`, + which should return an :class:`~numbers.Integral` value. .. function:: comb(n, k) @@ -77,9 +77,9 @@ Number-theoretic and representation functions .. function:: floor(x) - Return the floor of *x*, the largest integer less than or equal to *x*. - If *x* is not a float, delegates to ``x.__floor__()``, which should return an - :class:`~numbers.Integral` value. + Return the floor of *x*, the largest integer less than or equal to *x*. If + *x* is not a float, delegates to :meth:`x.__floor__ <object.__floor__>`, which + should return an :class:`~numbers.Integral` value. .. function:: fmod(x, y) @@ -298,9 +298,11 @@ Number-theoretic and representation functions .. function:: trunc(x) - Return the :class:`~numbers.Real` value *x* truncated to an - :class:`~numbers.Integral` (usually an integer). Delegates to - :meth:`x.__trunc__() <object.__trunc__>`. + Return *x* with the fractional part + removed, leaving the integer part. This rounds toward 0: ``trunc()`` is + equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` + for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__ + <object.__trunc__>`, which should return an :class:`~numbers.Integral` value. .. function:: ulp(x)

1 0

bpo-45584: Clarify `math.trunc` documentation (GH-29183)
by JelleZijlstra April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/ebbdbbff5d6840807e46ec61b8a323e94e… commit: ebbdbbff5d6840807e46ec61b8a323e94ee88de2 branch: main author: Arthur Milchior <arthur(a)milchior.fr> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-02T15:11:20-07:00 summary: bpo-45584: Clarify `math.trunc` documentation (GH-29183) While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious) Co-authored-by: Alex Waygood <Alex.Waygood(a)Gmail.com> Co-authored-by: Éric Araujo <merwok(a)netwok.org> Co-authored-by: Terry Jan Reedy <tjreedy(a)udel.edu> Co-authored-by: Jelle Zijlstra <jelle.zijlstra(a)gmail.com> files: M Doc/library/math.rst diff --git a/Doc/library/math.rst b/Doc/library/math.rst index c0f9614231912..48030fae189ba 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -32,8 +32,8 @@ Number-theoretic and representation functions .. function:: ceil(x) Return the ceiling of *x*, the smallest integer greater than or equal to *x*. - If *x* is not a float, delegates to ``x.__ceil__()``, which should return an - :class:`~numbers.Integral` value. + If *x* is not a float, delegates to :meth:`x.__ceil__ <object.__ceil__>`, + which should return an :class:`~numbers.Integral` value. .. function:: comb(n, k) @@ -77,9 +77,9 @@ Number-theoretic and representation functions .. function:: floor(x) - Return the floor of *x*, the largest integer less than or equal to *x*. - If *x* is not a float, delegates to ``x.__floor__()``, which should return an - :class:`~numbers.Integral` value. + Return the floor of *x*, the largest integer less than or equal to *x*. If + *x* is not a float, delegates to :meth:`x.__floor__ <object.__floor__>`, which + should return an :class:`~numbers.Integral` value. .. function:: fmod(x, y) @@ -298,9 +298,11 @@ Number-theoretic and representation functions .. function:: trunc(x) - Return the :class:`~numbers.Real` value *x* truncated to an - :class:`~numbers.Integral` (usually an integer). Delegates to - :meth:`x.__trunc__() <object.__trunc__>`. + Return *x* with the fractional part + removed, leaving the integer part. This rounds toward 0: ``trunc()`` is + equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil` + for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__ + <object.__trunc__>`, which should return an :class:`~numbers.Integral` value. .. function:: ulp(x)

1 0

os docs: fix typo (GH-28996)
by miss-islington April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/8d9a75b206d40b096d9a8f9bcc40d95b76… commit: 8d9a75b206d40b096d9a8f9bcc40d95b7687d6eb branch: 3.10 author: Miss Islington (bot) <31488909+miss-islington(a)users.noreply.github.com> committer: miss-islington <31488909+miss-islington(a)users.noreply.github.com> date: 2022-04-02T15:00:12-07:00 summary: os docs: fix typo (GH-28996) Co-authored-by: Jacob Walls <jacobtylerwalls(a)gmail.com> (cherry picked from commit 1f80dcd2442f2a354097797fedc077592984903b) Co-authored-by: Vitor Buxbaum Orlandi <vitorbuxbaum(a)gmail.com> files: M Doc/library/os.rst diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 2a1ea05c5c833..203995c80fd32 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -113,7 +113,7 @@ of the UTF-8 encoding: :ref:`error handler <error-handlers>` being enabled for :data:`sys.stdin` and :data:`sys.stdout` (:data:`sys.stderr` continues to use ``backslashreplace`` as it does in the default locale-aware mode) -* On Unix, :func:`os.device_encoding` returns ``'UTF-8'``. rather than the +* On Unix, :func:`os.device_encoding` returns ``'UTF-8'`` rather than the device encoding. Note that the standard stream settings in UTF-8 mode can be overridden by

1 0

os docs: fix typo (GH-28996)
by JelleZijlstra April 2, 2022

April 2, 2022

https://github.com/python/cpython/commit/1f80dcd2442f2a354097797fedc0775929… commit: 1f80dcd2442f2a354097797fedc077592984903b branch: main author: Vitor Buxbaum Orlandi <vitorbuxbaum(a)gmail.com> committer: JelleZijlstra <jelle.zijlstra(a)gmail.com> date: 2022-04-02T14:38:33-07:00 summary: os docs: fix typo (GH-28996) Co-authored-by: Jacob Walls <jacobtylerwalls(a)gmail.com> files: M Doc/library/os.rst diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 05e0303614ed1..60eac2f78572e 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -113,7 +113,7 @@ of the UTF-8 encoding: :ref:`error handler <error-handlers>` being enabled for :data:`sys.stdin` and :data:`sys.stdout` (:data:`sys.stderr` continues to use ``backslashreplace`` as it does in the default locale-aware mode) -* On Unix, :func:`os.device_encoding` returns ``'UTF-8'``. rather than the +* On Unix, :func:`os.device_encoding` returns ``'UTF-8'`` rather than the device encoding. Note that the standard stream settings in UTF-8 mode can be overridden by

1 0