Merge branch 'main' into chore/cleanup-win95-locale

Author: serhiy-storchaka

Doc/.ruff.toml

@@ -32,6 +32,9 @@ ignore = [
     "E501",  # Ignore line length errors (we use auto-formatting)
 ]
 
+[lint.per-file-ignores]
+"tools/check-html-ids.py" = ["I001"]  # Unsorted imports
+
 [format]
 preview = true
 quote-style = "preserve"

Doc/Makefile

@@ -336,3 +336,9 @@ autobuild-stable-html:
 		exit 1;; \
 	esac
 	@$(MAKE) autobuild-dev-html
+
+# Collect HTML IDs to a JSON document
+.PHONY: html-ids
+html-ids:
+	$(PYTHON) tools/check-html-ids.py collect build/html \
+		-o build/html/html-ids.json.gz

Doc/c-api/dict.rst

@@ -82,6 +82,9 @@ Dictionary objects
 
    Return a new dictionary that contains the same key-value pairs as *p*.
 
+   .. versionchanged:: next
+      If *p* is a subclass of :class:`frozendict`, the result will be a
+      :class:`frozendict` instance instead of a :class:`dict` instance.
 
 .. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
 

Doc/library/index.rst

@@ -43,6 +43,7 @@ the `Python Package Index <https://pypi.org>`_.
    constants.rst
    stdtypes.rst
    exceptions.rst
+   threadsafety.rst
 
    text.rst
    binary.rst

Doc/library/shutil.rst

@@ -618,22 +618,23 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
 
    Create an archive file (such as zip or tar) and return its name.
 
-   *base_name* is the name of the file to create, including the path, minus
-   any format-specific extension.
+   *base_name* is a string or :term:`path-like object` specifying the name of
+   the file to create, including the path, minus any format-specific extension.
 
    *format* is the archive format: one of
    "zip" (if the :mod:`zlib` module is available), "tar", "gztar" (if the
    :mod:`zlib` module is available), "bztar" (if the :mod:`bz2` module is
    available), "xztar" (if the :mod:`lzma` module is available), or "zstdtar"
    (if the :mod:`compression.zstd` module is available).
 
-   *root_dir* is a directory that will be the root directory of the
-   archive, all paths in the archive will be relative to it; for example,
-   we typically chdir into *root_dir* before creating the archive.
+   *root_dir* is a string or :term:`path-like object` specifying a directory
+   that will be the root directory of the archive, all paths in the archive
+   will be relative to it; for example, we typically chdir into *root_dir*
+   before creating the archive.
 
-   *base_dir* is the directory where we start archiving from;
-   i.e. *base_dir* will be the common prefix of all files and
-   directories in the archive.  *base_dir* must be given relative
+   *base_dir* is a string or :term:`path-like object` specifying a directory
+   where we start archiving from; i.e. *base_dir* will be the common prefix of
+   all files and directories in the archive.  *base_dir* must be given relative
    to *root_dir*.  See :ref:`shutil-archiving-example-with-basedir` for how to
    use *base_dir* and *root_dir* together.
 
@@ -668,6 +669,10 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
       This function is now made thread-safe during creation of standard
       ``.zip`` and tar archives.
 
+   .. versionchanged:: next
+      Accepts a :term:`path-like object` for *base_name*, *root_dir* and
+      *base_dir*.
+
 .. function:: get_archive_formats()
 
    Return a list of supported formats for archiving.

Doc/library/stdtypes.rst

@@ -1449,111 +1449,10 @@ application).
          list appear empty for the duration, and raises :exc:`ValueError` if it can
          detect that the list has been mutated during a sort.
 
-.. _thread-safety-list:
-
-.. rubric:: Thread safety for list objects
-
-Reading a single element from a :class:`list` is
-:term:`atomic <atomic operation>`:
-
-.. code-block::
-   :class: green
-
-   lst[i]   # list.__getitem__
-
-The following methods traverse the list and use :term:`atomic <atomic operation>`
-reads of each item to perform their function. That means that they may
-return results affected by concurrent modifications:
-
-.. code-block::
-   :class: maybe
-
-   item in lst
-   lst.index(item)
-   lst.count(item)
-
-All of the above operations avoid acquiring :term:`per-object locks
-<per-object lock>`. They do not block concurrent modifications. Other
-operations that hold a lock will not block these from observing intermediate
-states.
-
-All other operations from here on block using the :term:`per-object lock`.
-
-Writing a single item via ``lst[i] = x`` is safe to call from multiple
-threads and will not corrupt the list.
-
-The following operations return new objects and appear
-:term:`atomic <atomic operation>` to other threads:
-
-.. code-block::
-   :class: good
-
-   lst1 + lst2    # concatenates two lists into a new list
-   x * lst        # repeats lst x times into a new list
-   lst.copy()     # returns a shallow copy of the list
-
-The following methods that only operate on a single element with no shifting
-required are :term:`atomic <atomic operation>`:
-
-.. code-block::
-   :class: good
-
-   lst.append(x)  # append to the end of the list, no shifting required
-   lst.pop()      # pop element from the end of the list, no shifting required
-
-The :meth:`~list.clear` method is also :term:`atomic <atomic operation>`.
-Other threads cannot observe elements being removed.
-
-The :meth:`~list.sort` method is not :term:`atomic <atomic operation>`.
-Other threads cannot observe intermediate states during sorting, but the
-list appears empty for the duration of the sort.
-
-The following operations may allow :term:`lock-free` operations to observe
-intermediate states since they modify multiple elements in place:
-
-.. code-block::
-   :class: maybe
-
-   lst.insert(idx, item)  # shifts elements
-   lst.pop(idx)           # idx not at the end of the list, shifts elements
-   lst *= x               # copies elements in place
-
-The :meth:`~list.remove` method may allow concurrent modifications since
-element comparison may execute arbitrary Python code (via
-:meth:`~object.__eq__`).
-
-:meth:`~list.extend` is safe to call from multiple threads.  However, its
-guarantees depend on the iterable passed to it. If it is a :class:`list`, a
-:class:`tuple`, a :class:`set`, a :class:`frozenset`, a :class:`dict` or a
-:ref:`dictionary view object <dict-views>` (but not their subclasses), the
-``extend`` operation is safe from concurrent modifications to the iterable.
-Otherwise, an iterator is created which can be concurrently modified by
-another thread.  The same applies to inplace concatenation of a list with
-other iterables when using ``lst += iterable``.
-
-Similarly, assigning to a list slice with ``lst[i:j] = iterable`` is safe
-to call from multiple threads, but ``iterable`` is only locked when it is
-also a :class:`list` (but not its subclasses).
-
-Operations that involve multiple accesses, as well as iteration, are never
-atomic. For example:
-
-.. code-block::
-   :class: bad
-
-   # NOT atomic: read-modify-write
-   lst[i] = lst[i] + 1
-
-   # NOT atomic: check-then-act
-   if lst:
-         item = lst.pop()
-
-   # NOT thread-safe: iteration while modifying
-   for item in lst:
-         process(item)  # another thread may modify lst
+.. seealso::
 
-Consider external synchronization when sharing :class:`list` instances
-across threads.  See :ref:`freethreading-python-howto` for more information.
+   For detailed information on thread-safety guarantees for :class:`list`
+   objects, see :ref:`thread-safety-list`.
 
 
 .. _typesseq-tuple:
@@ -2605,6 +2504,19 @@ expression support in the :mod:`re` module).
    done using the specified *fillchar* (default is an ASCII space). The
    original string is returned if *width* is less than or equal to ``len(s)``.
 
+   For example:
+
+   .. doctest::
+
+      >>> 'Python'.rjust(10)
+      '    Python'
+      >>> 'Python'.rjust(10, '.')
+      '....Python'
+      >>> 'Monty Python'.rjust(10, '.')
+      'Monty Python'
+
+   See also :meth:`ljust` and :meth:`zfill`.
+
 
 .. method:: str.rpartition(sep, /)
 
@@ -2929,13 +2841,17 @@ expression support in the :mod:`re` module).
    than before. The original string is returned if *width* is less than
    or equal to ``len(s)``.
 
-   For example::
+   For example:
+
+   .. doctest::
 
       >>> "42".zfill(5)
       '00042'
       >>> "-42".zfill(5)
       '-0042'
 
+   See also :meth:`rjust`.
+
 
 .. index::
    single: ! formatted string literal
@@ -5601,144 +5517,10 @@ can be used interchangeably to index the same dictionary entry.
       :class:`frozendict` and :class:`types.MappingProxyType` can be used to
       create a read-only view of a :class:`dict`.
 
-.. _thread-safety-dict:
-
-.. rubric:: Thread safety for dict objects
-
-Creating a dictionary with the :class:`dict` constructor is atomic when the
-argument to it is a :class:`dict` or a :class:`tuple`. When using the
-:meth:`dict.fromkeys` method, dictionary creation is atomic when the
-argument is a :class:`dict`, :class:`tuple`, :class:`set` or
-:class:`frozenset`.
-
-The following operations and functions are :term:`lock-free` and
-:term:`atomic <atomic operation>`.
-
-.. code-block::
-   :class: good
-
-   d[key]       # dict.__getitem__
-   d.get(key)   # dict.get
-   key in d     # dict.__contains__
-   len(d)       # dict.__len__
-
-All other operations from here on hold the :term:`per-object lock`.
-
-Writing or removing a single item is safe to call from multiple threads
-and will not corrupt the dictionary:
-
-.. code-block::
-   :class: good
-
-   d[key] = value        # write
-   del d[key]            # delete
-   d.pop(key)            # remove and return
-   d.popitem()           # remove and return last item
-   d.setdefault(key, v)  # insert if missing
-
-These operations may compare keys using :meth:`~object.__eq__`, which can
-execute arbitrary Python code. During such comparisons, the dictionary may
-be modified by another thread. For built-in types like :class:`str`,
-:class:`int`, and :class:`float`, that implement :meth:`~object.__eq__` in C,
-the underlying lock is not released during comparisons and this is not a
-concern.
-
-The following operations return new objects and hold the :term:`per-object lock`
-for the duration of the operation:
-
-.. code-block::
-   :class: good
-
-   d.copy()      # returns a shallow copy of the dictionary
-   d | other     # merges two dicts into a new dict
-   d.keys()      # returns a new dict_keys view object
-   d.values()    # returns a new dict_values view object
-   d.items()     # returns a new dict_items view object
-
-The :meth:`~dict.clear` method holds the lock for its duration. Other
-threads cannot observe elements being removed.
-
-The following operations lock both dictionaries. For :meth:`~dict.update`
-and ``|=``, this applies only when the other operand is a :class:`dict`
-that uses the standard dict iterator (but not subclasses that override
-iteration). For equality comparison, this applies to :class:`dict` and
-its subclasses:
-
-.. code-block::
-   :class: good
-
-   d.update(other_dict)  # both locked when other_dict is a dict
-   d |= other_dict       # both locked when other_dict is a dict
-   d == other_dict       # both locked for dict and subclasses
-
-All comparison operations also compare values using :meth:`~object.__eq__`,
-so for non-built-in types the lock may be released during comparison.
-
-:meth:`~dict.fromkeys` locks both the new dictionary and the iterable
-when the iterable is exactly a :class:`dict`, :class:`set`, or
-:class:`frozenset` (not subclasses):
-
-.. code-block::
-   :class: good
-
-   dict.fromkeys(a_dict)      # locks both
-   dict.fromkeys(a_set)       # locks both
-   dict.fromkeys(a_frozenset) # locks both
-
-When updating from a non-dict iterable, only the target dictionary is
-locked. The iterable may be concurrently modified by another thread:
-
-.. code-block::
-   :class: maybe
-
-   d.update(iterable)        # iterable is not a dict: only d locked
-   d |= iterable             # iterable is not a dict: only d locked
-   dict.fromkeys(iterable)   # iterable is not a dict/set/frozenset: only result locked
-
-Operations that involve multiple accesses, as well as iteration, are never
-atomic:
-
-.. code-block::
-   :class: bad
-
-   # NOT atomic: read-modify-write
-   d[key] = d[key] + 1
-
-   # NOT atomic: check-then-act (TOCTOU)
-   if key in d:
-         del d[key]
-
-   # NOT thread-safe: iteration while modifying
-   for key, value in d.items():
-         process(key)  # another thread may modify d
-
-To avoid time-of-check to time-of-use (TOCTOU) issues, use atomic
-operations or handle exceptions:
-
-.. code-block::
-   :class: good
-
-   # Use pop() with default instead of check-then-delete
-   d.pop(key, None)
-
-   # Or handle the exception
-   try:
-         del d[key]
-   except KeyError:
-         pass
-
-To safely iterate over a dictionary that may be modified by another
-thread, iterate over a copy:
-
-.. code-block::
-   :class: good
-
-   # Make a copy to iterate safely
-   for key, value in d.copy().items():
-         process(key)
+.. seealso::
 
-Consider external synchronization when sharing :class:`dict` instances
-across threads. See :ref:`freethreading-python-howto` for more information.
+   For detailed information on thread-safety guarantees for :class:`dict`
+   objects, see :ref:`thread-safety-dict`.
 
 
 .. _dict-views: