oracletrace 2.0.0__tar.gz → 2.0.2__tar.gz

oracletrace-2.0.2/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: oracletrace
+Version: 2.0.2
+Summary: Detect Python performance regressions and compare execution traces with lightweight call graph visualization
+Author: Kayk Caputo, André Gustavo
+License: MIT License
+        
+        Copyright (c) 2025 Kayk Caputo and André Gustavo
+        
+        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.
+Project-URL: Homepage, https://kaykcaputo.github.io/oracletrace/
+Project-URL: Repository, https://github.com/KaykCaputo/oracletrace
+Project-URL: Documentation, https://kaykcaputo.github.io/oracletrace/
+Project-URL: Issues, https://github.com/KaykCaputo/oracletrace/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich
+Dynamic: license-file
+
+# OracleTrace — Detect Python Performance Regressions with Execution Diff
+
+> Detect performance regressions between runs of your Python script in seconds.
+
+<table><tr>
+<td><img src="https://raw.githubusercontent.com/KaykCaputo/oracletrace/master/oracletracecat.png" alt="OracleTrace Logo" width="185"/></td>
+<td>
+
+**Fail your CI when performance regresses.**
+
+OracleTrace is a **git diff for performance.**
+
+**Run your script twice and instantly see what got slower — with function-level precision.**
+
+</td>
+</tr></table>
+
+[![PyPI](https://img.shields.io/pypi/v/oracletrace?label=PyPI)](https://pypi.org/project/oracletrace)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/oracletrace?period=total\&units=INTERNATIONAL_SYSTEM\&left_color=BLACK\&right_color=GREEN\&left_text=downloads)](https://pepy.tech/projects/oracletrace)
+[![GitHub Stars](https://img.shields.io/github/stars/KaykCaputo/oracletrace?style=social)](https://github.com/KaykCaputo/oracletrace/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/KaykCaputo/oracletrace?style=social)](https://github.com/KaykCaputo/oracletrace/network/members)
+[![CI Tests](https://github.com/KaykCaputo/oracletrace/actions/workflows/tests.yml/badge.svg)](https://github.com/KaykCaputo/oracletrace/actions/workflows/tests.yml)
+
+Documentation: [https://kaykcaputo.github.io/oracletrace/](https://kaykcaputo.github.io/oracletrace/)
+
+**Featured in:** [PyCoder's Weekly #729](https://pycoders.com/issues/729) • [awesome-debugger](https://github.com/taowen/awesome-debugger) • [awesome-profiling](https://github.com/msaroufim/awesome-profiling)
+
+---
+### Installation
+```bash
+pip install oracletrace
+```
+
+## Quick Start
+
+### 1. See where your program spends time instantly:
+```bash
+oracletrace app.py
+```
+
+### 2. Compare runs and detect regressions:
+```bash
+oracletrace app.py --json baseline.json
+oracletrace app.py --json new.json --compare baseline.json
+```
+
+---
+
+## See it in action
+
+See exactly which functions got slower between runs:
+
+![OracleTrace CLI demo](https://raw.githubusercontent.com/KaykCaputo/oracletrace/master/oracletrace-cli-demo.gif)
+
+---
+
+## Example Output
+
+```
+Starting application...
+
+Iteration 1:
+  > Processing data...
+    > Calculating results...
+
+Iteration 2:
+  > Processing data...
+    > Calculating results...
+
+Application finished.
+
+Summary:
+                         Top functions by Total Time
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Function                     ┃ Total Time (s) ┃ Calls ┃ Avg. Time/Call (ms) ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ my_app.py:main               │         0.6025 │     1 │             602.510 │
+│ my_app.py:process_data       │         0.6021 │     2 │             301.050 │
+│ my_app.py:calculate_results  │         0.4015 │     2 │             200.750 │
+└──────────────────────────────┴────────────────┴───────┴─────────────────────┘
+
+Logic Flow:
+<module>
+└── my_app.py:main (1x, 0.6025s)
+    └── my_app.py:process_data (2x, 0.6021s)
+        └── my_app.py:calculate_results (2x, 0.4015s)
+```
+
+---
+
+## Why OracleTrace?
+
+### Problem
+
+Performance regressions are hard to detect early.
+
+### Solution
+
+OracleTrace compares execution traces and highlights what got slower.
+
+### How it works
+
+1. Run your script
+2. Generate a trace
+3. Compare results
+4. Identify slowdowns
+
+---
+
+## CI Integration
+
+Fail your pipeline when performance degrades:
+
+```bash
+oracletrace app.py --json current.json --compare baseline.json --fail-on-regression --threshold 25
+```
+Add it to your CI to automatically fail on performance regressions.
+
+---
+
+## Key Features
+
+* Detect slower and faster functions
+* Identify new or removed functions
+* Execution time and call count analysis
+* Call graph visualization
+* JSON and CSV export
+* Regex-based filtering (`--ignore`)
+* Top-N function focus (`--top`)
+* CI regression gates
+
+---
+
+## CLI Reference
+
+| Flag                   | Description                            |
+| ---------------------- | -------------------------------------- |
+| `--json`               | Export trace to JSON                   |
+| `--csv`               | Export trace to CSV                     |
+| `--compare`            | Compare with another trace             |
+| `--fail-on-regression` | Exit with error if regression detected |
+| `--threshold`          | Regression percentage threshold        |
+| `--ignore`             | Ignore functions/files via regex       |
+| `--top`                | Show top N functions                   |
+
+---
+
+## Use Cases
+
+### Primary
+
+* Detect performance regressions between runs
+
+### Secondary
+
+* CI performance validation
+* Execution trace inspection
+* Call graph visualization
+
+---
+
+## How It Works
+
+OracleTrace uses Python’s `sys.setprofile()` to intercept function calls and returns.
+
+It measures execution time per function and records caller–callee relationships.
+
+Filtering removes external/internal calls to focus on application code.
+
+---
+
+## Requirements
+
+* Python >= 3.10
+* rich
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+Please read the [Contributing Guide](CONTRIBUTING.md) for details on how to get started, coding standards, and the contribution process.
+
+---
+
+## Contributors
+
+<a href="https://github.com/KaykCaputo/oracletrace/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=KaykCaputo/oracletrace" />
+</a>
+
+---
+
+## ⭐ Support the Project
+
+If OracleTrace is useful, consider giving it a star:
+
+[GitHub Repository](https://github.com/KaykCaputo/oracletrace)
+
+---
+
+## Maintainers
+
+* [Kayk Caputo](https://github.com/KaykCaputo)
+* [André Gustavo](https://github.com/AndreXP1)

oracletrace-2.0.2/README.md

@@ -0,0 +1,206 @@
+# OracleTrace — Detect Python Performance Regressions with Execution Diff
+
+> Detect performance regressions between runs of your Python script in seconds.
+
+<table><tr>
+<td><img src="https://raw.githubusercontent.com/KaykCaputo/oracletrace/master/oracletracecat.png" alt="OracleTrace Logo" width="185"/></td>
+<td>
+
+**Fail your CI when performance regresses.**
+
+OracleTrace is a **git diff for performance.**
+
+**Run your script twice and instantly see what got slower — with function-level precision.**
+
+</td>
+</tr></table>
+
+[![PyPI](https://img.shields.io/pypi/v/oracletrace?label=PyPI)](https://pypi.org/project/oracletrace)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/oracletrace?period=total\&units=INTERNATIONAL_SYSTEM\&left_color=BLACK\&right_color=GREEN\&left_text=downloads)](https://pepy.tech/projects/oracletrace)
+[![GitHub Stars](https://img.shields.io/github/stars/KaykCaputo/oracletrace?style=social)](https://github.com/KaykCaputo/oracletrace/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/KaykCaputo/oracletrace?style=social)](https://github.com/KaykCaputo/oracletrace/network/members)
+[![CI Tests](https://github.com/KaykCaputo/oracletrace/actions/workflows/tests.yml/badge.svg)](https://github.com/KaykCaputo/oracletrace/actions/workflows/tests.yml)
+
+Documentation: [https://kaykcaputo.github.io/oracletrace/](https://kaykcaputo.github.io/oracletrace/)
+
+**Featured in:** [PyCoder's Weekly #729](https://pycoders.com/issues/729) • [awesome-debugger](https://github.com/taowen/awesome-debugger) • [awesome-profiling](https://github.com/msaroufim/awesome-profiling)
+
+---
+### Installation
+```bash
+pip install oracletrace
+```
+
+## Quick Start
+
+### 1. See where your program spends time instantly:
+```bash
+oracletrace app.py
+```
+
+### 2. Compare runs and detect regressions:
+```bash
+oracletrace app.py --json baseline.json
+oracletrace app.py --json new.json --compare baseline.json
+```
+
+---
+
+## See it in action
+
+See exactly which functions got slower between runs:
+
+![OracleTrace CLI demo](https://raw.githubusercontent.com/KaykCaputo/oracletrace/master/oracletrace-cli-demo.gif)
+
+---
+
+## Example Output
+
+```
+Starting application...
+
+Iteration 1:
+  > Processing data...
+    > Calculating results...
+
+Iteration 2:
+  > Processing data...
+    > Calculating results...
+
+Application finished.
+
+Summary:
+                         Top functions by Total Time
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Function                     ┃ Total Time (s) ┃ Calls ┃ Avg. Time/Call (ms) ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ my_app.py:main               │         0.6025 │     1 │             602.510 │
+│ my_app.py:process_data       │         0.6021 │     2 │             301.050 │
+│ my_app.py:calculate_results  │         0.4015 │     2 │             200.750 │
+└──────────────────────────────┴────────────────┴───────┴─────────────────────┘
+
+Logic Flow:
+<module>
+└── my_app.py:main (1x, 0.6025s)
+    └── my_app.py:process_data (2x, 0.6021s)
+        └── my_app.py:calculate_results (2x, 0.4015s)
+```
+
+---
+
+## Why OracleTrace?
+
+### Problem
+
+Performance regressions are hard to detect early.
+
+### Solution
+
+OracleTrace compares execution traces and highlights what got slower.
+
+### How it works
+
+1. Run your script
+2. Generate a trace
+3. Compare results
+4. Identify slowdowns
+
+---
+
+## CI Integration
+
+Fail your pipeline when performance degrades:
+
+```bash
+oracletrace app.py --json current.json --compare baseline.json --fail-on-regression --threshold 25
+```
+Add it to your CI to automatically fail on performance regressions.
+
+---
+
+## Key Features
+
+* Detect slower and faster functions
+* Identify new or removed functions
+* Execution time and call count analysis
+* Call graph visualization
+* JSON and CSV export
+* Regex-based filtering (`--ignore`)
+* Top-N function focus (`--top`)
+* CI regression gates
+
+---
+
+## CLI Reference
+
+| Flag                   | Description                            |
+| ---------------------- | -------------------------------------- |
+| `--json`               | Export trace to JSON                   |
+| `--csv`               | Export trace to CSV                     |
+| `--compare`            | Compare with another trace             |
+| `--fail-on-regression` | Exit with error if regression detected |
+| `--threshold`          | Regression percentage threshold        |
+| `--ignore`             | Ignore functions/files via regex       |
+| `--top`                | Show top N functions                   |
+
+---
+
+## Use Cases
+
+### Primary
+
+* Detect performance regressions between runs
+
+### Secondary
+
+* CI performance validation
+* Execution trace inspection
+* Call graph visualization
+
+---
+
+## How It Works
+
+OracleTrace uses Python’s `sys.setprofile()` to intercept function calls and returns.
+
+It measures execution time per function and records caller–callee relationships.
+
+Filtering removes external/internal calls to focus on application code.
+
+---
+
+## Requirements
+
+* Python >= 3.10
+* rich
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+Please read the [Contributing Guide](CONTRIBUTING.md) for details on how to get started, coding standards, and the contribution process.
+
+---
+
+## Contributors
+
+<a href="https://github.com/KaykCaputo/oracletrace/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=KaykCaputo/oracletrace" />
+</a>
+
+---
+
+## ⭐ Support the Project
+
+If OracleTrace is useful, consider giving it a star:
+
+[GitHub Repository](https://github.com/KaykCaputo/oracletrace)
+
+---
+
+## Maintainers
+
+* [Kayk Caputo](https://github.com/KaykCaputo)
+* [André Gustavo](https://github.com/AndreXP1)

oracletrace-2.0.2/oracletrace/cli.py

@@ -0,0 +1,160 @@
+import re
+import sys
+import os
+import json
+import runpy
+import csv
+from dataclasses import asdict
+from typing import List, Dict, Any, Optional
+from re import Pattern
+from argparse import ArgumentParser, Namespace
+from importlib.metadata import version
+from .tracer import Tracer, TracerData
+from .compare import compare_traces, ComparisonData
+from .reporters import generate_html_report
+
+
+def main() -> int:
+    module_name = __name__.split(".")[0]
+    parser: ArgumentParser  = ArgumentParser(
+        prog=module_name,
+        description="OracleTrace - Lightweight execution tracer for Python projects"
+    )
+    parser.add_argument("target", help="Python script to trace")
+    parser.add_argument("--json", help="Export trace result to JSON file")
+    parser.add_argument("--compare", help="Compare against previous trace JSON")
+    parser.add_argument("--csv", help="Export trace result to CSV file")
+    parser.add_argument("--html", help="Export trace result to interactive HTML file")
+    parser.add_argument(
+        "--ignore",
+        metavar="REGEX",
+        nargs="+",
+        help="Space separated list of regex patterns for keys (file path and function name) to ignore."
+    )
+    parser.add_argument(
+        "--top",
+        metavar="NUMBER",
+        help="Limits the number of functions shown in the summary table"
+    )
+    parser.add_argument(
+    "--fail-on-regression",
+    action="store_true",
+    help="Exit with a non-zero code when regression exceeds threshold.",
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=5.0,
+        help="Regression threshold percentage used with --fail-on-regression.",
+    )
+    parser.add_argument(
+        "--only-regressions",
+        action="store_true",
+        help="Hide functions which didn't run slower than baseline. Use with --compare"
+    )
+    
+    parser.add_argument(
+        "--version",
+        action="version",
+        help="Print version information then exit with a zero code",
+        version=f"%(prog)s {version(module_name)}"
+    )
+    args: Namespace = parser.parse_args()
+
+    target: str = args.target
+
+    # Validate --top argument manually to ensure all paths are testable
+    if args.top is not None:
+        try:
+            args.top = int(args.top)
+        except ValueError:
+            print(f"argument --top: invalid int value: '{args.top}'", file=sys.stderr)
+            return 2
+        if args.top < 1:
+            print(f"--top must be a positive integer, got: {args.top}", file=sys.stderr)
+            return 1
+
+    if not os.path.exists(target):
+        print(f"Target not found: {target}", file=sys.stderr)
+        return 1
+
+    target = os.path.abspath(target)
+    root: str = os.getcwd()
+    target_dir: str = os.path.dirname(target)
+    # Setup paths so imports work correctly in the target script
+    sys.path.insert(0, target_dir)
+    ignored_args: List[str] = [] if args.ignore is None else args.ignore
+    ignore_patterns: List[Pattern] = []
+
+    for pattern in ignored_args:
+        try:
+            ignore_patterns.append(re.compile(pattern))
+        except re.error as e:
+            print(f"Regex error: {pattern} -> {e}", file=sys.stderr)
+            return 1
+
+    # Start tracing, run the script, then stop
+    tracer: Tracer = Tracer(root, ignore_patterns=ignore_patterns)
+    tracer.start()
+    try:
+        runpy.run_path(target, run_name="__main__")
+    finally:
+        tracer.stop()
+
+    data: TracerData = tracer.get_trace_data()
+
+    # Save json
+    if args.json:
+        with open(args.json, "w", encoding="utf-8") as f:
+            json.dump(asdict(data), f, indent=4)
+
+    # Display the analysis
+    if args.top is not None:
+        tracer.show_results(args.top)
+    else:
+        tracer.show_results(None)
+
+    # Export as csv
+    if args.csv:
+        with open(args.csv, "w", newline="", encoding="utf-8") as f:
+            writer: csv.DictWriter = csv.DictWriter(f, fieldnames=["function", "total_time", "calls", "avg_time"])
+            writer.writeheader()
+            for fn in data.functions:
+                writer.writerow({
+                    "function":   fn.name,
+                    "total_time": fn.total_time,
+                    "calls":      fn.call_count,
+                    "avg_time":   fn.avg_time,
+                })
+
+    # Generare a report as html
+    if args.html:
+        generate_html_report(data, args.html)
+        print(f"HTML report generated: {os.path.abspath(args.html)}")
+
+    comparison_result: Optional[ComparisonData] = None
+
+    # Compare jsons
+    if args.compare:
+        if not os.path.exists(args.compare):
+            print(f"Compare file not found: {args.compare}", file=sys.stderr)
+            return 1
+
+        with open(args.compare, "r", encoding="utf-8") as f:
+            old_data: TracerData = TracerData.from_dict(json.load(f))
+
+        comparison_result = compare_traces(old_data, data, threshold=args.threshold, show_only_regressions=args.only_regressions)
+
+        if args.fail_on_regression and comparison_result.has_regression:
+            print(
+                f"Build failed: performance regression above {args.threshold:.2f}% detected.",
+                file=sys.stderr,
+            )
+            return 2
+        
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

oracletrace-2.0.2/oracletrace/compare.py

@@ -0,0 +1,80 @@
+from .tracer import TracerData, FunctionData
+from rich import print
+from typing import Any, Dict, List, Set, Optional
+from dataclasses import dataclass
+
+@dataclass
+class RegressionData:
+    name: str
+    old_time: float
+    new_time: float
+    percent: float
+
+@dataclass
+class ComparisonData:
+    regressions: List[RegressionData]
+    has_regression: bool
+
+def compare_traces(
+    old_data: TracerData,
+    new_data: TracerData,
+    threshold: float = 5.0,
+    show_only_regressions: bool = False
+) -> ComparisonData:
+    old_funcs: Dict[str, FunctionData] = {f.name: f for f in old_data.functions}
+    new_funcs: Dict[str, FunctionData] = {f.name: f for f in new_data.functions}
+
+    regressions: List[RegressionData] = []
+
+    print("\n[bold cyan]Comparison Results:[/]\n")
+
+    all_functions: Set[str] = set(old_funcs) | set(new_funcs)
+
+    for name in sorted(all_functions):
+        old: Optional[FunctionData] = old_funcs.get(name)
+        new: Optional[FunctionData] = new_funcs.get(name)
+
+        if not old:
+            print(f"[green]+ {name} (new function)[/]")
+            continue
+
+        if not new:
+            print(f"[red]- {name} (removed)[/]")
+            continue
+
+        old_time: float = old.total_time
+        new_time: float = new.total_time
+
+        if old_time == 0:
+            if new_time == 0:
+                print(f"{name} [yellow](no signal)[/]")
+                continue
+            print(f"{name} [yellow](no baseline)[/]")
+            continue
+
+        diff: float = new_time - old_time
+        percent: float = (diff / old_time) * 100
+
+        color: str = "red" if percent > threshold else "green" if percent < -threshold else "yellow"
+
+        print(
+            f"{name}\n"
+            f"    total_time: {old_time:.4f}s → {new_time:.4f}s "
+            f"[{color}]({percent:+.2f}%)[/]\n"
+        ) if not show_only_regressions or percent > threshold else ...
+        
+        
+        if percent > threshold:
+            regressions.append(
+                RegressionData(
+                        name = name,
+                        new_time = new_time,
+                        old_time = old_time,
+                        percent = percent
+                    )
+            )
+
+    return ComparisonData(
+        regressions = regressions,
+        has_regression = len(regressions) > 0
+    )

oracletrace-2.0.2/oracletrace/reporters/__init__.py

@@ -0,0 +1,3 @@
+from .html import generate_html_report
+
+__all__ = ["generate_html_report"]