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

mermaid_trace/integrations/fastapi.py

@@ -1,14 +1,21 @@
 """
-FastAPI Integration Module
+FastAPI Integration Module for MermaidTrace.
 
-This module provides middleware for integrating MermaidTrace with FastAPI applications.
-It automatically traces HTTP requests and responses, converting them into Mermaid
-sequence diagram events.
+This module provides the middleware necessary to integrate MermaidTrace with
+FastAPI applications. It serves as the bridge between HTTP requests and the
+sequence diagram generation logic.
+
+Key functionalities include:
+- Middleware for intercepting all incoming HTTP requests.
+- Automatic extraction of tracing headers (X-Source, X-Trace-ID).
+- Initialization of logging context for request lifecycles.
+- Automatic logging of request start and response completion (success or error).
 """
 
 from typing import Any, TYPE_CHECKING
 import time
 import uuid
+import traceback
 
 from ..core.events import FlowEvent
 from ..core.context import LogContext
@@ -16,21 +23,21 @@ 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
+    # For static type checkers (mypy, pyright), import the actual types.
     from fastapi import Request, Response
     from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
 else:
     try:
-        # Try to import FastAPI/Starlette at runtime
+        # Runtime import attempt for FastAPI and Starlette.
         from fastapi import Request, Response
         from starlette.middleware.base import (
             BaseHTTPMiddleware,
             RequestResponseEndpoint,
         )
     except ImportError:
-        # Handle the case where FastAPI/Starlette are not installed
-        # Define dummy types to prevent NameErrors at import time
-        # Instantiation will fail explicitly in __init__
+        # Fallback for when FastAPI is not installed in the environment.
+        # This prevents ImportErrors when importing this module without FastAPI.
+        # However, instantiating the middleware will still fail.
         BaseHTTPMiddleware = object  # type: ignore[misc,assignment]
         Request = Any  # type: ignore[assignment]
         Response = Any  # type: ignore[assignment]
@@ -41,12 +48,22 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
     """
     FastAPI Middleware to trace HTTP requests as interactions in the sequence diagram.
 
-    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
+    This middleware wraps the entire request processing pipeline. It is responsible for
+    recording the initial interaction between an external client (Source) and this
+    service (Target).
+
+    Middleware Logic:
+    1.  **Request Interception**: Captures the request before it reaches any route handler.
+    2.  **Context Initialization**: Sets up the `LogContext` with the current service name
+        and trace ID, ensuring all internal function calls are correctly associated.
+    3.  **Event Logging**: Logs the "Request" event (Client -> API) and the corresponding
+        "Response" event (API -> Client).
+    4.  **Error Handling**: Captures exceptions, logs error events (API --x Client),
+        and re-raises them to standard error handlers.
+
+    Attributes:
+        app_name (str): The name of the current service/application. This name will
+                        appear as a participant in the generated Mermaid sequence diagram.
     """
 
     def __init__(self, app: Any, app_name: str = "FastAPI"):
@@ -54,19 +71,20 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
         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 (Any): The FastAPI application instance.
+            app_name (str): The name of this service to appear in the diagram (e.g., "UserAPI").
+                            Defaults to "FastAPI".
 
         Raises:
-            ImportError: If FastAPI/Starlette are not installed
+            ImportError: If FastAPI or Starlette is not installed in the current environment.
         """
-        # Check if FastAPI is installed by verifying BaseHTTPMiddleware is not our dummy object
+        # Validate that the necessary dependencies are present.
         if BaseHTTPMiddleware is object:  # type: ignore[comparison-overlap]
             raise ImportError(
                 "FastAPI/Starlette is required to use MermaidTraceMiddleware"
             )
 
-        # Initialize the parent BaseHTTPMiddleware
+        # Initialize the base class.
         super().__init__(app)
         self.app_name = app_name
 
@@ -74,62 +92,88 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
         self, request: Request, call_next: RequestResponseEndpoint
     ) -> Response:
         """
-        Intercepts and processes incoming HTTP requests.
+        Dispatch method to handle the incoming request.
+
+        This is the core logic of the middleware. It wraps the `call_next` execution
+        with tracing logic.
 
-        This method is called for each incoming request and handles the full
-        request-response cycle tracing.
+        Request Tracing & Header Handling:
+        - **X-Source**: Used to identify the caller. If present, the diagram will show
+          an arrow from `X-Source` to `app_name`. If missing, defaults to "Client".
+        - **X-Trace-ID**: Used for distributed tracing. If provided, it links this
+          request to an existing trace. If missing, a new UUID is generated.
 
         Args:
-            request (Request): The incoming HTTP request object
-            call_next (RequestResponseEndpoint): Function to call the next middleware or endpoint
+            request (Request): The incoming HTTP request object.
+            call_next (RequestResponseEndpoint): A callable that invokes the next
+                                                 middleware or the route handler.
 
         Returns:
-            Response: The HTTP response object
+            Response: The HTTP response generated by the application.
         """
-        # 1. Determine Source (Client participant)
-        # Try to get a specific ID from X-Source header (useful for distributed tracing),
-        # otherwise fallback to "Client"
+        # ----------------------------------------------------------------------
+        # 1. Header Handling and Metadata Extraction
+        # ----------------------------------------------------------------------
+
+        # Determine the source participant (Who is calling us?).
+        # If the request comes from another service traced by MermaidTrace,
+        # it might include the 'X-Source' header.
         source = request.headers.get("X-Source", "Client")
 
-        # 2. Determine Trace ID
-        # Check for X-Trace-ID header (for distributed tracing) or generate new UUID
+        # Determine the unique Trace ID.
+        # This ID is critical for grouping all logs related to a single request flow.
         trace_id = request.headers.get("X-Trace-ID") or str(uuid.uuid4())
 
-        # 3. Determine Action name
-        # Format: "METHOD /path" (e.g., "GET /users", "POST /items")
+        # Define the action name for the diagram arrow.
+        # Format: "METHOD /path" (e.g., "GET /api/v1/users")
         action = f"{request.method} {request.url.path}"
 
+        # Get the configured logger for flow events.
         logger = get_flow_logger()
 
-        # 4. Log Request (Source -> App)
-        # Create and log the initial request event
+        # ----------------------------------------------------------------------
+        # 2. Log Request Start (Source -> App)
+        # ----------------------------------------------------------------------
+
+        # Create the 'Request' event representing the call coming into this service.
         req_event = FlowEvent(
             source=source,
             target=self.app_name,
             action=action,
             message=action,
+            # Include query parameters in the note if they exist.
             params=f"query={request.query_params}" if request.query_params else None,
             trace_id=trace_id,
         )
+
+        # Log the event. This writes the JSON entry that the visualizer will parse.
         logger.info(
             f"{source}->{self.app_name}: {action}", extra={"flow_event": req_event}
         )
 
-        # 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()
+        # ----------------------------------------------------------------------
+        # 3. Context Setup and Request Processing
+        # ----------------------------------------------------------------------
+
+        # Initialize the LogContext for this async task.
+        # Any 'traced' function called within this block will inherit 'trace_id'
+        # and see 'participant' as self.app_name.
         async with LogContext.ascope(
             {"participant": self.app_name, "trace_id": trace_id}
         ):
             start_time = time.time()
             try:
-                # Pass control to the next middleware or endpoint
-                # This executes the actual route logic and returns the response
+                # Process the request by calling the next item in the middleware chain.
                 response = await call_next(request)
 
-                # 6. Log Success Response (App -> Source)
-                # Calculate execution duration in milliseconds
+                # ------------------------------------------------------------------
+                # 4. Log Success Response (App -> Source)
+                # ------------------------------------------------------------------
+
+                # Calculate execution time for performance insights.
                 duration = (time.time() - start_time) * 1000
+
+                # Create the 'Return' event (dashed line back to caller).
                 resp_event = FlowEvent(
                     source=self.app_name,
                     target=source,
@@ -146,9 +190,17 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
                 return response
 
             except Exception as e:
-                # 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
+                # ------------------------------------------------------------------
+                # 5. Log Error Response (App --x Source)
+                # ------------------------------------------------------------------
+
+                # Capture full stack trace for the error.
+                stack_trace = "".join(
+                    traceback.format_exception(type(e), e, e.__traceback__)
+                )
+
+                # If an unhandled exception occurs, log it as an error event.
+                # This will render as a cross (X) on the sequence diagram return arrow.
                 err_event = FlowEvent(
                     source=self.app_name,
                     target=source,
@@ -157,10 +209,13 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
                     is_return=True,
                     is_error=True,
                     error_message=str(e),
+                    stack_trace=stack_trace,
                     trace_id=trace_id,
                 )
                 logger.error(
                     f"{self.app_name}-x{source}: Error", extra={"flow_event": err_event}
                 )
-                # Re-raise the exception to maintain normal error handling flow
+
+                # Re-raise the exception so FastAPI's exception handlers can take over.
+                # We strictly monitor the flow here, not swallow errors.
                 raise

{mermaid_trace-0.4.1.dist-info → mermaid_trace-0.5.3.post0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mermaid-trace
-Version: 0.4.1
+Version: 0.5.3.post0
 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
@@ -39,7 +39,6 @@ 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
@@ -83,18 +82,35 @@ MermaidTrace is a specialized logging tool that automatically generates [Mermaid
 
 ## 📚 Documentation
 
+### Core 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)
 
+### Code Comment Documents (Chinese)
+
+| Category | Links |
+| :--- | :--- |
+| **Core Modules** | [Context](docs/zh/code_comments/src/mermaid_trace/core/context.md) · [Decorators](docs/zh/code_comments/src/mermaid_trace/core/decorators.md) · [Events](docs/zh/code_comments/src/mermaid_trace/core/events.md) · [Formatter](docs/zh/code_comments/src/mermaid_trace/core/formatter.md) |
+| **Handlers** | [Async Handler](docs/zh/code_comments/src/mermaid_trace/handlers/async_handler.md) · [Mermaid Handler](docs/zh/code_comments/src/mermaid_trace/handlers/mermaid_handler.md) |
+| **Integrations** | [FastAPI](docs/zh/code_comments/src/mermaid_trace/integrations/fastapi.md) |
+| **Others** | [init](docs/zh/code_comments/src/mermaid_trace/__init__.md) · [CLI](docs/zh/code_comments/src/mermaid_trace/cli.md) |
+
 ---
 
 ## ✨ Key Features
 
 - **Decorator-Driven**: Just add `@trace` or `@trace_interaction` to your functions.
+- **Auto-Instrumentation**: Use `@trace_class` to trace a whole class at once.
+- **Third-Party Patching**: Use `patch_object` to trace calls inside external libraries.
 - **Auto-Diagramming**: Generates `.mmd` files that can be viewed in VS Code, GitHub, or Mermaid Live Editor.
 - **Async Support**: Works seamlessly with `asyncio` coroutines.
 - **Context Inference**: Automatically tracks nested calls and infers `source` participants using `contextvars`.
-- **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing.
-- **CLI Tool**: Built-in viewer to preview diagrams in your browser.
+- **Intelligent Collapsing**: Prevents diagram explosion by collapsing repetitive high-frequency calls and identifying recurring patterns (e.g., loops).
+- **Detailed Exceptions**: Captures full stack traces for errors, displayed in interactive notes.
+- **Simplified Objects**: Automatically cleans up memory addresses (e.g., `<__main__.Obj at 0x...>` -> `<Obj>`) and **groups consecutive identical items** in lists/tuples (e.g., `[<Obj> x 5]`) for cleaner diagrams.
+- **Log Rotation**: Supports `RotatingMermaidFileHandler` for handling long-running systems by splitting logs based on size or time.
+- **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing, supporting distributed tracing via `X-Trace-ID` and `X-Source` headers.
+- **CLI Tool**: Built-in viewer with live-reload to preview diagrams in your browser.
 
 ---
 
@@ -113,7 +129,8 @@ from mermaid_trace import trace, configure_flow
 import time
 
 # 1. Configure output
-configure_flow("my_flow.mmd")
+# Recommendation: Store diagrams in a dedicated directory (e.g., mermaid_diagrams/)
+configure_flow("mermaid_diagrams/my_flow.mmd", async_mode=True)
 
 # 2. Add decorators
 @trace(source="Client", target="PaymentService", action="Process Payment")
@@ -130,6 +147,29 @@ def check_balance(amount):
 process_payment(100)
 ```
 
+### Configuration
+
+You can configure global settings via `configure_flow` or environment variables to control performance and behavior.
+
+```python
+configure_flow(
+    "flow.mmd", 
+    overwrite=True,    # Overwrite the file on each restart (default: True)
+    level=logging.DEBUG, 
+    queue_size=5000,  # Increase buffer for high-throughput
+    config_overrides={
+        "capture_args": False,       # Disable arg capturing for max performance
+        "max_string_length": 100     # Increase string truncation limit
+    }
+)
+```
+
+**Environment Variables:**
+- `MERMAID_TRACE_CAPTURE_ARGS` (true/false)
+- `MERMAID_TRACE_MAX_STRING_LENGTH` (int)
+- `MERMAID_TRACE_MAX_ARG_DEPTH` (int)
+- `MERMAID_TRACE_QUEUE_SIZE` (int)
+
 ### Nested Calls (Context Inference)
 
 You don't need to specify `source` every time. MermaidTrace infers it from the current context.
@@ -167,6 +207,18 @@ Visualize your generated `.mmd` files instantly:
 mermaid-trace serve my_flow.mmd
 ```
 
+### Examples
+
+Check out the [examples/](examples/) directory for a complete set of demos covering all features:
+- **[Basic Usage](examples/01_basic_usage.py)**: Decorators and class methods.
+- **[Advanced Instrumentation](examples/02_advanced_instrumentation.py)**: `@trace_class` and `patch_object` for third-party libraries.
+- **[Async & Concurrency](examples/03_async_concurrency.py)**: Tracing `asyncio` and concurrent tasks.
+- **[Error Handling](examples/04_error_handling.py)**: Stack trace capture and error rendering.
+- **[Intelligent Collapsing](examples/05_intelligent_collapsing.py)**: Keeping diagrams clean in loops.
+- **[FastAPI Integration](examples/06_fastapi_integration.py)**: Middleware for web apps.
+- **[Full Stack App](examples/07_full_stack_app.py)**: Comprehensive example with FastAPI, SQLAlchemy, and Pydantic.
+- **[Log Rotation](examples/08-log-rotation.py)**: Handling long-running processes with file rotation.
+
 ---
 
 ## 🤝 Contributing

mermaid_trace-0.5.3.post0.dist-info/RECORD

@@ -0,0 +1,19 @@
+mermaid_trace/__init__.py,sha256=EnAsz6R6ag4dtabdHEg1wdB2k7V1uwmwpYTTC41GQX4,6721
+mermaid_trace/cli.py,sha256=g7Qriiox9YqfJutUntE1a7GwByg62wGwQcLfpvicjT8,15076
+mermaid_trace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mermaid_trace/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mermaid_trace/core/config.py,sha256=akTOc3m_bzcZ7e1Qtf1n5Ct9Dj8XPTTcWzATG3-qJHw,1890
+mermaid_trace/core/context.py,sha256=wr-Ys3c6PsYCtbPUsQTrnaciSkP-fofxOewo4oZ27QM,8556
+mermaid_trace/core/decorators.py,sha256=2h7UzjQcL46jrCIdVMWSZT_4JlTsDkpY9M9Ihr0vuq4,23037
+mermaid_trace/core/events.py,sha256=2etS45A40GaP4dF_F6Jh99rhF2YVip4AjoZlLPuP6pQ,1949
+mermaid_trace/core/formatter.py,sha256=3KEq236E3GAj_j53MuBM2ndWm7Kx4KeywJWmoY5o568,11038
+mermaid_trace/core/utils.py,sha256=FagsMYLZcbmOgKmRo3v9tcRNVIpuc1YEKTAjcRk7keY,3410
+mermaid_trace/handlers/async_handler.py,sha256=WmLcULXHasapt7-W0p_Eltjmwvlq6r6BS6pViuseZ4w,8252
+mermaid_trace/handlers/mermaid_handler.py,sha256=Czar6JYSPTu5L1fQC0I8v1UpToD6aE_r96IkPpRSByw,6142
+mermaid_trace/integrations/__init__.py,sha256=uU_8E1tlP327Fn79kvzlgEdoiIpQLsWJl3BgyqgsFMQ,104
+mermaid_trace/integrations/fastapi.py,sha256=6LRs4Z508l38ymfj5SP39vOV6OLfYLRkpxyL_SxvudM,9483
+mermaid_trace-0.5.3.post0.dist-info/METADATA,sha256=FR1kgM-wlTzrFasLpIeqbWbV_X3h3TwwUkxQCvgbvo0,9959
+mermaid_trace-0.5.3.post0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mermaid_trace-0.5.3.post0.dist-info/entry_points.txt,sha256=WS57KT_870v0A4B87QDjQUqJcddMQxbCQyYeczDAX34,57
+mermaid_trace-0.5.3.post0.dist-info/licenses/LICENSE,sha256=BrBog1Etiq9PdWy0SVQNVByIMD9ss4Edz-R0oXt49zA,1062
+mermaid_trace-0.5.3.post0.dist-info/RECORD,,

mermaid_trace-0.4.1.dist-info/RECORD

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