Merge branch 'main' into enum-doc_tuple

Author: ethanfurman

Doc/c-api/import.rst

@@ -13,20 +13,8 @@ Importing Modules
       single: __all__ (package variable)
       single: modules (in module sys)
 
-   This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,
-   leaving the *globals* and *locals* arguments set to ``NULL`` and *level* set
-   to 0.  When the *name*
-   argument contains a dot (when it specifies a submodule of a package), the
-   *fromlist* argument is set to the list ``['*']`` so that the return value is the
-   named module rather than the top-level package containing it as would otherwise
-   be the case.  (Unfortunately, this has an additional side effect when *name* in
-   fact specifies a subpackage instead of a submodule: the submodules specified in
-   the package's ``__all__`` variable are  loaded.)  Return a new reference to the
-   imported module, or ``NULL`` with an exception set on failure.  A failing
-   import of a module doesn't leave the module in :data:`sys.modules`.
-
-   This function always uses absolute imports.
-
+   This is a wrapper around :c:func:`PyImport_Import()` which takes a
+   :c:expr:`const char *` as an argument instead of a :c:expr:`PyObject *`.
 
 .. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
 

Doc/c-api/list.rst

@@ -56,13 +56,21 @@ List Objects
    Similar to :c:func:`PyList_Size`, but without error checking.
 
 
-.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
+.. c:function:: PyObject* PyList_GetItemRef(PyObject *list, Py_ssize_t index)
 
    Return the object at position *index* in the list pointed to by *list*.  The
    position must be non-negative; indexing from the end of the list is not
-   supported.  If *index* is out of bounds (<0 or >=len(list)),
+   supported.  If *index* is out of bounds (:code:`<0 or >=len(list)`),
    return ``NULL`` and set an :exc:`IndexError` exception.
 
+   .. versionadded:: 3.13
+
+
+.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
+
+   Like :c:func:`PyList_GetItemRef`, but returns a
+   :term:`borrowed reference` instead of a :term:`strong reference`.
+
 
 .. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
 

Doc/data/refcounts.dat

@@ -1133,6 +1133,10 @@ PyList_GetItem:PyObject*::0:
 PyList_GetItem:PyObject*:list:0:
 PyList_GetItem:Py_ssize_t:index::
 
+PyList_GetItemRef:PyObject*::+1:
+PyList_GetItemRef:PyObject*:list:0:
+PyList_GetItemRef:Py_ssize_t:index::
+
 PyList_GetSlice:PyObject*::+1:
 PyList_GetSlice:PyObject*:list:0:
 PyList_GetSlice:Py_ssize_t:low::

Doc/data/stable_abi.dat

@@ -512,7 +512,7 @@ to interactively print a calendar.
 
    python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]
                       [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
-                      [year] [month]
+                      [-f FIRST_WEEKDAY] [year] [month]
 
 
 For example, to print a calendar for the year 2000:
@@ -586,12 +586,13 @@ The following options are accepted:
    or as an HTML document.
 
 
-.. option:: --first-weekday WEEKDAY, -f WEEKDAY
+.. option:: --first-weekday FIRST_WEEKDAY, -f FIRST_WEEKDAY
 
    The weekday to start each week.
    Must be a number between 0 (Monday) and 6 (Sunday).
    Defaults to 0.
 
+   .. versionadded:: 3.13
 
 .. option:: year
 

Doc/library/calendar.rst

@@ -400,30 +400,7 @@ objects (see below).
    the :func:`divmod` function. True division and multiplication of a
    :class:`timedelta` object by a :class:`float` object are now supported.
 
-
-Comparisons of :class:`timedelta` objects are supported, with some caveats.
-
-The comparisons ``==`` or ``!=`` *always* return a :class:`bool`, no matter
-the type of the compared object::
-
-    >>> from datetime import timedelta
-    >>> delta1 = timedelta(seconds=57)
-    >>> delta2 = timedelta(hours=25, seconds=2)
-    >>> delta2 != delta1
-    True
-    >>> delta2 == 5
-    False
-
-For all other comparisons (such as ``<`` and ``>``), when a :class:`timedelta`
-object is compared to an object of a different type, :exc:`TypeError`
-is raised::
-
-    >>> delta2 > delta1
-    True
-    >>> delta2 > 5
-    Traceback (most recent call last):
-      File "<stdin>", line 1, in <module>
-    TypeError: '>' not supported between instances of 'datetime.timedelta' and 'int'
+:class:`timedelta` objects support equality and order comparisons.
 
 In Boolean contexts, a :class:`timedelta` object is
 considered to be true if and only if it isn't equal to ``timedelta(0)``.
@@ -614,8 +591,13 @@ Supported operations:
 +-------------------------------+----------------------------------------------+
 | ``timedelta = date1 - date2`` | \(3)                                         |
 +-------------------------------+----------------------------------------------+
-| ``date1 < date2``             | *date1* is considered less than *date2* when |
-|                               | *date1* precedes *date2* in time. (4)        |
+| | ``date1 == date2``          | Equality comparison. (4)                     |
+| | ``date1 != date2``          |                                              |
++-------------------------------+----------------------------------------------+
+| | ``date1 < date2``           | Order comparison. (5)                        |
+| | ``date1 > date2``           |                                              |
+| | ``date1 <= date2``          |                                              |
+| | ``date1 >= date2``          |                                              |
 +-------------------------------+----------------------------------------------+
 
 Notes:
@@ -635,15 +617,12 @@ Notes:
    timedelta.microseconds are 0, and date2 + timedelta == date1 after.
 
 (4)
+   :class:`date` objects are equal if they represent the same date.
+
+(5)
+   *date1* is considered less than *date2* when *date1* precedes *date2* in time.
    In other words, ``date1 < date2`` if and only if ``date1.toordinal() <
-   date2.toordinal()``. Date comparison raises :exc:`TypeError` if
-   the other comparand isn't also a :class:`date` object. However,
-   ``NotImplemented`` is returned instead if the other comparand has a
-   :attr:`~date.timetuple` attribute. This hook gives other kinds of date objects a
-   chance at implementing mixed-type comparison. If not, when a :class:`date`
-   object is compared to an object of a different type, :exc:`TypeError` is raised
-   unless the comparison is ``==`` or ``!=``. The latter cases return
-   :const:`False` or :const:`True`, respectively.
+   date2.toordinal()``.
 
 In Boolean contexts, all :class:`date` objects are considered to be true.
 
@@ -1170,8 +1149,13 @@ Supported operations:
 +---------------------------------------+--------------------------------+
 | ``timedelta = datetime1 - datetime2`` | \(3)                           |
 +---------------------------------------+--------------------------------+
-| ``datetime1 < datetime2``             | Compares :class:`.datetime` to |
-|                                       | :class:`.datetime`. (4)        |
+| | ``datetime1 == datetime2``          | Equality comparison. (4)       |
+| | ``datetime1 != datetime2``          |                                |
++---------------------------------------+--------------------------------+
+| | ``datetime1 < datetime2``           | Order comparison. (5)          |
+| | ``datetime1 > datetime2``           |                                |
+| | ``datetime1 <= datetime2``          |                                |
+| | ``datetime1 >= datetime2``          |                                |
 +---------------------------------------+--------------------------------+
 
 (1)
@@ -1199,40 +1183,41 @@ Supported operations:
    are done in this case.
 
    If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a-b`` acts
-   as if *a* and *b* were first converted to naive UTC datetimes first. The
+   as if *a* and *b* were first converted to naive UTC datetimes. The
    result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)
    - b.utcoffset())`` except that the implementation never overflows.
 
 (4)
+   :class:`.datetime` objects are equal if they represent the same date
+   and time, taking into account the time zone.
+
+   Naive and aware :class:`!datetime` objects are never equal.
+   :class:`!datetime` objects are never equal to :class:`date` objects
+   that are not also :class:`!datetime` instances, even if they represent
+   the same date.
+
+   If both comparands are aware and have different :attr:`~.datetime.tzinfo`
+   attributes, the comparison acts as comparands were first converted to UTC
+   datetimes except that the implementation never overflows.
+   :class:`!datetime` instances in a repeated interval are never equal to
+   :class:`!datetime` instances in other time zone.
+
+(5)
    *datetime1* is considered less than *datetime2* when *datetime1* precedes
-   *datetime2* in time.
+   *datetime2* in time, taking into account the time zone.
 
-   If one comparand is naive and the other is aware, :exc:`TypeError`
-   is raised if an order comparison is attempted. For equality
-   comparisons, naive instances are never equal to aware instances.
+   Order comparison between naive and aware :class:`.datetime` objects,
+   as well as a :class:`!datetime` object and a :class:`!date` object
+   that is not also a :class:`!datetime` instance, raises :exc:`TypeError`.
 
-   If both comparands are aware, and have the same :attr:`~.datetime.tzinfo` attribute, the
-   common :attr:`~.datetime.tzinfo` attribute is ignored and the base datetimes are
-   compared. If both comparands are aware and have different :attr:`~.datetime.tzinfo`
-   attributes, the comparands are first adjusted by subtracting their UTC
-   offsets (obtained from ``self.utcoffset()``).
+   If both comparands are aware and have different :attr:`~.datetime.tzinfo`
+   attributes, the comparison acts as comparands were first converted to UTC
+   datetimes except that the implementation never overflows.
 
    .. versionchanged:: 3.3
       Equality comparisons between aware and naive :class:`.datetime`
       instances don't raise :exc:`TypeError`.
 
-   .. note::
-
-      In order to stop comparison from falling back to the default scheme of comparing
-      object addresses, datetime comparison normally raises :exc:`TypeError` if the
-      other comparand isn't also a :class:`.datetime` object. However,
-      ``NotImplemented`` is returned instead if the other comparand has a
-      :attr:`~.datetime.timetuple` attribute. This hook gives other kinds of date objects a
-      chance at implementing mixed-type comparison. If not, when a :class:`.datetime`
-      object is compared to an object of a different type, :exc:`TypeError` is raised
-      unless the comparison is ``==`` or ``!=``. The latter cases return
-      :const:`False` or :const:`True`, respectively.
-
 Instance methods:
 
 .. method:: datetime.date()
@@ -1766,21 +1751,18 @@ Instance attributes (read-only):
 
    .. versionadded:: 3.6
 
-:class:`.time` objects support comparison of :class:`.time` to :class:`.time`,
-where *a* is considered less
-than *b* when *a* precedes *b* in time. If one comparand is naive and the other
-is aware, :exc:`TypeError` is raised if an order comparison is attempted. For equality
-comparisons, naive instances are never equal to aware instances.
+:class:`.time` objects support equality and order comparisons,
+where *a* is considered less than *b* when *a* precedes *b* in time.
+
+Naive and aware :class:`!time` objects are never equal.
+Order comparison between naive and aware :class:`!time` objects raises
+:exc:`TypeError`.
 
 If both comparands are aware, and have
 the same :attr:`~.time.tzinfo` attribute, the common :attr:`!tzinfo` attribute is
 ignored and the base times are compared. If both comparands are aware and
 have different :attr:`!tzinfo` attributes, the comparands are first adjusted by
-subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order
-to stop mixed-type comparisons from falling back to the default comparison by
-object address, when a :class:`.time` object is compared to an object of a
-different type, :exc:`TypeError` is raised unless the comparison is ``==`` or
-``!=``. The latter cases return :const:`False` or :const:`True`, respectively.
+subtracting their UTC offsets (obtained from ``self.utcoffset()``).
 
 .. versionchanged:: 3.3
   Equality comparisons between aware and naive :class:`.time` instances

Doc/library/datetime.rst

@@ -586,7 +586,9 @@ 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. *format* is the archive format: one of
+   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), or "xztar" (if the :mod:`lzma` module is available).

Doc/library/shutil.rst

@@ -1528,7 +1528,7 @@ between them will be implicitly converted to a single string literal. That
 is, ``("spam " "eggs") == "spam eggs"``.
 
 See :ref:`strings` for more about the various forms of string literal,
-including supported escape sequences, and the ``r`` ("raw") prefix that
+including supported :ref:`escape sequences <escape-sequences>`, and the ``r`` ("raw") prefix that
 disables most escape sequence processing.
 
 Strings may also be created from other objects using the :class:`str`

Doc/library/stdtypes.rst

@@ -1376,6 +1376,10 @@ New Features
   UTF-8 encoded bytes string, rather than a :c:expr:`PyObject*`.
   (Contributed by Victor Stinner in :gh:`108314`.)
 
+* Added :c:func:`PyList_GetItemRef` function: similar to
+  :c:func:`PyList_GetItem` but returns a :term:`strong reference` instead of
+  a :term:`borrowed reference`.
+
 * Add :c:func:`Py_IsFinalizing` function: check if the main Python interpreter is
   :term:`shutting down <interpreter shutdown>`.
   (Contributed by Victor Stinner in :gh:`108014`.)

Doc/whatsnew/3.13.rst

@@ -17,6 +17,9 @@ typedef struct {
     /* Dictionary version: globally unique, value change each time
        the dictionary is modified */
 #ifdef Py_BUILD_CORE
+    /* Bits 0-7 are for dict watchers.
+     * Bits 8-11 are for the watched mutation counter (used by tier2 optimization)
+     * The remaining bits (12-63) are the actual version tag. */
     uint64_t ma_version_tag;
 #else
     Py_DEPRECATED(3.12) uint64_t ma_version_tag;