PyPI - mermaid-trace - Versions diffs - 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl - Mend

mermaid-trace 0.4.0py3-none-any.whl → 0.4.1py3-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 +4 -2
mermaid_trace/cli.py +88 -46
mermaid_trace/core/context.py +83 -23
mermaid_trace/core/decorators.py +112 -22
mermaid_trace/core/events.py +134 -21
mermaid_trace/core/formatter.py +92 -22
mermaid_trace/handlers/async_handler.py +70 -17
mermaid_trace/handlers/mermaid_handler.py +59 -39
mermaid_trace/integrations/fastapi.py +54 -33
{mermaid_trace-0.4.0.dist-info → mermaid_trace-0.4.1.dist-info}/METADATA +23 -8
mermaid_trace-0.4.1.dist-info/RECORD +16 -0
mermaid_trace-0.4.0.dist-info/RECORD +0 -16
{mermaid_trace-0.4.0.dist-info → mermaid_trace-0.4.1.dist-info}/WHEEL +0 -0
{mermaid_trace-0.4.0.dist-info → mermaid_trace-0.4.1.dist-info}/entry_points.txt +0 -0
{mermaid_trace-0.4.0.dist-info → mermaid_trace-0.4.1.dist-info}/licenses/LICENSE +0 -0

mermaid_trace/__init__.py CHANGED Viewed

@@ -29,9 +29,9 @@ Usage Example:
 from .core.decorators import trace_interaction, trace
 from .handlers.mermaid_handler import MermaidFileHandler
 from .handlers.async_handler import AsyncMermaidHandler
-from .core.events import FlowEvent
+from .core.events import Event, FlowEvent
 from .core.context import LogContext
-from .core.formatter import MermaidFormatter
+from .core.formatter import BaseFormatter, MermaidFormatter
 # We don't import integrations by default to avoid hard dependencies
 # Integrations (like FastAPI) must be imported explicitly by the user if needed.
@@ -126,6 +126,8 @@ __all__ = [
     "MermaidFileHandler",
     "AsyncMermaidHandler",
     "LogContext",
+    "Event",
     "FlowEvent",
+    "BaseFormatter",
     "MermaidFormatter",
 ]

mermaid_trace/cli.py CHANGED Viewed

@@ -1,3 +1,10 @@
+"""
+Command Line Interface Module
+This module provides command-line functionality for MermaidTrace, primarily for
+previewing generated Mermaid diagrams in a web browser with live reload capabilities.
+"""
 import argparse
 import http.server
 import socketserver
@@ -8,22 +15,21 @@ from pathlib import Path
 from typing import Type, Any
 try:
-    # Watchdog is an optional dependency that allows efficient file monitoring.
-    # If installed, we use it to detect file changes instantly.
+    # Watchdog is an optional dependency for efficient file monitoring
+    # If installed, it enables instant file change detection
     from watchdog.observers import Observer
     from watchdog.events import FileSystemEventHandler
     HAS_WATCHDOG = True
 except ImportError:
-    # Fallback for when watchdog is not installed (e.g., minimal install).
+    # Fallback when watchdog is not installed (minimal install case)
     HAS_WATCHDOG = False
-# HTML Template for the preview page
-# This template provides a self-contained environment to render Mermaid diagrams.
-# It includes:
-# 1. Mermaid.js library from CDN.
-# 2. CSS for basic styling and layout.
-# 3. JavaScript logic for auto-refreshing when the source file changes.
+# HTML Template for the diagram preview page
+# Provides a self-contained environment to render Mermaid diagrams with:
+# 1. Mermaid.js library from CDN for diagram rendering
+# 2. Basic CSS styling for readability and layout
+# 3. JavaScript for auto-refreshing when the source file changes
 HTML_TEMPLATE = """
 <!DOCTYPE html>
 <html lang="en">
@@ -98,47 +104,59 @@ def _create_handler(
     filename: str, path: Path
 ) -> Type[http.server.SimpleHTTPRequestHandler]:
     """
-    Factory function to create a custom request handler class.
+    Factory function to create a custom HTTP request handler class.
     This uses a closure to inject `filename` and `path` into the handler's scope,
     allowing the `do_GET` method to access them without global variables.
     Args:
-        filename (str): Display name of the file.
-        path (Path): Path object to the file on disk.
+        filename (str): Display name of the file being served
+        path (Path): Path object pointing to the file on disk
     Returns:
-        Type[SimpleHTTPRequestHandler]: A custom handler class.
+        Type[SimpleHTTPRequestHandler]: A custom request handler class
     """
     class Handler(http.server.SimpleHTTPRequestHandler):
         """
-        Custom Request Handler to serve the generated HTML dynamically.
-        It intercepts GET requests to serve the constructed HTML instead of static files.
+        Custom HTTP Request Handler for serving Mermaid diagram previews.
+        This handler intercepts GET requests to:
+        - Serve the HTML wrapper with embedded diagram content at the root path ('/')
+        - Provide file modification time for live reload at '/_status'
+        - Fall back to default behavior for other paths
         """
         def log_message(self, format: str, *args: Any) -> None:
-            # Suppress default logging to keep console clean
-            # We only want to see application logs, not every HTTP request
+            """
+            Suppress default request logging to keep the console clean.
+            Only application logs are shown, not every HTTP request.
+            """
             pass
         def do_GET(self) -> None:
             """
-            Handle GET requests.
-            Serves the HTML wrapper for the root path ('/').
+            Handle GET requests for different paths.
+            Routes:
+            - '/'          : Serves HTML wrapper with embedded Mermaid content
+            - '/_status'   : Returns current file modification time for live reload
+            - other paths  : Falls back to default SimpleHTTPRequestHandler behavior
             """
             if self.path == "/":
+                # Serve the main HTML page with embedded diagram
                 self.send_response(200)
                 self.send_header("Content-type", "text/html")
                 self.end_headers()
                 try:
-                    # Read the current content of the mermaid file
+                    # Read 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)
-                    # Show the error directly in the diagram area
+                    # Fallback if reading fails (e.g., file locked, permission error)
+                    # Display error directly in the diagram area
                     content = f"sequenceDiagram\nNote right of Error: Failed to read file: {e}"
                     mtime = "0"
@@ -149,14 +167,15 @@ def _create_handler(
                 self.wfile.write(html.encode("utf-8"))
             elif self.path == "/_status":
-                # API endpoint for client-side polling.
-                # Returns the current modification time of the file.
+                # API endpoint for client-side polling
+                # Returns current file modification time as plain text
                 self.send_response(200)
                 self.send_header("Content-type", "text/plain")
                 self.end_headers()
                 try:
                     mtime = str(path.stat().st_mtime)
                 except OSError:
+                    # Fallback if file can't be accessed
                     mtime = "0"
                 self.wfile.write(mtime.encode("utf-8"))
@@ -169,35 +188,40 @@ def _create_handler(
 def serve(filename: str, port: int = 8000) -> None:
     """
-    Starts a local HTTP server to preview the Mermaid diagram.
+    Starts a local HTTP server to preview Mermaid diagrams in a web browser.
-    This function blocks the main thread and runs a TCP server.
-    It automatically opens the default web browser to the preview URL.
+    This function blocks the main thread while running a TCP server. It automatically
+    opens the default web browser to the preview URL and supports live reload when
+    the source .mmd file changes.
     Features:
-    - Serves the .mmd file wrapped in an HTML viewer.
-    - Uses Watchdog (if available) or client-side polling for live reloads.
-    - Gracefully handles shutdown on Ctrl+C.
+    - Serves .mmd files wrapped in an HTML viewer with Mermaid.js
+    - Live reload functionality using Watchdog (if available) or client-side polling
+    - Graceful shutdown handling on Ctrl+C
+    - Automatic browser opening
     Args:
-        filename (str): Path to the .mmd file to serve.
-        port (int): Port to bind the server to. Default is 8000.
+        filename (str): Path to the .mmd file to serve
+        port (int, optional): Port to bind the server to. Defaults to 8000.
     """
+    # Resolve the file path
     path = Path(filename)
     if not path.exists():
         print(f"Error: File '{filename}' not found.")
         sys.exit(1)
-    # Setup Watchdog if available
-    # Watchdog allows us to print console messages when the file changes.
-    # The actual browser reload is triggered by the client polling the /_status endpoint,
-    # but Watchdog gives immediate feedback in the terminal.
+    # Setup Watchdog file watcher if available
+    # Watchdog provides immediate file change notifications in the terminal
+    # The actual browser reload is handled by client-side polling
     observer = None
     if HAS_WATCHDOG:
         class FileChangeHandler(FileSystemEventHandler):
+            """Watchdog event handler for detecting changes to the served file"""
             def on_modified(self, event: Any) -> None:
-                # Filter for the specific file we are watching
+                """Called when a file is modified"""
+                # Filter only for modifications to our specific file
                 if not event.is_directory and os.path.abspath(event.src_path) == str(
                     path.resolve()
                 ):
@@ -212,50 +236,68 @@ def serve(filename: str, port: int = 8000) -> None:
             "Watchdog not installed. Falling back to polling mode (client-side only)."
         )
+    # Create the custom HTTP handler
     HandlerClass = _create_handler(filename, path)
+    # Print server information
     print(f"Serving {filename} at http://localhost:{port}")
     print("Press Ctrl+C to stop.")
-    # Open browser automatically to the server URL
+    # Automatically open the default web browser to the preview URL
     webbrowser.open(f"http://localhost:{port}")
     # Start the TCP server
-    # ThreadingTCPServer is used to handle multiple requests concurrently if needed,
-    # ensuring the browser polling doesn't block the initial load.
+    # Using ThreadingTCPServer to handle multiple requests concurrently
+    # This ensures browser polling doesn't block the initial page load
     with socketserver.ThreadingTCPServer(("", port), HandlerClass) as httpd:
         try:
+            # Serve forever until interrupted
             httpd.serve_forever()
         except KeyboardInterrupt:
+            # Handle Ctrl+C gracefully
             print("\nStopping server...")
+            # Stop the watchdog observer if it was started
             if observer:
                 observer.stop()
                 observer.join()
+            # Close the server
             httpd.server_close()
 def main() -> None:
     """
     Entry point for the CLI application.
-    Parses arguments and dispatches to the appropriate command handler.
+    Parses command-line arguments and dispatches to the appropriate command handler.
+    Currently supports only the 'serve' command for previewing Mermaid diagrams.
     """
-    parser = argparse.ArgumentParser(description="MermaidTrace CLI")
-    subparsers = parser.add_subparsers(dest="command", required=True)
+    # Create argument parser
+    parser = argparse.ArgumentParser(
+        description="MermaidTrace CLI - Preview Mermaid diagrams in browser"
+    )
+    # Add subparsers for different commands
+    subparsers = parser.add_subparsers(
+        dest="command", required=True, help="Available commands"
+    )
-    # 'serve' command definition
+    # Define 'serve' command for previewing diagrams
     serve_parser = subparsers.add_parser(
-        "serve", help="Serve a Mermaid file in the browser"
+        "serve", help="Serve a Mermaid file in the browser with live reload"
     )
-    serve_parser.add_argument("file", help="Path to the .mmd file")
+    serve_parser.add_argument("file", help="Path to the .mmd file to serve")
     serve_parser.add_argument(
         "--port", type=int, default=8000, help="Port to bind to (default: 8000)"
     )
+    # Parse arguments and execute command
     args = parser.parse_args()
     if args.command == "serve":
+        # Execute the serve command
         serve(args.file, args.port)
 if __name__ == "__main__":
+    # Run the main function when script is executed directly
     main()

mermaid_trace/core/context.py CHANGED Viewed

@@ -1,3 +1,12 @@
+"""
+Log Context Management Module
+This module provides a thread-safe, async-friendly context management system
+for tracking execution context across the application. It uses Python's ContextVar
+mechanism to ensure proper context propagation in both synchronous and asynchronous
+environments.
+"""
 from contextvars import ContextVar, Token
 from contextlib import asynccontextmanager, contextmanager
 from typing import Any, AsyncIterator, Dict, Iterator
@@ -9,16 +18,14 @@ 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
+    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).
+    # ContextVar stores a dictionary unique to the current execution context (Task/Thread)
+    # The name "log_context" is used for debugging purposes
     _context_store: ContextVar[Dict[str, Any]] = ContextVar("log_context")
     @classmethod
@@ -27,13 +34,19 @@ class LogContext:
         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.
+        it creates a fresh empty dictionary, sets it to the contextvar,
+        and returns it. This prevents LookupError and ensures there's
+        always a valid dictionary to work with.
+        Returns:
+            Dict[str, Any]: Current context dictionary for the execution flow
         """
         try:
             return cls._context_store.get()
         except LookupError:
-            return {}
+            empty_dict: Dict[str, Any] = {}
+            cls._context_store.set(empty_dict)
+            return empty_dict
     @classmethod
     def set(cls, key: str, value: Any) -> None:
@@ -42,10 +55,14 @@ class LogContext:
         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.
+        1. Retrieve the current dictionary using _get_store()
+        2. Create a shallow copy to avoid affecting parent contexts
+        3. Update the copy with the new key-value pair
+        4. Re-set the ContextVar with the new dictionary
+        Args:
+            key (str): Name of the context variable to set
+            value (Any): Value to associate with the key
         """
         ctx = cls._get_store().copy()
         ctx[key] = value
@@ -57,7 +74,10 @@ class LogContext:
         Updates multiple keys in the current context at once.
         This follows the same Copy-Update-Set pattern as `set()` to maintain
-        context isolation.
+        context isolation between different execution flows.
+        Args:
+            data (Dict[str, Any]): Dictionary of key-value pairs to update in context
         """
         if not data:
             return
@@ -69,6 +89,13 @@ class LogContext:
     def get(cls, key: str, default: Any = None) -> Any:
         """
         Retrieves a value from the current context safely.
+        Args:
+            key (str): Name of the context variable to retrieve
+            default (Any, optional): Default value if key doesn't exist. Defaults to None.
+        Returns:
+            Any: Value associated with the key, or default if key not found
         """
         return cls._get_store().get(key, default)
@@ -76,6 +103,9 @@ class LogContext:
     def get_all(cls) -> Dict[str, Any]:
         """
         Returns a copy of the entire context dictionary.
+        Returns:
+            Dict[str, Any]: Complete copy of the current context
         """
         return cls._get_store().copy()
@@ -92,11 +122,17 @@ class LogContext:
             # 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.
+            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.
+               before the block entered
+        Args:
+            data (Dict[str, Any]): Dictionary of context values to set within the scope
+        Yields:
+            None: Control to the block using this context manager
         """
         current_ctx = cls._get_store().copy()
         current_ctx.update(data)
@@ -104,7 +140,7 @@ class LogContext:
         try:
             yield
         finally:
-            # Crucial: Reset restores the context to what it was before .set()
+            # Reset restores context to state before .set() was called
             cls._context_store.reset(token)
     @classmethod
@@ -120,6 +156,12 @@ class LogContext:
         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.
+        Args:
+            data (Dict[str, Any]): Dictionary of context values to set within the scope
+        Yields:
+            None: Control to the async block using this context manager
         """
         current_ctx = cls._get_store().copy()
         current_ctx.update(data)
@@ -137,6 +179,12 @@ class LogContext:
         """
         Replaces the entire context with the provided data.
         Returns a Token that can be used to manually reset the context later.
+        Args:
+            data (Dict[str, Any]): New context dictionary to replace the current one
+        Returns:
+            Token[Dict[str, Any]]: Token for resetting context to previous state
         """
         return cls._context_store.set(data.copy())
@@ -144,21 +192,30 @@ class LogContext:
     def reset(cls, token: Token[Dict[str, Any]]) -> None:
         """
         Manually resets the context using a Token obtained from `set` or `set_all`.
+        Args:
+            token (Token[Dict[str, Any]]): Token returned by set_all() method
         """
         cls._context_store.reset(token)
     @classmethod
     def current_participant(cls) -> str:
         """
-        Helper to get the 'participant' field, representing the current active object/module.
+        Helper method to get the 'participant' field, representing the current active object/module.
         Defaults to 'Unknown' if not set.
+        Returns:
+            str: Name of the current participant in the trace flow
         """
         return str(cls.get("participant", "Unknown"))
     @classmethod
     def set_participant(cls, name: str) -> None:
         """
-        Helper to set the 'participant' field.
+        Helper method to set the 'participant' field.
+        Args:
+            name (str): Name of the participant to set
         """
         cls.set("participant", name)
@@ -170,9 +227,12 @@ class LogContext:
         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.
+        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.
+           (unless manually changed), linking all subsequent logs together
+        Returns:
+            str: Unique trace ID for the current execution flow
         """
         tid = cls.get("trace_id")
         if not tid:

mermaid-trace 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

mermaid-trace 0.4.0py3-none-any.whl → 0.4.1py3-none-any.whl