Metadata-Version: 2.4
Name: profiling-explorer
Version: 1.1.1
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/main/screenshot.png
   :alt: profiling-explorer screenshot

Read more in `the introductory blog post <https://adamj.eu/tech/2026/04/03/python-introducing-profiling-explorer/>`__.

----

**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.
  Separate multiple search terms by spaces to match records that contain all terms.
* Press a keyboard shortcut to focus the search box: ``/``, ``Control+K``, or ``Command+K``.
  Select some text first, like a filename, to pre-fill the search box with that text.
* 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]]]
