https://github.com/python/cpython/commit/bd3be61c4a12058d7b4f8ac89804d4558ff68ea8
commit: bd3be61c4a12058d7b4f8ac89804d4558ff68ea8
branch: main
author: Inada Naoki <[email protected]>
committer: methane <[email protected]>
date: 2026-10-30T13:11:34+09:00
summary:
Docs: correct API guidance and examples (#160907)
files:
M Doc/builtins/functions.rst
M Doc/builtins/stdtypes.rst
M Doc/c-api/code.rst
M Doc/c-api/codec.rst
M Doc/c-api/extension-modules.rst
M Doc/c-api/gcsupport.rst
M Doc/extending/extending.rst
M Doc/extending/first-extension-module.rst
M Doc/extending/newtypes_tutorial.rst
M Doc/library/http.cookiejar.rst
M Doc/library/mailbox.rst
M Doc/library/os.rst
M Doc/library/ssl.rst
M Doc/library/tracemalloc.rst
M Doc/library/zipfile.rst
M Doc/whatsnew/3.13.rst
diff --git a/Doc/builtins/functions.rst b/Doc/builtins/functions.rst
index e97fd8293b6a716..dd84d96c1b751ba 100644
--- a/Doc/builtins/functions.rst
+++ b/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::
diff --git a/Doc/builtins/stdtypes.rst b/Doc/builtins/stdtypes.rst
index cf05f947c5908df..55a59f2879f2155 100644
--- a/Doc/builtins/stdtypes.rst
+++ b/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.
diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 96104017da59754..6f0b7838d6cfeda 100644
--- a/Doc/c-api/code.rst
+++ b/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.
diff --git a/Doc/c-api/codec.rst b/Doc/c-api/codec.rst
index 35ee048bd5fa9f5..6c8a764f635aa75 100644
--- a/Doc/c-api/codec.rst
+++ b/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)
diff --git a/Doc/c-api/extension-modules.rst b/Doc/c-api/extension-modules.rst
index 0b05a63bb09d7f8..df1a16e94e1afe0 100644
--- a/Doc/c-api/extension-modules.rst
+++ b/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
};
diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst
index 904303274ba075f..0106fc115ff180d 100644
--- a/Doc/c-api/gcsupport.rst
+++ b/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.
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index 6a807085cc328f0..6bf27ce33c31826 100644
--- a/Doc/extending/extending.rst
+++ b/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 */
diff --git a/Doc/extending/first-extension-module.rst
b/Doc/extending/first-extension-module.rst
index 55a772e2aca24f5..7504622723100c9 100644
--- a/Doc/extending/first-extension-module.rst
+++ b/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;
}
diff --git a/Doc/extending/newtypes_tutorial.rst
b/Doc/extending/newtypes_tutorial.rst
index 9f3cd1d6f4cf33a..61b19fcc1d5e8b7 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/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
diff --git a/Doc/library/http.cookiejar.rst b/Doc/library/http.cookiejar.rst
index ce65bc961a98a68..59302b6aa9c6456 100644
--- a/Doc/library/http.cookiejar.rst
+++ b/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))
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index bb60546c8aec57c..ea0d746d0fe322d 100644
--- a/Doc/library/mailbox.rst
+++ b/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()
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 3f0b91af4d0a86f..80e119e720574ed 100644
--- a/Doc/library/os.rst
+++ b/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
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 46bc37e6bae7133..139dc2c24eab764 100644
--- a/Doc/library/ssl.rst
+++ b/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.
diff --git a/Doc/library/tracemalloc.rst b/Doc/library/tracemalloc.rst
index 0fa70389f1f5771..4a19acb430b0d13 100644
--- a/Doc/library/tracemalloc.rst
+++ b/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
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 7ade7fbc3266173..b64699300bf43bc 100644
--- a/Doc/library/zipfile.rst
+++ b/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_')))
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 23f464afe3f6e57..6b9bf8172eb0e01 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/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`
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
