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

mermaid_trace/handlers/mermaid_handler.py

@@ -1,25 +1,33 @@
 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.
-        
+
         Args:
             filename (str): The path to the output .mmd file.
             title (str): The title of the Mermaid diagram (written in the header).
@@ -30,22 +38,23 @@ class MermaidFileHandler(logging.FileHandler):
         """
         # Ensure directory exists to prevent FileNotFoundError on open
         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.
+        # This prevents invalid Mermaid files (e.g., multiple "sequenceDiagram" lines).
         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)
         super().__init__(filename, mode, encoding, delay)
         self.title = title
-        
+
         # Write header immediately if needed.
         if should_write_header:
             self._write_header()
@@ -53,14 +62,17 @@ class MermaidFileHandler(logging.FileHandler):
     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.
+        It defines the diagram type (sequenceDiagram), title, and enables autonumbering.
         """
         # 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")
+            # Flush ensures the header is written to disk immediately,
+            # so it appears even if the program crashes right after.
             self.flush()
         else:
             # Handling 'delay=True' case:
@@ -74,13 +86,14 @@ class MermaidFileHandler(logging.FileHandler):
     def emit(self, record: logging.LogRecord) -> None:
         """
         Process a log record.
-        
+
         Optimization:
-        - Checks for `flow_event` attribute first. This allows this handler 
+        - 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.
+          It acts as a high-performance filter before formatting.
+        - Delegates the actual writing to `super().emit()`, which handles
+          thread locking and stream flushing safely.
         """
         # Only process records that contain our structured FlowEvent data
-        if hasattr(record, 'flow_event'):
+        if hasattr(record, "flow_event"):
             super().emit(record)

mermaid_trace/integrations/fastapi.py

@@ -12,7 +12,10 @@ if TYPE_CHECKING:
 else:
     try:
         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,
@@ -22,37 +25,43 @@ else:
         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.
     """
+
     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").
         """
-        if BaseHTTPMiddleware is object: # type: ignore[comparison-overlap]
-             raise ImportError("FastAPI/Starlette is required to use MermaidTraceMiddleware")
+        if BaseHTTPMiddleware is object:  # type: ignore[comparison-overlap]
+            raise ImportError(
+                "FastAPI/Starlette is required to use MermaidTraceMiddleware"
+            )
         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.
-        
+
         Args:
             request (Request): The incoming HTTP request.
             call_next (Callable): The function to call the next middleware or endpoint.
-            
+
         Returns:
             Response: The HTTP response.
         """
@@ -60,17 +69,17 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
         # Try to get a specific ID from headers (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
         trace_id = request.headers.get("X-Trace-ID") or str(uuid.uuid4())
-        
+
         # 2. Determine Action
         # Format: "METHOD /path" (e.g., "GET /users")
         action = f"{request.method} {request.url.path}"
-        
+
         logger = get_flow_logger()
-        
+
         # 3. Log Request (Source -> App)
         req_event = FlowEvent(
             source=source,
@@ -78,20 +87,27 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
             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}):
+        # This includes route handlers, dependencies, and other middlewares called after this one.
+        async with LogContext.ascope(
+            {"participant": self.app_name, "trace_id": trace_id}
+        ):
             start_time = time.time()
             try:
                 # Pass control to the application
+                # This executes the actual route logic
                 response = await call_next(request)
-                
+
                 # 5. Log Response (App -> Source)
+                # Calculate execution duration for the response label
                 duration = (time.time() - start_time) * 1000
                 resp_event = FlowEvent(
                     source=self.app_name,
@@ -100,14 +116,19 @@ 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)
                 # This captures unhandled exceptions that bubble up to the middleware
+                # Note: FastAPI's ExceptionHandlers might catch this before it reaches here.
+                # If so, you might see a successful return with 500 status instead.
                 err_event = FlowEvent(
                     source=self.app_name,
                     target=source,
@@ -116,7 +137,9 @@ 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})
                 raise

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mermaid-trace
-Version: 0.3.1
+Version: 0.4.0
 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
@@ -151,7 +153,7 @@ mermaid-trace serve my_flow.mmd
 
 ## 📂 Documentation
 
-- [English Documentation](docs/en/README.md)
+- [English Documentation](docs/en/USER_GUIDE.md)
 - [中文文档](README_CN.md)
 
 ## 🤝 Contributing

mermaid_trace-0.4.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+mermaid_trace/__init__.py,sha256=yhc-shETKioVEQEfqmCGFyVelRR3_ypeClbMR_D2oBQ,5267
+mermaid_trace/cli.py,sha256=F5-QfnKp_Et719IKWvU5IAWZTpq9ft01ow62DqNpHdA,9477
+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=WyTKbC_I1ge802VUj9PdUiqa-VgL1r3DQUW_y8PlG8M,6618
+mermaid_trace/core/decorators.py,sha256=13-n6qsmWnInpKgQ0Bgnnn5aQIWkRZ7raTD2xVtKVmU,12303
+mermaid_trace/core/events.py,sha256=TVtarp7IwfTR_C404ZWoyqBZmTtScROz5hWL0uel3G4,2857
+mermaid_trace/core/formatter.py,sha256=6k79eBU09TSCEUcDJN1mfn-_KMld0xXfKtQTKZb8Ogw,3178
+mermaid_trace/handlers/async_handler.py,sha256=uGC27TCgfxyvQQEiJ_7Ir1EFJdsLHBUzHEsLktEaFtM,1893
+mermaid_trace/handlers/mermaid_handler.py,sha256=JUq5gSQepNISreUYkyucS_rk27zGIiwSYFw_Lb8lL28,4314
+mermaid_trace/integrations/fastapi.py,sha256=GJL2H0Ypi4HqiAR-kkV4kSUTitdOj4RkhPi26GGNORM,5515
+mermaid_trace-0.4.0.dist-info/METADATA,sha256=4oszQifzCHhgCEI0Ly1nKAUuvcF-Bs-ejCReGUOsTbo,6287
+mermaid_trace-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mermaid_trace-0.4.0.dist-info/entry_points.txt,sha256=WS57KT_870v0A4B87QDjQUqJcddMQxbCQyYeczDAX34,57
+mermaid_trace-0.4.0.dist-info/licenses/LICENSE,sha256=BrBog1Etiq9PdWy0SVQNVByIMD9ss4Edz-R0oXt49zA,1062
+mermaid_trace-0.4.0.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,,