Merge branch 'main' into docs-clarify-argparse-neg-num

Author: savannahostrowski

Doc/library/argparse.rst

@@ -1564,12 +1564,12 @@ it exits and prints the error along with a usage message::
    >>> # invalid option
    >>> parser.parse_args(['--bar'])
    usage: PROG [-h] [--foo FOO] [bar]
-   PROG: error: no such option: --bar
+   PROG: error: unrecognized arguments: --bar
 
    >>> # wrong number of arguments
    >>> parser.parse_args(['spam', 'badger'])
    usage: PROG [-h] [--foo FOO] [bar]
-   PROG: error: extra arguments found: badger
+   PROG: error: unrecognized arguments: badger
 
 
 Arguments containing ``-``
@@ -1606,7 +1606,7 @@ there are no options in the parser that look like negative numbers::
    >>> # negative number options present, so -2 is an option
    >>> parser.parse_args(['-2'])
    usage: PROG [-h] [-1 ONE] [foo]
-   PROG: error: no such option: -2
+   PROG: error: unrecognized arguments: -2
 
    >>> # negative number options present, so both -1s are options
    >>> parser.parse_args(['-1', '-1'])

Doc/library/inspect.rst

@@ -707,9 +707,10 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 Retrieving source code
 ----------------------
 
-.. function:: getdoc(object, *, inherit_class_doc=True, fallback_to_class_doc=True)
+.. function:: getdoc(object, *, inherit_class_doc=True, fallback_to_class_doc=True, dedent=True)
 
-   Get the documentation string for an object, cleaned up with :func:`cleandoc`.
+   Get the documentation string for an object, cleaned up with :func:`cleandoc`
+   (with the same meaning of *dedent*).
    If the documentation string for an object is not provided:
 
    * if the object is a class and *inherit_class_doc* is true (by default),
@@ -730,6 +731,9 @@ Retrieving source code
       Documentation strings on :class:`~functools.cached_property`
       objects are now inherited if not overridden.
 
+   .. versionchanged:: next
+      Added the *dedent* parameter.
+
 
 .. function:: getcomments(object)
 
@@ -791,15 +795,23 @@ Retrieving source code
       former.
 
 
-.. function:: cleandoc(doc)
+.. function:: cleandoc(doc, *, dedent=True)
 
    Clean up indentation from docstrings that are indented to line up with blocks
    of code.
 
    All leading whitespace is removed from the first line.  Any leading whitespace
-   that can be uniformly removed from the second line onwards is removed.  Empty
-   lines at the beginning and end are subsequently removed.  Also, all tabs are
-   expanded to spaces.
+   that can be uniformly removed from the second line onwards is removed, unless
+   *dedent* is false.  Empty lines at the beginning and end are subsequently
+   removed.  Also, all tabs are expanded to spaces.
+
+   Since Python 3.13 the compiler removes the indentation of docstrings, so
+   *dedent* only affects documentation strings which are not written as
+   docstrings in the source code, like those generated by Argument Clinic,
+   where the indentation is meaningful.
+
+   .. versionchanged:: next
+      Added the *dedent* parameter.
 
 
 .. _inspect-signature-object:

Doc/library/subprocess.rst

@@ -236,8 +236,8 @@ underlying :class:`Popen` interface can be used directly.
 
     .. attribute:: returncode
 
-        Exit status of the child process.  If the process exited due to a
-        signal, this will be the negative signal number.
+        Exit status of the child process, an integer.  If the process
+        exited due to a signal, this will be the negative signal number.
 
     .. attribute:: cmd
 

Doc/library/test.rst

@@ -1656,6 +1656,32 @@ The :mod:`!test.support.os_helper` module provides support for os tests.
    wrapped with a wait loop that checks for the existence of the file.
 
 
+.. decorator:: with_source_date_epoch(*, epoch=123456789)
+
+   A decorator for running tests with the :envvar:`SOURCE_DATE_EPOCH`
+   environment variable set to *epoch*.
+
+
+.. decorator:: without_source_date_epoch
+
+   A decorator for running tests with the :envvar:`SOURCE_DATE_EPOCH`
+   environment variable unset.
+
+
+.. class:: SourceDateEpochTestMeta
+
+   Metaclass wrapping all test methods of the class with
+   :func:`with_source_date_epoch` if the *source_date_epoch* keyword class
+   argument is true, or with :func:`without_source_date_epoch` otherwise.
+   For example::
+
+      class TestsWithSourceEpoch(Tests,
+                                 metaclass=SourceDateEpochTestMeta,
+                                 source_date_epoch=True):
+          pass
+
+
+
 :mod:`!test.support.import_helper` --- Utilities for import tests
 =================================================================
 

Doc/library/zipfile.rst

@@ -285,6 +285,10 @@ ZipFile objects
       Added support for specifying member name encoding for reading
       metadata in the zipfile's directory and file headers.
 
+   .. versionchanged:: next
+      Deleting a writable, open :class:`zipfile.ZipFile` now emits a
+      :exc:`ResourceWarning`. Use as a :term:`context manager` or call
+      :meth:`~zipfile.ZipFile.close` explicitly.
 
 .. method:: ZipFile.close()
 

Lib/argparse.py

@@ -2917,11 +2917,14 @@ def print_help(self, file=None):
         self._print_message(help_text, file)
 
     def _print_message(self, message, file=None):
-        if message:
-            file = file or _sys.stderr
+        if not message:
+            return
+        if file is None:
+            file = _sys.stderr
+        if file is not None:
             try:
                 file.write(message)
-            except (AttributeError, OSError):
+            except OSError:
                 pass
 
     def _get_theme(self, file=None):

Lib/inspect.py

@@ -793,12 +793,14 @@ def _getowndoc(obj):
     except AttributeError:
         return None
 
-def getdoc(object, *, fallback_to_class_doc=True, inherit_class_doc=True):
+def getdoc(object, *, fallback_to_class_doc=True, inherit_class_doc=True,
+           dedent=True):
     """Get the documentation string for an object.
 
     All tabs are expanded to spaces.  To clean up docstrings that are
     indented to line up with blocks of code, any whitespace than can be
-    uniformly removed from the second line onwards is removed."""
+    uniformly removed from the second line onwards is removed, unless
+    dedent is false."""
     if fallback_to_class_doc:
         try:
             doc = object.__doc__
@@ -813,22 +815,23 @@ def getdoc(object, *, fallback_to_class_doc=True, inherit_class_doc=True):
             return None
     if not isinstance(doc, str):
         return None
-    return cleandoc(doc)
+    return cleandoc(doc, dedent=dedent)
 
-def cleandoc(doc):
+def cleandoc(doc, *, dedent=True):
     """Clean up indentation from docstrings.
 
     Any whitespace that can be uniformly removed from the second line
-    onwards is removed."""
+    onwards is removed, unless dedent is false."""
     lines = doc.expandtabs().split('\n')
 
     # Find minimum indentation of any non-blank lines after first line.
     margin = sys.maxsize
-    for line in lines[1:]:
-        content = len(line.lstrip(' '))
-        if content:
-            indent = len(line) - content
-            margin = min(margin, indent)
+    if dedent:
+        for line in lines[1:]:
+            content = len(line.lstrip(' '))
+            if content:
+                indent = len(line) - content
+                margin = min(margin, indent)
     # Remove indentation.
     if lines:
         lines[0] = lines[0].lstrip(' ')

Lib/pydoc.py

@@ -130,9 +130,12 @@ def pathdirs():
     return dirs
 
 def _getdoc(object):
+    # Docstrings written in the source are dedented by the compiler; the
+    # indentation of generated docstrings is meaningful.
     return inspect.getdoc(object,
                           fallback_to_class_doc=False,
-                          inherit_class_doc=False)
+                          inherit_class_doc=False,
+                          dedent=False)
 
 def getdoc(object):
     """Get the doc string or comments for an object."""

Lib/subprocess.py

@@ -143,16 +143,16 @@ def __init__(self, returncode, cmd, output=None, stderr=None):
         self.stderr = stderr
 
     def __str__(self):
-        if self.returncode and self.returncode < 0:
+        if isinstance(self.returncode, int) and self.returncode < 0:
             try:
                 return "Command %r died with %r." % (
                         self.cmd, signal.Signals(-self.returncode))
             except ValueError:
                 return "Command %r died with unknown signal %d." % (
                         self.cmd, -self.returncode)
         else:
-            return "Command %r returned non-zero exit status %d." % (
-                    self.cmd, self.returncode)
+            return (f"Command {self.cmd!r} returned non-zero "
+                    f"exit status {self.returncode}.")
 
     @property
     def stdout(self):

Lib/test/dtracedata/call_stack.stp

@@ -10,7 +10,7 @@ function basename:string(path:string)
     return last_token;
 }
 
-probe process.mark("function__entry")
+probe @PYTHON_SYSTEMTAP_PROBE@("function__entry")
 {
     funcname = user_string($arg2);
 
@@ -19,7 +19,8 @@ probe process.mark("function__entry")
     }
 }
 
-probe process.mark("function__entry"), process.mark("function__return")
+probe @PYTHON_SYSTEMTAP_PROBE@("function__entry"),
+      @PYTHON_SYSTEMTAP_PROBE@("function__return")
 {
     filename = user_string($arg1);
     funcname = user_string($arg2);
@@ -31,7 +32,7 @@ probe process.mark("function__entry"), process.mark("function__return")
     }
 }
 
-probe process.mark("function__return")
+probe @PYTHON_SYSTEMTAP_PROBE@("function__return")
 {
     funcname = user_string($arg2);