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

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

@pablogsal

CC @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"

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.

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

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

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.

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

gh-140727: Update tachyon logo (#148965)

pythongh-140727: Move tachyon logo to static assets

Navigation Menu

Repository navigation

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

Documentation

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

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

Description

Documentation

Linked PRs

Activity

StanFromIreland commented on Oct 28, 2025

pablogsal commented on Oct 29, 2025

terryjreedy commented on Dec 6, 2025

pablogsal commented on Dec 6, 2025

pablogsal commented on Dec 6, 2025

gpshead commented on Dec 7, 2025

pablogsal commented on Dec 7, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions