gh-134939: Add a Multiple Interpreters Howto Doc

.pre-commit-config.yaml

@@ -6,6 +6,7 @@ repos:
         name: Run Ruff (lint) on Doc/
         args: [--exit-non-zero-on-fix]
         files: ^Doc/
+        exclude: ^Doc/howto/multiple-interpreters-run-examples.py
       - id: ruff
         name: Run Ruff (lint) on Lib/test/
         args: [--exit-non-zero-on-fix]
@@ -22,6 +23,7 @@ repos:
         name: Run Ruff (format) on Doc/
         args: [--check]
         files: ^Doc/
+        exclude: ^Doc/howto/multiple-interpreters-run-examples.py
       - id: ruff-format
         name: Run Ruff (format) on Tools/build/check_warnings.py
         args: [--check, --config=Tools/build/.ruff.toml]

Doc/howto/index.rst

@@ -32,6 +32,7 @@ Python Library Reference.
    isolating-extensions.rst
    timerfd.rst
    mro.rst
+   multiple-interpreters.rst
    free-threading-python.rst
    free-threading-extensions.rst
    remote_debugging.rst
@@ -57,6 +58,7 @@ Advanced development:
 * :ref:`freethreading-python-howto`
 * :ref:`freethreading-extensions-howto`
 * :ref:`isolating-extensions-howto`
+* :ref:`multiple-interpreters-howto`
 * :ref:`python_2.3_mro`
 * :ref:`socket-howto`
 * :ref:`timerfd-howto`

Doc/howto/multiple-interpreters-run-examples.py

@@ -0,0 +1,177 @@
+import os
+import os.path
+import shutil
+import subprocess
+import sys
+import tempfile
+from textwrap import dedent
+import traceback
+
+
+HOWTO_DIR = os.path.dirname(__file__)
+HOWTO_FILE = os.path.join(HOWTO_DIR, 'multiple-interpreters.rst')
+
+VERBOSITY = 3
+
+
+def get_examples(lines):
+    examples = {}
+    current = None
+    expected = None
+    start = None
+    for lno, line in enumerate(lines, 1):
+        if current is None:
+            if line.endswith('::'):
+                # It *might* be an example.
+                current = []
+        else:
+            if not current:
+                if line.strip():
+                    if line == '    from concurrent import interpreters':
+                        # It *is* an example.
+                        current.append(line)
+                        expected = []
+                        start = lno
+                    else:
+                        # It wasn't actually an example.
+                        current = None
+            elif not line.strip() or line.startswith('    '):
+                # The example continues.
+                current.append(line)
+                before, sep, after = line.partition('# prints: ')
+                if sep:
+                    assert not before.strip(), before
+                    expected.append(after)
+            else:
+                # We've reached the end of the example.
+                assert not current[-1].strip(), current
+                example = dedent(os.linesep.join(current))
+                expected = ''.join(f'{l}{os.linesep}' for l in expected)
+                examples[start] = (example, expected)
+                current = expected = start = None
+
+                if line.endswith('::'):
+                    # It *might* be an example.
+                    current = []
+    if current:
+        if current[-1].strip():
+            current.append('')
+        example = dedent(os.linesep.join(current))
+        expected = ''.join(f'{l}{os.linesep}' for l in expected)
+        examples[start] = (example, expected)
+        current = expected = start = None
+    return examples
+
+
+def write_example(examplesdir, name, text):
+    filename = os.path.join(examplesdir, f'example-{name}.py')
+    with open(filename, 'w') as outfile:
+        outfile.write(text)
+    return filename, name, text
+
+
+def run_example(filename, expected):
+    if isinstance(expected, str):
+        rc = 0
+        stdout = expected
+        stderr = ''
+    else:
+        rc, stdout, stderr = expected
+
+    proc = subprocess.run(
+        [sys.executable, filename],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        cwd=os.path.dirname(filename),
+    )
+    if proc.returncode != rc:
+        if proc.returncode != 0 and proc.stderr:
+            print(proc.stderr)
+        raise AssertionError((proc.returncode, rc))
+    assert proc.stdout == stdout, (proc.stdout, stdout)
+    assert proc.stderr == stderr, (proc.stderr, stderr)
+
+
+#######################################
+# the script
+
+def parse_args(argv=sys.argv[1:], prog=sys.argv[0]):
+    import argparse
+    parser = argparse.ArgumentParser(prog=prog)
+
+    parser.add_argument('--dry-run', dest='dryrun', action='store_true')
+
+    parser.add_argument('-v', '--verbose', action='count', default=0)
+    parser.add_argument('-q', '--quiet', action='count', default=0)
+
+    parser.add_argument('requested', nargs='*')
+
+    args = parser.parse_args(argv)
+    ns = vars(args)
+
+    args.verbosity = max(0, VERBOSITY + ns.pop('verbose') - ns.pop('quiet'))
+
+    requested = []
+    for req in args.requested:
+        for i in req.replace(',', ' ').split():
+            requested.append(int(i))
+    args.requested = requested or None
+
+    return ns
+
+
+def main(requested=None, *, verbosity=VERBOSITY, dryrun=False):
+    with open(HOWTO_FILE) as infile:
+        examples = get_examples(l.rstrip(os.linesep) for l in infile)
+    examplesdir = tempfile.mkdtemp(prefix='multi-interp-howto-')
+    try:
+        if requested:
+            requested = set(requested)
+            _req = f', {len(requested)} requested'
+        else:
+            _req = ''
+        summary = f'({len(examples)} found{_req})'
+        print('#', summary)
+
+        failed = []
+        for i, (lno, (text, expected)) in enumerate(examples.items(), 1):
+            if requested and i not in requested:
+                continue
+            name = 'multiinterp-{i}'
+            print()
+            print('#'*60)
+            print(f'# example {i}  ({os.path.relpath(HOWTO_FILE)}:{lno})')
+            print('#'*60)
+            print()
+            if verbosity > VERBOSITY or (verbosity == VERBOSITY and dryrun):
+                print(text)
+                print('----')
+                if expected.rstrip():
+                    print(expected.rstrip(os.linesep))
+                print('----')
+            if dryrun:
+                continue
+            filename, _, _ = write_example(examplesdir, name, text)
+            try:
+                run_example(filename, expected)
+            except Exception:
+                traceback.print_exc()
+                failed.append(str(i))
+
+        print()
+        if failed:
+            print(f'{len(failed)} failed: {",".join(failed)}')
+        else:
+            print(f'all succeeded')
+        print(summary)
+
+        return len(failed)
+    finally:
+        shutil.rmtree(examplesdir)
+
+
+if __name__ == '__main__':
+    kwargs = parse_args()
+    ec = main(**kwargs)
+    sys.exit(ec)