runmap 0.1.0__tar.gz

runmap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

runmap-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+.venv/
+venv/
+*.whl

runmap-0.1.0/INSTRUCTIONS.md

@@ -0,0 +1,160 @@
+# Project Instructions
+
+General rules for code, markdown, and documentation written by AI in this project.
+
+---
+
+## Code
+
+### Comments
+
+- Use single-line comments only, unless a comment is 2-3+ lines — then use a docstring/block comment
+- Write comments only when the code is not obvious to someone with basic knowledge of the language
+- If a block needs explaining — explain it briefly; don't over-describe
+
+### Naming & style
+
+- No self-praising names — no `Advanced`, `Ultimate`, `Professional`, `Expert`, `Smart`, `Intelligent`, etc. in class, function, variable, or constant names
+- No "Modern", "intuitive", "polished", "seamless" in package names, descriptions, or identifiers unless there's a specific reason (e.g. marketing)
+- Use abbreviations and short words where it reads naturally
+- Use standard libraries, well-known packages, tools, and frameworks — don't reinvent the wheel unless there's no other way
+
+### General
+
+- No unused imports, dependencies, or dead code
+- No overly technical terms when simpler ones work
+- Code should be readable to other developers without a tour; middle-level language features are fine when appropriate
+- Don't write explanations about what code does outside code blocks
+
+---
+
+## Markdown files
+
+Follow standard markdown linting rules (markdownlint):
+
+- Headings increment by one level at a time (MD001)
+- Consistent heading style (MD003)
+- Consistent unordered list style (MD004, MD007)
+- No trailing spaces (MD009), no hard tabs (MD010)
+- No multiple consecutive blank lines (MD012)
+- No reversed link syntax (MD011), no bare URLs (MD034), no empty links (MD042)
+- Fenced code blocks surrounded by blank lines (MD031) and have a language specified (MD040)
+- Lists surrounded by blank lines (MD032)
+- No inline HTML (MD033) unless necessary
+- Single top-level heading per file (MD025)
+- No trailing punctuation in headings (MD026)
+- Images must have alt text (MD045)
+- Files end with a single newline (MD047)
+- Tables surrounded by blank lines (MD058), consistent pipe style (MD055), correct column count (MD056)
+- Proper capitalization of proper names (MD044)
+
+The file must be readable and make sense to humans, not just pass a linter.
+
+---
+
+## README and documentation
+
+### Main rule
+
+Don't praise the project, code, or yourself. Describe what it does and how to use it.
+
+### Tone
+
+- Natural, conversational — like explaining to a developer, not writing a spec
+- Short sentences, no walls of text
+- No emojis, no excessive exclamation marks
+- No "just" or "simply" before instructions
+- No redundant phrases like "This project is built with..."
+
+### Avoid these words and phrases
+
+`Modern`, `intuitive`, `polished`, `seamless`, `instant`, `robust`, `scalable`, `high performance`,
+`lightweight` (unless in a general factual context like "LuminFM is a fast, lightweight file manager"),
+`easy to use`, `user-friendly`, `powerful features`, `out of the box`, `state of the art`,
+`cutting edge`, `industry standard`, `next-generation`, `best-in-class`, `world-class`,
+`game-changer`, `revolutionary`, `innovative`, `versatile`, `flexible`, `customizable`,
+`seamless experience`, `that makes your workflow easier`, `that enhances productivity`,
+`that simplifies complex tasks`, `that redefines excellence` — and similar marketing copy
+
+### Structure
+
+1. Title with badges (release, license, versions, platforms, latest commit, etc.)
+2. One-sentence tagline
+3. One paragraph: what it is and why you'd use it
+4. `## Getting Started` — download link and setup commands
+5. `## Features` — main features in plain language (see below)
+6. `## Requirements` — if needed; link to requirements file if one exists
+7. `## License` — link to LICENSE file
+
+Don't add project structure, implementation details, or contribution guidelines unless asked. If developer info is needed, add it separately under `## Build` or `## Contributing`.
+
+### Headings
+
+- Use `##` for main sections
+- Avoid `###` unless a critical subsection is needed
+- Keep total heading count low (5–7)
+
+### Features section
+
+Write features as a short list with this pattern:
+
+```markdown
+## Features
+
+- Feature name: Short description of what it does.
+```
+
+Don't state obvious things (e.g. "You can open files" in a file manager). Write only features that
+are notable or non-obvious. Keep descriptions short — don't explain why a feature is good, just
+what it does.
+
+Bad:
+
+```markdown
+- Tabbed browsing: Work with multiple folders at once without opening new windows
+- Themes: Light and dark modes that persist across sessions
+```
+
+Good:
+
+```markdown
+- Tabbed browsing: Work with multiple folders at once
+- Themes: Light and dark themes support
+```
+
+### Code blocks
+
+- Always specify the language
+- Keep examples short and runnable
+- Show only what's necessary
+
+### Links
+
+Use `[Release Downloads](url)` format. You can link to releases, the LICENSE file, a website if
+there is one, etc.
+
+---
+
+## Typography
+
+Use standard keyboard characters where possible. Avoid special Unicode symbols unless there's
+no alternative.
+
+| Instead of | Use |
+|------------|-----|
+| `—` (em dash) | `-` (preffered) or `--` |
+| `–` (en dash) | `-` |
+| `«»` or `""` (curly/guillemet quotes) | `"` |
+| `''` (curly single quotes) | `'` |
+| `→`, `←`, `↑`, `↓` (arrows) | `->`, `<-`, `^`, or plain words |
+| `…` (ellipsis) | `...` |
+| `×` (multiplication sign) | `x` |
+| `•` (bullet) | `-` in markdown lists |
+
+This applies to code, markdown, docs, and comments. Exception: if a symbol is part of an
+actual string value, a UI label, or has semantic meaning in context — use whatever is correct.
+
+## Dots
+
+- Do not add periods at the end of docstrings or comments unless required by the language, tooling, or style guide used by the project
+- In this project, comments and docstrings are typically written without trailing periods

runmap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NazarHK
+
+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.

runmap-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: runmap
+Version: 0.1.0
+Summary: Python call tree profiler for the terminal
+Project-URL: Homepage, https://github.com/nazarhktwitch/runmap
+Project-URL: Repository, https://github.com/nazarhktwitch/runmap
+Project-URL: Issues, https://github.com/nazarhktwitch/runmap/issues
+Author: Nazar Burlai
+License-Expression: MIT
+License-File: LICENSE
+Keywords: call-tree,cli,performance,profiler,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# runmap
+
+Visualize Python function call trees with timing in the terminal
+
+Run any script through runmap and see a tree of every function call, how long
+each took, and where the hot spots are
+
+## Getting Started
+
+```bash
+pip install runmap
+```
+
+```bash
+python -m runmap script.py
+python -m runmap script.py --min-ms 5 --depth 3
+python -m runmap script.py --out run.trace
+python -m runmap diff before.trace after.trace
+```
+
+## Features
+
+- Call tree view: shows the full function call hierarchy with per-node timing.
+- Time bars: proportional block bars next to each node for quick visual scanning.
+- Hot markers: flags functions whose self time exceeds 20% of total runtime.
+- Depth and threshold filters: `--depth` and `--min-ms` trim noise from large trees.
+- Trace files: `--out` saves a `.trace` JSON file for later comparison.
+- Diff mode: `runmap diff A.trace B.trace` shows a delta table (faster/slower/new).
+- Sampling mode: `--sample` uses signal-based 100 Hz sampling instead of `sys.settrace` (Unix only).
+
+## Requirements
+
+- Python 3.10+
+- [rich](https://github.com/Textualize/rich) >= 13.0
+
+## License
+
+[MIT](LICENSE)

runmap-0.1.0/README.md

@@ -0,0 +1,38 @@
+# runmap
+
+Visualize Python function call trees with timing in the terminal
+
+Run any script through runmap and see a tree of every function call, how long
+each took, and where the hot spots are
+
+## Getting Started
+
+```bash
+pip install runmap
+```
+
+```bash
+python -m runmap script.py
+python -m runmap script.py --min-ms 5 --depth 3
+python -m runmap script.py --out run.trace
+python -m runmap diff before.trace after.trace
+```
+
+## Features
+
+- Call tree view: shows the full function call hierarchy with per-node timing.
+- Time bars: proportional block bars next to each node for quick visual scanning.
+- Hot markers: flags functions whose self time exceeds 20% of total runtime.
+- Depth and threshold filters: `--depth` and `--min-ms` trim noise from large trees.
+- Trace files: `--out` saves a `.trace` JSON file for later comparison.
+- Diff mode: `runmap diff A.trace B.trace` shows a delta table (faster/slower/new).
+- Sampling mode: `--sample` uses signal-based 100 Hz sampling instead of `sys.settrace` (Unix only).
+
+## Requirements
+
+- Python 3.10+
+- [rich](https://github.com/Textualize/rich) >= 13.0
+
+## License
+
+[MIT](LICENSE)

runmap-0.1.0/example.py

@@ -0,0 +1,24 @@
+import time
+
+def load_data():
+    time.sleep(0.01)
+    return list(range(100))
+
+def validate(data):
+    time.sleep(0.003)
+    return [x for x in data if x % 2 == 0]
+
+def process(data):
+    time.sleep(0.005)
+    return [x * 2 for x in data]
+
+def save(data):
+    time.sleep(0.004)
+
+def main():
+    data = load_data()
+    clean = validate(data)
+    result = process(clean)
+    save(result)
+
+main()

runmap-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runmap"
+version = "0.1.0"
+description = "Python call tree profiler for the terminal"
+requires-python = ">=3.10"
+dependencies = ["rich>=13.0"]
+readme = "README.md"
+license = "MIT"
+keywords = ["profiler", "call-tree", "tracing", "performance", "cli"]
+authors = [
+    { name = "Nazar Burlai" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/nazarhktwitch/runmap"
+Repository = "https://github.com/nazarhktwitch/runmap"
+Issues = "https://github.com/nazarhktwitch/runmap/issues"
+
+[project.scripts]
+runmap = "runmap.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

runmap-0.1.0/runmap/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

runmap-0.1.0/runmap/__main__.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import argparse
+import runpy
+import sys
+import traceback as tb
+from pathlib import Path
+
+from runmap import __version__
+from runmap import exporter, diff as diff_mod
+from runmap.tracer import Tracer
+from runmap.tree import build
+from runmap.renderer import render
+
+
+def _run_script(script: str, args: list[str]) -> None:
+    """Execute target script in its own namespace, replacing sys.argv"""
+    script_path = Path(script).resolve()
+    if not script_path.exists():
+        sys.exit(f"runmap: file not found: {script}")
+
+    sys.argv = [str(script_path)] + args
+    sys.path.insert(0, str(script_path.parent))
+    runpy.run_path(str(script_path), run_name="__main__")
+
+
+def _build_run_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="runmap",
+        description="Visualize Python function call trees with timing",
+    )
+    p.add_argument("--version", action="version", version=f"runmap {__version__}")
+    p.add_argument("--no-color", action="store_true", help="Disable rich styling")
+    p.add_argument("--depth", type=int, default=None, metavar="INT",
+                   help="Max tree depth (default: unlimited)")
+    p.add_argument("--min-ms", type=float, default=0.0, metavar="MS",
+                   help="Hide nodes below this threshold in ms (default: 0)")
+    p.add_argument("--sample", action="store_true",
+                   help="Use signal-based sampler instead of sys.settrace (Unix only)")
+    p.add_argument("--out", default=None, metavar="FILE",
+                   help="Save .trace JSON to file")
+    p.add_argument("script", help="Path to script to profile")
+    p.add_argument("script_args", nargs=argparse.REMAINDER,
+                   help="Arguments passed to the script")
+    return p
+
+
+def _build_diff_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="runmap diff",
+        description="Compare two .trace files",
+    )
+    p.add_argument("a", metavar="A.trace")
+    p.add_argument("b", metavar="B.trace")
+    p.add_argument("--min-delta-ms", type=float, default=0.0, metavar="MS",
+                   help="Hide entries with |delta| below this value (default: 0)")
+    p.add_argument("--no-color", action="store_true", help="Disable rich styling")
+    return p
+
+
+def _cmd_run(args: argparse.Namespace) -> None:
+    if args.sample:
+        if sys.platform == "win32":
+            sys.exit(
+                "runmap: --sample is not available on Windows. "
+                "signal.setitimer is Unix-only. Use the default tracer mode."
+            )
+        from runmap.sampler import Sampler
+        sampler = Sampler()
+        sampler.start()
+        exc_info = None
+        try:
+            _run_script(args.script, args.script_args)
+        except SystemExit:
+            raise
+        except Exception:
+            exc_info = sys.exc_info()
+        finally:
+            sampler.stop()
+        records = sampler.to_records()
+    else:
+        tracer = Tracer()
+        tracer.start()
+        exc_info = None
+        try:
+            _run_script(args.script, args.script_args)
+        except SystemExit:
+            raise
+        except Exception:
+            exc_info = sys.exc_info()
+        finally:
+            tracer.stop()
+        records = tracer.records
+
+    root = build(records)
+    render(
+        root,
+        depth_limit=args.depth,
+        min_ms=args.min_ms,
+        no_color=args.no_color,
+    )
+
+    if args.out:
+        exporter.save(records, args.out)
+
+    if exc_info is not None:
+        # Re-raise with original traceback after showing the partial tree
+        raise exc_info[1].with_traceback(exc_info[2])
+
+
+def _cmd_diff(args: argparse.Namespace) -> None:
+    old_records = exporter.load(args.a)
+    new_records = exporter.load(args.b)
+    results = diff_mod.compare(old_records, new_records)
+    diff_mod.render_diff(results, min_delta_ms=args.min_delta_ms, no_color=args.no_color)
+
+
+def main() -> None:
+    # Ensure stdout uses UTF-8 regardless of the system codepage (e.g. CP1251 on Windows)
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+    argv = sys.argv[1:]
+
+    # Detect diff subcommand before handing to argparse so that a script path
+    # like "example.py" is never mistaken for an invalid subcommand choice
+    if argv and argv[0] == "diff":
+        parser = _build_diff_parser()
+        args = parser.parse_args(argv[1:])
+        _cmd_diff(args)
+        return
+
+    # Handle --version / --help with no script given
+    if not argv or argv == ["--version"]:
+        parser = _build_run_parser()
+        parser.parse_args(argv)  # prints version or help and exits
+        return
+
+    parser = _build_run_parser()
+    args = parser.parse_args(argv)
+    _cmd_run(args)
+
+
+if __name__ == "__main__":
+    main()

runmap-0.1.0/runmap/diff.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import math
+
+from rich.console import Console
+from rich.table import Table
+
+from runmap.models import DiffResult, TraceRecord
+
+
+def _aggregate(records: list[TraceRecord]) -> dict[str, float]:
+    """Sum total_ms per qualname"""
+    totals: dict[str, float] = {}
+    for r in records:
+        ms = (r.end_time - r.start_time) * 1000
+        totals[r.qualname] = totals.get(r.qualname, 0.0) + ms
+    return totals
+
+
+def compare(old_records: list[TraceRecord], new_records: list[TraceRecord]) -> list[DiffResult]:
+    old = _aggregate(old_records)
+    new = _aggregate(new_records)
+
+    all_names = set(old) | set(new)
+    results: list[DiffResult] = []
+
+    for name in all_names:
+        old_ms = old.get(name, 0.0)
+        new_ms = new.get(name, 0.0)
+        delta_ms = new_ms - old_ms
+        if old_ms == 0:
+            delta_pct = math.inf if new_ms > 0 else 0.0
+        else:
+            delta_pct = (delta_ms / old_ms) * 100
+
+        results.append(DiffResult(
+            node_name=name,
+            old_ms=old_ms,
+            new_ms=new_ms,
+            delta_ms=delta_ms,
+            delta_pct=delta_pct,
+        ))
+
+    # Sort by abs delta descending
+    results.sort(key=lambda r: abs(r.delta_ms), reverse=True)
+    return results
+
+
+def render_diff(
+    results: list[DiffResult],
+    min_delta_ms: float = 0.0,
+    no_color: bool = False,
+) -> None:
+    console = Console(highlight=False, no_color=no_color, legacy_windows=False)
+
+    filtered = [r for r in results if abs(r.delta_ms) >= min_delta_ms]
+    if not filtered:
+        console.print("[dim]No differences above threshold.[/dim]")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Function", style="", no_wrap=True)
+    table.add_column("Old (ms)", justify="right")
+    table.add_column("New (ms)", justify="right")
+    table.add_column("Delta (ms)", justify="right")
+
+    for r in filtered:
+        pct = r.delta_pct
+        old_str = f"{r.old_ms:.1f}" if r.old_ms else "-"
+        new_str = f"{r.new_ms:.1f}" if r.new_ms else "-"
+
+        if math.isinf(pct) or abs(pct) < 5:
+            delta_str = f"{r.delta_ms:+.1f}"
+            style = "dim"
+        elif r.delta_ms < 0:
+            delta_str = f"{r.delta_ms:+.1f} ({pct:+.1f}%)"
+            style = "green"
+        else:
+            delta_str = f"{r.delta_ms:+.1f} ({pct:+.1f}%)"
+            style = "red"
+
+        table.add_row(r.node_name, old_str, new_str, f"[{style}]{delta_str}[/{style}]")
+
+    console.print(table)

runmap-0.1.0/runmap/exporter.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from runmap.models import TraceRecord
+
+
+def save(records: list[TraceRecord], path: str | Path) -> None:
+    data = [
+        {
+            "qualname": r.qualname,
+            "filename": r.filename,
+            "lineno": r.lineno,
+            "start_time": r.start_time,
+            "end_time": r.end_time,
+            "depth": r.depth,
+            "parent_name": r.parent_name,
+        }
+        for r in records
+    ]
+    Path(path).write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def load(path: str | Path) -> list[TraceRecord]:
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(
+            f"Trace file not found: {p}\n"
+            "Generate one with: python -m runmap script.py --out output.trace"
+        )
+    data = json.loads(p.read_text(encoding="utf-8"))
+    return [
+        TraceRecord(
+            qualname=d["qualname"],
+            filename=d["filename"],
+            lineno=d["lineno"],
+            start_time=d["start_time"],
+            end_time=d["end_time"],
+            depth=d["depth"],
+            parent_name=d["parent_name"],
+        )
+        for d in data
+    ]