[pull] main from python:main

.github/workflows/reusable-docs.yml

@@ -66,7 +66,7 @@ jobs:
       run: |
         set -Eeuo pipefail
         # Build docs with the nit-picky option; write warnings to file
-        make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --fail-on-warning --warning-file sphinx-warnings.txt" html
+        make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --warning-file sphinx-warnings.txt" html
     - name: 'Check warnings'
       if: github.event_name == 'pull_request'
       run: |
@@ -75,6 +75,18 @@ jobs:
           --fail-if-regression \
           --fail-if-improved \
           --fail-if-new-news-nit
+    - name: 'Build EPUB documentation'
+      continue-on-error: true
+      run: |
+        set -Eeuo pipefail
+        make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet" epub
+        pip install epubcheck
+        epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt
+    - name: 'Check for fatal errors in EPUB'
+      if: github.event_name == 'pull_request'
+      continue-on-error: true  # until gh-136155 is fixed
+      run: |
+        python Doc/tools/check-epub.py
 
   # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
   doctest:

Doc/conf.py

@@ -448,6 +448,7 @@
 
 epub_author = 'Python Documentation Authors'
 epub_publisher = 'Python Software Foundation'
+epub_exclude_files = ('index.xhtml', 'download.xhtml')
 
 # index pages are not valid xhtml
 # https://github.com/sphinx-doc/sphinx/issues/12359

Doc/library/doctest.rst

@@ -311,9 +311,13 @@ Which Docstrings Are Examined?
 The module docstring, and all function, class and method docstrings are
 searched.  Objects imported into the module are not searched.
 
+.. currentmodule:: None
+
 .. attribute:: module.__test__
    :no-typesetting:
 
+.. currentmodule:: doctest
+
 In addition, there are cases when you want tests to be part of a module but not part
 of the help text, which requires that the tests not be included in the docstring.
 Doctest looks for a module-level variable called ``__test__`` and uses it to locate other

Doc/library/hmac.rst

@@ -12,6 +12,9 @@
 --------------
 
 This module implements the HMAC algorithm as described by :rfc:`2104`.
+The interface allows to use any hash function with a *fixed* digest size.
+In particular, extendable output functions such as SHAKE-128 or SHAKE-256
+cannot be used with HMAC.
 
 
 .. function:: new(key, msg=None, digestmod)

Doc/library/os.path.rst

@@ -508,9 +508,6 @@ the :mod:`glob` module.)
    .. versionchanged:: 3.4
       Added Windows support.
 
-   .. versionchanged:: 3.6
-      Accepts a :term:`path-like object`.
-
 
 .. function:: split(path)
 

Doc/tools/check-epub.py

@@ -0,0 +1,24 @@
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    wrong_directory_msg = "Must run this script from the repo root"
+    if not Path("Doc").exists() or not Path("Doc").is_dir():
+        raise RuntimeError(wrong_directory_msg)
+
+    with Path("Doc/epubcheck.txt").open(encoding="UTF-8") as f:
+        messages = [message.split(" - ") for message in f.read().splitlines()]
+
+    fatal_errors = [message for message in messages if message[0] == "FATAL"]
+
+    if fatal_errors:
+        print("\nError: must not contain fatal errors:\n")
+        for error in fatal_errors:
+            print(" - ".join(error))
+
+    return len(fatal_errors)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

Lib/_pyrepl/console.py

@@ -27,6 +27,7 @@
 import linecache
 from dataclasses import dataclass, field
 import os.path
+import re
 import sys
 
 
@@ -195,7 +196,19 @@ def runsource(self, source, filename="<input>", symbol="single"):
                 ast.PyCF_ONLY_AST,
                 incomplete_input=False,
             )
-        except (SyntaxError, OverflowError, ValueError):
+        except SyntaxError as e:
+            # If it looks like pip install was entered (a common beginner
+            # mistake), provide a hint to use the system command prompt.
+            if re.match(r"^\s*(pip3?|py(thon3?)? -m pip) install.*", source):
+                e.add_note(
+                    "The Python package manager (pip) can only be used"
+                    " outside of the Python REPL.\n"
+                    "Try the 'pip' command in a separate terminal or"
+                    " command prompt."
+                )
+            self.showsyntaxerror(filename, source=source)
+            return False
+        except (OverflowError, ValueError):
             self.showsyntaxerror(filename, source=source)
             return False
         if tree.body:

Lib/doctest.py

@@ -1997,8 +1997,8 @@ def testmod(m=None, name=None, globs=None, verbose=None,
     from module m (or the current module if m is not supplied), starting
     with m.__doc__.
 
-    Also test examples reachable from dict m.__test__ if it exists and is
-    not None.  m.__test__ maps names to functions, classes and strings;
+    Also test examples reachable from dict m.__test__ if it exists.
+    m.__test__ maps names to functions, classes and strings;
     function and class docstrings are tested even if the name is private;
     strings are tested directly, as if they were docstrings.
 

Lib/test/test_pyrepl/test_pyrepl.py

@@ -1757,3 +1757,14 @@ def test_showrefcount(self):
         output, _ = self.run_repl("1\n1+2\nexit()\n", cmdline_args=['-Xshowrefcount'], env=env)
         matches = re.findall(r'\[-?\d+ refs, \d+ blocks\]', output)
         self.assertEqual(len(matches), 3)
+
+    def test_detect_pip_usage_in_repl(self):
+        for pip_cmd in ("pip", "pip3", "python -m pip", "python3 -m pip"):
+            with self.subTest(pip_cmd=pip_cmd):
+                output, exit_code = self.run_repl([f"{pip_cmd} install sampleproject", "exit"])
+                self.assertIn("SyntaxError", output)
+                hint = (
+                    "The Python package manager (pip) can only be used"
+                    " outside of the Python REPL"
+                )
+                self.assertIn(hint, output)

Misc/ACKS

@@ -1744,6 +1744,7 @@ Joel Shprentz
 Yue Shuaijie
 Jaysinh Shukla
 Terrel Shumway
+Richard Si
 Eric Siegerman
 Reilly Tucker Siemens
 Paul Sijben
@@ -1988,6 +1989,7 @@ Olivier Vielpeau
 Kannan Vijayan
 Kurt Vile
 Norman Vine
+Tom Viner
 Pauli Virtanen
 Frank Visser
 Long Vo

Misc/NEWS.d/next/Documentation/2025-07-01-23-00-58.gh-issue-136155.4siQQO.rst

@@ -0,0 +1 @@
+We are now checking for fatal errors in EPUB builds in CI.

Misc/NEWS.d/next/Library/2025-07-07-16-46-55.gh-issue-72327.wLvRuj.rst

@@ -0,0 +1,2 @@
+Suggest using the system command prompt when ``pip install`` is typed into
+the REPL. Patch by Tom Viner, Richard Si, and Brian Schubert.