Docs: correct API guidance and examples

Doc/builtins/functions.rst

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

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.
 

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/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;
       }

Doc/extending/newtypes_tutorial.rst

@@ -893,7 +893,7 @@ function::
 Before calling :c:func:`PyType_Ready`, the type structure must have the
 :c:member:`~PyTypeObject.tp_base` slot filled in.  When we are deriving an
 existing type, it is not necessary to fill out the :c:member:`~PyTypeObject.tp_alloc`
-slot with :c:func:`PyType_GenericNew` -- the allocation function from the base
+slot with :c:func:`PyType_GenericAlloc` -- the allocation function from the base
 type will be inherited.
 
 After that, calling :c:func:`PyType_Ready` and adding the type object to the

Doc/library/http.cookiejar.rst

@@ -777,7 +777,7 @@ returned::
    import urllib.request
    from http.cookiejar import CookieJar, DefaultCookiePolicy
    policy = DefaultCookiePolicy(
-       rfc2965=True, strict_ns_domain=Policy.DomainStrict,
+       rfc2965=True, strict_ns_domain=DefaultCookiePolicy.DomainStrict,
        blocked_domains=["ads.net", ".ads.net"])
    cj = CookieJar(policy)
    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))

Doc/library/mailbox.rst

@@ -1747,6 +1747,6 @@ due to malformed messages in the mailbox::
                inbox.unlock()
                break               # Found destination, so stop looking.
 
-   for box in boxes.itervalues():
+   for box in boxes.values():
        box.close()
 

Doc/library/os.rst

@@ -1284,8 +1284,8 @@ as internal buffering of data.
    * :const:`SEEK_SET` or ``0`` -- set *pos* relative to the beginning of the file
    * :const:`SEEK_CUR` or ``1`` -- set *pos* relative to the current file position
    * :const:`SEEK_END` or ``2`` -- set *pos* relative to the end of the file
-   * :const:`SEEK_HOLE` -- set *pos* to the next data location, relative to *pos*
-   * :const:`SEEK_DATA` -- set *pos* to the next data hole, relative to *pos*
+   * :const:`SEEK_DATA` -- set *pos* to the next data location, relative to *pos*
+   * :const:`SEEK_HOLE` -- set *pos* to the next data hole, relative to *pos*
 
    .. versionchanged:: 3.3
 

Doc/library/ssl.rst

@@ -479,7 +479,7 @@ Certificate handling
 
    The function returns a list of (cert_bytes, encoding_type, trust) tuples.
    The encoding_type specifies the encoding of cert_bytes. It is either
-   :const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
+   ``'x509_asn'`` for X.509 ASN.1 data or ``'pkcs_7_asn'`` for
    PKCS#7 ASN.1 data. Trust specifies the purpose of the certificate as a set
    of OIDS or exactly ``True`` if the certificate is trustworthy for all
    purposes.
@@ -500,9 +500,9 @@ Certificate handling
    one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
    stores, too.
 
-   The function returns a list of (cert_bytes, encoding_type, trust) tuples.
+   The function returns a list of (cert_bytes, encoding_type) tuples.
    The encoding_type specifies the encoding of cert_bytes. It is either
-   :const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
+   ``'x509_asn'`` for X.509 ASN.1 data or ``'pkcs_7_asn'`` for
    PKCS#7 ASN.1 data.
 
    .. availability:: Windows.

Doc/library/tracemalloc.rst

@@ -655,8 +655,7 @@ StatisticDiff
    .. attribute:: count_diff
 
       Difference of number of memory blocks between the old and the new
-      snapshots (``int``): ``0`` if the memory blocks have been allocated in
-      the new snapshot.
+      snapshots (``int``).
 
    .. attribute:: size
 
@@ -666,8 +665,7 @@ StatisticDiff
    .. attribute:: size_diff
 
       Difference of total size of memory blocks in bytes between the old and
-      the new snapshots (``int``): ``0`` if the memory blocks have been
-      allocated in the new snapshot.
+      the new snapshots (``int``).
 
    .. attribute:: traceback
 

Doc/library/zipfile.rst

@@ -856,7 +856,7 @@ The :class:`PyZipFile` constructor takes the same parameters as the
       in ``test`` directories or start with the string ``test_``, we can use a
       *filterfunc* to exclude them::
 
-          >>> zf = PyZipFile('myprog.zip')
+          >>> zf = PyZipFile('myprog.zip', 'w')
           >>> def notests(s):
           ...     fn = os.path.basename(s)
           ...     return (not (fn == 'test' or fn.startswith('test_')))

Doc/whatsnew/3.13.rst

@@ -1805,8 +1805,8 @@ urllib
 * Remove the *cafile*, *capath*, and *cadefault* parameters of the
   :func:`urllib.request.urlopen` function, deprecated in Python 3.6.
   Use the *context* parameter instead with an :class:`~ssl.SSLContext` instance.
-  The :meth:`ssl.SSLContext.load_cert_chain` function
-  can be used to load specific certificates,
+  The :meth:`ssl.SSLContext.load_verify_locations` method
+  can be used to load specific CA certificates,
   or let :func:`ssl.create_default_context` select
   the operating system's trusted certificate authority (CA) certificates.
   (Contributed by Victor Stinner in :gh:`105382`.)
@@ -2434,7 +2434,7 @@ Removed C APIs
   * :c:func:`!PySys_AddXOption`:
     Use :c:member:`PyConfig.xoptions` instead.
   * :c:func:`!PySys_HasWarnOptions`:
-    Use :c:member:`PyConfig.xoptions` instead.
+    Use :c:member:`PyConfig.warnoptions` instead.
   * :c:func:`!PySys_SetPath`:
     Set :c:member:`PyConfig.module_search_paths` instead.
   * :c:func:`!Py_SetPath`:
@@ -2455,7 +2455,7 @@ Removed C APIs
   They can be replaced with:
 
   * :c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`;
-  * low-level :c:func:`PyEval_AcquireThread` and :c:func:`PyEval_RestoreThread`;
+  * low-level :c:func:`PyEval_AcquireThread` and :c:func:`PyEval_ReleaseThread`;
   * or :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
 
   (Contributed by Victor Stinner in :gh:`105182`.)
@@ -2773,8 +2773,7 @@ Changes in the C API
   * Calling :c:func:`PyFrame_GetLocals` in an :term:`optimized scope`
     now returns a write-through proxy rather than a snapshot
     that gets updated at ill-specified times.
-    If a snapshot is desired, it must be created explicitly
-    (e.g. with :c:func:`PyDict_Copy`),
+    If a snapshot is desired, it must be created explicitly,
     or by calling the new :c:func:`PyEval_GetFrameLocals` API.
 
   * :c:func:`!PyFrame_FastToLocals` and :c:func:`!PyFrame_FastToLocalsWithError`