profiling-explorer 1.0.0__tar.gz

profiling_explorer-1.0.0/CHANGELOG.rst

@@ -0,0 +1,8 @@
+=========
+Changelog
+=========
+
+1.0.0 (2026-04-02)
+------------------
+
+* Initial release.

profiling_explorer-1.0.0/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/MANIFEST.in

@@ -0,0 +1,8 @@
+prune tests
+include CHANGELOG.rst
+include LICENSE
+include pyproject.toml
+include README.rst
+include src/*/py.typed
+graft src/profiling_explorer/static/
+graft src/profiling_explorer/templates/

profiling_explorer-1.0.0/PKG-INFO

@@ -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/README.rst

@@ -0,0 +1,123 @@
+==================
+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/pyproject.toml

@@ -0,0 +1,134 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=77",
+]
+
+[project]
+name = "profiling-explorer"
+version = "1.0.0"
+description = "Table-based exploration tool for Python profiling data (pstats files)."
+readme = "README.rst"
+keywords = [
+  "profiler",
+  "profiling",
+  "pstats",
+]
+license = "MIT"
+license-files = [ "LICENSE" ]
+authors = [
+  { name = "Adam Johnson", email = "me@adamj.eu" },
+]
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "django>=5.2",
+]
+urls.Changelog = "https://github.com/adamchainz/profiling-explorer/blob/main/CHANGELOG.rst"
+urls.Funding = "https://adamj.eu/books/"
+urls.Repository = "https://github.com/adamchainz/profiling-explorer"
+scripts.profiling-explorer = "profiling_explorer.main:main"
+
+[dependency-groups]
+test = [
+  "cogapp>=3.6",
+  "coverage[toml]",
+  "pytest",
+  "pytest-django",
+  "pytest-randomly",
+]
+
+[tool.ruff]
+lint.select = [
+  # flake8-bugbear
+  "B",
+  # flake8-comprehensions
+  "C4",
+  # pycodestyle
+  "E",
+  # Pyflakes errors
+  "F",
+  # isort
+  "I",
+  # flake8-simplify
+  "SIM",
+  # flake8-tidy-imports
+  "TID",
+  # pyupgrade
+  "UP",
+  # Pyflakes warnings
+  "W",
+]
+lint.ignore = [
+  # flake8-bugbear opinionated rules
+  "B9",
+  # line-too-long
+  "E501",
+  # suppressible-exception
+  "SIM105",
+  # if-else-block-instead-of-if-exp
+  "SIM108",
+]
+lint.extend-safe-fixes = [
+  # non-pep585-annotation
+  "UP006",
+]
+lint.isort.required-imports = [ "from __future__ import annotations" ]
+
+[tool.pyproject-fmt]
+max_supported_python = "3.14"
+
+[tool.pytest]
+ini_options.addopts = """\
+    --strict-config
+    --strict-markers
+    --ds=profiling_explorer.settings
+    """
+ini_options.django_find_project = false
+ini_options.xfail_strict = true
+
+[tool.coverage]
+run.branch = true
+run.data_file = ".coverage/cov"
+run.parallel = true
+run.source = [
+  "profiling_explorer",
+  "tests",
+]
+paths.source = [
+  "src",
+  ".tox/**/site-packages",
+]
+report.exclude_also = [
+  "if TYPE_CHECKING:",
+]
+report.show_missing = true
+report.skip_covered = true
+report.skip_empty = true
+
+[tool.mypy]
+enable_error_code = [
+  "ignore-without-code",
+  "redundant-expr",
+  "truthy-bool",
+]
+mypy_path = "src/"
+namespace_packages = false
+strict = true
+warn_unreachable = true
+overrides = [ { module = "tests.*", allow_untyped_defs = true } ]
+
+[tool.rstcheck]
+report_level = "ERROR"

profiling_explorer-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

profiling_explorer-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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);