gh-138122: Refactor the CLI of profiling.sampling into subcommands

[pablogsal]

• Issue: Implement PEP 799 – A dedicated profiling package for organizing Python profiling tools #138122

[pablogsal]

@savannahostrowski I have reformulated the CLI to break it into sub commands. Could you play with this a bit and tell me what you think?

[pablogsal]

CC @lkollar

[pablogsal]

@hugovk if you have some time can you play with the CLI and tell be if you see any improvements we could do?

[savannahostrowski]

This refactoring makes the UX so much less intimidating off the jump IMO. I really like what it does for help tbh. Makes things a bit more intuitive!

One suggestion around how we can clean up examples in the help but otherwise, LGTM!

[lkollar]

I played around with it a bit and the subcommands make the CLI much nicer.

One odd thing I noticed is that both run and attach is fine with --pstats and any of the pstats format options with --live. We should probably block these in live mode.

[hugovk]

We'll need to update the examples at https://docs.python.org/3.15/whatsnew/3.15.html#pep-799-high-frequency-statistical-sampling-profiler but this can also be a followup PR once this is settled.

---

Looks good, thanks!

[hugovk]

Rather than using ANSIColors directly, it would be good to set and use a theme instead, so people can easily customise. Can be a followup PR.

[pablogsal]

Rather than using ANSIColors directly, it would be good to set and use a theme instead, so people can easily customise. Can be a followup PR.

Yeah good point, will do in a separate PR since the live TUI also may need that

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot x86-64 MacOS Intel NoGIL 3.x (tier-2) has failed when building commit 3eec46d.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/1258/builds/6275) and take a look at the build logs.
4. Check if the failure is related to this commit (3eec46d) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/1258/builds/6275

Failed tests:

• test_profiling

Failed subtests:

• test_script_error_treatment - test.test_profiling.test_sampling_profiler.test_integration.TestSampleProfilerErrorHandling.test_script_error_treatment

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/test/test_profiling/test_sampling_profiler/test_integration.py", line 730, in test_script_error_treatment
    self.assertIn(
    ~~~~~~~~~~~~~^
        "No such file or directory: 'nonexistent_file.txt'", output
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
AssertionError: "No such file or directory: 'nonexistent_file.txt'" not found in 'Traceback (most recent call last):\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/runpy.py", line 198, in _run_module_as_main\n    return _run_code(code, main_globals, None,\n                     "__main__", mod_spec)\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/runpy.py", line 88, in _run_code\n    exec(code, run_globals)\n    ~~~~^^^^^^^^^^^^^^^^^^^\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/cli.py", line 705, in <module>\n    main()\n    ~~~~^^\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/cli.py", line 525, in main\n    handler(args)\n    ~~~~~~~^^^^^^\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/cli.py", line 601, in _handle_run\n    collector = sample(\n        process.pid,\n    ...<6 lines>...\n        gc=args.gc,\n    )\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/sample.py", line 216, in sample\n    profiler = SampleProfiler(\n        pid,\n    ...<5 lines>...\n        skip_non_matching_threads=skip_non_matching_threads\n    )\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/sample.py", line 35, in __init__\n    self.unwinder = _remote_debugging.RemoteUnwinder(\n                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^\n        self.pid, all_threads=self.all_threads, mode=mode, native=native, gc=gc,\n        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n        skip_non_matching_threads=skip_non_matching_threads\n        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n    )\n    ^\nPermissionError: Cannot get task port for PID 15855 (kern_return_t: 5). This typically requires running as root or having the \'com.apple.system-task-ports\' entitlement.\n'


Traceback (most recent call last):
  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/test/test_profiling/test_sampling_profiler/test_integration.py", line 730, in test_script_error_treatment
    self.assertIn(
    ~~~~~~~~~~~~~^
        "No such file or directory: 'nonexistent_file.txt'", output
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
AssertionError: "No such file or directory: 'nonexistent_file.txt'" not found in 'Traceback (most recent call last):\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/runpy.py", line 198, in _run_module_as_main\n    return _run_code(code, main_globals, None,\n                     "__main__", mod_spec)\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/runpy.py", line 88, in _run_code\n    exec(code, run_globals)\n    ~~~~^^^^^^^^^^^^^^^^^^^\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/cli.py", line 705, in <module>\n    main()\n    ~~~~^^\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/cli.py", line 525, in main\n    handler(args)\n    ~~~~~~~^^^^^^\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/cli.py", line 601, in _handle_run\n    collector = sample(\n        process.pid,\n    ...<6 lines>...\n        gc=args.gc,\n    )\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/sample.py", line 216, in sample\n    profiler = SampleProfiler(\n        pid,\n    ...<5 lines>...\n        skip_non_matching_threads=skip_non_matching_threads\n    )\n  File "/Users/buildbot/buildarea/3.x.itamaro-macos-intel-aws.nogil/build/Lib/profiling/sampling/sample.py", line 35, in __init__\n    self.unwinder = _remote_debugging.RemoteUnwinder(\n                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^\n        self.pid, all_threads=self.all_threads, mode=mode, native=native, gc=gc,\n        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n        skip_non_matching_threads=skip_non_matching_threads\n        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n    )\n    ^\nPermissionError: Cannot get task port for PID 20032 (kern_return_t: 5). This typically requires running as root or having the \'com.apple.system-task-ports\' entitlement.\n'

[pablogsal]

will fix this bug

[pablogsal]

http://github.com/python/cpython/pull/141897