Merge branch 'main' into gh-50720-urllib

Author: orsenthil

Doc/builtins/exceptions.rst

@@ -396,10 +396,9 @@ The following exceptions are the exceptions that are usually raised.
 
    .. attribute:: strerror
 
-      The corresponding error message, as provided by
-      the operating system.  It is formatted by the C
-      functions :c:func:`!perror` under POSIX, and :c:func:`!FormatMessage`
-      under Windows.
+      The corresponding error message, as provided by the operating system.
+      Under POSIX, it is obtained using the C functions :c:func:`!strerror`
+      or :c:func:`!strerror_r`; under Windows, :c:func:`!FormatMessage` is used.
 
    .. attribute:: filename
                   filename2
@@ -567,11 +566,6 @@ The following exceptions are the exceptions that are usually raised.
       The column in the end line where the error occurred finishes. This is
       1-indexed: the first character in the line has an ``offset`` of 1.
 
-   For errors in f-string fields, the message is prefixed by "f-string: "
-   and the offsets are offsets in a text constructed from the replacement
-   expression.  For example, compiling f'Bad {a b} field' results in this
-   args attribute: ('f-string: ...', ('', 1, 2, '(a b)\n', 1, 5)).
-
    .. versionchanged:: 3.10
       Added the :attr:`end_lineno` and :attr:`end_offset` attributes.
 

Doc/builtins/functions.rst

@@ -772,7 +772,7 @@ are always available.  They are listed here in alphabetical order.
    still access all builtins.
 
    The *closure* argument specifies a closure--a tuple of cellvars.
-   It's only valid when the *object* is a code object containing
+   It's only valid when *source* is a code object containing
    :term:`free (closure) variables <closure variable>`.
    The length of the tuple must exactly match the length of the code object's
    :attr:`~codeobject.co_freevars` attribute.
@@ -1853,8 +1853,6 @@ are always available.  They are listed here in alphabetical order.
    including the name and address of the object.  A class can control what this
    function returns for its instances
    by defining a :meth:`~object.__repr__` method.
-   If :func:`sys.displayhook` is not accessible, this function will raise
-   :exc:`RuntimeError`.
 
    This class has a custom representation that can be evaluated::
 
@@ -2168,10 +2166,10 @@ are always available.  They are listed here in alphabetical order.
 
    When called directly within an ordinary method of a class, both arguments may
    be omitted ("zero-argument :func:`!super`"). In this case, *type* will be the
-   enclosing class, and *obj* will be the first argument of the immediately
-   enclosing function (typically ``self``). (This means that zero-argument
+   enclosing class, and *object_or_type* will be the first argument of the
+   immediately enclosing function (typically ``self``). Zero-argument
    :func:`!super` will not work as expected within nested functions, including
-   generator expressions, which implicitly create nested functions.)
+   generator expressions, which implicitly create nested functions.
 
    There are two typical use cases for *super*.  In a class hierarchy with
    single inheritance, *super* can be used to refer to parent classes without
@@ -2430,10 +2428,9 @@ are always available.  They are listed here in alphabetical order.
    determine the package context of the :keyword:`import` statement.
 
    *level* specifies whether to use absolute or relative imports. ``0`` (the
-   default) means only perform absolute imports.  Positive values for
-   *level* indicate the number of parent directories to search relative to the
-   directory of the module calling :func:`__import__` (see :pep:`328` for the
-   details).
+   default) means only perform absolute imports.  For relative imports,
+   ``1`` refers to the current package, ``2`` to its parent package, and so on
+   (see :pep:`328` for details).
 
    When the *name* variable is of the form ``package.module``, normally, the
    top-level package (the name up till the first dot) is returned, *not* the

Doc/builtins/stdtypes.rst

@@ -3780,8 +3780,8 @@ objects.
 
       If the :class:`bytearray` needs to shrink, bytes beyond *size* are truncated.
 
-      If the :class:`bytearray` needs to grow, all new bytes, those beyond *size*,
-      will be set to null bytes.
+      If the :class:`bytearray` needs to grow, all new bytes will be set to null
+      bytes.
 
 
       This is equivalent to:
@@ -5616,9 +5616,8 @@ Note, the non-operator versions of the :meth:`~set.update`,
 argument.
 
 Note, the *elem* argument to the :meth:`~object.__contains__`,
-:meth:`~set.remove`, and
-:meth:`~set.discard` methods may be a set.  To support searching for an equivalent
-frozenset, a temporary one is created from *elem*.
+:meth:`~set.remove`, and :meth:`~set.discard` methods may be a set.  In this case,
+an equivalent frozenset is searched for.
 
 Sets and frozensets are :ref:`generic <generics>` over the type of their elements.
 
@@ -5668,7 +5667,7 @@ can be used interchangeably to index the same dictionary entry.
 
    * Use a comma-separated list of ``key: value`` pairs within braces:
      ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 'jack', 4127: 'sjoerd'}``
-   * Use a dict comprehension: ``{}``, ``{x: x ** 2 for x in range(10)}``
+   * Use a dict comprehension: ``{x: x ** 2 for x in range(10)}``
    * Use the type constructor: ``dict()``,
      ``dict([('foo', 100), ('bar', 200)])``, ``dict(foo=100, bar=200)``
 
@@ -5879,9 +5878,8 @@ can be used interchangeably to index the same dictionary entry.
       Return a new view of the dictionary's values.  See the
       :ref:`documentation of view objects <dict-views>`.
 
-      An equality comparison between one ``dict.values()`` view and another
-      will always return ``False``. This also applies when comparing
-      ``dict.values()`` to itself::
+      An equality comparison between two distinct ``dict.values()`` views
+      will always return ``False``, even for views of the same dictionary::
 
          >>> d = {'a': 1}
          >>> d.values() == d.values()

Doc/c-api/code.rst

@@ -315,9 +315,9 @@ may change without deprecation warnings.
 
    Return a new opaque index value used to adding data to code objects.
 
-   You generally call this function once (per interpreter) and use the result
-   with ``PyCode_GetExtra`` and ``PyCode_SetExtra`` to manipulate
-   data on individual code objects.
+   You generally call this function once (per interpreter). Use the result with
+   :c:func:`PyUnstable_Code_GetExtra` and :c:func:`PyUnstable_Code_SetExtra`
+   to manipulate data on individual code objects.
 
    If *free* is not ``NULL``: when a code object is deallocated,
    *free* will be called on non-``NULL`` data stored under the new index.

Doc/c-api/codec.rst

@@ -47,7 +47,7 @@ Codec lookup API
 
 In the following functions, the *encoding* string is looked up converted to all
 lower-case characters, which makes encodings looked up through this mechanism
-effectively case-insensitive.  If no codec is found, a :exc:`KeyError` is set
+effectively case-insensitive.  If no codec is found, a :exc:`LookupError` is set
 and ``NULL`` returned.
 
 .. c:function:: PyObject* PyCodec_Encoder(const char *encoding)

Doc/c-api/extension-modules.rst

@@ -86,7 +86,7 @@ For example, a module called ``spam`` would be defined like this::
    static PySlot spam_slots[] = {
        PySlot_STATIC_DATA(Py_mod_abi, &abi_info),
        PySlot_STATIC_DATA(Py_mod_name, "spam"),
-       PySlot_FUNC(Py_mod_init, spam_init_function),
+       PySlot_FUNC(Py_mod_exec, spam_init_function),
        ...
        PySlot_END
    };

Doc/c-api/gcsupport.rst

@@ -127,7 +127,7 @@ rules:
 
 .. c:macro:: PyObject_GC_Resize(TYPE, op, newsize)
 
-   Resize an object allocated by :c:macro:`PyObject_NewVar`.
+   Resize an object allocated by :c:macro:`PyObject_GC_NewVar`.
    Returns the resized object of type ``TYPE*`` (refers to any C type)
    or ``NULL`` on failure.
 

Doc/deprecations/pending-removal-in-3.20.rst

@@ -39,6 +39,27 @@ Pending removal in Python 3.20
 
   (Contributed by Hugo van Kemenade and Stan Ulbrych in :gh:`76007`.)
 
+* The ``__author__``, ``__credits__``, ``__copyright__`` and ``__date__``
+  attributes have been deprecated in these standard library modules and will
+  be removed in Python 3.20. Attribution is preserved in the source code
+  and the version control history.
+
+  - :mod:`bz2`
+  - :mod:`concurrent.futures`
+  - :mod:`inspect`
+  - :mod:`io`
+  - :mod:`json`
+  - :mod:`logging`
+  - :mod:`optparse`
+  - :mod:`platform`
+  - :mod:`pydoc`
+  - :mod:`tarfile`
+  - :mod:`tkinter.ttk`
+  - :mod:`tokenize`
+  - :mod:`uuid`
+
+  (Contributed by Stan Ulbrych in :gh:`159240`.)
+
 * Deprecations defined by :pep:`829`:
 
   * Warnings are produced for ``import`` lines found in :file:`{name}.pth`

Doc/extending/extending.rst

@@ -334,6 +334,8 @@ event code, you might use the following code::
    PyObject *arglist;
    ...
    arglist = Py_BuildValue("(l)", eventcode);
+   if (arglist == NULL)
+       return NULL;
    result = PyObject_CallObject(my_callback, arglist);
    Py_DECREF(arglist);
    if (result == NULL)
@@ -342,17 +344,24 @@ event code, you might use the following code::
    Py_DECREF(result);
 
 Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
-the error check!  Also note that strictly speaking this code is not complete:
-:c:func:`Py_BuildValue` may run out of memory, and this should be checked.
+the error check!
 
 You may also call a function with keyword arguments by using
 :c:func:`PyObject_Call`, which supports arguments and keyword arguments.  As in
 the above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::
 
-   PyObject *dict;
+   PyObject *arglist, *dict;
    ...
+   arglist = PyTuple_New(0);
+   if (arglist == NULL)
+       return NULL;
    dict = Py_BuildValue("{s:i}", "name", val);
-   result = PyObject_Call(my_callback, NULL, dict);
+   if (dict == NULL) {
+       Py_DECREF(arglist);
+       return NULL;
+   }
+   result = PyObject_Call(my_callback, arglist, dict);
+   Py_DECREF(arglist);
    Py_DECREF(dict);
    if (result == NULL)
        return NULL; /* Pass error back */

Doc/extending/first-extension-module.rst

@@ -378,7 +378,7 @@ Add this array just below the ``spam_system`` function:
 As with module slots, a zero-filled sentinel marks the end of the array.
 
 Next, we'll add the method to the module.
-Add a :c:data:`Py_mod_methods` slot to your :c:type:`PyMethodDef` array:
+Add a :c:data:`Py_mod_methods` slot to your :c:type:`PySlot` array:
 
 .. literalinclude:: ../includes/capi-extension/spammodule-01.c
    :start-after: /// Module slot table
@@ -518,7 +518,7 @@ Add an ``if`` block for this:
    static PyObject *
    spam_system(PyObject *self, PyObject *arg)
    {
-      const char *command = PyUnicode_AsUTF8AndSize(arg);
+      const char *command = PyUnicode_AsUTF8AndSize(arg, NULL);
       if (command == NULL) {
          return NULL;
       }
@@ -548,7 +548,7 @@ the ``char *`` buffer, and using its result instead of the ``3``:
    static PyObject *
    spam_system(PyObject *self, PyObject *arg)
    {
-      const char *command = PyUnicode_AsUTF8AndSize(arg);
+      const char *command = PyUnicode_AsUTF8AndSize(arg, NULL);
       if (command == NULL) {
          return NULL;
       }