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

mermaid_trace/__init__.py

@@ -7,57 +7,109 @@ developers understand the flow of their applications, debug complex interactions
 and document system behavior.
 
 Key Components:
-- `trace`: A decorator to instrument functions for tracing.
+- `trace`: A decorator to instrument functions for tracing. It captures arguments,
+  return values, and errors, and logs them as interactions.
 - `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.
+  It handles handler configuration, file modes, and async logging setup.
+
+Usage Example:
+    from mermaid_trace import trace, configure_flow
+
+    configure_flow("my_flow.mmd")
+
+    @trace
+    def hello():
+        print("Hello")
+
+    hello()
 """
 
 from .core.decorators import trace_interaction, trace
 from .handlers.mermaid_handler import MermaidFileHandler
-from .core.events import FlowEvent
+from .handlers.async_handler import AsyncMermaidHandler
+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.
 
 from importlib.metadata import PackageNotFoundError, version
+from typing import List, Optional
 
 import logging
 
-def configure_flow(output_file: str = "flow.mmd") -> logging.Logger:
+
+def configure_flow(
+    output_file: str = "flow.mmd",
+    handlers: Optional[List[logging.Handler]] = None,
+    append: bool = False,
+    async_mode: bool = False,
+) -> 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.
-    
+    be called once at the start of your application to initialize the tracing system.
+
     Args:
         output_file (str): The absolute or relative path to the output .mmd file.
                            Defaults to "flow.mmd" in the current directory.
-    
+                           If the file does not exist, it will be created with the correct header.
+        handlers (List[logging.Handler], optional): A list of custom logging handlers.
+                                                    If provided, 'output_file' is ignored unless
+                                                    you explicitly include a MermaidFileHandler.
+                                                    Useful if you want to stream logs to other destinations.
+        append (bool): If True, adds the new handler(s) without removing existing ones.
+                       Defaults to False (clears existing handlers to prevent duplicate logging).
+        async_mode (bool): If True, uses a non-blocking background thread for logging (QueueHandler).
+                           Recommended for high-performance production environments to avoid
+                           blocking the main execution thread during file I/O.
+                           Defaults to False.
+
     Returns:
         logging.Logger: The configured logger instance used for flow tracing.
     """
     # Get the specific logger used by the tracing decorators
+    # This logger is isolated from the root logger to prevent pollution
     logger = logging.getLogger("mermaid_trace.flow")
     logger.setLevel(logging.INFO)
-    
+
     # Remove existing handlers to avoid duplicate logs if configured multiple times
-    if logger.hasHandlers():
+    # unless 'append' is requested. This ensures idempotency when calling configure_flow multiple times.
+    if not append and 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)
-    
+
+    # Determine the target handlers
+    target_handlers = []
+
+    if handlers:
+        # Use user-provided handlers if available
+        target_handlers = handlers
+    else:
+        # Create default Mermaid handler
+        # This handler knows how to write the Mermaid header and format events
+        handler = MermaidFileHandler(output_file)
+        handler.setFormatter(MermaidFormatter())
+        target_handlers = [handler]
+
+    if async_mode:
+        # Wrap the target handlers in an AsyncMermaidHandler (QueueHandler)
+        # The QueueListener will pick up logs from the queue and dispatch to target_handlers
+        # This decouples the application execution from the logging I/O
+        async_handler = AsyncMermaidHandler(target_handlers)
+        logger.addHandler(async_handler)
+    else:
+        # Attach handlers directly to the logger for synchronous logging
+        # Simple and reliable for debugging or low-throughput applications
+        for h in target_handlers:
+            logger.addHandler(h)
+
     return logger
 
+
 try:
     # Attempt to retrieve the installed package version
     __version__ = version("mermaid-trace")
@@ -67,4 +119,15 @@ except PackageNotFoundError:
 
 
 # Export public API for easy access
-__all__ = ["trace_interaction", "trace", "configure_flow", "MermaidFileHandler", "LogContext", "FlowEvent", "MermaidFormatter"]
+__all__ = [
+    "trace_interaction",
+    "trace",
+    "configure_flow",
+    "MermaidFileHandler",
+    "AsyncMermaidHandler",
+    "LogContext",
+    "Event",
+    "FlowEvent",
+    "BaseFormatter",
+    "MermaidFormatter",
+]

mermaid_trace/cli.py

@@ -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,13 +15,21 @@ from pathlib import Path
 from typing import Type, Any
 
 try:
-    from watchdog.observers import Observer  
-    from watchdog.events import FileSystemEventHandler  
+    # 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 when watchdog is not installed (minimal install case)
     HAS_WATCHDOG = False
 
-# HTML Template for the preview page
+# 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">
@@ -59,12 +74,15 @@ HTML_TEMPLATE = """
         mermaid.initialize({{ startOnLoad: true, theme: 'default' }});
         
         // Live Reload Logic
+        // We track the file's modification time (mtime) sent by the server.
         const currentMtime = "{mtime}";
         
         function checkUpdate() {{
+            // Poll the /_status endpoint to check if the file has changed on disk
             fetch('/_status')
                 .then(response => response.text())
                 .then(mtime => {{
+                    // If the server reports a different mtime, reload the page
                     if (mtime && mtime !== currentMtime) {{
                         console.log("File changed, reloading...");
                         location.reload();
@@ -74,76 +92,139 @@ HTML_TEMPLATE = """
         }}
         
         // Poll every 1 second
+        // This is a simple alternative to WebSockets for local dev tools
         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."""
+
+def _create_handler(
+    filename: str, path: Path
+) -> Type[http.server.SimpleHTTPRequestHandler]:
+    """
+    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 being served
+        path (Path): Path object pointing to the file on disk
+
+    Returns:
+        Type[SimpleHTTPRequestHandler]: A custom request handler class
+    """
+
     class Handler(http.server.SimpleHTTPRequestHandler):
         """
-        Custom Request Handler to serve the generated HTML dynamically.
+        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
+            """
+            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)
+                    # 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"
-                
+
                 # Inject content into the HTML template
-                html = HTML_TEMPLATE.format(filename=filename, content=content, mtime=mtime)
+                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
+                # 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"))
-                
+
             else:
-                # Serve static files if needed, or return 404
+                # Serve other 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.
+    Starts a local HTTP server to preview Mermaid diagrams in a web browser.
+
+    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 .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, 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
+    # 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:
-                if not event.is_directory and os.path.abspath(event.src_path) == str(path.resolve()):
+                """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()
+                ):
                     print(f"[Watchdog] File changed: {filename}")
 
         print("Initializing file watcher...")
@@ -151,43 +232,72 @@ def serve(filename: str, port: int = 8000) -> None:
         observer.schedule(FileChangeHandler(), path=str(path.parent), recursive=False)
         observer.start()
     else:
-        print("Watchdog not installed. Falling back to polling mode (client-side only).")
+        print(
+            "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
+    # 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 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)
-    
-    # '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)")
-    
+    # 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"
+    )
+
+    # Define 'serve' command for previewing diagrams
+    serve_parser = subparsers.add_parser(
+        "serve", help="Serve a Mermaid file in the browser with live reload"
+    )
+    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()