mermaid-trace 0.5.3.post0__tar.gz → 0.6.0.post0__tar.gz

mermaid_trace-0.6.0.post0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: mermaid-trace
+Version: 0.6.0.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
+Project-URL: Issues, https://github.com/xt765/mermaid-trace/issues
+Project-URL: Source, https://github.com/xt765/mermaid-trace
+Author-email: xt765 <xt765@foxmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 xt765
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: asyncio,logging,mermaid,mermaid-trace,sequence-diagram,trace,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: watchdog>=2.0.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: langchain-core>=0.1.0; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# MermaidTrace: Visualize Your Python Code Logic
+
+**Stop drowning in cryptic logs. One line of code to transform complex execution logic into clear Mermaid sequence diagrams.**
+
+🌐 **Language**: [English](README.md) | [中文](README_CN.md)
+
+[![CSDN Blog](https://img.shields.io/badge/CSDN-玄同765-orange?style=flat-square&logo=csdn)](https://blog.csdn.net/Yunyi_Chi)
+[![GitHub](https://img.shields.io/badge/GitHub-mermaid--trace-black?style=flat-square&logo=github)](https://github.com/xt765/mermaid-trace)
+[![Gitee](https://img.shields.io/badge/Gitee-mermaid--trace-red?style=flat-square&logo=gitee)](https://gitee.com/xt765/mermaid-trace)
+[![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)
+
+---
+
+## ⚡️ Understand MermaidTrace in 5 Seconds
+
+#### 1. Original Code (15+ lines)
+```python
+@trace(source="User", target="OrderSys")
+def create_order(user_id, items):
+    # Complex business logic
+    if not check_inventory(items):
+        return "Out of Stock"
+
+    # Nested logic calls
+    price = calculate_price(items)
+    discount = get_discount(user_id)
+    final = price - discount
+
+    # External service interactions
+    res = pay_service.process(final)
+    if res.success:
+        update_stock(items)
+        send_notif(user_id)
+        return "Success"
+    return "Failed"
+```
+
+#### 2. Auto-Generated Sequence Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    User->>OrderSys: create_order(user_id, items)
+    activate OrderSys
+    OrderSys->>Inventory: check_inventory(items)
+    Inventory-->>OrderSys: True
+    OrderSys->>Pricing: calculate_price(items)
+    Pricing-->>OrderSys: 100.0
+    OrderSys->>UserDB: get_discount(user_id)
+    UserDB-->>OrderSys: 5.0
+    OrderSys->>PayService: process(95.0)
+    activate PayService
+    PayService-->>OrderSys: success
+    deactivate PayService
+    OrderSys->>Inventory: update_stock(items)
+    OrderSys->>Notification: send_notif(user_id)
+    OrderSys-->>User: "Success"
+    deactivate OrderSys
+```
+
+---
+
+## 🚀 Dynamic Demo & Online Tryout
+
+### 🎬 Quick Demo
+
+![MermaidTrace Master Preview](docs/images/master_preview.png)
+
+*(Master Preview: Multi-file browsing, live-reload, and interactive pan/zoom)*
+
+```mermaid
+sequenceDiagram
+    participant CLI as mermaid-trace CLI
+    participant App as Python App
+    participant Web as Live Preview
+
+    Note over CLI, Web: Enable Live Preview Mode
+    CLI->>Web: Start HTTP Server (localhost:8000)
+    App->>App: Run Logic (with @trace decorator)
+    App->>App: Auto-update flow.mmd
+    Web->>Web: File Change Detected (Hot Reload)
+    Web-->>CLI: Render Latest Diagram
+```
+*(From adding decorators to browser live preview in 10 seconds)*
+
+### 🛠️ Try Online (Google Colab)
+
+No local setup required. Experience core features in your browser:
+
+[![Open In Colab](https://img.shields.io/badge/Colab-Open%20in%20Colab-blue?style=flat&logo=google-colab&logoColor=white)](https://colab.research.google.com/github/xt765/mermaid-trace/blob/main/examples/MermaidTrace_Demo.ipynb)
+
+---
+
+## 🎯 Why MermaidTrace? (Use Cases)
+
+### 1. Master "Legacy" Codebases
+**Pain**: Taking over a complex, undocumented legacy project with tangled function calls.
+**Solution**: Add `@trace_class` or `@trace` to entry points and run the code once.
+**Value**: Instantly generate a complete execution path map to understand the architecture.
+
+### 2. Automated Technical Docs
+**Pain**: Manual sequence diagrams are time-consuming and quickly become outdated.
+**Solution**: Integrate MermaidTrace during development.
+**Value**: Diagrams stay 100% in sync with your code logic automatically.
+
+### 3. Debug Complex Recursion & Concurrency
+**Pain**: Nested calls or async tasks produce interleaved logs that are impossible to read.
+**Solution**: Use built-in async support and intelligent collapsing.
+**Value**: Visualize recursion depth and concurrency flow to pinpoint logic bottlenecks.
+
+---
+
+## 🚀 Quick Start in 3 Steps
+
+### 1. Install
+```bash
+pip install mermaid-trace
+```
+
+### 2. Add Decorators
+```python
+from mermaid_trace import trace, configure_flow
+
+# Configure output file
+configure_flow("my_flow.mmd")
+
+@trace(source="User", target="AuthService")
+def login(username):
+    return verify_db(username)
+
+@trace(source="AuthService", target="DB")
+def verify_db(username):
+    return True
+
+login("admin")
+```
+
+### 3. View Diagram
+
+Run the built-in CLI tool to preview in real-time (with hot-reload):
+
+```bash
+# Basic preview
+mermaid-trace serve my_flow.mmd
+
+# Master mode (Directory browsing, zoom, multi-file switching)
+mermaid-trace serve . --master
+# Or preview a specific file in Master mode
+mermaid-trace serve .\mermaid_diagrams\examples\08-log-rotation.mmd --master
+```
+
+### 🔗 LangChain Integration
+Visualize LLM chains, agents, and RAG retrieval with a single handler:
+```python
+from mermaid_trace.integrations.langchain import MermaidTraceCallbackHandler
+
+handler = MermaidTraceCallbackHandler(host_name="MyAIApp")
+# Pass to any LangChain object
+chain.invoke({"input": "..."}, config={"callbacks": [handler]})
+```
+
+---
+
+## ✨ Key Features
+
+- **Decorator-Driven**: Simply add `@trace` or `@trace_interaction` to 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.
+- **Async Support**: Seamlessly works with `asyncio` coroutines and concurrency.
+- **Enhanced Web UI**: Interactive preview server with file browsing, auto-reload, and pan/zoom support (use `--master`).
+- **Intelligent Collapsing**: Automatically collapses repetitive calls and identifies loops.
+- **FastAPI Integration**: Middleware for zero-config HTTP request tracing.
+- **LangChain Integration**: Callback Handler for LLM chains and agent visualization.
+- **Detailed Exceptions**: Captures full stack traces for errors, displayed in the diagram.
+
+---
+
+## 📚 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](LICENSE)
+
+### Code Comment Documents
+
+| Category | Links |
+| :--- | :--- |
+| **Core Modules** | [Context](docs/en/code_comments/src/mermaid_trace/core/context.md) · [Decorators](docs/en/code_comments/src/mermaid_trace/core/decorators.md) · [Events](docs/en/code_comments/src/mermaid_trace/core/events.md) · [Formatter](docs/en/code_comments/src/mermaid_trace/core/formatter.md) |
+| **Handlers** | [Async Handler](docs/en/code_comments/src/mermaid_trace/handlers/async_handler.md) · [Mermaid Handler](docs/en/code_comments/src/mermaid_trace/handlers/mermaid_handler.md) |
+| **Integrations** | [FastAPI](docs/en/code_comments/src/mermaid_trace/integrations/fastapi.md) |
+| **Others** | [init](docs/en/code_comments/src/mermaid_trace/__init__.md) · [CLI](docs/en/code_comments/src/mermaid_trace/cli.md) |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
+
+---
+
+## 📄 License
+
+MIT

mermaid_trace-0.6.0.post0/README.md

@@ -0,0 +1,206 @@
+# MermaidTrace: Visualize Your Python Code Logic
+
+**Stop drowning in cryptic logs. One line of code to transform complex execution logic into clear Mermaid sequence diagrams.**
+
+🌐 **Language**: [English](README.md) | [中文](README_CN.md)
+
+[![CSDN Blog](https://img.shields.io/badge/CSDN-玄同765-orange?style=flat-square&logo=csdn)](https://blog.csdn.net/Yunyi_Chi)
+[![GitHub](https://img.shields.io/badge/GitHub-mermaid--trace-black?style=flat-square&logo=github)](https://github.com/xt765/mermaid-trace)
+[![Gitee](https://img.shields.io/badge/Gitee-mermaid--trace-red?style=flat-square&logo=gitee)](https://gitee.com/xt765/mermaid-trace)
+[![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)
+
+---
+
+## ⚡️ Understand MermaidTrace in 5 Seconds
+
+#### 1. Original Code (15+ lines)
+```python
+@trace(source="User", target="OrderSys")
+def create_order(user_id, items):
+    # Complex business logic
+    if not check_inventory(items):
+        return "Out of Stock"
+
+    # Nested logic calls
+    price = calculate_price(items)
+    discount = get_discount(user_id)
+    final = price - discount
+
+    # External service interactions
+    res = pay_service.process(final)
+    if res.success:
+        update_stock(items)
+        send_notif(user_id)
+        return "Success"
+    return "Failed"
+```
+
+#### 2. Auto-Generated Sequence Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    User->>OrderSys: create_order(user_id, items)
+    activate OrderSys
+    OrderSys->>Inventory: check_inventory(items)
+    Inventory-->>OrderSys: True
+    OrderSys->>Pricing: calculate_price(items)
+    Pricing-->>OrderSys: 100.0
+    OrderSys->>UserDB: get_discount(user_id)
+    UserDB-->>OrderSys: 5.0
+    OrderSys->>PayService: process(95.0)
+    activate PayService
+    PayService-->>OrderSys: success
+    deactivate PayService
+    OrderSys->>Inventory: update_stock(items)
+    OrderSys->>Notification: send_notif(user_id)
+    OrderSys-->>User: "Success"
+    deactivate OrderSys
+```
+
+---
+
+## 🚀 Dynamic Demo & Online Tryout
+
+### 🎬 Quick Demo
+
+![MermaidTrace Master Preview](docs/images/master_preview.png)
+
+*(Master Preview: Multi-file browsing, live-reload, and interactive pan/zoom)*
+
+```mermaid
+sequenceDiagram
+    participant CLI as mermaid-trace CLI
+    participant App as Python App
+    participant Web as Live Preview
+
+    Note over CLI, Web: Enable Live Preview Mode
+    CLI->>Web: Start HTTP Server (localhost:8000)
+    App->>App: Run Logic (with @trace decorator)
+    App->>App: Auto-update flow.mmd
+    Web->>Web: File Change Detected (Hot Reload)
+    Web-->>CLI: Render Latest Diagram
+```
+*(From adding decorators to browser live preview in 10 seconds)*
+
+### 🛠️ Try Online (Google Colab)
+
+No local setup required. Experience core features in your browser:
+
+[![Open In Colab](https://img.shields.io/badge/Colab-Open%20in%20Colab-blue?style=flat&logo=google-colab&logoColor=white)](https://colab.research.google.com/github/xt765/mermaid-trace/blob/main/examples/MermaidTrace_Demo.ipynb)
+
+---
+
+## 🎯 Why MermaidTrace? (Use Cases)
+
+### 1. Master "Legacy" Codebases
+**Pain**: Taking over a complex, undocumented legacy project with tangled function calls.
+**Solution**: Add `@trace_class` or `@trace` to entry points and run the code once.
+**Value**: Instantly generate a complete execution path map to understand the architecture.
+
+### 2. Automated Technical Docs
+**Pain**: Manual sequence diagrams are time-consuming and quickly become outdated.
+**Solution**: Integrate MermaidTrace during development.
+**Value**: Diagrams stay 100% in sync with your code logic automatically.
+
+### 3. Debug Complex Recursion & Concurrency
+**Pain**: Nested calls or async tasks produce interleaved logs that are impossible to read.
+**Solution**: Use built-in async support and intelligent collapsing.
+**Value**: Visualize recursion depth and concurrency flow to pinpoint logic bottlenecks.
+
+---
+
+## 🚀 Quick Start in 3 Steps
+
+### 1. Install
+```bash
+pip install mermaid-trace
+```
+
+### 2. Add Decorators
+```python
+from mermaid_trace import trace, configure_flow
+
+# Configure output file
+configure_flow("my_flow.mmd")
+
+@trace(source="User", target="AuthService")
+def login(username):
+    return verify_db(username)
+
+@trace(source="AuthService", target="DB")
+def verify_db(username):
+    return True
+
+login("admin")
+```
+
+### 3. View Diagram
+
+Run the built-in CLI tool to preview in real-time (with hot-reload):
+
+```bash
+# Basic preview
+mermaid-trace serve my_flow.mmd
+
+# Master mode (Directory browsing, zoom, multi-file switching)
+mermaid-trace serve . --master
+# Or preview a specific file in Master mode
+mermaid-trace serve .\mermaid_diagrams\examples\08-log-rotation.mmd --master
+```
+
+### 🔗 LangChain Integration
+Visualize LLM chains, agents, and RAG retrieval with a single handler:
+```python
+from mermaid_trace.integrations.langchain import MermaidTraceCallbackHandler
+
+handler = MermaidTraceCallbackHandler(host_name="MyAIApp")
+# Pass to any LangChain object
+chain.invoke({"input": "..."}, config={"callbacks": [handler]})
+```
+
+---
+
+## ✨ Key Features
+
+- **Decorator-Driven**: Simply add `@trace` or `@trace_interaction` to 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.
+- **Async Support**: Seamlessly works with `asyncio` coroutines and concurrency.
+- **Enhanced Web UI**: Interactive preview server with file browsing, auto-reload, and pan/zoom support (use `--master`).
+- **Intelligent Collapsing**: Automatically collapses repetitive calls and identifies loops.
+- **FastAPI Integration**: Middleware for zero-config HTTP request tracing.
+- **LangChain Integration**: Callback Handler for LLM chains and agent visualization.
+- **Detailed Exceptions**: Captures full stack traces for errors, displayed in the diagram.
+
+---
+
+## 📚 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](LICENSE)
+
+### Code Comment Documents
+
+| Category | Links |
+| :--- | :--- |
+| **Core Modules** | [Context](docs/en/code_comments/src/mermaid_trace/core/context.md) · [Decorators](docs/en/code_comments/src/mermaid_trace/core/decorators.md) · [Events](docs/en/code_comments/src/mermaid_trace/core/events.md) · [Formatter](docs/en/code_comments/src/mermaid_trace/core/formatter.md) |
+| **Handlers** | [Async Handler](docs/en/code_comments/src/mermaid_trace/handlers/async_handler.md) · [Mermaid Handler](docs/en/code_comments/src/mermaid_trace/handlers/mermaid_handler.md) |
+| **Integrations** | [FastAPI](docs/en/code_comments/src/mermaid_trace/integrations/fastapi.md) |
+| **Others** | [init](docs/en/code_comments/src/mermaid_trace/__init__.md) · [CLI](docs/en/code_comments/src/mermaid_trace/cli.md) |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
+
+---
+
+## 📄 License
+
+MIT