profiling-explorer 1.0.0__py3-none-any.whl

profiling_explorer/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from profiling_explorer.main import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

profiling_explorer/main.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+import os
+import pstats
+import sys
+from collections.abc import Sequence
+
+import django
+from django.core.management import call_command
+
+from profiling_explorer import settings, views
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(prog="profiling-explorer", allow_abbrev=False)
+    parser.suggest_on_error = True  # type: ignore[attr-defined]
+    parser.add_argument(
+        "filename",
+        metavar="FILE",
+        help="The pstats data file to explore.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8099,
+        metavar="PORT",
+        help="Port for the local web server (default: 8099).",
+    )
+    parser.add_argument(
+        "--dev",
+        action="store_true",
+        default=False,
+        help="Run in development mode (enables server reload and debug mode).",
+    )
+    args = parser.parse_args(argv)
+
+    settings.DEBUG = args.dev  # type: ignore[attr-defined]
+
+    views.profile = views.build_profile(pstats.Stats(args.filename), args.filename)
+
+    os.environ["DJANGO_SETTINGS_MODULE"] = "profiling_explorer.settings"
+
+    django.setup()
+
+    call_command(
+        "runserver",
+        f"127.0.0.1:{args.port}",
+        "--nothreading",
+        *(() if args.dev else ("--noreload",)),
+    )
+
+    return 0

profiling_explorer/management/commands/runserver.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import logging
+import webbrowser
+from typing import Any
+
+from django.core.management.commands.runserver import Command as RunserverCommand
+from django.utils.log import RequireDebugTrue
+
+logger = logging.getLogger("django.server")
+logger.filters.append(RequireDebugTrue())
+
+
+class Command(RunserverCommand):
+    addr: str
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        self.use_reloader = options["use_reloader"]
+        super().handle(*args, **options)
+
+    def on_bind(self, server_port: int) -> None:
+        self.stdout.write(
+            f"profiling-explorer running at http://{self.addr}:{server_port}/\n"
+            "Press CTRL+C to quit."
+        )
+        if not self.use_reloader:
+            print("Opening in web browser…")
+            webbrowser.open(f"http://{self.addr}:{server_port}")

profiling_explorer/settings.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+
+# Hide development server warning
+# https://docs.djangoproject.com/en/stable/ref/django-admin/#envvar-DJANGO_RUNSERVER_HIDE_WARNING
+os.environ["DJANGO_RUNSERVER_HIDE_WARNING"] = "true"
+
+# Disable host header validation
+ALLOWED_HOSTS = ["*"]
+
+INSTALLED_APPS = [
+    "profiling_explorer",
+    "django.contrib.humanize",
+]
+
+MIDDLEWARE = [
+    "django.middleware.common.CommonMiddleware",
+]
+
+ROOT_URLCONF = "profiling_explorer.urls"
+
+SECRET_KEY = "we-dont-use-any-secret-features-so-whatever"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "builtins": [
+                "profiling_explorer.templatetags.profiling_explorer_tags",
+                "django.contrib.humanize.templatetags.humanize",
+            ],
+        },
+    }
+]

profiling_explorer/static/script.js

@@ -0,0 +1,84 @@
+async function fetchDoc(url, options) {
+  const response = await fetch(url, options);
+  const html = await response.text();
+  return new DOMParser().parseFromString(html, 'text/html');
+}
+
+// Filter box
+const searchInput = document.getElementById('pe-search');
+let searchTimeout = null;
+let searchAbort = null;
+
+searchInput.addEventListener('input', () => {
+  clearTimeout(searchTimeout);
+  searchTimeout = setTimeout(async () => {
+    const q = searchInput.value.trim();
+    const url = new URL(window.location.href);
+    if (q) {
+      url.searchParams.set('q', q);
+    } else {
+      url.searchParams.delete('q');
+    }
+    history.replaceState(null, '', url);
+
+    searchAbort?.abort();
+    searchAbort = new AbortController();
+    try {
+      const doc = await fetchDoc(url, { signal: searchAbort.signal });
+      document.querySelector('main').replaceWith(doc.querySelector('main'));
+    } catch (e) {
+      if (e.name !== 'AbortError') throw e;
+    }
+  }, 300);
+});
+
+// Copy buttons
+document.addEventListener('click', (e) => {
+  const btn = e.target.closest('button.copy-btn');
+  if (!btn) return;
+
+  const text = btn.dataset.copy;
+  navigator.clipboard.writeText(text).then(() => {
+    btn.classList.add('copied');
+    setTimeout(() => btn.classList.remove('copied'), 1500);
+  });
+});
+
+
+// Pagination
+class PePaginationMarker extends HTMLElement {
+  connectedCallback() {
+    this._observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0].isIntersecting) {
+          this._observer.disconnect();
+          this._load();
+        }
+      },
+      { root: document.querySelector('main'), rootMargin: '200px' }
+    );
+    this._observer.observe(this);
+  }
+
+  disconnectedCallback() {
+    this._observer?.disconnect();
+  }
+
+  async _load() {
+    const doc = await fetchDoc(this.dataset.url);
+
+    const tbody = document.querySelector('tbody');
+    for (const row of doc.querySelectorAll('tbody tr')) {
+      tbody.appendChild(document.adoptNode(row));
+    }
+
+    const nextMarker = doc.querySelector('pe-pagination-marker');
+    if (nextMarker) {
+      this.replaceWith(document.adoptNode(nextMarker));
+    } else {
+      this.remove();
+    }
+  }
+}
+
+customElements.define('pe-pagination-marker', PePaginationMarker);

profiling_explorer/static/styles.css

@@ -0,0 +1,281 @@
+:root {
+  --bg: #ffffff;
+  --surface: #f6f8fa;
+  --text: #1a1a1a;
+  --text-dim: #57606a;
+  --funcname: #7c3aed;
+  --border: #d0d7de;
+  --stripe: rgba(0, 0, 0, .03);
+  --row-hover: rgba(0, 0, 0, .06);
+  --nav-bg: #ffffff;
+  --nav-text: #1a1a1a;
+  --nav-dim: rgba(0, 0, 0, .4);
+  --nav-border: var(--border);
+
+  font-family: system-ui, sans-serif;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0d1117;
+    --surface: #161b22;
+    --text: #e6edf3;
+    --text-dim: #8b949e;
+    --funcname: #c084fc;
+    --border: #30363d;
+    --stripe: rgba(255, 255, 255, .03);
+    --row-hover: rgba(255, 255, 255, .06);
+    --nav-bg: #161b22;
+    --nav-text: #e6edf3;
+    --nav-dim: rgba(230, 237, 243, .45);
+    --nav-border: rgba(230, 237, 243, .08);
+  }
+}
+
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  display: flex;
+  flex-direction: column;
+  height: 100dvh;
+  overflow: hidden;
+}
+
+nav.primary {
+  background: var(--nav-bg);
+  color: var(--nav-text);
+  flex-shrink: 0;
+  display: flex;
+  align-items: baseline;
+  gap: 0 1rem;
+  padding: 0.6rem 1.5rem 0 1.5rem;
+  border-bottom: 1px solid var(--nav-border);
+
+  & h1 {
+    margin: 0;
+    font-size: 1.1rem;
+    font-weight: 600;
+    letter-spacing: -.01em;
+    white-space: nowrap;
+  }
+
+  & h2 {
+    margin: 0;
+    font-size: 1.1rem;
+    font-weight: 400;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    min-width: 0;
+  }
+
+  & p {
+    margin: 0;
+    font-size: 0.9rem;
+    white-space: nowrap;
+  }
+
+  & input[type=search] {
+    margin-inline-start: auto;
+    margin-block-end: 0.3rem;
+    padding: 0.25rem 0.55rem;
+    border: 1px solid var(--border);
+    background: var(--bg);
+    color: var(--text);
+    font-size: 0.875rem;
+    width: 20rem;
+
+    &::placeholder {
+      color: var(--text-dim);
+    }
+
+    &:focus {
+      outline: 2px solid var(--funcname);
+      outline-offset: -1px;
+      border-color: transparent;
+    }
+  }
+}
+
+nav.secondary {
+  display: flex;
+  align-items: baseline;
+  gap: 1rem;
+  padding: 0.6rem 1.5rem;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+
+  & h3 {
+    margin: 0;
+    font-size: 1rem;
+    font-weight: 600;
+  }
+
+  a.back-link {
+    color: var(--text-dim);
+
+    &:hover {
+      color: var(--text);
+    }
+  }
+}
+
+
+main {
+  overflow: auto;
+  flex: 1;
+  min-height: 0;
+}
+
+table {
+  border-collapse: collapse;
+  white-space: nowrap;
+  width: 100%;
+}
+
+thead tr {
+  background: var(--surface);
+}
+
+th {
+  position: sticky;
+  top: 0;
+  background: var(--surface);
+  z-index: 1;
+  padding: 0.45rem 0.9rem;
+  text-align: right;
+  font-weight: 600;
+  letter-spacing: .05em;
+  color: var(--text-dim);
+  border-bottom: 2px solid var(--border);
+  width: 1%;
+
+  &.filename {
+    width: auto;
+    text-align: left;
+  }
+
+  & a {
+    text-decoration: none;
+    color: inherit;
+
+    &:hover {
+      color: var(--text);
+    }
+  }
+}
+
+pe-sort-indicator {
+  margin-left: 0.3em;
+}
+
+td {
+  padding: 0.28rem 0.9rem;
+  text-align: right;
+  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace;
+  border-bottom: 1px solid var(--border);
+  font-variant-numeric: tabular-nums;
+  width: 1%;
+
+  &.filename {
+    width: auto;
+    text-align: left;
+  }
+
+  tr.focal & {
+    background: color-mix(in srgb, var(--funcname) 10%, var(--surface));
+    border-bottom: 2px solid var(--border);
+  }
+}
+
+pe-funcname {
+  color: var(--funcname);
+}
+
+button.copy-btn {
+  display: inline-flex;
+  align-items: center;
+  background: none;
+  border: none;
+  padding: 0;
+  margin-right: 0.35em;
+  cursor: pointer;
+  color: var(--text-dim);
+  opacity: 0;
+  vertical-align: middle;
+  transition: color 0.1s, opacity 0.1s;
+
+  &:hover {
+    color: var(--text);
+  }
+
+  tr:hover & {
+    opacity: 1;
+  }
+
+  tr:hover &:disabled {
+    opacity: 0;
+  }
+
+  &.copied {
+    color: #22c55e;
+  }
+}
+
+tbody tr:nth-child(even) {
+  background: var(--stripe);
+}
+
+tbody tr:hover {
+  background: var(--row-hover);
+}
+
+a.callexs {
+  color: var(--text-dim);
+  text-decoration: none;
+
+  &:hover {
+    color: var(--text);
+  }
+}
+
+pe-pagination-marker {
+  display: block;
+}
+
+/* [[[cog
+import cog, math
+cog.outl(".pct-0  { color: var(--text); }")
+for b in range(1, 20):
+    v = round((b / 20) ** 0.75 * 100)
+    cog.outl(f".pct-{b:<2} {{ color: color-mix(in srgb, red {v}%, var(--text)); }}")
+cog.outl(".pct-20 { color: red; }")
+]]] */
+.pct-0  { color: var(--text); }
+.pct-1  { color: color-mix(in srgb, red 11%, var(--text)); }
+.pct-2  { color: color-mix(in srgb, red 18%, var(--text)); }
+.pct-3  { color: color-mix(in srgb, red 24%, var(--text)); }
+.pct-4  { color: color-mix(in srgb, red 30%, var(--text)); }
+.pct-5  { color: color-mix(in srgb, red 35%, var(--text)); }
+.pct-6  { color: color-mix(in srgb, red 41%, var(--text)); }
+.pct-7  { color: color-mix(in srgb, red 46%, var(--text)); }
+.pct-8  { color: color-mix(in srgb, red 50%, var(--text)); }
+.pct-9  { color: color-mix(in srgb, red 55%, var(--text)); }
+.pct-10 { color: color-mix(in srgb, red 59%, var(--text)); }
+.pct-11 { color: color-mix(in srgb, red 64%, var(--text)); }
+.pct-12 { color: color-mix(in srgb, red 68%, var(--text)); }
+.pct-13 { color: color-mix(in srgb, red 72%, var(--text)); }
+.pct-14 { color: color-mix(in srgb, red 77%, var(--text)); }
+.pct-15 { color: color-mix(in srgb, red 81%, var(--text)); }
+.pct-16 { color: color-mix(in srgb, red 85%, var(--text)); }
+.pct-17 { color: color-mix(in srgb, red 89%, var(--text)); }
+.pct-18 { color: color-mix(in srgb, red 92%, var(--text)); }
+.pct-19 { color: color-mix(in srgb, red 96%, var(--text)); }
+.pct-20 { color: red; }
+/* [[[end]]] */

profiling_explorer/templates/_row.html

@@ -0,0 +1,9 @@
+{% load humanize profiling_explorer_tags %}
+<tr{% if focal %} class=focal{% endif %}>
+  <td>{{ stats.calls|intcomma }}
+  <td class="{{ stats.calls_pct|pct_class }}">{{ stats.calls_pct|pct }}
+  <td>{% if stats.internal_ms != None %}{{ stats.internal_ms|intcomma }}{% endif %}
+  <td>{{ stats.cumulative_ms|intcomma }}
+  <td class="{{ stats.cumulative_ms_pct|pct_class }}">{{ stats.cumulative_ms_pct|pct }}
+  <td class=filename title="{{ row.full_filename }}"><button {% if not row.full_filename %}disabled{% endif %} class=copy-btn data-copy="{{ row.full_filename }}:{{ row.lineno }}" aria-label="Copy"><svg aria-hidden="true" width="18" height="18"><use href="#icon-copy"></use></svg></button>{% if row.filename %}{{ row.filename }}:{{ row.lineno }} {% endif %}<pe-funcname>{{ row.funcname }}</pe-funcname>
+  <td>{% if row.id %}<a class=callexs href="/callers/{{ row.id }}/"><svg aria-hidden="true" width="18" height="18"><use href="#icon-tree" transform="rotate(180 9 9)"></use></svg> callers</a> <a class=callexs href="/callees/{{ row.id }}/"><svg aria-hidden="true" width="18" height="18"><use href="#icon-tree"></use></svg> callees</a>{% endif %}

profiling_explorer/templates/base.html

@@ -0,0 +1,27 @@
+{% load humanize profiling_explorer_tags %}
+<!DOCTYPE html>
+<html lang=en>
+  <head>
+    <title>profiling-explorer</title>
+    <link rel=stylesheet href=/styles.css>
+    <script src=/script.js type=module></script>
+  </head>
+  <body>
+    <svg hidden width=0 height=0>
+      <symbol id="icon-copy" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2">
+        <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+        <rect width="13" height="13" x="9" y="9" rx="2"></rect>
+      </symbol>
+      <symbol id="icon-tree" viewBox="0 0 24 24" fill="none" stroke="none">
+        <path fill="currentColor" d="M19.5 23a3.5 3.5 0 0 1-1-6.855V14a1 1 0 0 0-1-1h-11a1 1 0 0 0-1 1v2.145A3.502 3.502 0 0 1 4.5 23a3.5 3.5 0 0 1-1-6.855V14a3 3 0 0 1 3-3H11V7.855A3.502 3.502 0 0 1 12 1a3.5 3.5 0 0 1 1 6.855V11h4.5a3 3 0 0 1 3 3v2.145a3.502 3.502 0 0 1-1 6.855"></path>
+    </symbol>
+    </svg>
+    <nav class=primary>
+      <h1>🗺️ profiling-explorer</h1>
+      <h2>{{ profile.filename }}</h2>
+      <p>{{ profile.total_calls|intcomma }} calls &middot; {{ profile.total_time_ms|intcomma }} ms</p>
+      <input type=search id=pe-search placeholder="Filter by filename or function…" autocomplete=off autofocus value="{{ q }}">
+    </nav>
+    {% block main %}{% endblock %}
+  </body>
+</html>

profiling_explorer/templates/callers_callees.html

@@ -0,0 +1,30 @@
+{% extends "base.html" %}
+{% load humanize profiling_explorer_tags %}
+{% block main %}
+<main>
+  <nav class=secondary>
+    <a href=/ class=back-link>← back</a>
+    <h3>{% if heading == "Callers" %}<svg aria-hidden="true" width="18" height="18"><use href="#icon-tree" transform="rotate(180 9 9)"></use></svg>{% else %}<svg aria-hidden="true" width="18" height="18"><use href="#icon-tree"></use></svg>{% endif %}
+      {{ heading }} of {{ focal_row.filename }}:{{ focal_row.lineno }} <pe-funcname>{{ focal_row.funcname }}</pe-funcname></h3>
+  </nav>
+  <table>
+    <thead>
+      <tr>
+        <th>calls
+        <th>%
+        <th>internal ms
+        <th>cumulative ms <pe-sort-indicator>↓</pe-sort-indicator>
+        <th>%
+        <th class=filename>filename:lineno function
+        <th>
+    </thead>
+    <tbody>
+      {% include "_row.html" with row=focal_row stats=focal_row focal=True only %}
+      {% for row, edge in rows_with_edges %}
+      {% include "_row.html" with row=row stats=edge focal=False only %}
+      {% endfor %}
+    </tbody>
+  </table>
+  {% if next_url %}<pe-pagination-marker data-url="{{ next_url }}"></pe-pagination-marker>{% endif %}
+</main>
+{% endblock %}

profiling_explorer/templates/index.html

@@ -0,0 +1,23 @@
+{% extends "base.html" %}
+{% load humanize profiling_explorer_tags %}
+{% block main %}
+<main>
+  <table>
+    <thead>
+      <tr>
+        {% for col in columns %}
+        <th><a href="{% querystring sort=col.next_sort %}">{{ col.label }} <pe-sort-indicator>{{ col.indicator }}</pe-sort-indicator></a>
+        {% if col.key == "calls" or col.key == "cumulative_ms" %}<th>%
+        {% endif %}{% endfor %}
+        <th class=filename>filename:lineno function
+        <th>
+    </thead>
+    <tbody>
+      {% for row in rows %}
+      {% include "_row.html" with row=row stats=row focal=False only %}
+      {% endfor %}
+    </tbody>
+  </table>
+  {% if next_url %}<pe-pagination-marker data-url="{{ next_url }}"></pe-pagination-marker>{% endif %}
+</main>
+{% endblock %}

profiling_explorer/templatetags/profiling_explorer_tags.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import math
+
+from django.template import Library
+
+register = Library()
+
+
+@register.filter
+def sub(value: int, arg: int) -> int:
+    return value - arg
+
+
+@register.filter
+def pct(value: float) -> str:
+    return f"{value:.1f}%"
+
+
+@register.filter
+def pct_class(value: float) -> str:
+    if value < 0.05:
+        return "pct-0"
+    return f"pct-{min(20, math.ceil(value / 5))}"

profiling_explorer/urls.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from django.urls import path
+
+from . import views
+
+urlpatterns = [
+    path("", views.index, name="index"),
+    path("callers/<str:row_id>/", views.callers_view, name="callers"),
+    path("callees/<str:row_id>/", views.callees_view, name="callees"),
+    path("favicon.ico", views.favicon),
+    path("styles.css", views.file, {"filename": "styles.css"}),
+    path("script.js", views.file, {"filename": "script.js"}),
+]

profiling_explorer/views.py

@@ -0,0 +1,330 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import pstats
+import re
+from dataclasses import dataclass
+from importlib.resources import files as resource_files
+from typing import Any
+from urllib.parse import urlencode
+
+from django.http import FileResponse, Http404, HttpRequest, HttpResponse
+from django.shortcuts import render
+from django.views.decorators.http import require_GET
+
+
+@dataclass(slots=True)
+class RowStats:
+    calls: int
+    calls_pct: float
+    internal_ms: int | None
+    cumulative_ms: int
+    cumulative_ms_pct: float
+
+
+@dataclass(slots=True)
+class EdgeStats(RowStats):
+    pass
+
+
+@dataclass(slots=True)
+class Row(RowStats):
+    id: str
+    filename: str
+    full_filename: str
+    lineno: int
+    funcname: str
+
+
+@dataclass(slots=True)
+class Profile:
+    filename: str
+    total_calls: int
+    total_time_ms: int
+    rows: list[Row]
+    rows_by_id: dict[str, Row]
+    callers_map: dict[str, dict[str, EdgeStats]]
+    callees_map: dict[str, dict[str, EdgeStats]]
+
+
+# Populated by main()
+profile: Profile = None  # type: ignore[assignment]
+
+
+_STRIP_PREFIX_RE = re.compile(
+    r"""
+    ^
+    .*
+    (?:
+        # virtualenv packages
+        /site-packages/
+        |
+        # standard library
+        lib/python3\.\d+/
+    )
+    """,
+    re.VERBOSE,
+)
+
+
+def _shorten_filename(filename: str) -> str:
+    match = _STRIP_PREFIX_RE.match(filename)
+    if match:
+        return filename[match.end() :]
+    return os.path.relpath(filename)
+
+
+def _row_id(full_filename: str, lineno: int, funcname: str) -> str:
+    return hashlib.sha256(f"{full_filename}:{lineno}:{funcname}".encode()).hexdigest()[
+        :12
+    ]
+
+
+def _row_id_from_pstats_key(key: tuple[str, int, str]) -> str:
+    filename, lineno, funcname = key
+    full_filename = "" if filename == "~" else filename
+    return _row_id(full_filename, lineno, funcname)
+
+
+def build_profile(s: pstats.Stats, path: str) -> Profile:
+    s.sort_stats("cumulative")
+    total_calls: int = s.total_calls  # type: ignore[attr-defined]
+    total_time_ms = round(s.total_tt * 1000)  # type: ignore[attr-defined]
+    rows = []
+    rows_by_id = {}
+    for key in s.fcn_list:  # type: ignore[attr-defined]
+        filename, lineno, funcname = key
+        _, calls, tottime, cumtime, _ = s.stats[key]  # type: ignore[attr-defined]
+        if filename == "~":
+            if funcname.startswith("<") and funcname.endswith(">"):
+                funcname = f"{{{funcname[1:-1]}}}"
+            short_filename = ""
+            full_filename = ""
+        else:
+            short_filename = _shorten_filename(filename)
+            full_filename = filename
+        row_id = _row_id(full_filename, lineno, funcname)
+        cumulative_ms = round(cumtime * 1_000)
+        row = Row(
+            id=row_id,
+            calls=calls,
+            calls_pct=min(100.0, calls / total_calls * 100) if total_calls else 0.0,
+            internal_ms=round(tottime * 1_000),
+            cumulative_ms=cumulative_ms,
+            cumulative_ms_pct=min(100.0, cumulative_ms / total_time_ms * 100)
+            if total_time_ms
+            else 0.0,
+            filename=short_filename,
+            full_filename=full_filename,
+            lineno=lineno,
+            funcname=funcname,
+        )
+        rows.append(row)
+        rows_by_id[row_id] = row
+
+    def make_edge(enc: int, etc: float) -> EdgeStats:
+        cumulative_ms = round(etc * 1_000)
+        return EdgeStats(
+            calls=enc,
+            calls_pct=min(100.0, enc / total_calls * 100) if total_calls else 0.0,
+            internal_ms=None,
+            cumulative_ms=cumulative_ms,
+            cumulative_ms_pct=(
+                min(100.0, cumulative_ms / total_time_ms * 100)
+                if total_time_ms
+                else 0.0
+            ),
+        )
+
+    callers_map: dict[str, dict[str, EdgeStats]] = {}
+    callees_map: dict[str, dict[str, EdgeStats]] = {}
+    for (filename, lineno, funcname), (*_, callers) in s.stats.items():  # type: ignore[attr-defined]
+        full_filename = "" if filename == "~" else filename
+        callee_id = _row_id(full_filename, lineno, funcname)
+        for caller_key, (enc, _, __, etc) in callers.items():
+            caller_id = _row_id_from_pstats_key(caller_key)
+            edge = make_edge(enc, etc)
+            callers_map.setdefault(callee_id, {})[caller_id] = edge
+            callees_map.setdefault(caller_id, {})[callee_id] = edge
+
+    return Profile(
+        filename=path,
+        total_calls=total_calls,
+        total_time_ms=total_time_ms,
+        rows=rows,
+        rows_by_id=rows_by_id,
+        callers_map=callers_map,
+        callees_map=callees_map,
+    )
+
+
+def _build_edge_rows(
+    edges: dict[str, EdgeStats],
+) -> list[tuple[Row, EdgeStats]]:
+    result = [
+        (row, edge)
+        for row_id, edge in edges.items()
+        if (row := profile.rows_by_id.get(row_id)) is not None
+    ]
+    result.sort(key=lambda pair: pair[1].cumulative_ms, reverse=True)
+    return result
+
+
+PAGE_SIZE = 200
+
+_VALID_SORT_COLS = {"calls", "internal_ms", "cumulative_ms"}
+
+
+def _render_table(
+    request: HttpRequest,
+    rows: list[Row],
+    template: str,
+    extra_context: dict[str, Any],
+    edge_stats: dict[str, EdgeStats] | None = None,
+) -> HttpResponse:
+    sort_param = request.GET.get("sort", "-cumulative_ms")
+    sort_desc = not sort_param.startswith("+")
+    sort_col = sort_param.lstrip("+-")
+    if sort_col not in _VALID_SORT_COLS:
+        sort_col = "cumulative_ms"
+        sort_desc = True
+        sort_param = "-cumulative_ms"
+
+    q = request.GET.get("q", "").strip()
+    filtered_rows = rows
+    if q:
+        filtered_rows = [r for r in rows if q in r.filename or q in r.funcname]
+
+    if edge_stats is None:
+        sorted_rows = sorted(
+            filtered_rows,
+            key=lambda r: (getattr(r, sort_col), r.filename, r.lineno, r.funcname),
+            reverse=sort_desc,
+        )
+    else:
+        sorted_rows = sorted(
+            filtered_rows,
+            key=lambda r: edge_stats[r.id].cumulative_ms,
+            reverse=True,
+        )
+
+    offset = int(request.GET.get("offset", 0))
+    page_rows = sorted_rows[offset : offset + PAGE_SIZE]
+
+    next_url = None
+    next_offset = offset + PAGE_SIZE
+    if next_offset < len(sorted_rows):
+        params: dict[str, str | int] = {"sort": sort_param, "offset": next_offset}
+        if q:
+            params["q"] = q
+        next_url = request.path + "?" + urlencode(params)
+
+    def col_config(key: str, label: str) -> dict[str, str]:
+        config = {"key": key, "label": label}
+        if sort_col == key:
+            config["indicator"] = "↓" if sort_desc else "↑"
+            config["next_sort"] = f"+{key}" if sort_desc else f"-{key}"
+        else:
+            config["indicator"] = ""
+            config["next_sort"] = f"-{key}"
+        return config
+
+    context = {
+        "profile": profile,
+        "rows": page_rows,
+        "next_url": next_url,
+        "q": q,
+        "columns": [
+            col_config("calls", "calls"),
+            col_config("internal_ms", "internal ms"),
+            col_config("cumulative_ms", "cumulative ms"),
+        ],
+        **extra_context,
+    }
+    if edge_stats is not None:
+        context["rows_with_edges"] = [(r, edge_stats[r.id]) for r in page_rows]
+
+    return render(request, template, context)
+
+
+def index(request: HttpRequest) -> HttpResponse:
+    return _render_table(request, profile.rows, "index.html", {})
+
+
+def _callers_callees_view(
+    request: HttpRequest,
+    focal_row: Row,
+    edges: dict[str, EdgeStats],
+    opposite_url: str,
+    heading: str,
+    opposite_label: str,
+) -> HttpResponse:
+    rows_with_edges = _build_edge_rows(edges)
+    rows = [r for r, _ in rows_with_edges]
+    edge_stats: dict[str, EdgeStats] = {r.id: e for r, e in rows_with_edges}
+
+    return _render_table(
+        request,
+        rows,
+        "callers_callees.html",
+        {
+            "focal_row": focal_row,
+            "heading": heading,
+            "opposite_label": opposite_label,
+            "opposite_url": opposite_url,
+        },
+        edge_stats=edge_stats,
+    )
+
+
+@require_GET
+def callers_view(request: HttpRequest, row_id: str) -> HttpResponse:
+    focal_row = profile.rows_by_id.get(row_id)
+    if focal_row is None:
+        raise Http404()
+    return _callers_callees_view(
+        request,
+        focal_row,
+        profile.callers_map.get(row_id, {}),
+        opposite_url=f"/callees/{row_id}/",
+        heading="Callers",
+        opposite_label="view callees →",
+    )
+
+
+@require_GET
+def callees_view(request: HttpRequest, row_id: str) -> HttpResponse:
+    focal_row = profile.rows_by_id.get(row_id)
+    if focal_row is None:
+        raise Http404()
+    return _callers_callees_view(
+        request,
+        focal_row,
+        profile.callees_map.get(row_id, {}),
+        opposite_url=f"/callers/{row_id}/",
+        heading="Callees",
+        opposite_label="← view callers",
+    )
+
+
+@require_GET
+def file(request: HttpRequest, *, filename: str) -> FileResponse:
+    return FileResponse(
+        resource_files("profiling_explorer")
+        .joinpath("static")
+        .joinpath(filename)
+        .open("rb"),
+    )
+
+
+@require_GET
+def favicon(request: HttpRequest) -> HttpResponse:
+    return HttpResponse(
+        (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">'
+            + '<text y=".9em" font-size="90">🗺️</text>'
+            + "</svg>"
+        ),
+        content_type="image/svg+xml",
+    )

profiling_explorer-1.0.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: profiling-explorer
+Version: 1.0.0
+Summary: Table-based exploration tool for Python profiling data (pstats files).
+Author-email: Adam Johnson <me@adamj.eu>
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/adamchainz/profiling-explorer/blob/main/CHANGELOG.rst
+Project-URL: Funding, https://adamj.eu/books/
+Project-URL: Repository, https://github.com/adamchainz/profiling-explorer
+Keywords: profiler,profiling,pstats
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: django>=5.2
+Dynamic: license-file
+
+==================
+profiling-explorer
+==================
+
+.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/profiling-explorer/main.yml.svg?branch=main&style=for-the-badge
+   :target: https://github.com/adamchainz/profiling-explorer/actions?workflow=CI
+
+.. image:: https://img.shields.io/badge/Coverage-70%25-success?style=for-the-badge
+   :target: https://github.com/adamchainz/profiling-explorer/actions?workflow=CI
+
+.. image:: https://img.shields.io/pypi/v/profiling-explorer.svg?style=for-the-badge
+   :target: https://pypi.org/project/profiling-explorer/
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+   :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+
+----
+
+Table-based exploration tool for Python profiling data (pstats files).
+
+.. Generated with:
+.. uvx --with django python -m cProfile -o django_utils_html.pstats -m django.utils.html
+.. uvr profiling-explorer django_utils_html.pstats
+.. …then in another tab:
+.. uvx shot-scraper --width 1280 --height 720 --retina --wait 1000 http://127.0.0.1:8099/ -o screenshot.png
+
+.. figure:: https://raw.githubusercontent.com/adamchainz/profiling-explorer/screenshot/screenshot.png
+   :alt: profiling-explorer screenshot
+
+----
+
+**Get better at command line Git** with my book `Boost Your Git DX <https://adamchainz.gumroad.com/l/bygdx>`__.
+
+----
+
+Requirements
+------------
+
+Python 3.10 to 3.14 supported.
+
+Installation
+------------
+
+1. Install with **pip**:
+
+   .. code-block:: sh
+
+       python -m pip install profiling-explorer
+
+Usage
+-----
+
+``profiling-explorer`` reads |pstats|__ files as generated by Python’s profilers: |profiling.tracing|__ (called ``cProfile`` on Python < 3.15) and |profiling.sampling|__ (new in Python 3.15).
+To use it, first generate a profile file, for example by running your program under cProfile:
+
+.. |pstats| replace:: ``pstats``
+__ https://docs.python.org/3.15/library/pstats.html
+
+.. |profiling.tracing| replace:: ``profiling.tracing``
+__ https://docs.python.org/3.15/library/profiling.tracing.html
+
+.. |profiling.sampling| replace:: ``profiling.sampling``
+__ https://docs.python.org/3.15/library/profiling.sampling.html
+
+.. code-block:: console
+
+    $ python -m cProfile -o example.pstats example.py
+
+(Also runnable as ``python -m profiling.tracing`` instead on Python 3.15+.)
+
+Then run ``profiling-explorer`` with the generated file:
+
+.. code-block:: console
+
+    $ profiling-explorer example.pstats
+
+The report will open in your web browser, and you can explore the profile data with the interactive interface.
+Features:
+
+* Click the **calls**, **internal ms**, or **cumulative ms** column headers to sort by that column.
+* Use the search box to filter by filename or function name.
+* Hover by a filename + line number pair to reveal the copy button, which copies the location to your clipboard for faster opening.
+* Click the **callers** or **callees** links on the right of a row to see the callers or callees of that function.
+
+Full help:
+
+.. [[[cog
+.. import cog
+.. import subprocess
+.. import sys
+.. result = subprocess.run(
+..     [sys.executable, "-m", "profiling_explorer", "--help"],
+..     capture_output=True,
+..     text=True,
+.. )
+.. cog.outl("")
+.. cog.outl(".. code-block:: console")
+.. cog.outl("")
+.. for line in result.stdout.splitlines():
+..     if line.strip() == "":
+..         cog.outl("")
+..     else:
+..         cog.outl("   " + line.rstrip())
+.. cog.outl("")
+.. ]]]
+
+.. code-block:: console
+
+   usage: profiling-explorer [-h] [--port PORT] [--dev] FILE
+
+   positional arguments:
+     FILE         The pstats data file to explore.
+
+   options:
+     -h, --help   show this help message and exit
+     --port PORT  Port for the local web server (default: 8099).
+     --dev        Run in development mode (enables server reload and debug mode).
+
+.. [[[end]]]

profiling_explorer-1.0.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+profiling_explorer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+profiling_explorer/__main__.py,sha256=4vXOGIOJCdezrLY-gKNANezVLN4Ln8j5bAe_KgZdXM0,154
+profiling_explorer/main.py,sha256=_ZuNCxKVnVVd8_2Z6-KD6Kvw9OHR_gAiikHXvTWfs8s,1410
+profiling_explorer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+profiling_explorer/settings.py,sha256=B1NmTGW5BqnTclh8Bn-RzfA-F4Gub4n5TdTfBhTwwVk,894
+profiling_explorer/urls.py,sha256=Mseb3NNwq7NgI0d6S0KnjpwmpKRdFI6QeCcJg37XKaw,454
+profiling_explorer/views.py,sha256=9WOYnsS1JRfoHmZxnFA0YOVAI4emPN5EmaLiIdtH3rc,9484
+profiling_explorer/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+profiling_explorer/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+profiling_explorer/management/commands/runserver.py,sha256=vE5k0G25gOkWjVwgnRnUowk3PtapcU-waitWK0ieSXs,859
+profiling_explorer/static/script.js,sha256=l9g5jZj8Tqkzc6TDQXzLGbu2HE63L59I7cZhrPwQhAc,2243
+profiling_explorer/static/styles.css,sha256=0Py97dRhvQqWcYvX9iLz1cwL5jAIk_St0d1mRXnGrtk,5690
+profiling_explorer/templates/_row.html,sha256=87uzUagddMDSJG7GzFIOKkqDfDkGxYg7Viv2gZMmCb0,1150
+profiling_explorer/templates/base.html,sha256=lt1dYznpuFd0jsdU14roWnpgf5btPRLw87f6NRqJY78,1368
+profiling_explorer/templates/callers_callees.html,sha256=T6qPTbOrSYMi_OmyJtAoeGxzsKfBzTotb_vero3WBb0,1180
+profiling_explorer/templates/index.html,sha256=yUdf7QO9erPdbBrWva_DvC2l5y3bUQjdqmH9SEn77FA,759
+profiling_explorer/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+profiling_explorer/templatetags/profiling_explorer_tags.py,sha256=9L3p2yIkdpGiLO_w87HsgjRpgpnA3k3fUjaw7lrYFIA,412
+profiling_explorer-1.0.0.dist-info/licenses/LICENSE,sha256=blVuFA7Qdp2_CcTyGXLxA4CsHsAjAquxVc4O6ODqye4,1069
+profiling_explorer-1.0.0.dist-info/METADATA,sha256=nLWYtNZPnd_1e9rJFYTY7ZMVMFLnUPOjCiCs11scBq4,5149
+profiling_explorer-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+profiling_explorer-1.0.0.dist-info/entry_points.txt,sha256=ZfJniu4afaqvx6Gv2hNrWLZcPx8amxp-E-eMY4oUxHs,68
+profiling_explorer-1.0.0.dist-info/top_level.txt,sha256=rcEyxu8VPgrOsvq9fNVwwX5FP4-s8l67lurknkqiZgc,19
+profiling_explorer-1.0.0.dist-info/RECORD,,

profiling_explorer-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

profiling_explorer-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+profiling-explorer = profiling_explorer.main:main

profiling_explorer-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

profiling_explorer-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+profiling_explorer