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

mermaid_trace/core/events.py

@@ -1,75 +1,190 @@
+"""
+Event Definition Module
+
+This module defines the event structure for the tracing system. It provides an
+abstract Event base class and a concrete FlowEvent implementation that represents
+individual interactions in the execution flow.
+"""
+
+from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 import time
 from typing import Optional
 
+
+class Event(ABC):
+    """
+    Abstract base class for all event types.
+
+    This provides a common interface for different types of events, allowing
+    for extensibility and supporting multiple output formats. Concrete event
+    classes must implement all abstract methods.
+    """
+
+    @abstractmethod
+    def get_source(self) -> str:
+        """
+        Get the source of the event.
+
+        Returns:
+            str: Name of the participant that generated the event
+        """
+        pass
+
+    @abstractmethod
+    def get_target(self) -> str:
+        """
+        Get the target of the event.
+
+        Returns:
+            str: Name of the participant that received the event
+        """
+        pass
+
+    @abstractmethod
+    def get_action(self) -> str:
+        """
+        Get the action name of the event.
+
+        Returns:
+            str: Short name describing the action performed
+        """
+        pass
+
+    @abstractmethod
+    def get_message(self) -> str:
+        """
+        Get the message text of the event.
+
+        Returns:
+            str: Detailed message describing the event
+        """
+        pass
+
+    @abstractmethod
+    def get_timestamp(self) -> float:
+        """
+        Get the timestamp of the event.
+
+        Returns:
+            float: Unix timestamp (seconds) when the event occurred
+        """
+        pass
+
+    @abstractmethod
+    def get_trace_id(self) -> str:
+        """
+        Get the trace ID of the event.
+
+        Returns:
+            str: Unique identifier for the trace session
+        """
+        pass
+
+
 @dataclass
-class FlowEvent:
+class FlowEvent(Event):
     """
     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
+    runtime code execution and the final diagram output. Each instance
     corresponds directly to one arrow or note in the sequence diagram.
-    
-    The fields map to Mermaid syntax components as follows:
+
+    The fields map to diagram syntax components as follows:
     `source` -> `target`: `message`
-    
+
     Attributes:
-        source (str): 
+        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): 
+            In sequence diagrams: 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): 
+            In sequence diagrams: 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): 
+
+        message (str):
             The actual text label displayed on the diagram arrow.
             Example: "getUser(id=1)" or "Return: User(name='Alice')".
-            
-        timestamp (float): 
+
+        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): 
+            Used for ordering events if logs are processed asynchronously.
+            Defaults to current time when event is created.
+
+        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): 
+
+        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): 
+            If True, the arrow is drawn as a dotted line in sequence diagrams.
+            If False, it is a solid line representing a call.
+            Defaults to False.
+
+        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]): 
+            If True, the arrow might be styled differently to show failure.
+            Defaults to False.
+
+        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]): 
+            Defaults to None.
+
+        params (Optional[str]):
             Stringified representation of function arguments.
             Captured only for request events (call start).
-            
-        result (Optional[str]): 
+            Defaults to None.
+
+        result (Optional[str]):
             Stringified representation of the return value.
             Captured only for return events (call end).
+            Defaults to None.
     """
-    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
+
+    # Required fields for every event
+    source: str  # Participant who initiated the action
+    target: str  # Participant who received the action
+    action: str  # Short name for the operation
+    message: str  # Detailed message for the diagram arrow
+    trace_id: str  # Unique identifier for the trace session
+
+    # Optional fields with defaults
+    timestamp: float = field(
+        default_factory=time.time
+    )  # Unix timestamp of event creation
+    is_return: bool = False  # Whether this is a response arrow
+    is_error: bool = False  # Whether an error occurred
+    error_message: Optional[str] = None  # Detailed error message if is_error is True
+    params: Optional[str] = None  # Stringified function arguments
+    result: Optional[str] = None  # Stringified return value
+
+    def get_source(self) -> str:
+        """Get the source of the event."""
+        return self.source
+
+    def get_target(self) -> str:
+        """Get the target of the event."""
+        return self.target
+
+    def get_action(self) -> str:
+        """Get the action name of the event."""
+        return self.action
+
+    def get_message(self) -> str:
+        """Get the message text of the event."""
+        return self.message
+
+    def get_timestamp(self) -> float:
+        """Get the timestamp of the event."""
+        return self.timestamp
+
+    def get_trace_id(self) -> str:
+        """Get the trace ID of the event."""
+        return self.trace_id

mermaid_trace/core/formatter.py

@@ -1,72 +1,151 @@
+"""
+Event Formatting Module
+
+This module provides formatters to convert Event objects into various output formats.
+Currently, it supports Mermaid sequence diagram syntax formatting, but can be extended
+with additional formatters for other diagram types or logging formats.
+"""
+
 import logging
 import re
+from abc import ABC, abstractmethod
 from typing import Optional
-from .events import FlowEvent
+from .events import Event, FlowEvent
+
 
-class MermaidFormatter(logging.Formatter):
+class BaseFormatter(ABC, logging.Formatter):
     """
-    Custom formatter to convert FlowEvents into Mermaid sequence diagram syntax.
+    Abstract base class for all event formatters.
+
+    This provides a common interface for different formatters, allowing
+    for extensibility and supporting multiple output formats.
+
+    Subclasses must implement the format_event method to convert Event objects
+    into the desired output string format.
     """
 
+    @abstractmethod
+    def format_event(self, event: Event) -> str:
+        """
+        Format an Event into the desired output string.
+
+        Args:
+            event: The Event object to format
+
+        Returns:
+            str: Formatted string representation of the event
+        """
+        pass
+
     def format(self, record: logging.LogRecord) -> str:
-        # 1. Retrieve the FlowEvent
-        event: Optional[FlowEvent] = getattr(record, 'flow_event', None)
-        
+        """
+        Format a logging record containing an event.
+
+        This method overrides the standard logging.Formatter.format method to
+        extract and format Event objects from log records.
+
+        Args:
+            record: The logging record to format. Must contain a 'flow_event' attribute
+                   if it represents a tracing event.
+
+        Returns:
+            str: Formatted string representation of the record
+        """
+        # Retrieve the Event object from the log record
+        event: Optional[Event] = 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)
+        # Convert event to the desired format using the subclass's format_event method
+        return self.format_event(event)
+
 
-    def _to_mermaid_line(self, event: FlowEvent) -> str:
+class MermaidFormatter(BaseFormatter):
+    """
+    Custom formatter to convert Events into Mermaid sequence diagram syntax.
+
+    This formatter transforms FlowEvent objects into lines of Mermaid syntax that
+    can be directly written to a .mmd file. Each event becomes a single line in the
+    sequence diagram.
+    """
+
+    def format_event(self, event: Event) -> str:
         """
-        Converts a FlowEvent into a Mermaid syntax string.
+        Converts an Event into a Mermaid syntax string.
+
+        Args:
+            event: The Event object to format
+
+        Returns:
+            str: Mermaid syntax string representation of the event
         """
-        # Sanitize participant names
+        if not isinstance(event, FlowEvent):
+            # Fallback format for non-FlowEvent types
+            return f"{event.get_source()}->>{event.get_target()}: {event.get_message()}"
+
+        # Sanitize participant names to avoid syntax errors in Mermaid
         src = self._sanitize(event.source)
         tgt = self._sanitize(event.target)
-        
-        # Determine arrow type
+
+        # Determine arrow type based on event properties
         # ->> : Solid line with arrowhead (synchronous call)
         # -->> : Dotted line with arrowhead (return)
         # --x : Dotted line with cross (error)
         arrow = "-->>" if event.is_return else "->>"
-        
+
+        # Construct message text based on event type
+        msg = ""
         if event.is_error:
             arrow = "--x"
             msg = f"Error: {event.error_message}"
         elif event.is_return:
+            # For return events, show return value or just "Return"
             msg = f"Return: {event.result}" if event.result else "Return"
         else:
+            # For call events, show Action(Params) or just Action
             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
+
+        # Escape message for Mermaid safety (e.g., replacing newlines)
         msg = self._escape_message(msg)
-        
+
+        # Return the complete Mermaid syntax line
+        # Format: Source->>Target: Message
         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.
+
+        Mermaid doesn't like spaces or special characters in participant aliases
+        unless they are quoted (which we are not doing here for simplicity),
+        so we replace them with underscores.
+
+        Args:
+            name: Original participant name
+
+        Returns:
+            str: Sanitized participant name
         """
         # 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)
+        clean_name = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+        # Ensure it doesn't start with a digit (Mermaid doesn't like that sometimes)
         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.
+        Escapes special characters in the message text for safe Mermaid rendering.
+
+        Args:
+            msg: Original message text
+
+        Returns:
+            str: Escaped message text
         """
-        # 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.
+        # Replace newlines with <br/> for proper display in Mermaid diagrams
+        msg = msg.replace("\n", "<br/>")
+        # Additional escaping could be added here if needed for other characters
         return msg

mermaid_trace/handlers/async_handler.py

@@ -0,0 +1,105 @@
+"""
+Asynchronous Mermaid Handler Module
+
+This module provides a non-blocking logging handler that uses a background thread
+for writing logs. It's designed to improve performance in high-throughput applications
+by decoupling the logging I/O from the main execution thread.
+"""
+
+import logging
+import logging.handlers
+import queue
+import atexit
+from typing import List, Optional
+
+
+class AsyncMermaidHandler(logging.handlers.QueueHandler):
+    """
+    A non-blocking logging handler that uses a background thread to write logs.
+
+    This handler pushes log records to a queue, which are then picked up by a
+    QueueListener running in a separate thread and dispatched to the actual
+    handlers (e.g., MermaidFileHandler).
+
+    This architecture provides several benefits:
+    - Main thread doesn't block waiting for disk I/O
+    - Logs are processed in the background
+    - Better performance in high-throughput applications
+    - Smooth handling of burst traffic
+    """
+
+    def __init__(self, handlers: List[logging.Handler], queue_size: int = 1000):
+        """
+        Initialize the async handler.
+
+        Args:
+            handlers: A list of handlers that should receive the logs from the queue.
+                      These are typically MermaidFileHandler instances.
+            queue_size: The maximum size of the queue. Default is 1000.
+                       If the queue fills up, new log records may be dropped.
+        """
+        # Create a bounded queue with the specified size
+        self._log_queue: queue.Queue[logging.LogRecord] = queue.Queue(queue_size)
+        self._queue_size = queue_size
+
+        # Initialize parent QueueHandler with our queue
+        super().__init__(self._log_queue)
+
+        # Initialize QueueListener to process records from the queue
+        # It starts an internal thread to monitor the queue
+        # respect_handler_level=True ensures the target handlers' log levels are respected
+        self._listener: Optional[logging.handlers.QueueListener] = (
+            logging.handlers.QueueListener(
+                self._log_queue, *handlers, respect_handler_level=True
+            )
+        )
+
+        # Start the listener thread
+        self._listener.start()
+
+        # Register stop method to be called on program exit
+        # This ensures all pending logs are written to disk before termination
+        atexit.register(self.stop)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        Emit a log record to the queue with a timeout and drop policy.
+
+        If the queue is full, this method will attempt to put the record with
+        a short timeout. If that fails, it will drop the record and print a warning.
+
+        Args:
+            record: The log record to emit
+        """
+        from typing import cast
+
+        try:
+            # Try to put the record in the queue with a short timeout (0.1 seconds)
+            # This prevents the main thread from blocking indefinitely if the queue is full
+            # Use cast to tell Mypy this is a queue.Queue instance
+            queue_instance = cast(queue.Queue[logging.LogRecord], self.queue)
+            queue_instance.put(record, block=True, timeout=0.1)
+        except queue.Full:
+            # If queue is full, log a warning and drop the record
+            if record.levelno >= logging.WARNING:
+                # Avoid infinite recursion by not using self.logger
+                print(
+                    f"WARNING: AsyncMermaidHandler queue is full (size: {self._queue_size}), dropping log record: {record.msg}"
+                )
+
+    def stop(self) -> None:
+        """
+        Stops the listener and flushes all pending logs from the queue.
+
+        This method is registered with `atexit` to ensure that all pending logs
+        are written to disk before the application terminates.
+        """
+        if self._listener:
+            try:
+                # Stop the listener - this will process all remaining records in the queue
+                self._listener.stop()
+                self._listener = None
+            except queue.Full:
+                # Handle case where queue is full when trying to put sentinel value
+                # The listener thread may still be processing, but we can safely exit
+                pass