Repository navigation
Document new profiling package and restructure the profiler docs according to PEP 799 #140727
Description
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
Metadata
Metadata
Assignees
Projects
- Status
Activity
StanFromIreland commentedon Oct 28, 2025
CC @pablogsal
pablogsal commentedon Oct 29, 2025
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 commentedon Dec 6, 2025
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 commentedon Dec 6, 2025
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.
I am not sure where is the 'redirect'. Can you point to where you are seeing that redirect to the docs?
Agreed. This will be done once we have the docs in place
pablogsal commentedon Dec 6, 2025
See also https://github.com/python/cpython/pull/140156/files
[-]3.15 what's new profiling example arguments seem incorrect[/-][+]Document new profiling package[/+]gpshead commentedon Dec 7, 2025
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-existant
Lib/profile/sample.pyfile and an unlinked presumed not-yet-existantprofiling.samplingreference.[-]Document new profiling package[/-][+]Document new profiling package and restructure the profiler docs according to PEP 799[/+]pablogsal commentedon Dec 7, 2025
Here we go #142373
Merge pull request #107 from StanFromIreland/pythongh-140727
Merge branch 'main' into pythongh-140727
gh-140727: Restructure profiling documentation for PEP 799 (#142373)
pythongh-140727: Update tachyon logo
pythongh-140727: Update tachyon logo
gh-140727: Update tachyon logo (#148965)
pythongh-140727: Move tachyon logo to static assets