Rename --children to --subprocesses

Author: pablogsal

Doc/library/profiling.sampling.rst

@@ -310,8 +310,8 @@ The default configuration works well for most use cases:
      - Wall-clock mode (all samples recorded)
    * - ``--realtime-stats``
      - No live statistics display during profiling
-   * - ``--children``
-     - Profile only the target process (no child process monitoring)
+   * - ``--subprocesses``
+     - Profile only the target process (no subprocess monitoring)
 
 
 Sampling interval and duration
@@ -444,14 +444,14 @@ working correctly and that sufficient samples are being collected. See
 :ref:`sampling-efficiency` for details on interpreting these metrics.
 
 
-Child process profiling
------------------------
+Subprocess profiling
+--------------------
 
-The :option:`--children` option enables automatic profiling of child processes
+The :option:`--subprocesses` option enables automatic profiling of subprocesses
 spawned by the target::
 
-   python -m profiling.sampling run --children script.py
-   python -m profiling.sampling attach --children 12345
+   python -m profiling.sampling run --subprocesses script.py
+   python -m profiling.sampling attach --subprocesses 12345
 
 When enabled, the profiler monitors the target process for child process
 creation. When a new Python child process is detected, a separate profiler
@@ -480,39 +480,39 @@ or other process spawning mechanisms.
 
 ::
 
-   python -m profiling.sampling run --children --flamegraph worker_pool.py
+   python -m profiling.sampling run --subprocesses --flamegraph worker_pool.py
 
 This produces separate flame graphs for the main process and each worker
 process: ``flamegraph.<main_pid>.html``, ``flamegraph.<worker1_pid>.html``,
 and so on.
 
-Each child process receives its own output file. The filename is derived from
-the specified output path (or the default) with the child's process ID
+Each subprocess receives its own output file. The filename is derived from
+the specified output path (or the default) with the subprocess's process ID
 appended:
 
-- If you specify ``-o profile.html``, children produce ``profile_12345.html``,
+- If you specify ``-o profile.html``, subprocesses produce ``profile_12345.html``,
   ``profile_12346.html``, and so on
-- With default output, children produce files like ``flamegraph.12345.html``
+- With default output, subprocesses produce files like ``flamegraph.12345.html``
   or directories like ``heatmap_12345``
-- For pstats format (which defaults to stdout), children produce files like
+- For pstats format (which defaults to stdout), subprocesses produce files like
   ``profile.12345.pstats``
 
-The child profilers inherit most sampling options from the parent (interval,
+The subprocess profilers inherit most sampling options from the parent (interval,
 duration, thread selection, native frames, GC frames, async-aware mode, and
 output format). All Python descendant processes are profiled recursively,
 including grandchildren and further descendants.
 
-Child process detection works by periodically scanning for new descendants of
+Subprocess detection works by periodically scanning for new descendants of
 the target process and checking whether each new process is a Python process.
 On Linux, this uses a fast check of the executable name followed by a full
-probe of the process memory if needed. Non-Python child processes (such as
+probe of the process memory if needed. Non-Python subprocesses (such as
 shell commands or external tools) are ignored.
 
-There is a limit of 100 concurrent child profilers to prevent resource
+There is a limit of 100 concurrent subprocess profilers to prevent resource
 exhaustion in programs that spawn many processes. If this limit is reached,
-additional child processes are not profiled and a warning is printed.
+additional subprocesses are not profiled and a warning is printed.
 
-The :option:`--children` option is incompatible with :option:`--live` mode
+The :option:`--subprocesses` option is incompatible with :option:`--live` mode
 because live mode uses an interactive terminal interface that cannot
 accommodate multiple concurrent profiler displays.
 
@@ -1203,9 +1203,9 @@ Sampling options
    Compatible with ``--live``, ``--flamegraph``, ``--heatmap``, and ``--gecko``
    formats only.
 
-.. option:: --children
+.. option:: --subprocesses
 
-   Also profile child processes. Each child process gets its own profiler
+   Also profile subprocesses. Each subprocess gets its own profiler
    instance and output file. Incompatible with ``--live``.
 
 

Lib/profiling/sampling/cli.py

@@ -89,7 +89,7 @@ class CustomFormatter(
 def _setup_child_monitor(args, parent_pid):
     from ._child_monitor import ChildProcessMonitor
 
-    # Build CLI args for child profilers (excluding --children to avoid recursion)
+    # Build CLI args for child profilers (excluding --subprocesses to avoid recursion)
     child_cli_args = _build_child_profiler_args(args)
 
     # Build output pattern
@@ -103,7 +103,7 @@ def _setup_child_monitor(args, parent_pid):
 
 
 def _get_child_monitor_context(args, pid):
-    if getattr(args, 'children', False):
+    if getattr(args, 'subprocesses', False):
         return _setup_child_monitor(args, pid)
     return nullcontext()
 
@@ -157,7 +157,7 @@ def _build_output_pattern(args):
         if args.format == "heatmap":
             return "heatmap_{pid}"
         if args.format == "pstats":
-            # pstats defaults to stdout, but for children we need files
+            # pstats defaults to stdout, but for subprocesses we need files
             return "profile.{pid}.pstats"
         return f"{args.format}.{{pid}}.{extension}"
 
@@ -286,9 +286,9 @@ def _add_sampling_options(parser):
         help="Enable async-aware profiling (uses task-based stack reconstruction)",
     )
     sampling_group.add_argument(
-        "--children",
+        "--subprocesses",
         action="store_true",
-        help="Also profile child processes. Each child gets its own profiler and output file.",
+        help="Also profile subprocesses. Each subprocess gets its own profiler and output file.",
     )
 
 
@@ -490,10 +490,10 @@ def _validate_args(args, parser):
             "Live mode requires the curses module, which is not available."
         )
 
-    # --children is incompatible with --live
-    if hasattr(args, 'children') and args.children:
+    # --subprocesses is incompatible with --live
+    if hasattr(args, 'subprocesses') and args.subprocesses:
         if hasattr(args, 'live') and args.live:
-            parser.error("--children is incompatible with --live mode.")
+            parser.error("--subprocesses is incompatible with --live mode.")
 
     # Async-aware mode is incompatible with --native, --no-gc, --mode, and --all-threads
     if args.async_aware:

Lib/test/test_profiling/test_sampling_profiler/test_children.py

@@ -1,4 +1,4 @@
-"""Tests for --children subprocess profiling support."""
+"""Tests for --subprocesses subprocess profiling support."""
 
 import argparse
 import io
@@ -334,36 +334,36 @@ def test_context_manager(self):
 @skip_if_not_supported
 @requires_subprocess()
 class TestCLIChildrenFlag(unittest.TestCase):
-    """Tests for the --children CLI flag."""
+    """Tests for the --subprocesses CLI flag."""
 
     def setUp(self):
         reap_children()
 
     def tearDown(self):
         reap_children()
 
-    def test_children_flag_parsed(self):
-        """Test that --children flag is recognized."""
+    def test_subprocesses_flag_parsed(self):
+        """Test that --subprocesses flag is recognized."""
         from profiling.sampling.cli import _add_sampling_options
 
         parser = argparse.ArgumentParser()
         _add_sampling_options(parser)
 
-        # Parse with --children
-        args = parser.parse_args(["--children"])
-        self.assertTrue(args.children)
+        # Parse with --subprocesses
+        args = parser.parse_args(["--subprocesses"])
+        self.assertTrue(args.subprocesses)
 
-        # Parse without --children
+        # Parse without --subprocesses
         args = parser.parse_args([])
-        self.assertFalse(args.children)
+        self.assertFalse(args.subprocesses)
 
-    def test_children_incompatible_with_live(self):
-        """Test that --children is incompatible with --live."""
+    def test_subprocesses_incompatible_with_live(self):
+        """Test that --subprocesses is incompatible with --live."""
         from profiling.sampling.cli import _validate_args
 
-        # Create mock args with both children and live
+        # Create mock args with both subprocesses and live
         args = argparse.Namespace(
-            children=True,
+            subprocesses=True,
             live=True,
             async_aware=False,
             format="pstats",
@@ -500,7 +500,7 @@ def test_build_output_pattern_default(self):
     "Test requires process_vm_readv support on Linux",
 )
 class TestChildrenIntegration(unittest.TestCase):
-    """Integration tests for --children functionality."""
+    """Integration tests for --subprocesses functionality."""
 
     def setUp(self):
         reap_children()
@@ -891,16 +891,16 @@ def test_wait_for_profilers_multiple(self):
     "Test requires process_vm_readv support on Linux",
 )
 class TestEndToEndChildrenCLI(unittest.TestCase):
-    """End-to-end tests for --children CLI flag."""
+    """End-to-end tests for --subprocesses CLI flag."""
 
     def setUp(self):
         reap_children()
 
     def tearDown(self):
         reap_children()
 
-    def test_children_flag_spawns_child_and_creates_output(self):
-        """Test that --children flag works end-to-end with actual subprocesses."""
+    def test_subprocesses_flag_spawns_child_and_creates_output(self):
+        """Test that --subprocesses flag works end-to-end with actual subprocesses."""
         # Create a temporary directory for output files
         with tempfile.TemporaryDirectory() as tmpdir:
             # Create a script that spawns a child Python process
@@ -926,14 +926,14 @@ def test_children_flag_spawns_child_and_creates_output(self):
 
             output_file = os.path.join(tmpdir, "profile.pstats")
 
-            # Run the profiler with --children flag
+            # Run the profiler with --subprocesses flag
             result = subprocess.run(
                 [
                     sys.executable,
                     "-m",
                     "profiling.sampling",
                     "run",
-                    "--children",
+                    "--subprocesses",
                     "-d",
                     "3",
                     "-i",
@@ -971,8 +971,8 @@ def test_children_flag_spawns_child_and_creates_output(self):
                     f"stdout: {result.stdout}, stderr: {result.stderr}"
                 )
 
-    def test_children_flag_with_flamegraph_output(self):
-        """Test --children with flamegraph output format."""
+    def test_subprocesses_flag_with_flamegraph_output(self):
+        """Test --subprocesses with flamegraph output format."""
         with tempfile.TemporaryDirectory() as tmpdir:
             # Simple parent that spawns a child
             parent_script = f"""
@@ -995,7 +995,7 @@ def test_children_flag_with_flamegraph_output(self):
                     "-m",
                     "profiling.sampling",
                     "run",
-                    "--children",
+                    "--subprocesses",
                     "-d",
                     "2",
                     "-i",
@@ -1024,8 +1024,8 @@ def test_children_flag_with_flamegraph_output(self):
                     "Flamegraph output should be HTML",
                 )
 
-    def test_children_flag_no_crash_on_quick_child(self):
-        """Test that --children doesn't crash when child exits quickly."""
+    def test_subprocesses_flag_no_crash_on_quick_child(self):
+        """Test that --subprocesses doesn't crash when child exits quickly."""
         with tempfile.TemporaryDirectory() as tmpdir:
             # Parent spawns a child that exits immediately
             parent_script = f"""
@@ -1049,7 +1049,7 @@ def test_children_flag_no_crash_on_quick_child(self):
                     "-m",
                     "profiling.sampling",
                     "run",
-                    "--children",
+                    "--subprocesses",
                     "-d",
                     "2",
                     "-i",

Misc/NEWS.d/next/Library/2025-12-12-15-14-03.gh-issue-138122.m3EF9E.rst

@@ -1,5 +1,5 @@
-Add ``--children`` flag to :mod:`profiling.sampling` CLI to automatically
-profile child processes spawned by the target. When enabled, the profiler
+Add ``--subprocesses`` flag to :mod:`profiling.sampling` CLI to automatically
+profile subprocesses spawned by the target. When enabled, the profiler
 monitors for new Python subprocesses and profiles each one separately,
 writing results to individual output files. This is useful for profiling
 applications that use :mod:`multiprocessing`, :class:`~concurrent.futures.ProcessPoolExecutor`,