PyPI - mermaid-trace - Versions diffs - 0.3.1__py3-none-any.whl - Mend

mermaid-trace 0.3.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

mermaid_trace/__init__.py +70 -0
mermaid_trace/cli.py +193 -0
mermaid_trace/core/__init__.py +0 -0
mermaid_trace/core/context.py +187 -0
mermaid_trace/core/decorators.py +252 -0
mermaid_trace/core/events.py +75 -0
mermaid_trace/core/formatter.py +72 -0
mermaid_trace/handlers/mermaid_handler.py +86 -0
mermaid_trace/integrations/fastapi.py +122 -0
mermaid_trace/py.typed +0 -0
mermaid_trace-0.3.1.dist-info/METADATA +163 -0
mermaid_trace-0.3.1.dist-info/RECORD +15 -0
mermaid_trace-0.3.1.dist-info/WHEEL +4 -0
mermaid_trace-0.3.1.dist-info/entry_points.txt +2 -0
mermaid_trace-0.3.1.dist-info/licenses/LICENSE +21 -0

mermaid_trace/__init__.py ADDED Viewed

@@ -0,0 +1,70 @@
+"""
+MermaidTrace: Visualize your Python code execution flow as Mermaid Sequence Diagrams.
+This package provides tools to automatically trace function calls and generate
+Mermaid-compatible sequence diagrams (.mmd files). It is designed to help
+developers understand the flow of their applications, debug complex interactions,
+and document system behavior.
+Key Components:
+- `trace`: A decorator to instrument functions for tracing.
+- `LogContext`: Manages execution context (like thread-local storage) to track
+  caller/callee relationships across async tasks and threads.
+- `configure_flow`: Sets up the logging handler to write diagrams to a file.
+"""
+from .core.decorators import trace_interaction, trace
+from .handlers.mermaid_handler import MermaidFileHandler
+from .core.events import FlowEvent
+from .core.context import LogContext
+from .core.formatter import MermaidFormatter
+# We don't import integrations by default to avoid hard dependencies
+# Integrations (like FastAPI) must be imported explicitly by the user if needed.
+from importlib.metadata import PackageNotFoundError, version
+import logging
+def configure_flow(output_file: str = "flow.mmd") -> logging.Logger:
+    """
+    Configures the flow logger to output to a Mermaid file.
+    This function sets up the logging infrastructure required to capture
+    trace events and write them to the specified output file. It should
+    be called once at the start of your application.
+    Args:
+        output_file (str): The absolute or relative path to the output .mmd file.
+                           Defaults to "flow.mmd" in the current directory.
+    Returns:
+        logging.Logger: The configured logger instance used for flow tracing.
+    """
+    # Get the specific logger used by the tracing decorators
+    logger = logging.getLogger("mermaid_trace.flow")
+    logger.setLevel(logging.INFO)
+    # Remove existing handlers to avoid duplicate logs if configured multiple times
+    if logger.hasHandlers():
+        logger.handlers.clear()
+    # Create and attach the custom handler that writes Mermaid syntax
+    handler = MermaidFileHandler(output_file)
+    # Use the custom formatter to convert FlowEvents to Mermaid strings
+    handler.setFormatter(MermaidFormatter())
+    logger.addHandler(handler)
+    return logger
+try:
+    # Attempt to retrieve the installed package version
+    __version__ = version("mermaid-trace")
+except PackageNotFoundError:
+    # Fallback version if the package is not installed (e.g., local development)
+    __version__ = "0.0.0"
+# Export public API for easy access
+__all__ = ["trace_interaction", "trace", "configure_flow", "MermaidFileHandler", "LogContext", "FlowEvent", "MermaidFormatter"]

mermaid_trace/cli.py ADDED Viewed

@@ -0,0 +1,193 @@
+import argparse
+import http.server
+import socketserver
+import webbrowser
+import sys
+import os
+from pathlib import Path
+from typing import Type, Any
+try:
+    from watchdog.observers import Observer
+    from watchdog.events import FileSystemEventHandler
+    HAS_WATCHDOG = True
+except ImportError:
+    HAS_WATCHDOG = False
+# HTML Template for the preview page
+HTML_TEMPLATE = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>MermaidTrace Flow Preview</title>
+    <!-- Load Mermaid.js from CDN -->
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <style>
+        /* Basic styling for readability and layout */
+        body {{ font-family: sans-serif; padding: 20px; background: #f4f4f4; }}
+        .container {{ background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); }}
+        h1 {{ color: #333; }}
+        #diagram {{ overflow-x: auto; }} /* Allow horizontal scrolling for wide diagrams */
+        .refresh-btn {{
+            position: fixed; bottom: 20px; right: 20px;
+            padding: 10px 20px; background: #007bff; color: white;
+            border: none; border-radius: 5px; cursor: pointer; font-size: 16px;
+        }}
+        .refresh-btn:hover {{ background: #0056b3; }}
+        .status {{
+            position: fixed; bottom: 20px; left: 20px;
+            font-size: 12px; color: #666;
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>MermaidTrace Flow Preview: {filename}</h1>
+        <!-- The Mermaid diagram content will be injected here -->
+        <div class="mermaid" id="diagram">
+            {content}
+        </div>
+    </div>
+    <!-- Button to manually reload the page/diagram -->
+    <button class="refresh-btn" onclick="location.reload()">Refresh Diagram</button>
+    <div class="status" id="status">Monitoring for changes...</div>
+    <script>
+        // Initialize Mermaid with default settings
+        mermaid.initialize({{ startOnLoad: true, theme: 'default' }});
+        // Live Reload Logic
+        const currentMtime = "{mtime}";
+        function checkUpdate() {{
+            fetch('/_status')
+                .then(response => response.text())
+                .then(mtime => {{
+                    if (mtime && mtime !== currentMtime) {{
+                        console.log("File changed, reloading...");
+                        location.reload();
+                    }}
+                }})
+                .catch(err => console.error("Error checking status:", err));
+        }}
+        // Poll every 1 second
+        setInterval(checkUpdate, 1000);
+    </script>
+</body>
+</html>
+"""
+def _create_handler(filename: str, path: Path) -> Type[http.server.SimpleHTTPRequestHandler]:
+    """Helper to create the request handler class with closure over filename/path."""
+    class Handler(http.server.SimpleHTTPRequestHandler):
+        """
+        Custom Request Handler to serve the generated HTML dynamically.
+        """
+        def log_message(self, format: str, *args: Any) -> None:
+            # Suppress default logging to keep console clean
+            pass
+        def do_GET(self) -> None:
+            """
+            Handle GET requests.
+            Serves the HTML wrapper for the root path ('/').
+            """
+            if self.path == "/":
+                self.send_response(200)
+                self.send_header("Content-type", "text/html")
+                self.end_headers()
+                try:
+                    # Read the current content of the mermaid file
+                    content = path.read_text(encoding="utf-8")
+                    mtime = str(path.stat().st_mtime)
+                except Exception as e:
+                    # Fallback if reading fails (e.g., file locked)
+                    content = f"sequenceDiagram\nNote right of Error: Failed to read file: {e}"
+                    mtime = "0"
+                # Inject content into the HTML template
+                html = HTML_TEMPLATE.format(filename=filename, content=content, mtime=mtime)
+                self.wfile.write(html.encode("utf-8"))
+            elif self.path == "/_status":
+                # API endpoint for client to check file status
+                self.send_response(200)
+                self.send_header("Content-type", "text/plain")
+                self.end_headers()
+                try:
+                    mtime = str(path.stat().st_mtime)
+                except OSError:
+                    mtime = "0"
+                self.wfile.write(mtime.encode("utf-8"))
+            else:
+                # Serve static files if needed, or return 404
+                super().do_GET()
+    return Handler
+def serve(filename: str, port: int = 8000) -> None:
+    """
+    Starts a local HTTP server to preview the Mermaid diagram.
+    """
+    path = Path(filename)
+    if not path.exists():
+        print(f"Error: File '{filename}' not found.")
+        sys.exit(1)
+    # Setup Watchdog if available
+    observer = None
+    if HAS_WATCHDOG:
+        class FileChangeHandler(FileSystemEventHandler):
+            def on_modified(self, event: Any) -> None:
+                if not event.is_directory and os.path.abspath(event.src_path) == str(path.resolve()):
+                    print(f"[Watchdog] File changed: {filename}")
+        print("Initializing file watcher...")
+        observer = Observer()
+        observer.schedule(FileChangeHandler(), path=str(path.parent), recursive=False)
+        observer.start()
+    else:
+        print("Watchdog not installed. Falling back to polling mode (client-side only).")
+    HandlerClass = _create_handler(filename, path)
+    print(f"Serving {filename} at http://localhost:{port}")
+    print("Press Ctrl+C to stop.")
+    # Open browser automatically to the server URL
+    webbrowser.open(f"http://localhost:{port}")
+    # Start the TCP server
+    with socketserver.ThreadingTCPServer(("", port), HandlerClass) as httpd:
+        try:
+            httpd.serve_forever()
+        except KeyboardInterrupt:
+            print("\nStopping server...")
+            if observer:
+                observer.stop()
+                observer.join()
+            httpd.server_close()
+def main() -> None:
+    """
+    Entry point for the CLI application.
+    """
+    parser = argparse.ArgumentParser(description="MermaidTrace CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    # 'serve' command definition
+    serve_parser = subparsers.add_parser("serve", help="Serve a Mermaid file in the browser")
+    serve_parser.add_argument("file", help="Path to the .mmd file")
+    serve_parser.add_argument("--port", type=int, default=8000, help="Port to bind to (default: 8000)")
+    args = parser.parse_args()
+    if args.command == "serve":
+        serve(args.file, args.port)
+if __name__ == "__main__":
+    main()

mermaid_trace/core/__init__.py ADDED Viewed

File without changes

mermaid_trace/core/context.py ADDED Viewed

@@ -0,0 +1,187 @@
+from contextvars import ContextVar, Token
+from contextlib import asynccontextmanager, contextmanager
+from typing import Any, AsyncIterator, Dict, Iterator
+import uuid
+class LogContext:
+    """
+    Manages global context information for logging (e.g., request_id, user_id, current_participant).
+    This class utilizes `contextvars.ContextVar` to ensure thread-safety and
+    correct context propagation in asynchronous (asyncio) environments.
+    Unlike `threading.local()`, `ContextVar` works natively with Python's async/await
+    event loop, ensuring that context is preserved across `await` points but isolated
+    between different concurrent tasks.
+    """
+    # ContextVar is the key mechanism here.
+    # It stores a dictionary unique to the current execution context (Task/Thread).
+    # "log_context" is the name of the variable, useful for debugging.
+    # The default value is implicitly an empty state if not set (handled in _get_store).
+    _context_store: ContextVar[Dict[str, Any]] = ContextVar("log_context")
+    @classmethod
+    def _get_store(cls) -> Dict[str, Any]:
+        """
+        Retrieves the current context dictionary.
+        If the context variable has not been set in the current context,
+        it returns a fresh empty dictionary. This prevents LookupError
+        and ensures there's always a valid dictionary to work with.
+        """
+        try:
+            return cls._context_store.get()
+        except LookupError:
+            return {}
+    @classmethod
+    def set(cls, key: str, value: Any) -> None:
+        """
+        Sets a specific key-value pair in the current context.
+        Important: ContextVars are immutable collections. To modify the context,
+        we must:
+        1. Retrieve the current dictionary.
+        2. Create a shallow copy (to avoid affecting parent contexts if we were reusing the object).
+        3. Update the copy.
+        4. Re-set the ContextVar with the new dictionary.
+        """
+        ctx = cls._get_store().copy()
+        ctx[key] = value
+        cls._context_store.set(ctx)
+    @classmethod
+    def update(cls, data: Dict[str, Any]) -> None:
+        """
+        Updates multiple keys in the current context at once.
+        This follows the same Copy-Update-Set pattern as `set()` to maintain
+        context isolation.
+        """
+        if not data:
+            return
+        ctx = cls._get_store().copy()
+        ctx.update(data)
+        cls._context_store.set(ctx)
+    @classmethod
+    def get(cls, key: str, default: Any = None) -> Any:
+        """
+        Retrieves a value from the current context safely.
+        """
+        return cls._get_store().get(key, default)
+    @classmethod
+    def get_all(cls) -> Dict[str, Any]:
+        """
+        Returns a copy of the entire context dictionary.
+        """
+        return cls._get_store().copy()
+    @classmethod
+    @contextmanager
+    def scope(cls, data: Dict[str, Any]) -> Iterator[None]:
+        """
+        Synchronous context manager for temporary context updates.
+        Usage:
+            with LogContext.scope({"user_id": 123}):
+                # user_id is 123 here
+                some_function()
+            # user_id reverts to previous value (or disappears) here
+        Mechanism:
+            1. Copies current context and updates it with new data.
+            2. Sets the ContextVar to this new state, receiving a `Token`.
+            3. Yields control to the block.
+            4. Finally, uses the `Token` to reset the ContextVar to its exact state
+               before the block entered.
+        """
+        current_ctx = cls._get_store().copy()
+        current_ctx.update(data)
+        token = cls._context_store.set(current_ctx)
+        try:
+            yield
+        finally:
+            # Crucial: Reset restores the context to what it was before .set()
+            cls._context_store.reset(token)
+    @classmethod
+    @asynccontextmanager
+    async def ascope(cls, data: Dict[str, Any]) -> AsyncIterator[None]:
+        """
+        Async context manager for temporary context updates in coroutines.
+        Usage:
+            async with LogContext.ascope({"request_id": "abc"}):
+                await some_async_function()
+        This is functionally identical to `scope` but designed for `async with` blocks.
+        It ensures that even if the code inside `yield` suspends execution (await),
+        the context remains valid for that task.
+        """
+        current_ctx = cls._get_store().copy()
+        current_ctx.update(data)
+        token = cls._context_store.set(current_ctx)
+        try:
+            yield
+        finally:
+            cls._context_store.reset(token)
+    # Alias for backward compatibility if needed
+    ascope_async = ascope
+    @classmethod
+    def set_all(cls, data: Dict[str, Any]) -> Token[Dict[str, Any]]:
+        """
+        Replaces the entire context with the provided data.
+        Returns a Token that can be used to manually reset the context later.
+        """
+        return cls._context_store.set(data.copy())
+    @classmethod
+    def reset(cls, token: Token[Dict[str, Any]]) -> None:
+        """
+        Manually resets the context using a Token obtained from `set` or `set_all`.
+        """
+        cls._context_store.reset(token)
+    @classmethod
+    def current_participant(cls) -> str:
+        """
+        Helper to get the 'participant' field, representing the current active object/module.
+        Defaults to 'Unknown' if not set.
+        """
+        return str(cls.get("participant", "Unknown"))
+    @classmethod
+    def set_participant(cls, name: str) -> None:
+        """
+        Helper to set the 'participant' field.
+        """
+        cls.set("participant", name)
+    @classmethod
+    def current_trace_id(cls) -> str:
+        """
+        Retrieves the current trace ID for correlating events in a single flow.
+        Lazy Initialization Logic:
+        If no trace_id exists in the current context, it generates a new UUIDv4
+        and sets it immediately. This ensures that:
+        1. A trace ID is always available when asked for.
+        2. Once generated, the same ID persists for the duration of the context
+           (unless manually changed), linking all subsequent logs together.
+        """
+        tid = cls.get("trace_id")
+        if not tid:
+            tid = str(uuid.uuid4())
+            cls.set("trace_id", tid)
+        return str(tid)
+    @classmethod
+    def set_trace_id(cls, trace_id: str) -> None:
+        """
+        Manually sets the trace ID (e.g., from an incoming HTTP request header).
+        """
+        cls.set("trace_id", trace_id)

mermaid_trace/core/decorators.py ADDED Viewed

@@ -0,0 +1,252 @@
+import functools
+import logging
+import inspect
+import reprlib
+from typing import Optional, Any, Callable, Tuple, Dict, Union, TypeVar, cast, overload
+from .events import FlowEvent
+from .context import LogContext
+FLOW_LOGGER_NAME = "mermaid_trace.flow"
+# Define generic type variable for the decorated function
+F = TypeVar("F", bound=Callable[..., Any])
+def get_flow_logger() -> logging.Logger:
+    """Returns the dedicated logger for flow events."""
+    return logging.getLogger(FLOW_LOGGER_NAME)
+def _safe_repr(obj: Any, max_len: int = 50) -> str:
+    """
+    Safely creates a string representation of an object.
+    Prevents massive log files by truncating long strings/objects
+    and handling exceptions during __repr__ calls (e.g. strict objects).
+    """
+    try:
+        r = reprlib.repr(obj)
+        if len(r) > max_len:
+            return r[:max_len] + "..."
+        return r
+    except Exception:
+        return "<unrepresentable>"
+def _format_args(args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> str:
+    """
+    Formats function arguments into a single string "arg1, arg2, k=v".
+    Used for the arrow label in the diagram.
+    """
+    parts = []
+    for arg in args:
+        parts.append(_safe_repr(arg))
+    for k, v in kwargs.items():
+        parts.append(f"{k}={_safe_repr(v)}")
+    return ", ".join(parts)
+def _resolve_target(func: Callable[..., Any], args: Tuple[Any, ...], target_override: Optional[str]) -> str:
+    """
+    Determines the name of the participant (Target) for the diagram.
+    Resolution Priority:
+    1. **Override**: If the user explicitly provided `target="Name"`, use it.
+    2. **Instance Method**: If the first arg looks like `self` (has __class__),
+       use the class name.
+    3. **Class Method**: If the first arg is a type (cls), use the class name.
+    4. **Module Function**: Fallback to the name of the module containing the function.
+    5. **Fallback**: "Unknown".
+    """
+    if target_override:
+        return target_override
+    # Heuristic: If it's a method call, args[0] is usually 'self'.
+    if args:
+        first_arg = args[0]
+        # Check if it looks like a class instance
+        # We check hasattr(__class__) to distinguish objects from primitives/containers broadly,
+        # ensuring we don't mislabel a plain list passed as first arg to a function as a "List" participant.
+        if hasattr(first_arg, "__class__") and not isinstance(first_arg, (str, int, float, bool, list, dict, type)):
+             return str(first_arg.__class__.__name__)
+        # Check if it looks like a class (cls) - e.g. @classmethod
+        if isinstance(first_arg, type):
+             return first_arg.__name__
+    # Fallback to module name for standalone functions
+    module = inspect.getmodule(func)
+    if module:
+        return module.__name__.split(".")[-1]
+    return "Unknown"
+def _log_interaction(logger: logging.Logger,
+                     source: str,
+                     target: str,
+                     action: str,
+                     params: str,
+                     trace_id: str) -> None:
+    """
+    Logs the 'Call' event (Start of function).
+    Arrow: source -> target
+    """
+    req_event = FlowEvent(
+        source=source, target=target,
+        action=action, message=action,
+        params=params, trace_id=trace_id
+    )
+    # The 'extra' dict is critical: the Handler will pick this up to format the Mermaid line
+    logger.info(f"{source}->{target}: {action}", extra={"flow_event": req_event})
+def _log_return(logger: logging.Logger,
+                source: str,
+                target: str,
+                action: str,
+                result: Any,
+                trace_id: str) -> None:
+    """
+    Logs the 'Return' event (End of function).
+    Arrow: target --> source (Dotted line return)
+    Note: 'source' here is the original caller, 'target' is the callee.
+    So the return arrow goes from target back to source.
+    """
+    result_str = _safe_repr(result)
+    resp_event = FlowEvent(
+        source=target, target=source,
+        action=action, message="Return",
+        is_return=True, result=result_str, trace_id=trace_id
+    )
+    logger.info(f"{target}->{source}: Return", extra={"flow_event": resp_event})
+def _log_error(logger: logging.Logger,
+               source: str,
+               target: str,
+               action: str,
+               error: Exception,
+               trace_id: str) -> None:
+    """
+    Logs an 'Error' event if the function raises an exception.
+    Arrow: target -x source (Error return)
+    """
+    err_event = FlowEvent(
+        source=target, target=source, action=action,
+        message=str(error), is_return=True, is_error=True, error_message=str(error),
+        trace_id=trace_id
+    )
+    logger.error(f"{target}-x{source}: Error", extra={"flow_event": err_event})
+@overload
+def trace_interaction(func: F) -> F:
+    ...
+@overload
+def trace_interaction(
+    *,
+    source: Optional[str] = None,
+    target: Optional[str] = None,
+    action: Optional[str] = None
+) -> Callable[[F], F]:
+    ...
+def trace_interaction(
+    func: Optional[F] = None,
+    *,
+    source: Optional[str] = None,
+    target: Optional[str] = None,
+    action: Optional[str] = None
+) -> Union[F, Callable[[F], F]]:
+    """
+    Main Decorator for tracing function execution in Mermaid diagrams.
+    It supports two modes of operation:
+    1. **Simple**: `@trace` (No arguments)
+    2. **Configured**: `@trace(action="Login", target="AuthService")`
+    Args:
+        func: The function being decorated (automatically passed in simple mode).
+        source: Explicit name of the caller participant (rarely used, usually inferred from Context).
+        target: Explicit name of the callee participant (overrides automatic resolution).
+        action: Label for the arrow (defaults to function name).
+    """
+    # Mode 1: @trace used without parentheses
+    if func is not None and callable(func):
+        return _create_decorator(func, source, target, action)
+    # Mode 2: @trace(...) used with arguments -> returns a factory
+    def factory(f: F) -> F:
+        return _create_decorator(f, source, target, action)
+    return factory
+def _create_decorator(
+    func: F,
+    source: Optional[str],
+    target: Optional[str],
+    action: Optional[str]
+) -> F:
+    """
+    Constructs the actual wrapper function.
+    Handles both synchronous and asynchronous functions.
+    """
+    # Pre-calculate static metadata to save time at runtime
+    if action is None:
+        action = func.__name__.replace("_", " ").title()
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        """Sync function wrapper."""
+        # 1. Resolve Context
+        # 'source' is who called us (from Context). 'target' is who we are (resolved from self/cls).
+        current_source = source or LogContext.current_participant()
+        trace_id = LogContext.current_trace_id()
+        current_target = _resolve_target(func, args, target)
+        logger = get_flow_logger()
+        params_str = _format_args(args, kwargs)
+        # 2. Log Request (Start of block)
+        _log_interaction(logger, current_source, current_target, action, params_str, trace_id)
+        # 3. Execute with New Context
+        # We push 'current_target' as the NEW 'participant' (source) for any internal calls.
+        with LogContext.scope({"participant": current_target, "trace_id": trace_id}):
+            try:
+                result = func(*args, **kwargs)
+                # 4. Log Success Return
+                _log_return(logger, current_source, current_target, action, result, trace_id)
+                return result
+            except Exception as e:
+                # 5. Log Error Return
+                _log_error(logger, current_source, current_target, action, e, trace_id)
+                raise
+    @functools.wraps(func)
+    async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+        """Async function wrapper (coroutine)."""
+        current_source = source or LogContext.current_participant()
+        trace_id = LogContext.current_trace_id()
+        current_target = _resolve_target(func, args, target)
+        logger = get_flow_logger()
+        params_str = _format_args(args, kwargs)
+        # 2. Log Request (Start of block)
+        _log_interaction(logger, current_source, current_target, action, params_str, trace_id)
+        # Use async context manager (ascope) to ensure context propagates correctly across awaits
+        async with LogContext.ascope({"participant": current_target, "trace_id": trace_id}):
+            try:
+                result = await func(*args, **kwargs)
+                _log_return(logger, current_source, current_target, action, result, trace_id)
+                return result
+            except Exception as e:
+                _log_error(logger, current_source, current_target, action, e, trace_id)
+                raise
+    # Detect if the wrapped function is a coroutine to choose the right wrapper
+    if inspect.iscoroutinefunction(func):
+        return cast(F, async_wrapper)
+    return cast(F, wrapper)
+# Alias for easy import
+trace = trace_interaction

mermaid_trace/core/events.py ADDED Viewed

@@ -0,0 +1,75 @@
+from dataclasses import dataclass, field
+import time
+from typing import Optional
+@dataclass
+class FlowEvent:
+    """
+    Represents a single interaction or step in the execution flow.
+    This data structure acts as the intermediate representation (IR) between
+    runtime code execution and the final Mermaid diagram output. Each instance
+    corresponds directly to one arrow or note in the sequence diagram.
+    The fields map to Mermaid syntax components as follows:
+    `source` -> `target`: `message`
+    Attributes:
+        source (str):
+            The name of the participant initiating the action (the "Caller").
+            In Mermaid: The participant on the LEFT side of the arrow.
+        target (str):
+            The name of the participant receiving the action (the "Callee").
+            In Mermaid: The participant on the RIGHT side of the arrow.
+        action (str):
+            A short, human-readable name for the operation (e.g., function name).
+            Used for grouping or filtering logs, but often redundant with message.
+        message (str):
+            The actual text label displayed on the diagram arrow.
+            Example: "getUser(id=1)" or "Return: User(name='Alice')".
+        timestamp (float):
+            Unix timestamp (seconds) of when the event occurred.
+            Used for ordering events if logs are processed asynchronously,
+            though Mermaid sequence diagrams primarily rely on line order.
+        trace_id (str):
+            Unique identifier for the trace session.
+            Allows filtering multiple concurrent traces from a single log file
+            to generate separate diagrams for separate requests.
+        is_return (bool):
+            Flag indicating if this is a response arrow.
+            If True, the arrow is drawn as a dotted line (`-->`) in Mermaid.
+            If False, it is a solid line (`->`) representing a call.
+        is_error (bool):
+            Flag indicating if an exception occurred.
+            If True, the arrow might be styled differently (e.g., `-x`) to show failure.
+        error_message (Optional[str]):
+            Detailed error text if `is_error` is True.
+            Can be added as a note or included in the arrow label.
+        params (Optional[str]):
+            Stringified representation of function arguments.
+            Captured only for request events (call start).
+        result (Optional[str]):
+            Stringified representation of the return value.
+            Captured only for return events (call end).
+    """
+    source: str
+    target: str
+    action: str
+    message: str
+    trace_id: str
+    timestamp: float = field(default_factory=time.time)
+    is_return: bool = False
+    is_error: bool = False
+    error_message: Optional[str] = None
+    params: Optional[str] = None
+    result: Optional[str] = None

mermaid_trace/core/formatter.py ADDED Viewed

@@ -0,0 +1,72 @@
+import logging
+import re
+from typing import Optional
+from .events import FlowEvent
+class MermaidFormatter(logging.Formatter):
+    """
+    Custom formatter to convert FlowEvents into Mermaid sequence diagram syntax.
+    """
+    def format(self, record: logging.LogRecord) -> str:
+        # 1. Retrieve the FlowEvent
+        event: Optional[FlowEvent] = getattr(record, 'flow_event', None)
+        if not event:
+            # Fallback for standard logs if they accidentally reach this handler
+            return super().format(record)
+        # 2. Convert event to Mermaid line
+        return self._to_mermaid_line(event)
+    def _to_mermaid_line(self, event: FlowEvent) -> str:
+        """
+        Converts a FlowEvent into a Mermaid syntax string.
+        """
+        # Sanitize participant names
+        src = self._sanitize(event.source)
+        tgt = self._sanitize(event.target)
+        # Determine arrow type
+        # ->> : Solid line with arrowhead (synchronous call)
+        # -->> : Dotted line with arrowhead (return)
+        # --x : Dotted line with cross (error)
+        arrow = "-->>" if event.is_return else "->>"
+        if event.is_error:
+            arrow = "--x"
+            msg = f"Error: {event.error_message}"
+        elif event.is_return:
+            msg = f"Return: {event.result}" if event.result else "Return"
+        else:
+            msg = f"{event.message}({event.params})" if event.params else event.message
+        # Optional: Add note or group if trace_id changes (not implemented in single line format)
+        # For now, we just output the interaction.
+        # Escape message for Mermaid safety
+        msg = self._escape_message(msg)
+        return f"{src}{arrow}{tgt}: {msg}"
+    def _sanitize(self, name: str) -> str:
+        """
+        Sanitizes participant names to be valid Mermaid identifiers.
+        Allows alphanumeric and underscores. Replaces others.
+        """
+        # Replace any non-alphanumeric character (except underscore) with underscore
+        clean_name = re.sub(r'[^a-zA-Z0-9_]', '_', name)
+        # Ensure it doesn't start with a digit (Mermaid doesn't like that sometimes, though often okay)
+        if clean_name and clean_name[0].isdigit():
+            clean_name = "_" + clean_name
+        return clean_name
+    def _escape_message(self, msg: str) -> str:
+        """
+        Escapes special characters in the message text.
+        Mermaid messages can contain most chars, but : and newlines can be tricky.
+        """
+        # Replace newlines with <br/> for Mermaid display
+        msg = msg.replace('\n', '<br/>')
+        # We might want to escape other chars if needed, but usually text after : is forgiving.
+        return msg

mermaid_trace/handlers/mermaid_handler.py ADDED Viewed

@@ -0,0 +1,86 @@
+import logging
+import os
+class MermaidFileHandler(logging.FileHandler):
+    """
+    A custom logging handler that writes `FlowEvent` objects to a Mermaid (.mmd) file.
+    Strategy & Optimization:
+    1. **Inheritance**: Inherits from `logging.FileHandler` to leverage robust,
+       thread-safe file writing capabilities (locking, buffering) provided by the stdlib.
+    2. **Header Management**: Automatically handles the Mermaid file header
+       (`sequenceDiagram`, `title`, `autonumber`) to ensure the output file
+       is a valid Mermaid document. It smartly detects if the file is new or
+       being appended to.
+    3. **Deferred Formatting**: The actual string conversion happens in the `emit`
+       method (via the formatter), keeping the handler focused on I/O.
+    """
+    def __init__(self, filename: str, title: str = "Log Flow", mode: str = 'a', encoding: str = 'utf-8', delay: bool = False):
+        """
+        Initialize the handler.
+        Args:
+            filename (str): The path to the output .mmd file.
+            title (str): The title of the Mermaid diagram (written in the header).
+            mode (str): File open mode. 'w' (overwrite) or 'a' (append).
+            encoding (str): File encoding. Defaults to 'utf-8'.
+            delay (bool): If True, file opening is deferred until the first call to emit.
+                          Useful to avoid creating empty files if no logs occur.
+        """
+        # Ensure directory exists to prevent FileNotFoundError on open
+        os.makedirs(os.path.dirname(os.path.abspath(filename)) or ".", exist_ok=True)
+        # Header Strategy:
+        # We need to write the "sequenceDiagram" preamble ONLY if:
+        # 1. We are overwriting the file (mode='w').
+        # 2. We are appending (mode='a'), but the file doesn't exist or is empty.
+        should_write_header = False
+        if mode == 'w':
+            should_write_header = True
+        elif mode == 'a':
+            if not os.path.exists(filename) or os.path.getsize(filename) == 0:
+                should_write_header = True
+        # Initialize standard FileHandler (opens the file unless delay=True)
+        super().__init__(filename, mode, encoding, delay)
+        self.title = title
+        # Write header immediately if needed.
+        if should_write_header:
+            self._write_header()
+    def _write_header(self) -> None:
+        """
+        Writes the initial Mermaid syntax lines.
+        This setup is required for Mermaid JS or Live Editor to render the diagram.
+        """
+        # We use the stream directly if available, or open momentarily if delayed
+        if self.stream:
+            self.stream.write("sequenceDiagram\n")
+            self.stream.write(f"    title {self.title}\n")
+            self.stream.write("    autonumber\n")
+            self.flush()
+        else:
+            # Handling 'delay=True' case:
+            # If the file isn't open yet, we temporarily open it just to write the header.
+            # This ensures the file is valid even if the application crashes before the first log.
+            with open(self.baseFilename, self.mode, encoding=self.encoding) as f:
+                f.write("sequenceDiagram\n")
+                f.write(f"    title {self.title}\n")
+                f.write("    autonumber\n")
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        Process a log record.
+        Optimization:
+        - Checks for `flow_event` attribute first. This allows this handler
+          to be attached to the root logger without processing irrelevant system logs.
+        - Delegates the actual writing to `super().emit()`, which handles
+          thread locking and stream flushing.
+        """
+        # Only process records that contain our structured FlowEvent data
+        if hasattr(record, 'flow_event'):
+            super().emit(record)

mermaid_trace/integrations/fastapi.py ADDED Viewed

@@ -0,0 +1,122 @@
+from typing import Any, TYPE_CHECKING
+import time
+import uuid
+from ..core.events import FlowEvent
+from ..core.context import LogContext
+from ..core.decorators import get_flow_logger
+if TYPE_CHECKING:
+    from fastapi import Request, Response
+    from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+else:
+    try:
+        from fastapi import Request, Response
+        from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+    except ImportError:
+        # Handle the case where FastAPI/Starlette are not installed.
+        # We define dummy types to prevent NameErrors at import time,
+        # but instantiation will fail explicitly in __init__.
+        BaseHTTPMiddleware = object  # type: ignore[misc,assignment]
+        Request = Any  # type: ignore[assignment]
+        Response = Any  # type: ignore[assignment]
+        RequestResponseEndpoint = Any  # type: ignore[assignment]
+class MermaidTraceMiddleware(BaseHTTPMiddleware):
+    """
+    FastAPI Middleware to trace HTTP requests as interactions in the sequence diagram.
+    This middleware acts as the entry point for tracing a web request. It:
+    1. Identifies the client (Source).
+    2. Logs the incoming request.
+    3. Initializes the `LogContext` for the request lifecycle.
+    4. Logs the response or error.
+    """
+    def __init__(self, app: Any, app_name: str = "FastAPI"):
+        """
+        Initialize the middleware.
+        Args:
+            app: The FastAPI application instance.
+            app_name: The name of this service to appear in the diagram (e.g., "UserAPI").
+        """
+        if BaseHTTPMiddleware is object: # type: ignore[comparison-overlap]
+             raise ImportError("FastAPI/Starlette is required to use MermaidTraceMiddleware")
+        super().__init__(app)
+        self.app_name = app_name
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        """
+        Intercepts the incoming request.
+        Args:
+            request (Request): The incoming HTTP request.
+            call_next (Callable): The function to call the next middleware or endpoint.
+        Returns:
+            Response: The HTTP response.
+        """
+        # 1. Determine Source (Client)
+        # Try to get a specific ID from headers (useful for distributed tracing),
+        # otherwise fallback to "Client".
+        source = request.headers.get("X-Source", "Client")
+        # Determine Trace ID
+        # Check X-Trace-ID header or generate new UUID
+        trace_id = request.headers.get("X-Trace-ID") or str(uuid.uuid4())
+        # 2. Determine Action
+        # Format: "METHOD /path" (e.g., "GET /users")
+        action = f"{request.method} {request.url.path}"
+        logger = get_flow_logger()
+        # 3. Log Request (Source -> App)
+        req_event = FlowEvent(
+            source=source,
+            target=self.app_name,
+            action=action,
+            message=action,
+            params=f"query={request.query_params}" if request.query_params else None,
+            trace_id=trace_id
+        )
+        logger.info(f"{source}->{self.app_name}: {action}", extra={"flow_event": req_event})
+        # 4. Set Context and Process Request
+        # We set the current participant to the app name.
+        # `ascope` ensures this context applies to all code running within `call_next`.
+        async with LogContext.ascope({"participant": self.app_name, "trace_id": trace_id}):
+            start_time = time.time()
+            try:
+                # Pass control to the application
+                response = await call_next(request)
+                # 5. Log Response (App -> Source)
+                duration = (time.time() - start_time) * 1000
+                resp_event = FlowEvent(
+                    source=self.app_name,
+                    target=source,
+                    action=action,
+                    message="Return",
+                    is_return=True,
+                    result=f"{response.status_code} ({duration:.1f}ms)",
+                    trace_id=trace_id
+                )
+                logger.info(f"{self.app_name}->{source}: Return", extra={"flow_event": resp_event})
+                return response
+            except Exception as e:
+                # 6. Log Error (App --x Source)
+                # This captures unhandled exceptions that bubble up to the middleware
+                err_event = FlowEvent(
+                    source=self.app_name,
+                    target=source,
+                    action=action,
+                    message=str(e),
+                    is_return=True,
+                    is_error=True,
+                    error_message=str(e),
+                    trace_id=trace_id
+                )
+                logger.error(f"{self.app_name}-x{source}: Error", extra={"flow_event": err_event})
+                raise

mermaid_trace/py.typed ADDED Viewed

File without changes

mermaid_trace-0.3.1.dist-info/METADATA ADDED Viewed

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: mermaid-trace
+Version: 0.3.1
+Summary: Visualize your Python code execution flow as Mermaid Sequence Diagrams.
+Project-URL: Documentation, https://github.com/xt765/mermaid-trace#readme
+Project-URL: Changelog, https://github.com/xt765/mermaid-trace/blob/main/docs/en/CHANGELOG.md
+Project-URL: Issues, https://github.com/xt765/mermaid-trace/issues
+Project-URL: Source, https://github.com/xt765/mermaid-trace
+Author-email: xt765 <xt765@foxmail.com>
+License: MIT License
+        Copyright (c) 2026 xt765
+        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.
+License-File: LICENSE
+Keywords: asyncio,logging,mermaid,mermaid-trace,sequence-diagram,trace,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: watchdog>=2.0.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+# MermaidTrace: The Python Logger That Draws Diagrams
+[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
+[![License](https://img.shields.io/github/license/xt765/mermaid-trace?style=flat-square)](LICENSE)
+[![CI Status](https://img.shields.io/github/actions/workflow/status/xt765/mermaid-trace/ci.yml?style=flat-square&label=CI)](https://github.com/xt765/mermaid-trace/actions/workflows/ci.yml)
+[![Codecov](https://img.shields.io/codecov/c/github/xt765/mermaid-trace?style=flat-square&logo=codecov)](https://codecov.io/gh/xt765/mermaid-trace)
+**Stop reading logs. Start watching them.**
+MermaidTrace is a specialized logging tool that automatically generates [Mermaid JS](https://mermaid.js.org/) sequence diagrams from your code execution. It's perfect for visualizing complex business logic, microservice interactions, or asynchronous flows.
+## ✨ Features
+- **Decorator-Driven**: Just add `@trace` or `@trace_interaction` to your functions.
+- **Auto-Diagramming**: Generates `.mmd` files that can be viewed in VS Code, GitHub, or Mermaid Live Editor.
+- **Async Support**: Works seamlessly with `asyncio` coroutines.
+- **Context Inference**: Automatically tracks nested calls and infers `source` participants using `contextvars`.
+- **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing.
+- **CLI Tool**: Built-in viewer to preview diagrams in your browser.
+## 🚀 Quick Start
+### Installation
+```bash
+pip install mermaid-trace
+```
+### Basic Usage
+```python
+from mermaid_trace import trace, configure_flow
+import time
+# 1. Configure output
+configure_flow("my_flow.mmd")
+# 2. Add decorators
+@trace(source="Client", target="PaymentService", action="Process Payment")
+def process_payment(amount):
+    if check_balance(amount):
+        return "Success"
+    return "Failed"
+@trace(source="PaymentService", target="Database", action="Check Balance")
+def check_balance(amount):
+    return True
+# 3. Run your code
+process_payment(100)
+```
+### Nested Calls (Context Inference)
+You don't need to specify `source` every time. MermaidTrace infers it from the current context.
+```python
+@trace(source="Client", target="API")
+def main():
+    # Inside here, current participant is "API"
+    service_call()
+@trace(target="Service") # source inferred as "API"
+def service_call():
+    pass
+```
+### FastAPI Integration
+```python
+from fastapi import FastAPI
+from mermaid_trace.integrations.fastapi import MermaidTraceMiddleware
+app = FastAPI()
+app.add_middleware(MermaidTraceMiddleware, app_name="MyAPI")
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}
+```
+### CLI Viewer
+Visualize your generated `.mmd` files instantly:
+```bash
+mermaid-trace serve my_flow.mmd
+```
+## 📂 Documentation
+- [English Documentation](docs/en/README.md)
+- [中文文档](README_CN.md)
+## 🤝 Contributing
+We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
+## 📄 License
+MIT

mermaid_trace-0.3.1.dist-info/RECORD ADDED Viewed

@@ -0,0 +1,15 @@
+mermaid_trace/__init__.py,sha256=yEtdgB0Cl2qAuhGnU0zp9_YANzT3ZIrDsnQu-i3qUAc,2741
+mermaid_trace/cli.py,sha256=_6Bm6oGIUQFbb-tr4yDoZIa9_5PQ-qjftCd7JNUm4F8,7033
+mermaid_trace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mermaid_trace/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mermaid_trace/core/context.py,sha256=H2aXivdarZgpvfAdATRWAAPpf7KHSNqhoJOepd1FK_E,6711
+mermaid_trace/core/decorators.py,sha256=vjTnqxOCbIZXBahpgvXHBp3BFIjnIRk15O2jR9V8Ls4,9274
+mermaid_trace/core/events.py,sha256=SG-S0hZYNa_gEpwB4Cuaahwj9WAMdzS7xXIpThoZzGQ,2999
+mermaid_trace/core/formatter.py,sha256=WKXQeNj4l-LvbF2_Jz8FS3dyWmvtD3CHX2bQKj8p7D0,2765
+mermaid_trace/handlers/mermaid_handler.py,sha256=dZ_T57qWUQlVNWWH5se52mB4ZioECOFwGJF52V-OOps,3931
+mermaid_trace/integrations/fastapi.py,sha256=DeBodoPxXz2nLUIAiqmdVfFrwNVo2P0jhe7rcdF60u4,4991
+mermaid_trace-0.3.1.dist-info/METADATA,sha256=rRBCzhTbof4unI0MPJkj-eHzKTazsodNpdfHpzDPDi0,6181
+mermaid_trace-0.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mermaid_trace-0.3.1.dist-info/entry_points.txt,sha256=WS57KT_870v0A4B87QDjQUqJcddMQxbCQyYeczDAX34,57
+mermaid_trace-0.3.1.dist-info/licenses/LICENSE,sha256=BrBog1Etiq9PdWy0SVQNVByIMD9ss4Edz-R0oXt49zA,1062
+mermaid_trace-0.3.1.dist-info/RECORD,,

mermaid_trace-0.3.1.dist-info/WHEEL ADDED Viewed

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

mermaid_trace-0.3.1.dist-info/entry_points.txt ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ [console_scripts]
2	+ mermaid-trace = mermaid_trace.cli:main

mermaid_trace-0.3.1.dist-info/licenses/LICENSE ADDED Viewed

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