Merge branch 'main' into fix-issue-116111-on-datetime-docs

Author: NehaJeevan

Doc/c-api/init.rst

@@ -2287,7 +2287,7 @@ The C-API provides a basic mutual exclusion lock.
       should not be used to make concurrency control decisions, as the lock
       state may change immediately after the check.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 .. _python-critical-section-api:
 
@@ -2372,7 +2372,7 @@ code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
 
    On the default build, this macro expands to ``{``.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 .. c:macro:: Py_END_CRITICAL_SECTION()
 
@@ -2418,7 +2418,7 @@ code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
 
    On the default build, this macro expands to ``{``.
 
-   .. versionadded:: next
+   .. versionadded:: 3.14
 
 .. c:macro:: Py_END_CRITICAL_SECTION2()
 

Doc/extending/extending.rst

@@ -214,7 +214,7 @@ and initialize it by calling :c:func:`PyErr_NewException` in the module's
 
    SpamError = PyErr_NewException("spam.error", NULL, NULL);
 
-Since :c:data:`!SpamError` is a global variable, it will be overwitten every time
+Since :c:data:`!SpamError` is a global variable, it will be overwritten every time
 the module is reinitialized, when the :c:data:`Py_mod_exec` function is called.
 
 For now, let's avoid the issue: we will block repeated initialization by raising an

Doc/howto/free-threading-extensions.rst

@@ -161,6 +161,8 @@ that return :term:`strong references <strong reference>`.
 +===================================+===================================+
 | :c:func:`PyList_GetItem`          | :c:func:`PyList_GetItemRef`       |
 +-----------------------------------+-----------------------------------+
+| :c:func:`PyList_GET_ITEM`         | :c:func:`PyList_GetItemRef`       |
++-----------------------------------+-----------------------------------+
 | :c:func:`PyDict_GetItem`          | :c:func:`PyDict_GetItemRef`       |
 +-----------------------------------+-----------------------------------+
 | :c:func:`PyDict_GetItemWithError` | :c:func:`PyDict_GetItemRef`       |

Doc/library/asyncio-queue.rst

@@ -102,17 +102,33 @@ Queue
 
    .. method:: shutdown(immediate=False)
 
-      Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put`
+      Put a :class:`Queue` instance into a shutdown mode.
+
+      The queue can no longer grow.
+      Future calls to :meth:`~Queue.put` raise :exc:`QueueShutDown`.
+      Currently blocked callers of :meth:`~Queue.put` will be unblocked
+      and will raise :exc:`QueueShutDown` in the formerly blocked thread.
+
+      If *immediate* is false (the default), the queue can be wound
+      down normally with :meth:`~Queue.get` calls to extract tasks
+      that have already been loaded.
+
+      And if :meth:`~Queue.task_done` is called for each remaining task, a
+      pending :meth:`~Queue.join` will be unblocked normally.
+
+      Once the queue is empty, future calls to :meth:`~Queue.get` will
       raise :exc:`QueueShutDown`.
 
-      By default, :meth:`~Queue.get` on a shut down queue will only
-      raise once the queue is empty. Set *immediate* to true to make
-      :meth:`~Queue.get` raise immediately instead.
+      If *immediate* is true, the queue is terminated immediately.
+      The queue is drained to be completely empty.  All callers of
+      :meth:`~Queue.join` are unblocked regardless of the number
+      of unfinished tasks.  Blocked callers of :meth:`~Queue.get`
+      are unblocked and will raise :exc:`QueueShutDown` because the
+      queue is empty.
 
-      All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get`
-      will be unblocked. If *immediate* is true, a task will be marked
-      as done for each remaining item in the queue, which may unblock
-      callers of :meth:`~Queue.join`.
+      Use caution when using :meth:`~Queue.join` with *immediate* set
+      to true. This unblocks the join even when no work has been done
+      on the tasks, violating the usual invariant for joining a queue.
 
       .. versionadded:: 3.13
 
@@ -129,9 +145,6 @@ Queue
       call was received for every item that had been :meth:`~Queue.put`
       into the queue).
 
-      ``shutdown(immediate=True)`` calls :meth:`task_done` for each
-      remaining item in the queue.
-
       Raises :exc:`ValueError` if called more times than there were
       items placed in the queue.
 

Doc/library/bdb.rst

@@ -192,12 +192,8 @@ The :mod:`bdb` module also defines two classes:
         entered.
       * ``"return"``: A function or other code block is about to return.
       * ``"exception"``: An exception has occurred.
-      * ``"c_call"``: A C function is about to be called.
-      * ``"c_return"``: A C function has returned.
-      * ``"c_exception"``: A C function has raised an exception.
 
-      For the Python events, specialized functions (see below) are called.  For
-      the C events, no action is taken.
+      For all the events, specialized functions (see below) are called.
 
       The *arg* parameter depends on the previous event.
 

Doc/library/importlib.resources.rst

@@ -16,11 +16,12 @@ within *packages*.
 "Resources" are file-like resources associated with a module or package in
 Python. The resources may be contained directly in a package, within a
 subdirectory contained in that package, or adjacent to modules outside a
-package. Resources may be text or binary. As a result, Python module sources
-(.py) of a package and compilation artifacts (pycache) are technically
-de-facto resources of that package. In practice, however, resources are
-primarily those non-Python artifacts exposed specifically by the package
-author.
+package. Resources may be text or binary. As a result, a package's Python
+module sources (.py), compilation artifacts (pycache), and installation
+artifacts (like :func:`reserved filenames <os.path.isreserved>`
+in directories) are technically de-facto resources of that package.
+In practice, however, resources are primarily those non-Python artifacts
+exposed specifically by the package author.
 
 Resources can be opened or read in either binary or text mode.
 

Doc/library/queue.rst

@@ -187,9 +187,6 @@ fully processed by daemon consumer threads.
    processed (meaning that a :meth:`task_done` call was received for every item
    that had been :meth:`put` into the queue).
 
-   ``shutdown(immediate=True)`` calls :meth:`task_done` for each remaining item
-   in the queue.
-
    Raises a :exc:`ValueError` if called more times than there were items placed in
    the queue.
 
@@ -204,6 +201,9 @@ fully processed by daemon consumer threads.
    count of unfinished tasks drops to zero, :meth:`join` unblocks.
 
 
+Waiting for task completion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Example of how to wait for enqueued tasks to be completed::
 
     import threading
@@ -233,22 +233,38 @@ Example of how to wait for enqueued tasks to be completed::
 Terminating queues
 ^^^^^^^^^^^^^^^^^^
 
-:class:`Queue` objects can be made to prevent further interaction by shutting
-them down.
+When no longer needed, :class:`Queue` objects can be wound down
+until empty or terminated immediately with a hard shutdown.
 
 .. method:: Queue.shutdown(immediate=False)
 
-   Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put` raise
-   :exc:`ShutDown`.
+   Put a :class:`Queue` instance into a shutdown mode.
+
+   The queue can no longer grow.
+   Future calls to :meth:`~Queue.put` raise :exc:`ShutDown`.
+   Currently blocked callers of :meth:`~Queue.put` will be unblocked
+   and will raise :exc:`ShutDown` in the formerly blocked thread.
+
+   If *immediate* is false (the default), the queue can be wound
+   down normally with :meth:`~Queue.get` calls to extract tasks
+   that have already been loaded.
+
+   And if :meth:`~Queue.task_done` is called for each remaining task, a
+   pending :meth:`~Queue.join` will be unblocked normally.
+
+   Once the queue is empty, future calls to :meth:`~Queue.get` will
+   raise :exc:`ShutDown`.
 
-   By default, :meth:`~Queue.get` on a shut down queue will only raise once the
-   queue is empty. Set *immediate* to true to make :meth:`~Queue.get` raise
-   immediately instead.
+   If *immediate* is true, the queue is terminated immediately.
+   The queue is drained to be completely empty.  All callers of
+   :meth:`~Queue.join` are unblocked regardless of the number
+   of unfinished tasks.  Blocked callers of :meth:`~Queue.get`
+   are unblocked and will raise :exc:`ShutDown` because the
+   queue is empty.
 
-   All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get` will be
-   unblocked. If *immediate* is true, a task will be marked as done for each
-   remaining item in the queue, which may unblock callers of
-   :meth:`~Queue.join`.
+   Use caution when using :meth:`~Queue.join` with *immediate* set
+   to true. This unblocks the join even when no work has been done
+   on the tasks, violating the usual invariant for joining a queue.
 
    .. versionadded:: 3.13
 

Doc/library/shelve.rst

@@ -144,7 +144,7 @@ Restrictions
   which can cause hard crashes when trying to read from the database.
 
 * :meth:`Shelf.reorganize` may not be available for all database packages and
-  may temporarely increase resource usage (especially disk space) when called.
+  may temporarily increase resource usage (especially disk space) when called.
   Additionally, it will never run automatically and instead needs to be called
   explicitly.
 

Doc/reference/expressions.rst

@@ -133,13 +133,18 @@ Literals
 
 Python supports string and bytes literals and various numeric literals:
 
-.. productionlist:: python-grammar
-   literal: `stringliteral` | `bytesliteral` | `NUMBER`
+.. grammar-snippet::
+   :group: python-grammar
+
+   literal: `strings` | `NUMBER`
 
 Evaluation of a literal yields an object of the given type (string, bytes,
 integer, floating-point number, complex number) with the given value.  The value
 may be approximated in the case of floating-point and imaginary (complex)
-literals.  See section :ref:`literals` for details.
+literals.
+See section :ref:`literals` for details.
+See section :ref:`string-concatenation` for details on ``strings``.
+
 
 .. index::
    triple: immutable; data; type
@@ -152,6 +157,58 @@ occurrence) may obtain the same object or a different object with the same
 value.
 
 
+.. _string-concatenation:
+
+String literal concatenation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Multiple adjacent string or bytes literals (delimited by whitespace), possibly
+using different quoting conventions, are allowed, and their meaning is the same
+as their concatenation::
+
+   >>> "hello" 'world'
+   "helloworld"
+
+Formally:
+
+.. grammar-snippet::
+   :group: python-grammar
+
+   strings: ( `STRING` | fstring)+ | tstring+
+
+This feature is defined at the syntactical level, so it only works with literals.
+To concatenate string expressions at run time, the '+' operator may be used::
+
+   >>> greeting = "Hello"
+   >>> space = " "
+   >>> name = "Blaise"
+   >>> print(greeting + space + name)   # not: print(greeting space name)
+   Hello Blaise
+
+Literal concatenation can freely mix raw strings, triple-quoted strings,
+and formatted string literals.
+For example::
+
+   >>> "Hello" r', ' f"{name}!"
+   "Hello, Blaise!"
+
+This feature can be used to reduce the number of backslashes
+needed, to split long strings conveniently across long lines, or even to add
+comments to parts of strings. For example::
+
+   re.compile("[A-Za-z_]"       # letter or underscore
+              "[A-Za-z0-9_]*"   # letter, digit or underscore
+             )
+
+However, bytes literals may only be combined with other byte literals;
+not with string literals of any kind.
+Also, template string literals may only be combined with other template
+string literals::
+
+   >>> t"Hello" t"{name}!"
+   Template(strings=('Hello', '!'), interpolations=(...))
+
+
 .. _parenthesized:
 
 Parenthesized forms

Doc/reference/grammar.rst

@@ -10,11 +10,8 @@ error recovery.
 
 The notation used here is the same as in the preceding docs,
 and is described in the :ref:`notation <notation>` section,
-except for a few extra complications:
+except for an extra complication:
 
-* ``&e``: a positive lookahead (that is, ``e`` is required to match but
-  not consumed)
-* ``!e``: a negative lookahead (that is, ``e`` is required *not* to match)
 * ``~`` ("cut"): commit to the current alternative and fail the rule
   even if this fails to parse