Document new profiling package and restructure the profiler docs according to PEP 799

[dimaqq]

Documentation

The doc states at https://docs.python.org/3.15/whatsnew/3.15.html#pep-799-high-frequency-statistical-sampling-profiler:

Profile process 1234 for 10 seconds with default settings:

python -m profiling.sampling 1234

At least on macOS, the argument "1234" is interpreted as a Python script to run, not a PID:

(jgol-peer) 🦐/c/j/peer (main)> sudo -E env PYTHONPATH=src python -m profiling.sampling 1234
Profiler coordinator error: Script not found: /code/jgol/peer/1234
...
...
TypeError: Cannot create or construct a <class 'pstats.SampledStats'> object from <profiling.sampling.pstats_collector.PstatsCollector object at 0x1036441a0>

Meanwhile a Python script is accepted:

(jgol-peer) 🦐/c/j/peer (main)> echo "import ops" > foo.py
(jgol-peer) 🦐/c/j/peer (main)> sudo -E env PYTHONPATH=src python -m profiling.sampling foo.py
Captured 586 samples in 0.06 seconds
Sample rate: 10000.02 samples/sec
Error rate: 7.17%
Profile Stats:
...
...

Linked PRs

• gh-140727: Restructure profiling documentation for PEP 799 #142373

[StanFromIreland]

CC @pablogsal

[pablogsal]

Ah this is out of date! Thanks for bringing it up. We are changing this quite a bit, and once the this stabilizes we will update back the what's new hopefully before the next alpha. You can always run `python3.15 -m profiling.sampling -h to know exactly what it takes"

[terryjreedy]

I suggest that this issue be broadened into "Document new profiling package" as there is nothing now in module list and index. Importing profiling, profiling.sampling (new subpackage), and profiling.tracing (package that replaces profile (and CProfile?) modules) and calling help result in an output that directs one to non-existent https://docs.python.org/3.15/library/profiling.html, etc. The long What's new entry should be moved to a new sampling.rst and replaced in What's New with a link to the new .html.

[pablogsal]

I suggest that this issue be broadened into "Document new profiling package" as there is nothing now in module list and index.

Indeed. We have planned a whole Docs overhaul once development stars to stabilize and we have a fixed list of things. We are planing some docs on understanding sampling profiling + a profiling HOWTO.

Importing profiling, profiling.sampling (new subpackage), and profiling.tracing (package that replaces profile (and CProfile?) modules) and calling help result in an output that directs one to non-existent https://docs.python.org/3.15/library/profiling.html, etc.

I am not sure where is the 'redirect'. Can you point to where you are seeing that redirect to the docs?

The long What's new entry should be moved to a new sampling.rst and replaced in What's New with a link to the new .html.

Agreed. This will be done once we have the docs in place

[pablogsal]

See also https://github.com/python/cpython/pull/140156/files

[gpshead]

what terry said... but also I assume this is work in progress. 😁 it was a bit confusing to look at the https://docs.python.org/3.15/library/profile.html and see a link to a non-existantLib/profile/sample.py file and an unlinked presumed not-yet-existant profiling.sampling reference.