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

mermaid_trace/handlers/mermaid_handler.py

@@ -1,86 +1,119 @@
+"""
+Mermaid File Handler Module
+
+This module provides a custom logging handler that writes FlowEvent objects to
+Mermaid (.mmd) files. It handles the Mermaid syntax formatting, file headers, and
+ensures thread-safe file writing.
+"""
+
 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, 
+    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 
+    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` 
+    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):
+
+    def __init__(
+        self,
+        filename: str,
+        title: str = "Log Flow",
+        mode: str = "a",
+        encoding: str = "utf-8",
+        delay: bool = False,
+    ):
         """
-        Initialize the handler.
-        
+        Initialize the Mermaid file 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.
+            title (str, optional): The title of the Mermaid diagram. Defaults to "Log Flow".
+            mode (str, optional): File open mode. 'w' (overwrite) or 'a' (append). Defaults to "a".
+            encoding (str, optional): File encoding. Defaults to "utf-8".
+            delay (bool, optional): If True, file opening is deferred until the first call to emit.
+                                   Useful to avoid creating empty files if no logs occur. Defaults to False.
         """
-        # Ensure directory exists to prevent FileNotFoundError on open
+        # Ensure the directory exists to prevent FileNotFoundError when opening the file
         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.
+
+        # Determine if we need to write a header
+        # Header is written only if:
+        # 1. We are overwriting the file (mode='w'), or
+        # 2. We are appending (mode='a') but the file doesn't exist or is empty
         should_write_header = False
-        if mode == 'w':
+        if mode == "w":
             should_write_header = True
-        elif mode == 'a':
+        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)
+
+        # Initialize the parent FileHandler (opens the file unless delay=True)
         super().__init__(filename, mode, encoding, delay)
         self.title = title
-        
-        # Write header immediately if needed.
+
+        # Write the 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.
+        Writes the initial Mermaid syntax lines to the file.
+
+        This setup is required for Mermaid JS or Live Editor to render the diagram correctly.
+        It defines:
+        - Diagram type (sequenceDiagram)
+        - Title of the diagram
+        - Autonumbering of steps
+
+        Thread Safety: Uses the handler's internal lock to prevent concurrent writes
+        when delay=True, ensuring the header is written only once.
         """
-        # 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")
+        # Use the handler's internal lock to ensure thread safety
+        assert self.lock is not None, "Handler lock should always be initialized"
+        with self.lock:
+            # Write to the existing stream if available, otherwise open temporarily
+            if self.stream:
+                # Stream is already open (delay=False or emit() has been called)
+                self.stream.write("sequenceDiagram\n")
+                self.stream.write(f"    title {self.title}\n")
+                self.stream.write("    autonumber\n")
+                # Flush ensures the header is written to disk immediately
+                self.flush()
+            else:
+                # Handle delay=True case: file not yet opened
+                # Temporarily open the file just to write the header
+                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.
-        
+        Process a log record and write it to the Mermaid file.
+
+        This method overrides the parent's emit method to filter out non-FlowEvent records.
+
         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.
+        - Checks for `flow_event` attribute first, acting as a high-performance filter
+        - Only processes records containing structured FlowEvent data
+        - Delegates actual writing to parent's emit() method, which handles locking and flushing
+
+        Args:
+            record (logging.LogRecord): The log record to process
         """
         # Only process records that contain our structured FlowEvent data
-        if hasattr(record, 'flow_event'):
+        # This allows the handler to be attached to the root logger without processing
+        # irrelevant system logs
+        if hasattr(record, "flow_event"):
             super().emit(record)

mermaid_trace/integrations/fastapi.py

@@ -1,3 +1,11 @@
+"""
+FastAPI Integration Module
+
+This module provides middleware for integrating MermaidTrace with FastAPI applications.
+It automatically traces HTTP requests and responses, converting them into Mermaid
+sequence diagram events.
+"""
+
 from typing import Any, TYPE_CHECKING
 import time
 import uuid
@@ -6,92 +14,121 @@ from ..core.events import FlowEvent
 from ..core.context import LogContext
 from ..core.decorators import get_flow_logger
 
+# Conditional imports to support optional FastAPI dependency
 if TYPE_CHECKING:
+    # For type checking only, import the actual FastAPI/Starlette types
     from fastapi import Request, Response
     from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
 else:
     try:
+        # Try to import FastAPI/Starlette at runtime
         from fastapi import Request, Response
-        from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+        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__.
+        # Handle the case where FastAPI/Starlette are not installed
+        # Define dummy types to prevent NameErrors at import time
+        # 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.
+
+    This middleware acts as the entry point for tracing web requests, handling:
+    1. Identification of the client (Source participant)
+    2. Logging of incoming requests
+    3. Initialization of the `LogContext` for the request lifecycle
+    4. Logging of responses or errors
+    5. Cleanup of context after request completion
     """
+
     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").
+            app: The FastAPI application instance
+            app_name: The name of this service to appear in the diagram (e.g., "UserAPI")
+
+        Raises:
+            ImportError: If FastAPI/Starlette are not installed
         """
-        if BaseHTTPMiddleware is object: # type: ignore[comparison-overlap]
-             raise ImportError("FastAPI/Starlette is required to use MermaidTraceMiddleware")
+        # Check if FastAPI is installed by verifying BaseHTTPMiddleware is not our dummy object
+        if BaseHTTPMiddleware is object:  # type: ignore[comparison-overlap]
+            raise ImportError(
+                "FastAPI/Starlette is required to use MermaidTraceMiddleware"
+            )
+
+        # Initialize the parent BaseHTTPMiddleware
         super().__init__(app)
         self.app_name = app_name
 
-    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
         """
-        Intercepts the incoming request.
-        
+        Intercepts and processes incoming HTTP requests.
+
+        This method is called for each incoming request and handles the full
+        request-response cycle tracing.
+
         Args:
-            request (Request): The incoming HTTP request.
-            call_next (Callable): The function to call the next middleware or endpoint.
-            
+            request (Request): The incoming HTTP request object
+            call_next (RequestResponseEndpoint): Function to call the next middleware or endpoint
+
         Returns:
-            Response: The HTTP response.
+            Response: The HTTP response object
         """
-        # 1. Determine Source (Client)
-        # Try to get a specific ID from headers (useful for distributed tracing),
-        # otherwise fallback to "Client".
+        # 1. Determine Source (Client participant)
+        # Try to get a specific ID from X-Source header (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
+
+        # 2. Determine Trace ID
+        # Check for X-Trace-ID header (for distributed tracing) 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")
+
+        # 3. Determine Action name
+        # Format: "METHOD /path" (e.g., "GET /users", "POST /items")
         action = f"{request.method} {request.url.path}"
-        
+
         logger = get_flow_logger()
-        
-        # 3. Log Request (Source -> App)
+
+        # 4. Log Request (Source -> App)
+        # Create and log the initial request event
         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
+            trace_id=trace_id,
+        )
+        logger.info(
+            f"{source}->{self.app_name}: {action}", extra={"flow_event": req_event}
         )
-        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}):
+
+        # 5. Set Context and Process Request
+        # Use async context manager to set the current participant to the app name
+        # This context will be inherited by all code called 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
+                # Pass control to the next middleware or endpoint
+                # This executes the actual route logic and returns the response
                 response = await call_next(request)
-                
-                # 5. Log Response (App -> Source)
+
+                # 6. Log Success Response (App -> Source)
+                # Calculate execution duration in milliseconds
                 duration = (time.time() - start_time) * 1000
                 resp_event = FlowEvent(
                     source=self.app_name,
@@ -100,14 +137,18 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
                     message="Return",
                     is_return=True,
                     result=f"{response.status_code} ({duration:.1f}ms)",
-                    trace_id=trace_id
+                    trace_id=trace_id,
+                )
+                logger.info(
+                    f"{self.app_name}->{source}: Return",
+                    extra={"flow_event": resp_event},
                 )
-                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)
+                # 7. Log Error Response (App --x Source)
                 # This captures unhandled exceptions that bubble up to the middleware
+                # Note: FastAPI's ExceptionHandlers might catch some exceptions before they reach here
                 err_event = FlowEvent(
                     source=self.app_name,
                     target=source,
@@ -116,7 +157,10 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
                     is_return=True,
                     is_error=True,
                     error_message=str(e),
-                    trace_id=trace_id
+                    trace_id=trace_id,
+                )
+                logger.error(
+                    f"{self.app_name}-x{source}: Error", extra={"flow_event": err_event}
                 )
-                logger.error(f"{self.app_name}-x{source}: Error", extra={"flow_event": err_event})
+                # Re-raise the exception to maintain normal error handling flow
                 raise

{mermaid_trace-0.3.1.dist-info → mermaid_trace-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mermaid-trace
-Version: 0.3.1
+Version: 0.4.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
@@ -38,6 +38,8 @@ 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 :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development :: Debuggers
@@ -61,17 +63,31 @@ 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/)
+🌐 **Language**: [English](README.md) | [中文](README_CN.md)
+
+[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square&color=blue)](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)
 
+---
+
+## 📋 Overview
+
 **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
+---
+
+## 📚 Documentation
+
+[User Guide](docs/en/USER_GUIDE.md) · [API Reference](docs/en/API.md) · [Contributing Guidelines](docs/en/CONTRIBUTING.md) · [Changelog](docs/en/CHANGELOG.md) · [License](docs/en/LICENSE)
+
+---
+
+## ✨ Key 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.
@@ -80,6 +96,8 @@ MermaidTrace is a specialized logging tool that automatically generates [Mermaid
 - **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing.
 - **CLI Tool**: Built-in viewer to preview diagrams in your browser.
 
+---
+
 ## 🚀 Quick Start
 
 ### Installation
@@ -149,15 +167,14 @@ Visualize your generated `.mmd` files instantly:
 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.4.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+mermaid_trace/__init__.py,sha256=ZXviz2KlX0eER7FPZJG2edsXfyDewt5iXpfGMifBoyE,5323
+mermaid_trace/cli.py,sha256=w7xh9kvyaokcUcuwIsBAtgwcl9zW8mosXesp5e0CtHg,11224
+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=wr-Ys3c6PsYCtbPUsQTrnaciSkP-fofxOewo4oZ27QM,8556
+mermaid_trace/core/decorators.py,sha256=lNNx_Qj2cDJkPX67qPl3NBH946ofoJ8osqxq3oBoCgU,16164
+mermaid_trace/core/events.py,sha256=h1g8uk1SGUj_NzefuJXYrkWO8ZuezeFjfU8IpYILnB8,5977
+mermaid_trace/core/formatter.py,sha256=A9ULgcu3xHiG3iD6k54sQ7nm9kHceMvplVCHw_nu09I,5259
+mermaid_trace/handlers/async_handler.py,sha256=Cbs6ZuKywf2VWwSIPNRXFOtoPArIhoYl-QHeW05hhWg,4272
+mermaid_trace/handlers/mermaid_handler.py,sha256=rF-S3IXsMvTS-6kgGN7By-_2kqlCyMwcNgaorlci1Q8,5137
+mermaid_trace/integrations/fastapi.py,sha256=H9Hl2pFxdbM3NwqONyJ7kAP-oGdOOnuoG3hEEbpoOjE,6487
+mermaid_trace-0.4.1.dist-info/METADATA,sha256=JLDyn-TuDnehsO34g6GAArjIl-XN4izSVZIVulmiu6c,6539
+mermaid_trace-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mermaid_trace-0.4.1.dist-info/entry_points.txt,sha256=WS57KT_870v0A4B87QDjQUqJcddMQxbCQyYeczDAX34,57
+mermaid_trace-0.4.1.dist-info/licenses/LICENSE,sha256=BrBog1Etiq9PdWy0SVQNVByIMD9ss4Edz-R0oXt49zA,1062
+mermaid_trace-0.4.1.dist-info/RECORD,,

mermaid_trace-0.3.1.dist-info/RECORD

@@ -1,15 +0,0 @@
-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,,