mithra-flow 1.0__py3-none-any.whl

mithra_flow/__init__.py

@@ -0,0 +1,5 @@
+from .decorator import MFlowResult, mflow, span, trace
+from .models import TraceNode
+from .version import __version__
+
+__all__ = ["MFlowResult", "TraceNode", "__version__", "mflow", "span", "trace"]

mithra_flow/decorator.py

@@ -0,0 +1,639 @@
+from __future__ import annotations
+
+import contextvars
+import dis
+import fnmatch
+import functools
+import inspect
+import json
+import os
+import sys
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import FrameType
+from typing import Any, Literal, TypeVar, overload
+
+from rich.console import Console
+from rich.text import Text
+from rich.tree import Tree
+
+from .models import TraceNode
+from .version import __version__
+
+F = TypeVar("F", bound=Callable[..., Any])
+OutputFormat = Literal["terminal", "dict", "json", "mermaid", "none"]
+
+
+@dataclass
+class MFlowResult:
+    value: Any
+    trace: dict[str, Any] | str | None
+
+
+@dataclass
+class _TraceConfig:
+    title: str | None = None
+    include: tuple[str, ...] = ()
+    exclude: tuple[str, ...] = ()
+    enabled: bool = True
+    min_duration_ms: float = 0.0
+    max_depth: int | None = None
+    show_args: bool = False
+    show_return: bool = False
+    show_file: bool = False
+    show_line: bool = False
+    on_error: bool = False
+    output: OutputFormat = "terminal"
+    save_to: str | None = None
+    return_trace: bool = False
+
+
+@dataclass
+class _TraceState:
+    config: _TraceConfig
+    stack: list[TraceNode] = field(default_factory=list)
+    frame_nodes: dict[int, TraceNode] = field(default_factory=dict)
+    root: TraceNode | None = None
+    previous_profile: Callable[[FrameType, str, Any], Any] | None = None
+    had_error: bool = False
+    exported_trace: dict[str, Any] | str | None = None
+
+
+_active_trace: contextvars.ContextVar[_TraceState | None] = contextvars.ContextVar(
+    "mithra_flow_active_trace",
+    default=None,
+)
+
+
+@overload
+def mflow(func: F) -> F:
+    ...
+
+
+@overload
+def mflow(
+    *,
+    name: str | None = None,
+    title: str | None = None,
+    include: Iterable[str] | None = None,
+    exclude: Iterable[str] | None = None,
+    enabled: bool | None = None,
+    min_duration_ms: float = 0.0,
+    max_depth: int | None = None,
+    show_args: bool = False,
+    show_return: bool = False,
+    show_file: bool = False,
+    show_line: bool = False,
+    on_error: bool = False,
+    output: OutputFormat = "terminal",
+    save_to: str | None = None,
+    return_trace: bool = False,
+) -> Callable[[F], F]:
+    ...
+
+
+def mflow(
+    func: F | None = None,
+    *,
+    name: str | None = None,
+    title: str | None = None,
+    include: Iterable[str] | None = None,
+    exclude: Iterable[str] | None = None,
+    enabled: bool | None = None,
+    min_duration_ms: float = 0.0,
+    max_depth: int | None = None,
+    show_args: bool = False,
+    show_return: bool = False,
+    show_file: bool = False,
+    show_line: bool = False,
+    on_error: bool = False,
+    output: OutputFormat = "terminal",
+    save_to: str | None = None,
+    return_trace: bool = False,
+) -> F | Callable[[F], F]:
+    """Trace project calls made while the decorated function executes."""
+
+    config = _make_config(
+        name=name,
+        title=title,
+        include=include,
+        exclude=exclude,
+        enabled=enabled,
+        min_duration_ms=min_duration_ms,
+        max_depth=max_depth,
+        show_args=show_args,
+        show_return=show_return,
+        show_file=show_file,
+        show_line=show_line,
+        on_error=on_error,
+        output=output,
+        save_to=save_to,
+        return_trace=return_trace,
+    )
+
+    def decorate(target: F) -> F:
+        if inspect.iscoroutinefunction(target):
+
+            @functools.wraps(target)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                if not config.enabled:
+                    return await target(*args, **kwargs)
+                state, token = _start_trace(config)
+                try:
+                    value = await target(*args, **kwargs)
+                    _finish_trace(state)
+                    return _return_value(value, state)
+                except Exception as error:
+                    _mark_error(state, error)
+                    _finish_trace(state)
+                    raise
+                finally:
+                    _active_trace.reset(token)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(target)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if not config.enabled:
+                return target(*args, **kwargs)
+            state, token = _start_trace(config)
+            try:
+                value = target(*args, **kwargs)
+                _finish_trace(state)
+                return _return_value(value, state)
+            except Exception as error:
+                _mark_error(state, error)
+                _finish_trace(state)
+                raise
+            finally:
+                _active_trace.reset(token)
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    if func is None:
+        return decorate
+
+    return decorate(func)
+
+
+class trace:
+    def __init__(
+        self,
+        name: str = "manual trace",
+        *,
+        include: Iterable[str] | None = None,
+        exclude: Iterable[str] | None = None,
+        enabled: bool | None = None,
+        min_duration_ms: float = 0.0,
+        max_depth: int | None = None,
+        show_args: bool = False,
+        show_return: bool = False,
+        show_file: bool = False,
+        show_line: bool = False,
+        on_error: bool = False,
+        output: OutputFormat = "terminal",
+        save_to: str | None = None,
+        return_trace: bool = False,
+    ) -> None:
+        self.config = _make_config(
+            name=name,
+            title=name,
+            include=include,
+            exclude=exclude,
+            enabled=enabled,
+            min_duration_ms=min_duration_ms,
+            max_depth=max_depth,
+            show_args=show_args,
+            show_return=show_return,
+            show_file=show_file,
+            show_line=show_line,
+            on_error=on_error,
+            output=output,
+            save_to=save_to,
+            return_trace=return_trace,
+        )
+        self.state: _TraceState | None = None
+        self.token: contextvars.Token[_TraceState | None] | None = None
+        self.result: dict[str, Any] | str | None = None
+
+    def __enter__(self) -> trace:
+        if self.config.enabled:
+            self.state, self.token = _start_trace(self.config, root_name=self.config.title)
+        return self
+
+    def __exit__(self, exc_type: Any, exc: BaseException | None, traceback: Any) -> None:
+        if self.state is None or self.token is None:
+            return
+        if exc is not None:
+            _mark_error(self.state, exc)
+        _finish_trace(self.state)
+        self.result = self.state.exported_trace
+        _active_trace.reset(self.token)
+
+
+class span:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.node: TraceNode | None = None
+
+    def __enter__(self) -> span:
+        state = _active_trace.get()
+        if state is None:
+            return self
+        now = time.perf_counter()
+        self.node = TraceNode(
+            name=f"{self.name}()",
+            filename="<manual>",
+            lineno=0,
+            start=now,
+            is_span=True,
+        )
+        if state.stack:
+            state.stack[-1].children.append(self.node)
+        elif state.root is None:
+            state.root = self.node
+        state.stack.append(self.node)
+        return self
+
+    def __exit__(self, exc_type: Any, exc: BaseException | None, traceback: Any) -> None:
+        state = _active_trace.get()
+        if state is None or self.node is None:
+            return
+        if exc is not None:
+            self.node.exception = f"{type(exc).__name__}: {exc}"
+            state.had_error = True
+        self.node.end = time.perf_counter()
+        if state.stack and state.stack[-1] is self.node:
+            state.stack.pop()
+
+
+def _make_config(
+    *,
+    name: str | None,
+    title: str | None,
+    include: Iterable[str] | None,
+    exclude: Iterable[str] | None,
+    enabled: bool | None,
+    min_duration_ms: float,
+    max_depth: int | None,
+    show_args: bool,
+    show_return: bool,
+    show_file: bool,
+    show_line: bool,
+    on_error: bool,
+    output: OutputFormat,
+    save_to: str | None,
+    return_trace: bool,
+) -> _TraceConfig:
+    env_enabled = os.getenv("MITHRA_FLOW", "1").lower() not in {"0", "false", "no", "off"}
+    return _TraceConfig(
+        title=title or name,
+        include=_normalize_filters(include),
+        exclude=_normalize_filters(exclude),
+        enabled=env_enabled if enabled is None else enabled,
+        min_duration_ms=max(0.0, min_duration_ms),
+        max_depth=max_depth,
+        show_args=show_args,
+        show_return=show_return,
+        show_file=show_file,
+        show_line=show_line,
+        on_error=on_error,
+        output=output,
+        save_to=save_to,
+        return_trace=return_trace,
+    )
+
+
+def _normalize_filters(filters: Iterable[str] | None) -> tuple[str, ...]:
+    return tuple(str(item) for item in filters or () if str(item))
+
+
+def _start_trace(
+    config: _TraceConfig,
+    *,
+    root_name: str | None = None,
+) -> tuple[_TraceState, contextvars.Token[_TraceState | None]]:
+    state = _TraceState(config=config)
+    token = _active_trace.set(state)
+    if root_name is not None:
+        now = time.perf_counter()
+        root = TraceNode(root_name, "<manual>", 0, now, is_span=True)
+        state.root = root
+        state.stack.append(root)
+    _install_profile(state)
+    return state, token
+
+
+def _install_profile(state: _TraceState) -> None:
+    state.previous_profile = sys.getprofile()
+    sys.setprofile(_profile)
+
+
+def _finish_trace(state: _TraceState) -> None:
+    sys.setprofile(state.previous_profile)
+    now = time.perf_counter()
+    while state.stack:
+        node = state.stack.pop()
+        if node.end is None:
+            node.end = now
+    if state.root is None:
+        return
+    state.exported_trace = _export_trace(state)
+    _save_trace(state)
+    if state.config.on_error and not state.had_error:
+        return
+    if state.config.output == "terminal":
+        _print_trace(state.root, state.config)
+
+
+def _return_value(value: Any, state: _TraceState) -> Any:
+    if state.config.return_trace:
+        return MFlowResult(value=value, trace=state.exported_trace)
+    if state.config.output == "dict":
+        return state.exported_trace
+    if state.config.output in {"json", "mermaid"}:
+        return state.exported_trace
+    return value
+
+
+def _profile(frame: FrameType, event: str, arg: Any) -> None:
+    state = _active_trace.get()
+    if state is None:
+        return
+
+    if event == "call":
+        _handle_call(state, frame)
+        return
+
+    if event == "return":
+        _handle_return(state, frame, arg)
+
+
+def _handle_call(state: _TraceState, frame: FrameType) -> None:
+    if not _should_trace_frame(state, frame):
+        return
+
+    frame_id = id(frame)
+    if frame_id in state.frame_nodes:
+        state.stack.append(state.frame_nodes[frame_id])
+        return
+
+    code = frame.f_code
+    node = TraceNode(
+        name=f"{code.co_name}()",
+        filename=os.path.abspath(code.co_filename),
+        lineno=code.co_firstlineno,
+        start=time.perf_counter(),
+        args=_format_args(frame) if state.config.show_args else None,
+    )
+
+    if state.stack:
+        state.stack[-1].children.append(node)
+    elif state.root is None:
+        state.root = node
+    else:
+        return
+
+    state.stack.append(node)
+    state.frame_nodes[frame_id] = node
+
+
+def _handle_return(state: _TraceState, frame: FrameType, arg: Any) -> None:
+    if not state.stack:
+        return
+
+    code = frame.f_code
+    if state.stack[-1].filename != os.path.abspath(code.co_filename):
+        return
+    if state.stack[-1].lineno != code.co_firstlineno:
+        return
+    if state.stack[-1].name != f"{code.co_name}()":
+        return
+
+    if _is_coroutine_suspension(frame):
+        state.stack.pop()
+        return
+
+    node = state.stack[-1]
+    if state.config.show_return:
+        node.return_value = _safe_repr(arg)
+    node.end = time.perf_counter()
+    state.stack.pop()
+    state.frame_nodes.pop(id(frame), None)
+
+
+def _mark_error(state: _TraceState, error: BaseException) -> None:
+    state.had_error = True
+    message = f"{type(error).__name__}: {error}"
+    if state.stack:
+        state.stack[-1].exception = message
+    elif state.root is not None:
+        state.root.exception = message
+
+
+def _should_trace_frame(state: _TraceState, frame: FrameType) -> bool:
+    filename = os.path.abspath(frame.f_code.co_filename)
+    module = frame.f_globals.get("__name__", "")
+    target = f"{module}:{frame.f_code.co_name}:{filename}"
+
+    if _matches(target, state.config.exclude):
+        return False
+
+    if state.config.include:
+        return _matches(target, state.config.include)
+
+    return not _is_external_frame(filename)
+
+
+def _matches(value: str, filters: tuple[str, ...]) -> bool:
+    return any(item in value or fnmatch.fnmatch(value, item) for item in filters)
+
+
+def _is_external_frame(filename: str) -> bool:
+    if filename.startswith("<"):
+        return True
+
+    cwd = os.path.abspath(os.getcwd())
+    return not os.path.abspath(filename).startswith(cwd + os.sep)
+
+
+def _is_coroutine_suspension(frame: FrameType) -> bool:
+    if not frame.f_code.co_flags & inspect.CO_COROUTINE:
+        return False
+    if frame.f_lasti < 0 or frame.f_lasti >= len(frame.f_code.co_code):
+        return False
+    return dis.opname[frame.f_code.co_code[frame.f_lasti]] == "YIELD_VALUE"
+
+
+def _print_trace(root: TraceNode, config: _TraceConfig) -> None:
+    console = Console()
+    banner = _banner(config.title)
+    console.print()
+    console.print(Text(banner, style="dim bold cyan"))
+    tree = Tree(_format_node(root, config, depth=0), guide_style="bold bright_blue")
+    _append_children(tree, root, config, depth=1)
+    console.print(tree)
+    console.print(Text("─" * len(banner), style="dim cyan"))
+    console.print()
+
+
+def _banner(title: str | None = None) -> str:
+    label = title or "MITHRA FLOW"
+    text = f"{label}  v{__version__}"
+    width = max(36, len(text) + 4)
+    side = max(1, (width - len(text) - 2) // 2)
+    line = "─" * side
+    banner = f"{line} {text} {line}"
+    if len(banner) < width:
+        banner += "─" * (width - len(banner))
+    return banner
+
+
+def _append_children(tree: Tree, node: TraceNode, config: _TraceConfig, depth: int) -> None:
+    if config.max_depth is not None and depth > config.max_depth:
+        return
+    for child in node.children:
+        if not _should_show_node(child, config, depth):
+            continue
+        branch = tree.add(_format_node(child, config, depth=depth), guide_style=_level_style(depth))
+        _append_children(branch, child, config, depth=depth + 1)
+
+
+def _should_show_node(node: TraceNode, config: _TraceConfig, depth: int) -> bool:
+    if config.max_depth is not None and depth > config.max_depth:
+        return False
+    if node.exception:
+        return True
+    if node.duration_ms >= config.min_duration_ms:
+        return True
+    return any(_should_show_node(child, config, depth + 1) for child in node.children)
+
+
+def _format_node(node: TraceNode, config: _TraceConfig, depth: int) -> Text:
+    level_style = "red" if node.exception else _level_style(depth)
+    label = Text()
+    label.append("◆ " if node.is_span else "● ", style=level_style)
+    label.append(node.name, style=f"bold {level_style}")
+    if node.args:
+        label.append(node.args, style="dim")
+    label.append("  ")
+    label.append(f"{node.duration_ms:.2f} ms", style="yellow")
+    if config.show_return and node.return_value is not None:
+        label.append(f" -> {node.return_value}", style="dim green")
+    if node.exception:
+        label.append(f" ! {node.exception}", style="red")
+    location = _format_location(node, config)
+    if location:
+        label.append(f"  {location}", style="dim")
+    return label
+
+
+def _format_location(node: TraceNode, config: _TraceConfig) -> str:
+    if not config.show_file and not config.show_line:
+        return ""
+    if node.filename == "<manual>":
+        return "<manual>"
+    location = Path(node.filename).name if config.show_file else ""
+    if config.show_line:
+        location = f"{location}:{node.lineno}" if location else f":{node.lineno}"
+    return location
+
+
+def _export_trace(state: _TraceState) -> dict[str, Any] | str | None:
+    if state.root is None:
+        return None
+    data = _node_to_dict(state.root, state.config, depth=0)
+    if state.config.output == "json":
+        return json.dumps(data, indent=2)
+    if state.config.output == "mermaid":
+        return _to_mermaid(state.root, state.config)
+    return data
+
+
+def _node_to_dict(node: TraceNode, config: _TraceConfig, depth: int) -> dict[str, Any]:
+    data = node.to_dict()
+    if not config.show_args:
+        data.pop("args", None)
+    if not config.show_return:
+        data.pop("return_value", None)
+    if not config.show_file:
+        data.pop("filename", None)
+    if not config.show_line:
+        data.pop("lineno", None)
+    children = []
+    if config.max_depth is None or depth < config.max_depth:
+        for child in node.children:
+            if _should_show_node(child, config, depth + 1):
+                children.append(_node_to_dict(child, config, depth + 1))
+    data["children"] = children
+    return data
+
+
+def _to_mermaid(root: TraceNode, config: _TraceConfig) -> str:
+    lines = ["graph TD"]
+    ids: dict[int, str] = {}
+
+    def walk(node: TraceNode, depth: int) -> str:
+        node_id = ids.setdefault(id(node), f"N{len(ids)}")
+        lines.append(f'  {node_id}["{node.name} {node.duration_ms:.2f} ms"]')
+        if config.max_depth is not None and depth >= config.max_depth:
+            return node_id
+        for child in node.children:
+            if not _should_show_node(child, config, depth + 1):
+                continue
+            child_id = walk(child, depth + 1)
+            lines.append(f"  {node_id} --> {child_id}")
+        return node_id
+
+    walk(root, 0)
+    return "\n".join(lines)
+
+
+def _save_trace(state: _TraceState) -> None:
+    if not state.config.save_to or state.exported_trace is None:
+        return
+    path = Path(state.config.save_to)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if isinstance(state.exported_trace, str):
+        path.write_text(state.exported_trace, encoding="utf-8")
+        return
+    path.write_text(json.dumps(state.exported_trace, indent=2), encoding="utf-8")
+
+
+def _format_args(frame: FrameType) -> str:
+    try:
+        args = inspect.getargvalues(frame)
+    except Exception:
+        return "()"
+    parts = []
+    for name in args.args:
+        parts.append(f"{name}={_safe_repr(args.locals.get(name))}")
+    if args.varargs:
+        parts.append(f"*{args.varargs}={_safe_repr(args.locals.get(args.varargs))}")
+    if args.keywords:
+        parts.append(f"**{args.keywords}={_safe_repr(args.locals.get(args.keywords))}")
+    return f"({', '.join(parts)})"
+
+
+def _safe_repr(value: Any, limit: int = 80) -> str:
+    try:
+        text = repr(value)
+    except Exception:
+        text = f"<{type(value).__name__}>"
+    if len(text) > limit:
+        return text[: limit - 3] + "..."
+    return text
+
+
+def _level_style(depth: int) -> str:
+    styles = (
+        "bright_cyan",
+        "bright_green",
+        "bright_magenta",
+        "bright_yellow",
+        "bright_blue",
+        "bright_red",
+    )
+    return styles[depth % len(styles)]

mithra_flow/models.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class TraceNode:
+    name: str
+    filename: str
+    lineno: int
+    start: float
+    end: float | None = None
+    args: str | None = None
+    return_value: str | None = None
+    exception: str | None = None
+    is_span: bool = False
+    children: list["TraceNode"] = field(default_factory=list)
+
+    @property
+    def duration_ms(self) -> float:
+        if self.end is None:
+            return 0.0
+        return (self.end - self.start) * 1000
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "filename": self.filename,
+            "lineno": self.lineno,
+            "duration_ms": round(self.duration_ms, 3),
+            "args": self.args,
+            "return_value": self.return_value,
+            "exception": self.exception,
+            "is_span": self.is_span,
+            "children": [child.to_dict() for child in self.children],
+        }

mithra_flow/version.py

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

mithra_flow-1.0.dist-info/METADATA

@@ -0,0 +1,723 @@
+Metadata-Version: 2.4
+Name: mithra-flow
+Version: 1.0
+Summary: Trace nested project function calls from decorated Python functions.
+Project-URL: Homepage, https://github.com/MITHUNMITS/mithra-flow
+Project-URL: Repository, https://github.com/MITHUNMITS/mithra-flow
+Project-URL: Issues, https://github.com/MITHUNMITS/mithra-flow/issues
+Author: MITHUNMITS
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: rich>=13.0.0
+Provides-Extra: examples
+Requires-Dist: fastapi>=0.115.0; extra == 'examples'
+Requires-Dist: uvicorn>=0.30.0; extra == 'examples'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mithra-flow
+
+`mithra-flow` traces nested Python function calls while a decorated function runs.
+It is built for terminal-first debugging: no web UI, no database, no framework lock-in.
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● basic_trace()  43.43 ms
+┗━━ ● parent_flow()  43.42 ms
+    ┣━━ ● child_one()  32.17 ms
+    ┃   ┣━━ ● grandchild_a()  11.90 ms
+    ┃   ┗━━ ● grandchild_b()  20.25 ms
+    ┗━━ ● child_two()  11.24 ms
+        ┗━━ ● grandchild_c()  11.23 ms
+────────────────────────────────────
+```
+
+## What It Does
+
+- Traces sync and async decorated functions.
+- Captures nested project-local child function calls with `sys.setprofile`.
+- Isolates each trace with `contextvars`.
+- Measures duration with `time.perf_counter`.
+- Prints a colored Rich tree in the terminal.
+- Supports filters, depth limits, duration thresholds, args, return values, errors, JSON, Mermaid, files, manual spans, and context manager traces.
+
+## Use Cases
+
+`mithra-flow` is useful when you need to understand what your code is doing without opening a full profiler, adding a web UI, or wiring a database.
+
+| Use Case | How It Helps |
+| --- | --- |
+| Debug complex flows | See the exact nested function path that ran during one request, job, or script execution. |
+| Understand a new codebase | New developers can trace one entry function and quickly see the project flow. |
+| Check performance hotspots | Durations make slow child calls visible without running a heavy profiler. |
+| Compare before and after changes | Run the same function before and after a refactor to check if the call tree or timing changed. |
+| Debug async behavior | See nested async calls across `await` points in one readable tree. |
+| Investigate API requests | Decorate a FastAPI route and inspect the internal service/helper calls behind that endpoint. |
+| Find noisy helper calls | Use `min_duration_ms` and `max_depth` to reduce clutter in large call trees. |
+| Explain business logic | Export Mermaid or JSON traces to show how a workflow moves through functions. |
+| Review errors faster | Use `on_error=True` to print traces only for failed executions. |
+| Trace manual work blocks | Use `span(...)` for database queries, cache writes, external API calls, or other blocks that are not standalone functions. |
+| Generate debugging artifacts | Use `save_to="trace.json"` to keep trace data for later review. |
+| Teach project architecture | Include trace examples in onboarding docs so new team members see real runtime structure. |
+
+Typical places to use it:
+
+- FastAPI route handlers.
+- CLI commands.
+- Background jobs.
+- Data processing pipelines.
+- Test/debug scripts.
+- Service-layer functions.
+- Async workflows.
+- Refactor verification.
+
+## Install
+
+From PyPI:
+
+```bash
+python3 -m pip install mithra-flow
+```
+
+With FastAPI example dependencies:
+
+```bash
+python3 -m pip install 'mithra-flow[examples]'
+```
+
+For local development:
+
+```bash
+python3 -m pip install -e '.[test,examples]'
+```
+
+Run tests:
+
+```bash
+python3 -m pytest -q
+```
+
+## Quick Start
+
+```python
+from mithra_flow import mflow
+
+def child():
+    return "ok"
+
+@mflow
+def parent():
+    return child()
+
+parent()
+```
+
+Output:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● parent()  0.04 ms
+┗━━ ● child()  0.01 ms
+────────────────────────────────────
+```
+
+## Async Example
+
+```python
+import asyncio
+from mithra_flow import mflow
+
+async def child():
+    await asyncio.sleep(0.01)
+    return "ok"
+
+@mflow
+async def parent():
+    return await child()
+
+asyncio.run(parent())
+```
+
+Output:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● parent()  11.20 ms
+┗━━ ● child()  11.14 ms
+────────────────────────────────────
+```
+
+## Decorator Options
+
+| Option | Purpose |
+| --- | --- |
+| `name="checkout"` | Sets a custom banner title. |
+| `title="checkout"` | Alias-style title input. |
+| `include=["examples"]` | Trace only matching module/function/path values. |
+| `exclude=["grandchild_b"]` | Hide matching module/function/path values. |
+| `enabled=False` | Disable tracing for that function. |
+| `min_duration_ms=15` | Hide calls faster than the threshold. |
+| `max_depth=1` | Limit displayed/exported child depth. |
+| `show_args=True` | Show function arguments. |
+| `show_return=True` | Show return values. |
+| `show_file=True` | Show source file names. |
+| `show_line=True` | Show source line numbers. |
+| `on_error=True` | Print only when an exception happens. |
+| `output="terminal"` | Print a Rich tree. |
+| `output="dict"` | Return a trace dictionary. |
+| `output="json"` | Return a JSON trace string. |
+| `output="mermaid"` | Return a Mermaid graph string. |
+| `output="none"` | Collect/save without terminal printing. |
+| `save_to="trace.json"` | Write trace output to disk. |
+| `return_trace=True` | Return `MFlowResult(value, trace)`. |
+
+Disable globally:
+
+```bash
+MITHRA_FLOW=0 python3 your_script.py
+```
+
+## FastAPI Example
+
+Run the example API:
+
+```bash
+python3 -m uvicorn examples.nested_flow:app --reload
+```
+
+Open docs:
+
+```text
+http://127.0.0.1:8000/docs
+```
+
+Or call endpoints directly:
+
+```bash
+curl http://127.0.0.1:8000/flow/basic
+```
+
+## Example API Map
+
+| Endpoint | Demonstrates |
+| --- | --- |
+| `/flow/basic` | Default nested async tracing. |
+| `/flow/title` | Custom banner title with `name=`. |
+| `/flow/args` | Arguments and return values. |
+| `/flow/location` | File name and line number display. |
+| `/flow/max-depth` | Depth-limited tree. |
+| `/flow/min-duration` | Duration filtering. |
+| `/flow/json` | JSON trace response. |
+| `/flow/mermaid` | Mermaid graph response. |
+| `/flow/return-trace` | Return value plus trace data. |
+| `/flow/include-exclude` | Include/exclude filtering. |
+| `/flow/save-to` | Save trace to `/tmp/mithra-flow-example.json`. |
+| `/flow/manual-span` | Manual spans inside a trace. |
+| `/flow/context` | Context manager tracing. |
+| `/flow/on-error` | Print only when an error happens. |
+| `/flow/disabled` | Disabled tracing. |
+
+## `/flow/basic`
+
+Code:
+
+```python
+@app.get("/flow/basic")
+@mflow(include=["examples"])
+async def basic_trace():
+    return {"result": await parent_flow()}
+```
+
+Call:
+
+```bash
+curl http://127.0.0.1:8000/flow/basic
+```
+
+Response:
+
+```json
+{"result":[["grandchild-a","grandchild-b"],["grandchild-c"]]}
+```
+
+Terminal graph:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● basic_trace()  43.43 ms
+┗━━ ● parent_flow()  43.42 ms
+    ┣━━ ● child_one()  32.17 ms
+    ┃   ┣━━ ● grandchild_a()  11.90 ms
+    ┃   ┗━━ ● grandchild_b()  20.25 ms
+    ┗━━ ● child_two()  11.24 ms
+        ┗━━ ● grandchild_c()  11.23 ms
+────────────────────────────────────
+```
+
+## `/flow/title`
+
+Code:
+
+```python
+@app.get("/flow/title")
+@mflow(name="checkout request", include=["examples"])
+async def custom_title():
+    return {"result": await parent_flow()}
+```
+
+Terminal graph:
+
+```text
+────── checkout request  v1.0 ──────
+● custom_title()  43.26 ms
+┗━━ ● parent_flow()  43.26 ms
+    ┣━━ ● child_one()  32.09 ms
+    ┃   ┣━━ ● grandchild_a()  10.88 ms
+    ┃   ┗━━ ● grandchild_b()  21.18 ms
+    ┗━━ ● child_two()  11.16 ms
+        ┗━━ ● grandchild_c()  11.15 ms
+────────────────────────────────────
+```
+
+## `/flow/args`
+
+Code:
+
+```python
+@app.get("/flow/args")
+@mflow(include=["examples"], show_args=True, show_return=True)
+def args_and_returns(amount: int = 100):
+    return sync_receipt(amount)
+```
+
+Call:
+
+```bash
+curl "http://127.0.0.1:8000/flow/args?amount=100"
+```
+
+Terminal graph:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● args_and_returns()(amount=100)  0.05 ms -> {'amount': 100, 'total': 105.0}
+┗━━ ● sync_receipt()(amount=100)  0.03 ms -> {'amount': 100, 'total': 105.0}
+    ┗━━ ● sync_price()(amount=100, tax=0.05)  0.01 ms -> 105.0
+────────────────────────────────────
+```
+
+## `/flow/location`
+
+Code:
+
+```python
+@app.get("/flow/location")
+@mflow(include=["examples"], show_file=True, show_line=True)
+async def file_and_line():
+    return {"result": await parent_flow()}
+```
+
+Terminal graph:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● file_and_line()  43.56 ms  nested_flow.py:75
+┗━━ ● parent_flow()  43.55 ms  nested_flow.py:37
+    ┣━━ ● child_one()  32.35 ms  nested_flow.py:26
+    ┃   ┣━━ ● grandchild_a()  11.14 ms  nested_flow.py:11
+    ┃   ┗━━ ● grandchild_b()  21.20 ms  nested_flow.py:16
+    ┗━━ ● child_two()  11.19 ms  nested_flow.py:32
+        ┗━━ ● grandchild_c()  11.18 ms  nested_flow.py:21
+────────────────────────────────────
+```
+
+## `/flow/max-depth`
+
+Code:
+
+```python
+@app.get("/flow/max-depth")
+@mflow(include=["examples"], max_depth=1)
+async def max_depth():
+    return {"result": await parent_flow()}
+```
+
+Terminal graph:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● max_depth()  42.98 ms
+┗━━ ● parent_flow()  42.97 ms
+────────────────────────────────────
+```
+
+## `/flow/min-duration`
+
+Code:
+
+```python
+@app.get("/flow/min-duration")
+@mflow(include=["examples"], min_duration_ms=15)
+async def min_duration():
+    return {"result": await parent_flow()}
+```
+
+Terminal graph:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● min_duration()  43.54 ms
+┗━━ ● parent_flow()  43.54 ms
+    ┗━━ ● child_one()  32.37 ms
+        ┗━━ ● grandchild_b()  21.20 ms
+────────────────────────────────────
+```
+
+## `/flow/json`
+
+Code:
+
+```python
+@app.get("/flow/json", response_class=PlainTextResponse)
+@mflow(include=["examples"], output="json", show_args=True)
+def json_trace():
+    return sync_receipt(50)
+```
+
+Response:
+
+```json
+{
+  "name": "json_trace()",
+  "duration_ms": 0.03,
+  "args": "()",
+  "exception": null,
+  "is_span": false,
+  "children": [
+    {
+      "name": "sync_receipt()",
+      "duration_ms": 0.01,
+      "args": "(amount=50)",
+      "exception": null,
+      "is_span": false,
+      "children": [
+        {
+          "name": "sync_price()",
+          "duration_ms": 0.0,
+          "args": "(amount=50, tax=0.05)",
+          "exception": null,
+          "is_span": false,
+          "children": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+## `/flow/mermaid`
+
+Code:
+
+```python
+@app.get("/flow/mermaid", response_class=PlainTextResponse)
+@mflow(include=["examples"], output="mermaid")
+async def mermaid_trace():
+    await parent_flow()
+```
+
+Response:
+
+```mermaid
+graph TD
+  N0["mermaid_trace() 43.50 ms"]
+  N1["parent_flow() 43.50 ms"]
+  N2["child_one() 32.30 ms"]
+  N3["grandchild_a() 11.15 ms"]
+  N2 --> N3
+  N4["grandchild_b() 21.15 ms"]
+  N2 --> N4
+  N1 --> N2
+  N5["child_two() 11.13 ms"]
+  N6["grandchild_c() 11.13 ms"]
+  N5 --> N6
+  N1 --> N5
+  N0 --> N1
+```
+
+Rendered shape:
+
+```text
+mermaid_trace()
+└── parent_flow()
+    ├── child_one()
+    │   ├── grandchild_a()
+    │   └── grandchild_b()
+    └── child_two()
+        └── grandchild_c()
+```
+
+## `/flow/return-trace`
+
+Code:
+
+```python
+@app.get("/flow/return-trace")
+@mflow(include=["examples"], return_trace=True, show_return=True)
+async def return_trace():
+    result = await parent_flow()
+    return result
+```
+
+Response shape:
+
+```json
+{
+  "value": [["grandchild-a", "grandchild-b"], ["grandchild-c"]],
+  "trace": {
+    "name": "return_trace()",
+    "duration_ms": 43.459,
+    "children": []
+  }
+}
+```
+
+## `/flow/include-exclude`
+
+Code:
+
+```python
+@app.get("/flow/include-exclude")
+@mflow(include=["examples"], exclude=["grandchild_b"])
+async def include_exclude():
+    return {"result": await parent_flow()}
+```
+
+Terminal graph:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● include_exclude()  42.71 ms
+┗━━ ● parent_flow()  42.70 ms
+    ┣━━ ● child_one()  32.33 ms
+    ┃   ┗━━ ● grandchild_a()  11.17 ms
+    ┗━━ ● child_two()  10.36 ms
+        ┗━━ ● grandchild_c()  10.35 ms
+────────────────────────────────────
+```
+
+`grandchild_b()` still executes, but it is hidden from the trace.
+
+## `/flow/save-to`
+
+Code:
+
+```python
+@app.get("/flow/save-to")
+@mflow(include=["examples"], save_to="/tmp/mithra-flow-example.json")
+async def save_to_file():
+    await parent_flow()
+    return {"saved_to": "/tmp/mithra-flow-example.json"}
+```
+
+Call:
+
+```bash
+curl http://127.0.0.1:8000/flow/save-to
+cat /tmp/mithra-flow-example.json
+```
+
+On macOS, `/tmp/mithra-flow-example.json` resolves to:
+
+```text
+/private/tmp/mithra-flow-example.json
+```
+
+## `/flow/manual-span`
+
+Code:
+
+```python
+@app.get("/flow/manual-span")
+@mflow(include=["examples"])
+async def manual_span():
+    with span("manual database query"):
+        await asyncio.sleep(0.01)
+    with span("manual cache write"):
+        await asyncio.sleep(0)
+    return {"ok": True}
+```
+
+Terminal graph:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● manual_span()  11.54 ms
+┣━━ ◆ manual database query()  11.30 ms
+┗━━ ◆ manual cache write()  0.22 ms
+────────────────────────────────────
+```
+
+Manual spans use `◆` instead of `●`.
+
+## `/flow/context`
+
+Code:
+
+```python
+@app.get("/flow/context")
+async def context_manager():
+    with trace("context managed flow", include=["examples"], show_return=True) as traced:
+        result = sync_receipt(25)
+    return {"result": result, "trace": traced.result}
+```
+
+Terminal graph:
+
+```text
+──── context managed flow  v1.0 ────
+◆ context managed flow  0.12 ms
+┗━━ ● sync_receipt()  0.01 ms -> {'amount': 25, 'total': 26.25}
+    ┗━━ ● sync_price()  0.01 ms -> 26.25
+────────────────────────────────────
+```
+
+## `/flow/on-error`
+
+Code:
+
+```python
+@app.get("/flow/on-error")
+@mflow(include=["examples"], on_error=True)
+async def on_error_only():
+    try:
+        await failing_child()
+    except RuntimeError as error:
+        raise HTTPException(status_code=500, detail=str(error)) from error
+```
+
+Response:
+
+```json
+{"detail":"example failure"}
+```
+
+Terminal graph:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● on_error_only()  0.12 ms ! HTTPException: 500: example failure
+┗━━ ● failing_child()  0.10 ms
+────────────────────────────────────
+```
+
+## `/flow/disabled`
+
+Code:
+
+```python
+@app.get("/flow/disabled")
+@mflow(include=["examples"], enabled=False)
+async def disabled_trace():
+    return {"result": await parent_flow()}
+```
+
+Response:
+
+```json
+{"result":[["grandchild-a","grandchild-b"],["grandchild-c"]]}
+```
+
+Terminal graph:
+
+```text
+No trace is printed.
+```
+
+## Context Manager
+
+Use `trace(...)` when you do not want to decorate a function.
+
+```python
+from mithra_flow import trace
+
+with trace("batch job", include=["jobs"]) as traced:
+    run_job()
+
+print(traced.result)
+```
+
+## Manual Spans
+
+Use `span(...)` to mark work that is not naturally represented by a function call.
+
+```python
+from mithra_flow import mflow, span
+
+@mflow
+def process():
+    with span("database query"):
+        query_database()
+```
+
+Output:
+
+```text
+──────── MITHRA FLOW  v1.0 ─────────
+● process()  12.30 ms
+┗━━ ◆ database query()  11.80 ms
+────────────────────────────────────
+```
+
+## Return Trace Data
+
+```python
+from mithra_flow import mflow
+
+@mflow(return_trace=True)
+def parent():
+    return "ok"
+
+result = parent()
+
+print(result.value)
+print(result.trace)
+```
+
+`result` is an `MFlowResult`:
+
+```python
+MFlowResult(value="ok", trace={...})
+```
+
+## Versioning
+
+The banner version comes from package versioning:
+
+```python
+from mithra_flow import __version__
+
+print(__version__)
+```
+
+Current source:
+
+```python
+__version__ = "1.0"
+```
+
+`pyproject.toml` reads the version from `src/mithra_flow/version.py`.

mithra_flow-1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mithra_flow/__init__.py,sha256=r8HAz5kRc0BDy9hbiGcXTP2AZC3ELn9StKg8p4p93Ww,199
+mithra_flow/decorator.py,sha256=Y0RRsQnShm38f76aBkzI2vGtVdjFsDjFdyVxP2gFHIw,19452
+mithra_flow/models.py,sha256=dztK2QljILfEhe5McVs7gCGXdcFAAVTQMIUKLDLs9OA,1013
+mithra_flow/version.py,sha256=kM55qqhSrc4b-StNTuN03Srg0kwfg1G4BckCKhUytaE,20
+mithra_flow-1.0.dist-info/METADATA,sha256=guB4Bt0KyPLPcq_bfD86aKtaafcK0kNc_SnunXYwFEU,18296
+mithra_flow-1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mithra_flow-1.0.dist-info/RECORD,,

mithra_flow-1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any