mermaid-trace 0.4.0__py3-none-any.whl → 0.5.3.post0__py3-none-any.whl

mermaid_trace/__init__.py

@@ -27,16 +27,41 @@ Usage Example:
 """
 
 from .core.decorators import trace_interaction, trace
-from .handlers.mermaid_handler import MermaidFileHandler
+from .core.utils import trace_class, patch_object
+from .handlers.mermaid_handler import (
+    MermaidFileHandler,
+    RotatingMermaidFileHandler,
+    TimedRotatingMermaidFileHandler,
+)
 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
+from .core.config import config, MermaidConfig
+
+__all__ = [
+    "trace_interaction",
+    "trace",
+    "trace_class",
+    "patch_object",
+    "MermaidFileHandler",
+    "RotatingMermaidFileHandler",
+    "TimedRotatingMermaidFileHandler",
+    "AsyncMermaidHandler",
+    "Event",
+    "FlowEvent",
+    "LogContext",
+    "BaseFormatter",
+    "MermaidFormatter",
+    "config",
+    "MermaidConfig",
+    "configure_flow",
+]
 # 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
+from typing import List, Optional, Dict, Any
 
 import logging
 
@@ -45,8 +70,12 @@ def configure_flow(
     output_file: str = "flow.mmd",
     handlers: Optional[List[logging.Handler]] = None,
     append: bool = False,
+    overwrite: bool = True,
     async_mode: bool = False,
-) -> logging.Logger:
+    level: int = logging.INFO,
+    config_overrides: Optional[Dict[str, Any]] = None,
+    queue_size: Optional[int] = None,
+) -> logging.Logger:  # noqa: PLR0913
     """
     Configures the flow logger to output to a Mermaid file.
 
@@ -64,18 +93,30 @@ def configure_flow(
                                                     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).
+        overwrite (bool): If True, overwrites the output file if it already exists.
+                         If False, appends to the existing file. Defaults to True.
         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.
+        level (int): Logging level. Defaults to logging.INFO.
+        config_overrides (Dict[str, Any], optional): Dictionary to override default configuration settings.
+                                                     Keys should match MermaidConfig attributes.
+        queue_size (int, optional): Size of the async queue. If provided, overrides config.queue_size.
 
     Returns:
         logging.Logger: The configured logger instance used for flow tracing.
     """
+    # Apply configuration overrides
+    if config_overrides:
+        for k, v in config_overrides.items():
+            if hasattr(config, k):
+                setattr(config, k, v)
+
     # 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)
+    logger.setLevel(level)
 
     # Remove existing handlers to avoid duplicate logs if configured multiple times
     # unless 'append' is requested. This ensures idempotency when calling configure_flow multiple times.
@@ -91,15 +132,21 @@ def configure_flow(
     else:
         # Create default Mermaid handler
         # This handler knows how to write the Mermaid header and format events
-        handler = MermaidFileHandler(output_file)
+        mode = "w" if overwrite else "a"
+        handler = MermaidFileHandler(output_file, mode=mode)
         handler.setFormatter(MermaidFormatter())
         target_handlers = [handler]
 
     if async_mode:
+        # Determine queue size
+        final_queue_size = queue_size if queue_size is not None else config.queue_size
+
         # 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)
+        async_handler = AsyncMermaidHandler(
+            target_handlers, queue_size=final_queue_size
+        )
         logger.addHandler(async_handler)
     else:
         # Attach handlers directly to the logger for synchronous logging
@@ -116,16 +163,3 @@ try:
 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",
-    "AsyncMermaidHandler",
-    "LogContext",
-    "FlowEvent",
-    "MermaidFormatter",
-]

mermaid_trace/cli.py

@@ -1,3 +1,22 @@
+"""
+Command Line Interface (CLI) Module for MermaidTrace.
+
+This module serves as the entry point for the MermaidTrace command-line tools.
+It provides functionality to:
+1.  **Serve** Mermaid diagram files (.mmd) via a local HTTP server.
+2.  **Preview** diagrams in a web browser with live-reload capabilities.
+3.  **Monitor** file changes using polling or filesystem events (via `watchdog`).
+
+Key Components:
+-   `serve`: The primary command function that sets up the HTTP server and file watcher.
+-   `_create_handler`: A factory function that generates a custom request handler with access to the target file.
+-   `HTML_TEMPLATE`: A self-contained HTML page that renders Mermaid diagrams using the Mermaid.js CDN.
+
+Usage:
+    Run this module directly or via the `mermaid-trace` command (if installed).
+    Example: `python -m mermaid_trace.cli serve diagram.mmd --port 8080`
+"""
+
 import argparse
 import http.server
 import socketserver
@@ -7,23 +26,28 @@ import os
 from pathlib import Path
 from typing import Type, Any
 
+# Attempt to import `watchdog` for efficient file system monitoring.
+# `watchdog` is an external library that allows the program to react to file events (like modifications) immediately.
+# We handle the ImportError gracefully to allow the CLI to function (via polling) even if `watchdog` is not installed.
 try:
-    # Watchdog is an optional dependency that allows efficient file monitoring.
-    # If installed, we use it to detect file changes instantly.
     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).
+    # If watchdog is missing, we fall back to a simpler polling mechanism in the browser
     HAS_WATCHDOG = False
 
-# HTML Template for the preview page
-# This template provides a self-contained environment to render Mermaid diagrams.
+# HTML Template for the diagram preview page.
+# This string contains the full HTML structure served to the browser.
+#
 # 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.
+# 1.  **Mermaid.js CDN**: Loads the library required to render the diagrams client-side.
+# 2.  **CSS Styling**: Basic styles for layout, readability, and the "Refresh" button.
+# 3.  **JavaScript Logic**:
+#     -   Initializes Mermaid.js.
+#     -   Implements a polling mechanism (`checkUpdate`) that hits the `/_status` endpoint.
+#     -   Reloads the page automatically if the server reports a newer file modification time.
 HTML_TEMPLATE = """
 <!DOCTYPE html>
 <html lang="en">
@@ -31,20 +55,30 @@ HTML_TEMPLATE = """
     <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 -->
+    <!-- Load Mermaid.js from CDN (Content Delivery Network) -->
+    <!-- This library parses the text-based diagram definition and renders it as an SVG -->
     <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 for the diagram to give it a "card" look */
         .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 */
+        
+        /* Allow horizontal scrolling for wide diagrams that might overflow the screen */
+        #diagram {{ overflow-x: auto; }}
+        
+        /* Floating refresh button for manual reloads */
         .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 indicator to show the user that the live-reload is active */
         .status {{
             position: fixed; bottom: 20px; left: 20px;
             font-size: 12px; color: #666;
@@ -54,29 +88,38 @@ HTML_TEMPLATE = """
 <body>
     <div class="container">
         <h1>MermaidTrace Flow Preview: {filename}</h1>
-        <!-- The Mermaid diagram content will be injected here -->
+        <!-- The Mermaid diagram content will be injected here by the Python server -->
+        <!-- The 'mermaid' class triggers the Mermaid.js library to process this div -->
         <div class="mermaid" id="diagram">
             {content}
         </div>
     </div>
-    <!-- Button to manually reload the page/diagram -->
+    
+    <!-- Button to manually reload the page/diagram if auto-reload fails or is slow -->
     <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
+        // Initialize Mermaid with default settings.
+        // 'startOnLoad: true' tells Mermaid to find all .mermaid classes and render them immediately.
         mermaid.initialize({{ startOnLoad: true, theme: 'default' }});
         
-        // Live Reload Logic
-        // We track the file's modification time (mtime) sent by the server.
+        // --- Live Reload Logic ---
+        
+        // We track the file's modification time (mtime) sent by the server during the initial page load.
+        // This value is injected into the template by Python.
         const currentMtime = "{mtime}";
         
+        /**
+         * Checks the server for updates to the source file.
+         * It fetches the '/_status' endpoint which returns the current file 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 the server reports a different mtime than what we loaded with,
+                    // it means the file has changed on disk. We reload the page to see the new diagram.
                     if (mtime && mtime !== currentMtime) {{
                         console.log("File changed, reloading...");
                         location.reload();
@@ -85,8 +128,9 @@ HTML_TEMPLATE = """
                 .catch(err => console.error("Error checking status:", err));
         }}
         
-        // Poll every 1 second
-        // This is a simple alternative to WebSockets for local dev tools
+        // Poll every 1 second (1000 milliseconds).
+        // This is a simple, robust alternative to WebSockets for local development tools.
+        // It creates minimal load for a local server.
         setInterval(checkUpdate, 1000);
     </script>
 </body>
@@ -98,70 +142,91 @@ 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.
+    We use a factory function (a function that returns a class) because `socketserver`
+    expects a class type, not an instance. This allows us to "close over" the `filename`
+    and `path` variables, making them available to the handler class without using globals.
 
     Args:
-        filename (str): Display name of the file.
-        path (Path): Path object to the file on disk.
+        filename (str): The display name of the file being served (used in the HTML title).
+        path (Path): The `pathlib.Path` object pointing to the actual file on disk.
 
     Returns:
-        Type[SimpleHTTPRequestHandler]: A custom handler class.
+        Type[SimpleHTTPRequestHandler]: A custom class inheriting from `SimpleHTTPRequestHandler`.
     """
 
     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 overrides standard methods to provide two specific endpoints:
+        1.  `/` (Root): Serves the HTML wrapper with the embedded diagram content.
+        2.  `/_status`: Returns the file's current modification time (used for live reload).
         """
 
         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
+            """
+            Override `log_message` to suppress default HTTP request logging.
+
+            By default, `SimpleHTTPRequestHandler` logs every request to stderr.
+            We override this to keep the console output clean, showing only important application logs.
+            """
             pass
 
         def do_GET(self) -> None:
             """
-            Handle GET requests.
-            Serves the HTML wrapper for the root path ('/').
+            Handle HTTP GET requests.
+
+            Routes:
+            -   **/**: Reads the target file, injects it into `HTML_TEMPLATE`, and serves the HTML.
+            -   **/_status**: Checks the file's modification time and returns it as plain text.
+            -   **Others**: Falls back to the default file serving behavior (though typically not used here).
             """
             if self.path == "/":
+                # --- Root Endpoint: Serve the HTML Page ---
                 self.send_response(200)
                 self.send_header("Content-type", "text/html")
                 self.end_headers()
 
                 try:
-                    # Read the current content of the mermaid file
+                    # Read the current content of the Mermaid file from disk.
+                    # We read it every time the page is requested to ensure we get the latest version.
                     content = path.read_text(encoding="utf-8")
+                    # Get the modification time to embed in the page for the JS poller.
                     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
+                    # Error Handling:
+                    # If reading fails (e.g., file locked, permissions, deleted),
+                    # we render a special Mermaid diagram showing the error message.
+                    # This provides immediate visual feedback in the browser.
                     content = f"sequenceDiagram\nNote right of Error: Failed to read file: {e}"
                     mtime = "0"
 
-                # Inject content into the HTML template
+                # Inject variables 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-side polling.
-                # Returns the current modification time of the file.
+                # --- Status Endpoint: Live Reload Polling ---
+                # The client-side JavaScript calls this endpoint periodically.
                 self.send_response(200)
                 self.send_header("Content-type", "text/plain")
                 self.end_headers()
                 try:
+                    # Return the current modification time as the response body.
                     mtime = str(path.stat().st_mtime)
                 except OSError:
+                    # If the file cannot be accessed (e.g., deleted), return "0".
                     mtime = "0"
                 self.wfile.write(mtime.encode("utf-8"))
 
             else:
-                # Serve other static files if needed, or return 404
+                # --- Fallback: Default Behavior ---
+                # Useful if the HTML template referenced other static assets (images, css files),
+                # though currently everything is embedded.
                 super().do_GET()
 
     return Handler
@@ -169,35 +234,43 @@ def _create_handler(
 
 def serve(filename: str, port: int = 8000) -> None:
     """
-    Starts a local HTTP server to preview the Mermaid diagram.
+    Starts the local HTTP server and file watcher to preview a Mermaid diagram.
 
-    This function blocks the main thread and runs a TCP server.
-    It automatically opens the default web browser to the preview URL.
+    This is the core logic for the `serve` command. It sets up the environment,
+    opens the browser, and enters a blocking loop to serve requests.
 
-    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.
+    Workflow:
+    1.  Validates the input file.
+    2.  Sets up a `watchdog` observer (if installed) for console logging of changes.
+    3.  Creates the custom HTTP handler using `_create_handler`.
+    4.  Opens the user's default web browser to the server URL.
+    5.  Starts a threaded TCP server to handle HTTP requests.
 
     Args:
-        filename (str): Path to the .mmd file to serve.
-        port (int): Port to bind the server to. Default is 8000.
+        filename (str): The path to the .mmd file to serve.
+        port (int): The port number to bind the server to (default: 8000).
     """
+    # Create a Path object for robust file path handling
     path = Path(filename)
+
+    # 1. Validation
     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.
+    # 2. Watchdog Setup (Optional)
+    # If `watchdog` is installed, we use it to print immediate feedback to the console when the file changes.
+    # Note: The browser reload is driven by the JS polling the `/_status` endpoint, not by this observer.
+    # This observer is primarily for developer feedback in the terminal.
     observer = None
     if HAS_WATCHDOG:
 
         class FileChangeHandler(FileSystemEventHandler):
+            """Internal handler class for Watchdog events."""
+
             def on_modified(self, event: Any) -> None:
-                # Filter for the specific file we are watching
+                """Triggered when a file is modified in the watched directory."""
+                # We only care about modifications to the specific file we are serving.
                 if not event.is_directory and os.path.abspath(event.src_path) == str(
                     path.resolve()
                 ):
@@ -205,6 +278,7 @@ def serve(filename: str, port: int = 8000) -> None:
 
         print("Initializing file watcher...")
         observer = Observer()
+        # Watch the directory containing the file, but filter events in the handler
         observer.schedule(FileChangeHandler(), path=str(path.parent), recursive=False)
         observer.start()
     else:
@@ -212,21 +286,28 @@ def serve(filename: str, port: int = 8000) -> None:
             "Watchdog not installed. Falling back to polling mode (client-side only)."
         )
 
+    # 3. Create Server Handler
     HandlerClass = _create_handler(filename, path)
 
+    # 4. User Feedback
     print(f"Serving {filename} at http://localhost:{port}")
     print("Press Ctrl+C to stop.")
 
-    # Open browser automatically to the server URL
+    # 5. Open Browser
+    # We open the browser *before* the server loop blocks, but the request might fail if the server
+    # isn't ready instantly. However, `socketserver` setup is usually fast enough.
     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.
+    # 6. Start Server
+    # We use `ThreadingTCPServer` so that multiple requests (e.g., polling + main page load)
+    # can be handled concurrently. This prevents the polling loop from blocking the page load.
     with socketserver.ThreadingTCPServer(("", port), HandlerClass) as httpd:
         try:
+            # Block and handle requests indefinitely
             httpd.serve_forever()
         except KeyboardInterrupt:
+            # 7. Graceful Shutdown
+            # Catch Ctrl+C to clean up resources properly
             print("\nStopping server...")
             if observer:
                 observer.stop()
@@ -236,26 +317,41 @@ def serve(filename: str, port: int = 8000) -> None:
 
 def main() -> None:
     """
-    Entry point for the CLI application.
-    Parses arguments and dispatches to the appropriate command handler.
+    Main entry point for the CLI application.
+
+    Responsibilities:
+    1.  **Argument Parsing**: Uses `argparse` to define commands and options.
+    2.  **Command Dispatch**: Calls the appropriate function based on the user's command.
     """
-    parser = argparse.ArgumentParser(description="MermaidTrace CLI")
-    subparsers = parser.add_subparsers(dest="command", required=True)
+    # Initialize the argument parser with a description of the tool
+    parser = argparse.ArgumentParser(
+        description="MermaidTrace CLI - Preview Mermaid diagrams in browser"
+    )
+
+    # Create sub-parsers to handle different commands (currently only 'serve')
+    subparsers = parser.add_subparsers(
+        dest="command", required=True, help="Available commands"
+    )
 
-    # 'serve' command definition
+    # --- 'serve' command ---
+    # Defines the 'serve' command which takes a file path and an optional port
     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 the arguments provided by the user
     args = parser.parse_args()
 
+    # Dispatch logic
     if args.command == "serve":
+        # Invoke the serve function with parsed arguments
         serve(args.file, args.port)
 
 
 if __name__ == "__main__":
+    # Standard boilerplate to run the main function when the script is executed directly
     main()

mermaid_trace/core/config.py

@@ -0,0 +1,55 @@
+"""
+Configuration Module for Mermaid Trace
+======================================
+
+This module provides a centralized configuration system for the library.
+It allows users to control behavior globally, such as argument capturing,
+string truncation limits, and logging levels.
+"""
+
+from dataclasses import dataclass
+import os
+
+
+@dataclass
+class MermaidConfig:
+    """
+    Global configuration settings for Mermaid Trace.
+
+    Attributes:
+        capture_args (bool): Whether to capture function arguments and return values.
+                             Defaults to True. Set to False for performance or privacy.
+        max_string_length (int): Maximum length for string representations of objects.
+                                 Defaults to 50. Prevents huge log files.
+        max_arg_depth (int): Maximum recursion depth for nested objects (lists/dicts).
+                             Defaults to 1.
+        queue_size (int): Size of the async queue. Defaults to 1000.
+    """
+
+    capture_args: bool = True
+    max_string_length: int = 50
+    max_arg_depth: int = 1
+    queue_size: int = 1000
+
+    @classmethod
+    def from_env(cls) -> "MermaidConfig":
+        """
+        Loads configuration from environment variables.
+
+        Env Vars:
+            MERMAID_TRACE_CAPTURE_ARGS (bool): "true"/"false"
+            MERMAID_TRACE_MAX_STRING_LENGTH (int)
+            MERMAID_TRACE_MAX_ARG_DEPTH (int)
+            MERMAID_TRACE_QUEUE_SIZE (int)
+        """
+        return cls(
+            capture_args=os.getenv("MERMAID_TRACE_CAPTURE_ARGS", "true").lower()
+            == "true",
+            max_string_length=int(os.getenv("MERMAID_TRACE_MAX_STRING_LENGTH", "50")),
+            max_arg_depth=int(os.getenv("MERMAID_TRACE_MAX_ARG_DEPTH", "1")),
+            queue_size=int(os.getenv("MERMAID_TRACE_QUEUE_SIZE", "1000")),
+        )
+
+
+# Global configuration instance
+config = MermaidConfig()