What is PyScope?
PyScope is a developer-oriented performance analysis tool designed to help identify bottlenecks in Python programs. Unlike traditional profilers that focus only on a single execution, PyScope tracks performance across multiple runs and detects regressions automatically.
PyScope is built as an end-to-end profiling system: data collection,
aggregation, regression analysis, and report generation.
Key Features
- 📊 Function-level hotspot profiling using
sys.setprofile - 🧠 Aggregated execution time, CPU usage, and peak memory
- 📈 Multi-run performance regression detection
- 📄 Automatic JSON & HTML report generation
- ⚡ Zero instrumentation — profile any Python script instantly
- 🧪 Designed for benchmarking, optimization, and experimentation workflows
Quick Start
Profile any Python script in one command:
python main.py your_script.pyPyScope automatically generates:
- CLI performance summary
- JSON report (
reports/json/) - HTML report (
reports/html/) - Regression analysis across historical runs
Sample Output
PyScope generates multiple forms of output to support both developer workflows and performance analysis over time. Below is a real example captured from profiling a slow Python script.
CLI Output
A concise command-line summary highlighting execution time, resource usage, hotspots, optimization hints, and regression warnings.
PyScope Performance Report
----------------------------------------
Execution Time : 1.8917 seconds
Average CPU : 40.91 %
Peak Memory : 19.15 MB
Top Hotspots
----------------------------------------
examples/slow_script.py:slow
Calls : 1
Total Time : 1.8782 seconds
Optimization Suggestions
----------------------------------------
• Function 'examples/slow_script.py:slow' dominates runtime (99%).
Consider optimizing its algorithm or reducing repeated work.
JSON report saved to : reports/json/pyscope_report_2025-12-16T12-26-04.603376.json
HTML report saved to : reports/html/pyscope_report_2025-12-16T12-26-04.603376.html
Performance Regression Check
----------------------------------------
⚠️ Execution time increased from 1.5524s → 1.9941s (+28.4541%)
⚠️ Peak memory increased from 18.844MB → 19.2539MB (+2.1766%)
⚠️ Top hotspot 'examples/slow_script.py:<module>' increased from 1.4750s → 1.9084s
JSON Report
A structured machine-readable report suitable for automation, dashboards, historical analysis, and research experiments.
{
"timestamp": "2025-12-16T12:26:04.603376",
"script": "examples/slow_script.py",
"execution_time": 1.8917008000425994,
"avg_cpu_percent": 40.90555555555555,
"peak_memory_mb": 19.15234375,
"hotspots": [
{
"function": "examples/slow_script.py:slow",
"calls": 1,
"total_time": 1.878245399799198
}
],
"suggestions": [
"Function 'examples/slow_script.py:slow' dominates runtime (99%).\nConsider optimizing its algorithm or reducing repeated work."
],
"regression": {
"status": "regression",
"messages": [
{
"level": "warning",
"text": "Execution time increased from 1.5524s → 1.9941s (+28.4541%)"
},
{
"level": "warning",
"text": "Peak memory increased from 18.844MB → 19.2539MB (+2.1766%)"
},
{
"level": "warning",
"text": "Top hotspot 'examples/slow_script.py:' increased from 1.4750s → 1.9084s"
}
]
}
} HTML Report
An interactive, human-readable HTML report that visualizes performance metrics, hotspots, optimization suggestions, and regression alerts in a single view.
Architecture Overview
Target Script
│
▼
Runner (runner.py)
│
├── ExecutionTimer → wall-clock execution time
├── ProcessProfiler → CPU & memory sampling
├── HotspotProfiler → function-level hotspots
│
▼
ProfilingReport
│
├── JSON Report (machine-readable)
├── HTML Report (human-readable)
│
├── OptimizationEngine → rule-based suggestions
└── MultiRunAnalyzer → regression detection
- HotspotProfiler: Captures function call/return timing
- Runner: Manages execution, CPU & memory sampling
- MultiRunAnalyzer: Detects regressions across runs
- Report Engine: Serializes results to JSON & HTML
The architecture emphasizes separation of concerns, extensibility, and
low runtime overhead.
Folder Structure
PyScope/
├── main.py # CLI entry point
├── pyscope/
│ ├── runner.py # Orchestrates profiling lifecycle
│ ├── timer.py # Wall-clock timing
│ ├── profiler.py # CPU & memory sampling (psutil)
│ ├── hotspots.py # Function-level execution tracking
│ ├── optimizer.py # Optimization suggestion engine
│ ├── report.py # JSON report generation
│ ├── html_report.py # HTML report rendering
│ └── multi_run.py # Historical regression analysis
├── examples/
│ └── slow_script.py # Sample workload
└── reports/
├── json/
└── html/
🔄 Multi-Run Regression Detection
Each run produces a timestamped JSON report
- Stored in
reports/json/ - Includes execution time, memory, hotspots, script path
Script-aware matching
- Only compares runs of the same script
- Uses OS-normalized absolute paths to avoid Windows/Linux mismatches
Latest-vs-Previous comparison
- Execution time
- Peak memory usage
- Top hotspot cumulative time
- Threshold-based decision
- Default: 10% increase = regression
- Fully configurable
Noise-aware
- Small runtime fluctuations are ignored
- Prevents false positives caused by OS scheduling variance
⚙️ Configuration
Adjust regression sensitivity in pyscope/multi_run.py:
def compare_latest(self, script_name=None, threshold=0.001):
# Lower threshold → more sensitive detection
# Higher threshold → more conservative detection
Why PyScope?
- Traditional profilers focus on single-run analysis
- PyScope treats performance as a time-series problem
- Built for experimentation, benchmarking, and optimization feedback loops
🛣️ Future Extensions
- Statistical confidence intervals over multiple baseline runs
- CI/CD integration (fail builds on regression)
- Flamegraph visualization
- ML-assisted optimization recommendations
- Language-agnostic profiling backend
🎓 Academic & Research Relevance
PyScope demonstrates:
- Systems-level performance engineering
- Runtime instrumentation
- Historical performance analysis
- Noise-aware regression detection
- Clean, extensible software architecture