linescope 0.1.0

Your code. In the spotlight.

A refreshingly simple source profiler for Python and Spark.

📜 Overview

General Information
Repository
Build
Code

💡 Introduction

LineScope shows where time is spent in your Python source, line by line. Browse full files and notebook cells, follow function and class links, and inspect Spark executions beside the driver code that triggered them. Work inside pandas, native libraries, I/O, and other dependencies stays attributed to the relevant source line instead of filling the report with their internals.

The result is a single HTML file with its own source snapshots, styles, and scripts. Open it offline, revisit it after code changes, or share it after reviewing the embedded source.

❗ Why use LineScope?

• Source first. Full files and cells, timing heatmaps, and unexecuted lines in context.
• Follow your code. Click individual function, class, and resolved method calls.
• Several ways to work. Context managers, explicit start/stop, CLI scripts/modules, and cell magic.
• Spark aware. Observe real actions and available executed plans without forcing lazy work.
• Honest measurements. Keep missing metrics unknown and driver time separate from executor work.
• Portable reports. No server or CDN needed to view the generated HTML.
• Pluggable collection. Choose from 3 different profiling backends: trace, scalene or trachyon.

🚀 Getting started

Installation

Install or upgrade LineScope in the same environment as your script or notebook. Python 3.11–3.15 is supported:

uv pip install --upgrade linescope

Use an existing virtual environment, or create one with uv venv first. Activate it with .venv\Scripts\Activate.ps1 in PowerShell or source .venv/bin/activate on Linux and macOS. With pip, use python -m pip install --upgrade linescope; you can replace uv pip with python -m pip in the commands below.

The base package includes the default Trace profiler, CLI, HTML reports, and driver memory collection.

Latest source

Install unreleased changes directly from the main branch. Git is required:

uv pip install --upgrade "git+https://github.com/tvdboom/linescope.git@main"

Optional dependencies

• scalene installs Scalene for CPU sampling and supported GPU measurements on Python 3.11–3.14. Select it with --backend scalene or backend="scalene"; it is omitted on Python 3.15.

  uv pip install --upgrade "linescope[scalene]"
  

• notebook installs IPython and ipykernel for cell magics, notebook capture, and inline reports.

  uv pip install --upgrade "linescope[notebook]"
  

• full installs both extras. Scalene is omitted on Python 3.15; development tools and GPU demo dependencies are separate.

  uv pip install --upgrade "linescope[full]"
  

Combine individual extras with linescope[scalene,notebook]. Spark and Databricks integration use the runtime's existing PySpark and Databricks SDK; LineScope does not install either library. Install the base package or linescope[notebook] in those environments. Spark profiling is opt-in with spark=True or --spark, and requires PySpark to be available.

Install the latest source with all integrations directly from Git:

uv pip install "linescope[full] @ git+https://github.com/tvdboom/linescope"

Contributing

Install the locked development environment from a checkout:

git clone https://github.com/tvdboom/linescope.git
cd linescope
uv sync --locked

See the installation guide for more setup details and the development guide for contribution checks.

Usage

From the terminal

Run your own script under LineScope without changing its source:

linescope --backend trace --output linescope.html your_script.py

The script runs normally, then LineScope saves linescope.html in the current directory and opens it in a browser. The report contains your source with line-by-line timings and works offline.

Place LineScope options before the script path. Arguments after the path go to your script. You can also profile an importable module from your project root:

linescope --backend trace --output linescope.html your_script.py --input data.csv
linescope --backend trace --output linescope.html -m your_package.your_module

To save the report without opening a browser:

linescope --backend trace --display none --output linescope.html your_script.py

From Python code

Wrap the work you want to measure with profile in your own script. Here, main() is your existing entry point; replace it with the calls you want to profile:

from linescope import profile

with profile(backend="trace", output="linescope.html") as session:
    main()

Run the script as usual:

python your_script.py

When the block exits, profiling stops and the report is saved and opened. For headless use, add display="none" to profile(...) and call session.save("linescope.html") after the block to write the report.

📘 Documentation