Visitar URL original
gh-140727: Restructure profiling documentation for PEP 799 by pablogsal · Pull Request #142373 · python/cpython · GitHub
Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
47 commits
Select commit Hold shift + click to select a range
ff62d3d
Add profiling module documentation structure
pablogsal Dec 7, 2025
1c712f1
Add profiling.sampling documentation
pablogsal Dec 7, 2025
d34d17b
Wire profiling docs into the documentation tree
pablogsal Dec 7, 2025
9da3576
Convert profile.rst to deprecation stub
pablogsal Dec 7, 2025
75413e4
Update CLI module references for profiling restructure
pablogsal Dec 7, 2025
1bcb081
Update whatsnew to link to profiling module docs
pablogsal Dec 7, 2025
ca3fed7
Fix warnings
pablogsal Dec 7, 2025
c1523bf
Fix warnings
pablogsal Dec 7, 2025
e8c5aca
Fix warnings
pablogsal Dec 7, 2025
f0f9dec
Apply suggestions from code review
pablogsal Dec 7, 2025
8c07f22
Update Doc/library/profile.rst
pablogsal Dec 7, 2025
ba35cd0
Small improvements and address feedback
pablogsal Dec 7, 2025
4ef946a
Add tachyon (provisional) logo
pablogsal Dec 7, 2025
eaa05bf
Update Doc/whatsnew/3.15.rst
pablogsal Dec 7, 2025
e614a80
find . -name '*.png' | xargs optipng -o7
StanFromIreland Dec 7, 2025
e2dc639
Remove image
pablogsal Dec 7, 2025
80cdcc4
Add Lib/ one too
StanFromIreland Dec 7, 2025
9485e14
Conflicts suck
StanFromIreland Dec 7, 2025
ecfda31
Merge pull request #107 from StanFromIreland/gh-140727
pablogsal Dec 7, 2025
994e224
Set default code formatting to shell-session, not Python
hugovk Dec 8, 2025
c357322
Sentence case for headers
hugovk Dec 8, 2025
fe20293
Links in headers don't always work nicely
hugovk Dec 8, 2025
87ae061
Global Interpreter Lock -> global interpreter lock
hugovk Dec 8, 2025
8f890d0
No need for caps
hugovk Dec 8, 2025
bf389fe
Exceptionally use plaintext formatting for output
hugovk Dec 8, 2025
7d7b14e
Prefer anonymous links
hugovk Dec 8, 2025
6f92adb
Use :kbd: role https://www.sphinx-doc.org/en/master/usage/restructure…
hugovk Dec 8, 2025
ffd5a27
Command-line interface
hugovk Dec 8, 2025
6f635e6
Use shell-session formatting
hugovk Dec 8, 2025
e3ed03c
Fix references
hugovk Dec 8, 2025
151e280
Wording
hugovk Dec 8, 2025
c20aa92
Link to pstats CLI
hugovk Dec 8, 2025
0ae0b99
Code formatting
hugovk Dec 8, 2025
e39ed69
Link Tachyon from release highlights
hugovk Dec 8, 2025
d7376db
Merge pull request #108 from hugovk/3.15-gh-140727
pablogsal Dec 8, 2025
3bfa0ec
Update Doc/library/profiling.rst
pablogsal Dec 8, 2025
8200ba7
Fixes
pablogsal Dec 8, 2025
2c2fd93
Add cross link
pablogsal Dec 8, 2025
ef985de
Improve sampling docs
pablogsal Dec 8, 2025
e7bd8b1
better logo
pablogsal Dec 9, 2025
fda1b16
Merge branch 'main' into gh-140727
pablogsal Dec 9, 2025
61d12a5
oxipng -o max --strip all (13.13% smaller)
hugovk Dec 9, 2025
8fb311b
Restructure dashes to dots
hugovk Dec 9, 2025
f766a5a
Use script.py like in other profiling docs
hugovk Dec 9, 2025
d667578
Sentence case headings
hugovk Dec 9, 2025
c697764
Merge pull request #111 from hugovk/3.15-gh-140727
pablogsal Dec 9, 2025
499e69e
Merge pull request #112 from hugovk/3.15-gh-140727-dashes-to-dots
pablogsal Dec 9, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Add tachyon (provisional) logo
  • Loading branch information
pablogsal committed Dec 7, 2025
commit 4ef946ac9e520f40eb68b4b20ea0aef8024999ff
17 changes: 11 additions & 6 deletions Doc/library/profiling-sampling.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,17 @@

--------------

The :mod:`profiling.sampling` module provides statistical profiling of Python
programs through periodic stack sampling. The profiler can attach to any
running Python process without requiring code changes or restarts, and it can
also launch and profile scripts directly. Because sampling occurs externally
to the target process, overhead is virtually zero, making this profiler
suitable for production environments.
.. image:: tachyon-logo.png
:alt: Tachyon logo
:align: center
:width: 300px

The :mod:`profiling.sampling` module, named **Tachyon**, provides statistical
profiling of Python programs through periodic stack sampling. The profiler can
run scripts directly or attach to any running Python process without requiring
code changes or restarts. Because sampling occurs externally to the target
process, overhead is virtually zero, making this profiler suitable for both
development and production environments.


What Is Statistical Profiling?
Expand Down
Binary file added Doc/library/tachyon-logo.png
Comment thread
pablogsal marked this conversation as resolved.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.15.rst
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,11 @@ The :mod:`profile` module is deprecated and will be removed in Python 3.17.
Tachyon: High frequency statistical sampling profiler
-----------------------------------------------------

.. image:: tachyon-logo.png
Comment thread
pablogsal marked this conversation as resolved.
Outdated
:alt: Tachyon profiler logo
:align: center
:width: 200px

A new statistical sampling profiler (Tachyon) has been added as
:mod:`profiling.sampling`. This profiler enables low-overhead performance analysis of
running Python processes without requiring code modification or process restart.
Expand Down
Binary file added Doc/whatsnew/tachyon-logo.png
Comment thread
pablogsal marked this conversation as resolved.
Outdated
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions Lib/profiling/sampling/_flamegraph_assets/flamegraph.css
Original file line number Diff line number Diff line change
Expand Up @@ -241,8 +241,8 @@ body.resizing-sidebar {
}

.sidebar-logo-img {
width: 90px;
height: 90px;
width: 220px;
height: 180px;
display: flex;
align-items: center;
justify-content: center;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
<!-- Top Bar -->
<header class="top-bar">
<div class="brand">
<div class="brand-logo"><!-- PYTHON_LOGO --></div>
<span class="brand-text">Tachyon</span>
<span class="brand-divider"></span>
<span class="brand-subtitle">Heatmap Report</span>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
<!-- Top Bar (Code Header) -->
<header class="top-bar">
<div class="brand">
<div class="brand-logo"><!-- PYTHON_LOGO --></div>
<span class="brand-text">Tachyon</span>
<span class="brand-divider"></span>
<span class="brand-subtitle" style="font-family: var(--font-mono); font-size: 13px;"><!-- FILENAME --></span>
Expand Down
8 changes: 4 additions & 4 deletions Lib/profiling/sampling/_shared_assets/base.css
Original file line number Diff line number Diff line change
Expand Up @@ -191,16 +191,16 @@ body {
display: flex;
align-items: center;
justify-content: center;
width: 28px;
height: 28px;
width: 48px;
height: 40px;
flex-shrink: 0;
}

/* Style the inlined SVG/img inside brand-logo */
.brand-logo svg,
.brand-logo img {
width: 28px;
height: 28px;
width: 48px;
height: 40px;
display: block;
object-fit: contain;
filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.2));
Expand Down
9 changes: 5 additions & 4 deletions Lib/profiling/sampling/heatmap_collector.py
Original file line number Diff line number Diff line change
Expand Up @@ -204,15 +204,15 @@ def _load_templates(self):
self.index_js = f"{shared_js}\n{(assets_dir / 'heatmap_index.js').read_text(encoding='utf-8')}"
self.file_js = f"{shared_js}\n{(assets_dir / 'heatmap.js').read_text(encoding='utf-8')}"

# Load Python logo
# Load Tachyon logo
logo_dir = template_dir / "_assets"
try:
png_path = logo_dir / "python-logo-only.png"
png_path = logo_dir / "tachyon-logo.png"
b64_logo = base64.b64encode(png_path.read_bytes()).decode("ascii")
self.logo_html = f'<img src="data:image/png;base64,{b64_logo}" alt="Python logo" class="python-logo"/>'
self.logo_html = f'<img src="data:image/png;base64,{b64_logo}" alt="Tachyon logo" class="python-logo"/>'
except (FileNotFoundError, IOError) as e:
self.logo_html = '<div class="python-logo-placeholder"></div>'
print(f"Warning: Could not load Python logo: {e}")
print(f"Warning: Could not load Tachyon logo: {e}")

except (FileNotFoundError, IOError) as e:
raise RuntimeError(f"Failed to load heatmap template files: {e}") from e
Expand Down Expand Up @@ -804,6 +804,7 @@ def _generate_file_html(self, output_path: Path, filename: str,
"<!-- CODE_LINES -->": ''.join(code_lines_html),
"<!-- INLINE_CSS -->": f"<style>\n{self._template_loader.file_css}\n</style>",
"<!-- INLINE_JS -->": f"<script>\n{self._template_loader.file_js}\n</script>",
"<!-- PYTHON_LOGO -->": self._template_loader.logo_html,
}

html_content = self._template_loader.file_template
Expand Down
4 changes: 2 additions & 2 deletions Lib/profiling/sampling/stack_collector.py
Original file line number Diff line number Diff line change
Expand Up @@ -352,11 +352,11 @@ def _create_flamegraph_html(self, data):
"<!-- INLINE_JS -->", f"<script>\n{js_content}\n</script>"
)

png_path = assets_dir / "python-logo-only.png"
png_path = assets_dir / "tachyon-logo.png"
b64_logo = base64.b64encode(png_path.read_bytes()).decode("ascii")

# Let CSS control size; keep markup simple
logo_html = f'<img src="data:image/png;base64,{b64_logo}" alt="Python logo"/>'
logo_html = f'<img src="data:image/png;base64,{b64_logo}" alt="Tachyon logo"/>'
html_template = html_template.replace("<!-- INLINE_LOGO -->", logo_html)

d3_js = d3_path.read_text(encoding="utf-8")
Expand Down
Loading