flamegraph-textual 0.1.0__tar.gz

flamegraph_textual-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.3
+Name: flamegraph-textual
+Version: 0.1.0
+Summary: Terminal flamegraph renderer built for Textual
+License: GPLv3
+Author: laixintao
+Author-email: laixintaoo@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: Other/Proprietary 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
+Requires-Dist: iteround (>=1.0.4,<2.0.0)
+Requires-Dist: protobuf (>=4.25,<5.0)
+Requires-Dist: rich (>=13.6.0,<14.0.0)
+Requires-Dist: textual (>=0.37.1,<0.38.0)
+Requires-Dist: typing-extensions (>=4.7.1,<5.0.0)
+Description-Content-Type: text/markdown
+
+# flamegraph-textual
+
+`flamegraph-textual` is an interactive flamegraph component for
+[Textual](https://github.com/Textualize/textual).
+
+![](./docs/flamegraph-textual.png)
+
+It is the rendering library extracted from
+[flameshow](https://github.com/laixintao/flameshow). Use it when you want to
+embed a terminal flamegraph inside your own Textual app instead of launching a
+standalone viewer.
+
+## Install
+
+```shell
+pip install flamegraph-textual
+```
+
+## What It Does
+
+- Renders flamegraphs as a Textual widget
+- Parses profile input for you
+- Supports keyboard and mouse navigation
+- Supports multiple sample types when present in the profile
+- Works with bundled demo data or your own files
+
+## Quick Start
+
+`FlameGraphView` is the main entrypoint. Pass it raw profile data and a
+filename. The library parses the content internally.
+
+```python
+from pathlib import Path
+
+from textual.app import App, ComposeResult
+
+from flamegraph_textual import FlameGraphView
+
+
+class Demo(App):
+    def compose(self) -> ComposeResult:
+        profile_bytes = Path("profile.out").read_bytes()
+        yield FlameGraphView(profile_bytes, filename="profile.out")
+
+
+Demo().run()
+```
+
+For stackcollapse text input, passing `str` also works:
+
+```python
+from pathlib import Path
+
+from flamegraph_textual import FlameGraphView
+
+profile_text = Path("stacks.txt").read_text(encoding="utf-8")
+widget = FlameGraphView(profile_text, filename="stacks.txt")
+```
+
+## Supported Input Formats
+
+- pprof protobuf profiles
+- stackcollapse text
+
+The parser selection is automatic through:
+[parse](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/parsers/__init__.py)
+
+## Try It Immediately
+
+This repo includes sample profiles under:
+
+- [tests/pprof_data](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/tests/pprof_data)
+- [tests/stackcollapse_data](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/tests/stackcollapse_data)
+
+Run the bundled examples with no setup:
+
+```shell
+python examples/pprof_binary.py
+python examples/pprof_binary.py --sample goroutine
+python examples/pprof_binary.py --sample heap
+
+python examples/stackcollapse_text.py
+python examples/stackcollapse_text.py --sample simple
+python examples/stackcollapse_text.py --sample perf
+```
+
+You can still pass your own file path:
+
+```shell
+python examples/pprof_binary.py /path/to/profile.out
+python examples/stackcollapse_text.py /path/to/stacks.txt
+```
+
+## Main API
+
+Most users only need:
+
+- [FlameGraphView](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/view.py)
+- [parse](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/parsers/__init__.py)
+
+Other exports are available if you want lower-level control:
+
+- `FlameGraph`
+- `FlameGraphScroll`
+- `Frame`
+- `Profile`
+- `SampleType`
+
+See:
+[__init__.py](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/__init__.py)
+
+## Controls
+
+Inside the widget:
+
+- `j` / `k` / `h` / `l` or arrow keys move selection
+- `Enter` zooms in
+- `Esc` zooms out
+- `Tab` switches sample type
+- `i` opens the detail screen when mounted inside a Textual app
+- Mouse hover updates frame details
+- Mouse click zooms into a frame
+
+## Regenerate Protobuf Bindings
+
+The canonical pprof schema lives in:
+[profile.proto](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/proto/profile.proto)
+
+The generated Python module lives in:
+[profile_pb2.py](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/parsers/profile_pb2.py)
+
+Regenerate it with:
+
+```shell
+poetry add --group dev grpcio-tools
+poetry run python -m grpc_tools.protoc \
+  -I proto \
+  --python_out=flamegraph_textual/parsers \
+  proto/profile.proto
+```
+
+## Development
+
+Run tests with:
+
+```shell
+pytest -q
+```
+

flamegraph_textual-0.1.0/README.md

@@ -0,0 +1,148 @@
+# flamegraph-textual
+
+`flamegraph-textual` is an interactive flamegraph component for
+[Textual](https://github.com/Textualize/textual).
+
+![](./docs/flamegraph-textual.png)
+
+It is the rendering library extracted from
+[flameshow](https://github.com/laixintao/flameshow). Use it when you want to
+embed a terminal flamegraph inside your own Textual app instead of launching a
+standalone viewer.
+
+## Install
+
+```shell
+pip install flamegraph-textual
+```
+
+## What It Does
+
+- Renders flamegraphs as a Textual widget
+- Parses profile input for you
+- Supports keyboard and mouse navigation
+- Supports multiple sample types when present in the profile
+- Works with bundled demo data or your own files
+
+## Quick Start
+
+`FlameGraphView` is the main entrypoint. Pass it raw profile data and a
+filename. The library parses the content internally.
+
+```python
+from pathlib import Path
+
+from textual.app import App, ComposeResult
+
+from flamegraph_textual import FlameGraphView
+
+
+class Demo(App):
+    def compose(self) -> ComposeResult:
+        profile_bytes = Path("profile.out").read_bytes()
+        yield FlameGraphView(profile_bytes, filename="profile.out")
+
+
+Demo().run()
+```
+
+For stackcollapse text input, passing `str` also works:
+
+```python
+from pathlib import Path
+
+from flamegraph_textual import FlameGraphView
+
+profile_text = Path("stacks.txt").read_text(encoding="utf-8")
+widget = FlameGraphView(profile_text, filename="stacks.txt")
+```
+
+## Supported Input Formats
+
+- pprof protobuf profiles
+- stackcollapse text
+
+The parser selection is automatic through:
+[parse](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/parsers/__init__.py)
+
+## Try It Immediately
+
+This repo includes sample profiles under:
+
+- [tests/pprof_data](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/tests/pprof_data)
+- [tests/stackcollapse_data](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/tests/stackcollapse_data)
+
+Run the bundled examples with no setup:
+
+```shell
+python examples/pprof_binary.py
+python examples/pprof_binary.py --sample goroutine
+python examples/pprof_binary.py --sample heap
+
+python examples/stackcollapse_text.py
+python examples/stackcollapse_text.py --sample simple
+python examples/stackcollapse_text.py --sample perf
+```
+
+You can still pass your own file path:
+
+```shell
+python examples/pprof_binary.py /path/to/profile.out
+python examples/stackcollapse_text.py /path/to/stacks.txt
+```
+
+## Main API
+
+Most users only need:
+
+- [FlameGraphView](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/view.py)
+- [parse](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/parsers/__init__.py)
+
+Other exports are available if you want lower-level control:
+
+- `FlameGraph`
+- `FlameGraphScroll`
+- `Frame`
+- `Profile`
+- `SampleType`
+
+See:
+[__init__.py](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/__init__.py)
+
+## Controls
+
+Inside the widget:
+
+- `j` / `k` / `h` / `l` or arrow keys move selection
+- `Enter` zooms in
+- `Esc` zooms out
+- `Tab` switches sample type
+- `i` opens the detail screen when mounted inside a Textual app
+- Mouse hover updates frame details
+- Mouse click zooms into a frame
+
+## Regenerate Protobuf Bindings
+
+The canonical pprof schema lives in:
+[profile.proto](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/proto/profile.proto)
+
+The generated Python module lives in:
+[profile_pb2.py](/Users/xintao.lai/Programs/flameshow-all/flamegraph-textual/flamegraph_textual/parsers/profile_pb2.py)
+
+Regenerate it with:
+
+```shell
+poetry add --group dev grpcio-tools
+poetry run python -m grpc_tools.protoc \
+  -I proto \
+  --python_out=flamegraph_textual/parsers \
+  proto/profile.proto
+```
+
+## Development
+
+Run tests with:
+
+```shell
+pytest -q
+```

flamegraph_textual-0.1.0/flamegraph_textual/__init__.py

@@ -0,0 +1,25 @@
+__version__ = "0.1.0"
+
+from flamegraph_textual.models import Frame, Profile, SampleType
+from flamegraph_textual.parsers import parse
+from flamegraph_textual.render.app import FlameGraphScroll, FlameshowApp
+from flamegraph_textual.render.flamegraph import FlameGraph, FrameMap, add_array
+from flamegraph_textual.view import FlameGraphView
+
+
+class FlameGraphApp(FlameshowApp):
+    """Convenience alias for embedding a full flamegraph app."""
+
+
+__all__ = [
+    "FlameGraph",
+    "FlameGraphApp",
+    "FlameGraphScroll",
+    "FlameGraphView",
+    "Frame",
+    "FrameMap",
+    "Profile",
+    "SampleType",
+    "add_array",
+    "parse",
+]

flamegraph_textual-0.1.0/flamegraph_textual/colors.py

@@ -0,0 +1,67 @@
+import random
+import logging
+
+from textual.color import Color
+
+logger = logging.getLogger(__name__)
+
+
+class ColorPlatteBase:
+    def __init__(self):
+        self.assigned_color = {}
+
+    def get_color(self, key):
+        if key not in self.assigned_color:
+            self.assigned_color[key] = self.assign_color(key)
+        return self.assigned_color[key]
+
+    def assign_color(self, key):
+        raise NotImplementedError
+
+
+class LinaerColorPlatte(ColorPlatteBase):
+    def __init__(
+        self,
+        start_color=Color.parse("#CD0000"),
+        end_color=Color.parse("#FFE637"),
+    ) -> None:
+        super().__init__()
+        self.assigned_color = {}
+        self.start_color = start_color
+        self.end_color = end_color
+        self.index = 0
+        self.platte = self.generate_platte()
+
+    def assign_color(self, key):
+        color = self.platte[self.index]
+        self.index += 1
+        if self.index == len(self.platte):
+            self.index = 0
+
+        logger.debug("assign color=%s", color)
+        return color
+
+    def generate_platte(self):
+        color_platte = []
+        for factor in range(0, 100, 5):
+            color_platte.append(
+                self.start_color.blend(self.end_color, factor / 100)
+            )
+        return color_platte
+
+
+class FlameGraphRandomColorPlatte(ColorPlatteBase):
+    def __init__(self) -> None:
+        super().__init__()
+        self.assigned_color = {}
+
+    def assign_color(self, *args):
+        return Color(
+            205 + int(50 * random.random()),
+            0 + int(230 * random.random()),
+            0 + int(55 * random.random()),
+        )
+
+
+flamegraph_random_color_platte = FlameGraphRandomColorPlatte()
+linaer_color_platte = LinaerColorPlatte()

flamegraph_textual-0.1.0/flamegraph_textual/const.py

@@ -0,0 +1,4 @@
+VIEW_INFO_COLOR = "#ffffff"
+VIEW_INFO_OTHER_COLOR = "#8884FF"
+SELECTED_PARENTS_BG_COLOR_BLEND_TO = "#8b0000"
+SELECTED_PARENTS_BG_COLOR_BLEND_FACTOR = 0.5

flamegraph_textual-0.1.0/flamegraph_textual/exceptions.py

@@ -0,0 +1,14 @@
+class FlamegraphTextualException(Exception):
+    """Base exception for flamegraph_textual."""
+
+
+class ProfileParseException(FlamegraphTextualException):
+    """Can not parse the profile."""
+
+
+class UsageError(FlamegraphTextualException):
+    """Usage Error."""
+
+
+class RenderException(FlamegraphTextualException):
+    """Error during flamegraph render."""

flamegraph_textual-0.1.0/flamegraph_textual/models.py

@@ -0,0 +1,204 @@
+from dataclasses import dataclass, field
+import datetime
+import logging
+import time
+from typing import Dict, List, Set
+from typing_extensions import Self
+
+from rich.style import Style
+from rich.text import Text
+
+from flamegraph_textual.utils import sizeof
+
+from flamegraph_textual.runtime import r
+
+
+logger = logging.getLogger(__name__)
+
+
+class Frame:
+    def __init__(
+        self, name, _id, children=None, parent=None, values=None, root=None
+    ) -> None:
+        self.name = name
+        self._id = _id
+        if children:
+            self.children = children
+        else:
+            self.children = []
+        self.parent = parent
+        if not values:
+            self.values = []
+        else:
+            self.values = values
+
+        self.root = root
+
+    def pile_up(self, childstack: Self):
+        childstack.parent = self
+
+        for exist_child in self.children:
+            # added to exist, no need to create one
+            if exist_child.name == childstack.name:
+                # some cases, childstack.children total value not equal to
+                # childstack.values
+                # so, we need to add values of "parent" instead of add values
+                # by every child
+                exist_child.values = list(
+                    map(sum, zip(exist_child.values, childstack.values))
+                )
+
+                for new_child in childstack.children:
+                    exist_child.pile_up(new_child)
+                return
+
+        self.children.append(childstack)
+
+    def __eq__(self, other):
+        if isinstance(other, Frame):
+            return self._id == other._id
+        return False
+
+    @property
+    def display_color(self):
+        return r.get_color(self.color_key)
+
+    def humanize(self, sample_unit, value):
+        display_value = value
+        if sample_unit == "bytes":
+            display_value = sizeof(value)
+
+        return display_value
+
+    def __repr__(self) -> str:
+        return f"<Frame #{self._id} {self.name}>"
+
+    def render_detail(self, sample_index: int, sample_unit: str):
+        """
+        render stacked information
+        """
+        detail = []
+        frame = self
+        while frame:
+            lines = self.render_one_frame_detail(
+                frame, sample_index, sample_unit
+            )
+            for line in lines:
+                detail.append(
+                    Text.assemble(
+                        (" ", Style(bgcolor=frame.display_color.rich_color)),
+                        " ",
+                        line,
+                    )
+                )
+            frame = frame.parent
+
+        return Text.assemble(*detail)
+
+    def render_one_frame_detail(
+        self, frame, sample_index: int, sample_unit: str
+    ):
+        raise NotImplementedError
+
+    @property
+    def title(self) -> Text:
+        """Full name which will be displayed in the frame detail panel"""
+        return Text(self.name)
+
+    @property
+    def color_key(self):
+        """Same key will get the same color"""
+        return self.name
+
+    @property
+    def display_name(self):
+        """The name display on the flamegraph"""
+        return self.name
+
+
+@dataclass
+class SampleType:
+    sample_type: str = ""
+    sample_unit: str = ""
+
+
+@dataclass
+class Profile:
+    # required
+    filename: str
+    root_stack: Frame
+    highest_lines: int
+    # total samples is one top most sample, it's a list that contains all
+    # its parents all the way up
+    total_sample: int
+    sample_types: List[SampleType]
+    # int id mapping to Frame
+    id_store: Dict[int, Frame]
+
+    # optional
+    default_sample_type_index: int = -1
+    period_type: SampleType | None = None
+    period: int = 0
+    created_at: datetime.datetime | None = None
+
+    # init by post_init
+    lines: List = field(init=False)
+
+    frameid_to_lineno: Dict[int, int] = field(init=False)
+
+    # Frame grouped by same name
+    name_aggr: Dict[str, List[Frame]] = field(init=False)
+
+    def __post_init__(self):
+        """
+        init_lines must be called before render
+        """
+        t1 = time.time()
+        logger.info("start to create lines...")
+
+        root = self.root_stack
+
+        lines = [
+            [root],
+        ]
+        frameid_to_lineno = {0: 0}
+        current = root.children
+        line_no = 1
+
+        while len(current) > 0:
+            line = []
+            next_line = []
+
+            for child in current:
+                line.append(child)
+                frameid_to_lineno[child._id] = line_no
+                next_line.extend(child.children)
+
+            lines.append(line)
+            line_no += 1
+            current = next_line
+
+        t2 = time.time()
+        logger.info("create lines done, took %.2f seconds", t2 - t1)
+        self.lines = lines
+        self.frameid_to_lineno = frameid_to_lineno
+
+        self.name_aggr = self.get_name_aggr(self.root_stack)
+
+    def get_name_aggr(
+        self, start_frame: Frame, names: Set[str] | None = None
+    ) -> Dict[str, List[Frame]]:
+        name = start_frame.name
+
+        result = {}
+        if names is None:
+            names = set()
+        if name not in names:
+            result[name] = [start_frame]
+
+        for child in start_frame.children:
+            name_aggr = self.get_name_aggr(child, names | set([name]))
+            for key, value in name_aggr.items():
+                result.setdefault(key, []).extend(value)
+
+        return result

flamegraph_textual-0.1.0/flamegraph_textual/parsers/__init__.py

@@ -0,0 +1,25 @@
+import logging
+
+from flamegraph_textual.exceptions import ProfileParseException
+from flamegraph_textual.parsers.pprof_parser import ProfileParser as PprofParser
+from flamegraph_textual.parsers.stackcollapse_parser import StackCollapseParser
+
+logger = logging.getLogger(__name__)
+
+
+ALL_PARSERS = [PprofParser, StackCollapseParser]
+
+
+def choose_parser(content: bytes):
+    for p in ALL_PARSERS:
+        if p.validate(content):
+            return p
+    raise ProfileParseException("Can not match any parser")
+
+
+def parse(filecontent: bytes, filename):
+    parser_cls = choose_parser(filecontent)
+    logger.info("Using %s...", parser_cls)
+    parser = parser_cls(filename)
+    profile = parser.parse(filecontent)
+    return profile