Merge branch 'python:main' into pcbuild

Author: Wulian233

Doc/Makefile

@@ -305,13 +305,15 @@ serve:
 
 # for development releases: always build
 .PHONY: autobuild-dev
+autobuild-dev: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short)
 autobuild-dev:
-	$(MAKE) dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(MAKE) dist-no-html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1' DISTVERSION=$(DISTVERSION)
 
-# for quick rebuilds (HTML only)
+# for HTML-only rebuilds
 .PHONY: autobuild-dev-html
+autobuild-dev-html: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short)
 autobuild-dev-html:
-	$(MAKE) html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(MAKE) dist-html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1' DISTVERSION=$(DISTVERSION)
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage

Doc/library/argparse.rst

@@ -30,7 +30,7 @@ Quick Links for ArgumentParser
 ========================= =========================================================================================================== ==================================================================================
 Name                      Description                                                                                                 Values
 ========================= =========================================================================================================== ==================================================================================
-prog_                     The name of the program                                                                                     Defaults to ``os.path.basename(sys.argv[0])``
+prog_                     The name of the program
 usage_                    The string describing the program usage
 description_              A brief description of what the program does
 epilog_                   Additional description of the program after the argument help
@@ -214,8 +214,8 @@ ArgumentParser objects
    as keyword arguments. Each parameter has its own more detailed description
    below, but in short they are:
 
-   * prog_ - The name of the program (default:
-     ``os.path.basename(sys.argv[0])``)
+   * prog_ - The name of the program (default: generated from the ``__main__``
+     module attributes and ``sys.argv[0]``)
 
    * usage_ - The string describing the program usage (default: generated from
      arguments added to parser)
@@ -268,10 +268,18 @@ The following sections describe how each of these are used.
 prog
 ^^^^
 
-By default, :class:`ArgumentParser` objects use the base name
-(see :func:`os.path.basename`) of ``sys.argv[0]`` to determine
-how to display the name of the program in help messages.  This default is almost
-always desirable because it will make the help messages match the name that was
+By default, :class:`ArgumentParser` calculates the name of the program
+to display in help messages depending on the way the Python inerpreter was run:
+
+* The :func:`base name <os.path.basename>` of ``sys.argv[0]`` if a file was
+  passed as argument.
+* The Python interpreter name followed by ``sys.argv[0]`` if a directory or
+  a zipfile was passed as argument.
+* The Python interpreter name followed by ``-m`` followed by the
+  module or package name if the :option:`-m` option was used.
+
+This default is almost
+always desirable because it will make the help messages match the string that was
 used to invoke the program on the command line.  For example, consider a file
 named ``myprogram.py`` with the following code::
 
@@ -281,7 +289,7 @@ named ``myprogram.py`` with the following code::
    args = parser.parse_args()
 
 The help for this program will display ``myprogram.py`` as the program name
-(regardless of where the program was invoked from):
+(regardless of where the program was invoked from) if it is run as a script:
 
 .. code-block:: shell-session
 
@@ -299,6 +307,17 @@ The help for this program will display ``myprogram.py`` as the program name
     -h, --help  show this help message and exit
     --foo FOO   foo help
 
+If it is executed via the :option:`-m` option, the help will display a corresponding command line:
+
+.. code-block:: shell-session
+
+   $ /usr/bin/python3 -m subdir.myprogram --help
+   usage: python3 -m subdir.myprogram [-h] [--foo FOO]
+
+   options:
+    -h, --help  show this help message and exit
+    --foo FOO   foo help
+
 To change this default behavior, another value can be supplied using the
 ``prog=`` argument to :class:`ArgumentParser`::
 
@@ -309,7 +328,8 @@ To change this default behavior, another value can be supplied using the
    options:
     -h, --help  show this help message and exit
 
-Note that the program name, whether determined from ``sys.argv[0]`` or from the
+Note that the program name, whether determined from ``sys.argv[0]``,
+from the ``__main__`` module attributes or from the
 ``prog=`` argument, is available to help messages using the ``%(prog)s`` format
 specifier.
 
@@ -324,6 +344,9 @@ specifier.
     -h, --help  show this help message and exit
     --foo FOO   foo of the myprogram program
 
+.. versionchanged:: 3.14
+   The default ``prog`` value now reflects how ``__main__`` was actually executed,
+   rather than always being ``os.path.basename(sys.argv[0])``.
 
 usage
 ^^^^^

Doc/library/dataclasses.rst

@@ -399,7 +399,7 @@ Module contents
    :func:`!astuple` raises :exc:`TypeError` if *obj* is not a dataclass
    instance.
 
-.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False, module=None)
+.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False, module=None, decorator=dataclass)
 
    Creates a new dataclass with name *cls_name*, fields as defined
    in *fields*, base classes as given in *bases*, and initialized
@@ -415,6 +415,11 @@ Module contents
    of the dataclass is set to that value.
    By default, it is set to the module name of the caller.
 
+   The *decorator* parameter is a callable that will be used to create the dataclass.
+   It should take the class object as a first argument and the same keyword arguments
+   as :func:`@dataclass <dataclass>`. By default, the :func:`@dataclass <dataclass>`
+   function is used.
+
    This function is not strictly required, because any Python
    mechanism for creating a new class with :attr:`!__annotations__` can
    then apply the :func:`@dataclass <dataclass>` function to convert that class to
@@ -438,6 +443,9 @@ Module contents
          def add_one(self):
              return self.x + 1
 
+   .. versionadded:: 3.14
+      Added the *decorator* parameter.
+
 .. function:: replace(obj, /, **changes)
 
    Creates a new object of the same type as *obj*, replacing

Doc/library/datetime.rst

@@ -295,6 +295,20 @@ Instance attributes (read-only):
 
    Between 0 and 86,399 inclusive.
 
+   .. caution::
+
+      It is a somewhat common bug for code to unintentionally use this attribute
+      when it is actually intended to get a :meth:`~timedelta.total_seconds`
+      value instead:
+
+      .. doctest::
+
+         >>> from datetime import timedelta
+         >>> duration = timedelta(seconds=11235813)
+         >>> duration.days, duration.seconds
+         (130, 3813)
+         >>> duration.total_seconds()
+         11235813.0
 
 .. attribute:: timedelta.microseconds
 
@@ -351,7 +365,7 @@ Supported operations:
 |                                | same value. (2)                               |
 +--------------------------------+-----------------------------------------------+
 | ``-t1``                        | Equivalent to ``timedelta(-t1.days,           |
-|                                | -t1.seconds*, -t1.microseconds)``,            |
+|                                | -t1.seconds, -t1.microseconds)``,             |
 |                                | and to ``t1 * -1``. (1)(4)                    |
 +--------------------------------+-----------------------------------------------+
 | ``abs(t)``                     | Equivalent to ``+t`` when ``t.days >= 0``,    |

Doc/library/sys.monitoring.rst

@@ -50,16 +50,14 @@ Registering and using tools
    *tool_id* must be in the range 0 to 5 inclusive.
    Raises a :exc:`ValueError` if *tool_id* is in use.
 
-.. function:: free_tool_id(tool_id: int, /) -> None
+.. function:: clear_tool_id(tool_id: int, /) -> None
 
-   Should be called once a tool no longer requires *tool_id*.
+   Unregister all events and callback functions associated with *tool_id*.
 
-.. note::
+.. function:: free_tool_id(tool_id: int, /) -> None
 
-   :func:`free_tool_id` will not disable global or local events associated
-   with *tool_id*, nor will it unregister any callback functions. This
-   function is only intended to be used to notify the VM that the
-   particular *tool_id* is no longer in use.
+   Should be called once a tool no longer requires *tool_id*.
+   Will call :func:`clear_tool_id` before releasing *tool_id*.
 
 .. function:: get_tool(tool_id: int, /) -> str | None
 

Doc/tools/extensions/patchlevel.py

@@ -74,4 +74,8 @@ def get_version_info():
 
 
 if __name__ == "__main__":
-    print(format_version_info(get_header_version_info())[0])
+    short_ver, full_ver = format_version_info(get_header_version_info())
+    if sys.argv[1:2] == ["--short"]:
+        print(short_ver)
+    else:
+        print(full_ver)

Doc/using/windows.rst

@@ -23,8 +23,9 @@ available for application-local distributions.
 
 As specified in :pep:`11`, a Python release only supports a Windows platform
 while Microsoft considers the platform under extended support. This means that
-Python |version| supports Windows 8.1 and newer. If you require Windows 7
-support, please install Python 3.8.
+Python |version| supports Windows 10 and newer. If you require Windows 7
+support, please install Python 3.8. If you require Windows 8.1 support,
+please install Python 3.12.
 
 There are a number of different installers available for Windows, each with
 certain benefits and downsides.

Doc/whatsnew/3.13.rst

@@ -46,7 +46,7 @@
    when researching a change.
 
 This article explains the new features in Python 3.13, compared to 3.12.
-Python 3.13 will be released on October 1, 2024.
+Python 3.13 will be released on October 7, 2024.
 For full details, see the :ref:`changelog <changelog>`.
 
 .. seealso::
@@ -320,12 +320,9 @@ The free-threaded mode requires a different executable,
 usually called ``python3.13t`` or ``python3.13t.exe``.
 Pre-built binaries marked as *free-threaded* can be installed as part of
 the official :ref:`Windows <install-freethreaded-windows>`
-and :ref:`macOS <getting-and-installing-macpython>` installers,
+and :ref:`macOS <install-freethreaded-macos>` installers,
 or CPython can be built from source with the :option:`--disable-gil` option.
 
-.. better macOS link pending
-   https://github.com/python/cpython/issues/109975#issuecomment-2286391179
-
 Free-threaded execution allows for full utilization of the available
 processing power by running threads in parallel on available CPU cores.
 While not all software will benefit from this automatically, programs

Doc/whatsnew/3.14.rst

@@ -202,6 +202,13 @@ New Modules
 Improved Modules
 ================
 
+argparse
+--------
+
+* The default value of the :ref:`program name <prog>` for
+  :class:`argparse.ArgumentParser` now reflects the way the Python
+  interpreter was instructed to find the ``__main__`` module code.
+  (Contributed by Serhiy Storchaka and Alyssa Coghlan in :gh:`66436`.)
 
 ast
 ---

Include/cpython/code.h

@@ -8,6 +8,8 @@
 extern "C" {
 #endif
 
+/* Total tool ids available */
+#define  _PY_MONITORING_TOOL_IDS 8
 /* Count of all local monitoring events */
 #define  _PY_MONITORING_LOCAL_EVENTS 10
 /* Count of all "real" monitoring events (not derived from other events) */
@@ -57,6 +59,8 @@ typedef struct {
     _Py_LocalMonitors active_monitors;
     /* The tools that are to be notified for events for the matching code unit */
     uint8_t *tools;
+    /* The version of tools when they instrument the code */
+    uintptr_t tool_versions[_PY_MONITORING_TOOL_IDS];
     /* Information to support line events */
     _PyCoLineInstrumentationData *lines;
     /* The tools that are to be notified for line events for the matching code unit */