mermaid-trace 0.3.1__tar.gz → 0.4.0__tar.gz

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/PKG-INFO

@@ -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.3.1 → mermaid_trace-0.4.0}/README.md

@@ -90,7 +90,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.3.1 → mermaid_trace-0.4.0}/README_CN.md

@@ -90,8 +90,8 @@ mermaid-trace serve my_flow.mmd
 
 ## 📂 文档
 
-- [英文文档](docs/en/README.md)
-- [中文文档](README_CN.md)
+- [英文文档](docs/en/USER_GUIDE.md)
+- [中文文档](docs/zh/USER_GUIDE.md)
 
 ## 🤝 贡献
 

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/docs/en/API.md

@@ -12,25 +12,37 @@ Decorator to trace function execution. Can be used with or without arguments.
 def my_func(): ...
 
 # Detailed usage
-@trace(source="Client", target="Server", action="Login")
+@trace(source="Client", target="Server", action="Login", capture_args=False)
 def login(username): ...
 ```
 
 **Arguments:**
 - `source` (Optional[str]): The caller participant name. If `None`, inferred from `contextvars`.
 - `target` (Optional[str]): The callee participant name. If `None`, inferred from class name (if method) or module name.
+- `name` (Optional[str]): Alias for `target`. Explicitly sets the participant name.
 - `action` (Optional[str]): Description of the interaction. If `None`, defaults to formatted function name (e.g., `process_payment` -> "Process Payment").
+- `capture_args` (bool): Whether to log arguments and return values. Defaults to `True`. Set to `False` for sensitive data.
+- `max_arg_length` (int): Maximum length of string representation for arguments. Defaults to 50.
+- `max_arg_depth` (int): Maximum depth for nested structures in argument representation. Defaults to 1.
 
 ### `configure_flow`
 
 Configures the global logger to output to a Mermaid file. This should be called once at application startup.
 
 ```python
-def configure_flow(output_file: str = "flow.mmd") -> logging.Logger
+def configure_flow(
+    output_file: str = "flow.mmd",
+    handlers: Optional[List[logging.Handler]] = None,
+    append: bool = False,
+    async_mode: bool = False
+) -> logging.Logger
 ```
 
 **Arguments:**
 - `output_file` (str): Path to the `.mmd` output file. Defaults to "flow.mmd".
+- `handlers` (List[logging.Handler]): Optional list of custom logging handlers. If provided, `output_file` is ignored unless you include `MermaidFileHandler` manually.
+- `append` (bool): If `True`, adds new handlers without removing existing ones. Defaults to `False`.
+- `async_mode` (bool): If `True`, uses a non-blocking background thread for logging (QueueHandler). Recommended for production. Defaults to `False`.
 
 ### `LogContext`
 

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/docs/en/CHANGELOG.md

@@ -5,12 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-01-26
+
+### Added
+- **Async Mode**: Introduced `async_mode=True` in `configure_flow` to offload log writing to a background thread, eliminating I/O blocking in the main application loop.
+- **Data Privacy**: Added `capture_args=False` to `@trace` to prevent sensitive arguments from being logged.
+- **Argument Truncation**: Added `max_arg_length` and `max_arg_depth` to `@trace` to control the size of logged data structures.
+- **Explicit Naming**: Added `name` (or `target` alias) parameter to `@trace` for explicitly setting the participant name, overriding automatic inference.
+- **Flexible Configuration**: Updated `configure_flow` to accept a list of custom handlers and an `append` flag, allowing better integration with existing logging setups.
+
+### Improved
+- **Test Coverage**: Achieved >90% test coverage with a comprehensive new test suite covering unit, integration, and concurrency scenarios.
+- **PyPI Compliance**: Switched to dynamic versioning via `hatch-vcs` and improved package metadata and artifact inclusion.
+
 ## [0.3.1] - 2026-01-26
 
 ### Fixed
 - **CI/CD**: Resolved test coverage reporting issues in GitHub Actions by standardizing on editable installs (`pip install -e .[dev]`) across all workflows.
 - **CI/CD**: Aligned coverage configuration in `pyproject.toml` to correctly target the source directory (`src/mermaid_trace`).
 - **Docs**: Fixed badge links in README to use consistent style and valid sources.
+- **Compatibility**: Officially added support for Python 3.13 and 3.14 in project classifiers and CI workflows.
 
 ## [0.3.0] - 2026-01-26
 

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/docs/en/CONTRIBUTING.md

@@ -29,7 +29,12 @@ The following is a set of guidelines for contributing to MermaidTrace and its pa
 
 4.  **Run tests**:
     ```bash
+    # Run all tests
     pytest
+
+    # Run tests across multiple Python versions (requires tox)
+    pip install tox
+    tox
     ```
 
 ## Styleguides
@@ -38,12 +43,17 @@ The following is a set of guidelines for contributing to MermaidTrace and its pa
 
 - All Python code is linted with `ruff`.
 - All Python code is type-checked with `mypy`.
+- We use `hatch` for build management and `hatch-vcs` for dynamic versioning.
 
 To run checks locally:
 
 ```bash
+# Using tox (recommended)
+tox -e lint
+
+# Or manually
 ruff check src tests
-mypy src
+mypy src/mermaid_trace
 ```
 
 ## Pull Requests

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/docs/en/USER_GUIDE.md

@@ -41,6 +41,47 @@ MermaidTrace uses Python's `contextvars` to track the "Current Participant".
 
 This means you usually only need to set the `source` on the *entry point* (the first function).
 
+## Advanced Configuration
+
+### Async Mode (Performance)
+For high-throughput production environments, enable `async_mode` to offload file writing to a background thread. This ensures your application's main thread is never blocked by disk I/O.
+
+```python
+configure_flow("flow.mmd", async_mode=True)
+```
+
+### Data Capture Control
+You can control how function arguments and return values are recorded to keep diagrams clean and secure.
+
+```python
+# Hide sensitive data
+@trace(capture_args=False)
+def login(password):
+    pass
+
+# Truncate long strings (default: 50 chars)
+@trace(max_arg_length=10)
+def process_large_data(data):
+    pass
+```
+
+### Explicit Naming
+If the automatic class/function name inference isn't what you want, you can explicitly name the participant.
+
+```python
+@trace(name="AuthService")  # "AuthService" will appear in the diagram
+def login():
+    pass
+```
+
+### Flexible Handler Configuration
+You can add MermaidTrace to an existing logging setup or append multiple handlers.
+
+```python
+# Append to existing handlers instead of clearing them
+configure_flow("flow.mmd", append=True)
+```
+
 ## CLI Viewer
 
 To view your diagrams, use the CLI:

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/docs/zh/API.md

@@ -12,25 +12,37 @@
 def my_func(): ...
 
 # 详细用法
-@trace(source="Client", target="Server", action="Login")
+@trace(source="Client", target="Server", action="Login", capture_args=False)
 def login(username): ...
 ```
 
 **参数：**
 - `source` (Optional[str]): 调用方参与者名称。如果为 `None`，则从 `contextvars` 推断。
 - `target` (Optional[str]): 被调用方参与者名称。如果为 `None`，则从类名（如果是方法）或模块名推断。
+- `name` (Optional[str]): `target` 的别名。显式设置参与者名称。
 - `action` (Optional[str]): 交互描述。如果为 `None`，默认为格式化后的函数名（例如 `process_payment` -> "Process Payment"）。
+- `capture_args` (bool): 是否记录参数和返回值。默认为 `True`。对于敏感数据可设置为 `False`。
+- `max_arg_length` (int): 参数字符串表示的最大长度。默认为 50。
+- `max_arg_depth` (int): 参数嵌套结构表示的最大深度。默认为 1。
 
 ### `configure_flow`
 
 配置全局日志记录器以输出到 Mermaid 文件。应在应用程序启动时调用一次。
 
 ```python
-def configure_flow(output_file: str = "flow.mmd") -> logging.Logger
+def configure_flow(
+    output_file: str = "flow.mmd",
+    handlers: Optional[List[logging.Handler]] = None,
+    append: bool = False,
+    async_mode: bool = False
+) -> logging.Logger
 ```
 
 **参数：**
 - `output_file` (str): `.mmd` 输出文件的路径。默认为 "flow.mmd"。
+- `handlers` (List[logging.Handler]): 可选的自定义日志处理器列表。如果提供，`output_file` 将被忽略，除非您手动包含了 `MermaidFileHandler`。
+- `append` (bool): 如果为 `True`，则添加新的处理器而不移除现有的。默认为 `False`。
+- `async_mode` (bool): 如果为 `True`，使用非阻塞后台线程进行日志记录 (QueueHandler)。推荐用于生产环境。默认为 `False`。
 
 ### `LogContext`
 

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/docs/zh/CHANGELOG.md

@@ -5,12 +5,26 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
 并且本项目遵守 [Semantic Versioning](https://semver.org/lang/zh-CN/)（语义化版本控制）。
 
+## [0.4.0] - 2026-01-26
+
+### 新增
+- **异步模式**: 在 `configure_flow` 中引入了 `async_mode=True`，将日志写入操作卸载到后台线程，消除了主应用程序循环中的 I/O 阻塞。
+- **数据隐私**: 为 `@trace` 添加了 `capture_args=False`，以防止敏感参数被记录。
+- **参数截断**: 为 `@trace` 添加了 `max_arg_length` 和 `max_arg_depth`，以控制记录的数据结构的大小。
+- **显式命名**: 为 `@trace` 添加了 `name`（或 `target` 别名）参数，用于显式设置参与者名称，覆盖自动推断。
+- **灵活配置**: 更新了 `configure_flow` 以接受自定义 Handler 列表和 `append` 标志，允许更好地与现有日志设置集成。
+
+### 改进
+- **测试覆盖率**: 实现了 >90% 的测试覆盖率，拥有覆盖单元、集成和并发场景的全面新测试套件。
+- **PyPI 合规性**: 切换到通过 `hatch-vcs` 进行动态版本控制，并改进了包元数据和工件包含。
+
 ## [0.3.1] - 2026-01-26
 
 ### 修复
 - **CI/CD**: 通过在所有工作流中统一使用可编辑安装 (`pip install -e .[dev]`)，解决了 GitHub Actions 中的测试覆盖率报告问题。
 - **CI/CD**: 调整了 `pyproject.toml` 中的覆盖率配置，以正确指向源代码目录 (`src/mermaid_trace`)。
 - **文档**: 修复了 README 中的徽章链接，使用了统一的样式和有效的来源。
+- **兼容性**: 在项目分类器和 CI 工作流中正式添加了对 Python 3.13 和 3.14 的支持。
 
 ## [0.3.0] - 2026-01-26
 
@@ -47,7 +61,7 @@ MermaidTrace 已从通用的日志包装器转型为专门的 **执行流可视
 - **上下文推断**：使用 `contextvars` 自动检测 `source`（源）参与者，无需手动连线即可实现嵌套调用可视化。
 - **Mermaid 处理器**：专门的日志处理器，实时写入 `.mmd` 文件。
 - **CLI 工具**：添加了 `mermaid-trace serve <file.mmd>` 命令，可在浏览器中预览生成的图表。
-- **FastAPI 中间件**：`MermaidTraceMiddleware`，用于零配置 HTTP 请求追踪。
+- **FastAPI 中间件**：`MermaidTraceMiddleware` for zero-config HTTP request tracing.
 - **数据捕获**：支持在图表中捕获并显示函数参数和返回值。
 
 ### 移除

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/docs/zh/CONTRIBUTING.md

@@ -29,7 +29,12 @@
 
 4.  **运行测试**：
     ```bash
+    # 运行所有测试
     pytest
+
+    # 跨多个 Python 版本运行测试 (需要 tox)
+    pip install tox
+    tox
     ```
 
 ## 代码风格指南
@@ -38,12 +43,17 @@
 
 - 所有 Python 代码均使用 `ruff` 进行 lint 检查。
 - 所有 Python 代码均使用 `mypy` 进行类型检查。
+- 我们使用 `hatch` 进行构建管理，使用 `hatch-vcs` 进行动态版本控制。
 
 要在本地运行检查：
 
 ```bash
+# 使用 tox (推荐)
+tox -e lint
+
+# 或者手动运行
 ruff check src tests
-mypy src
+mypy src/mermaid_trace
 ```
 
 ## Pull Request 流程

{mermaid_trace-0.3.1 → mermaid_trace-0.4.0}/docs/zh/USER_GUIDE.md

@@ -41,6 +41,47 @@ MermaidTrace 使用 Python 的 `contextvars` 来追踪“当前参与者”。
 
 这意味着通常您只需要在 *入口点*（第一个函数）设置 `source`。
 
+## 高级配置
+
+### 异步模式 (性能优化)
+对于高吞吐量的生产环境，请启用 `async_mode` 将文件写入操作卸载到后台线程。这确保了您的应用程序主线程永远不会被磁盘 I/O 阻塞。
+
+```python
+configure_flow("flow.mmd", async_mode=True)
+```
+
+### 数据捕获控制
+您可以控制如何记录函数参数和返回值，以保持图表整洁并保护敏感数据。
+
+```python
+# 隐藏敏感数据
+@trace(capture_args=False)
+def login(password):
+    pass
+
+# 截断长字符串 (默认: 50 字符)
+@trace(max_arg_length=10)
+def process_large_data(data):
+    pass
+```
+
+### 显式命名
+如果自动推断的类名/函数名不是您想要的，您可以显式命名参与者。
+
+```python
+@trace(name="AuthService")  # 图表中将显示 "AuthService"
+def login():
+    pass
+```
+
+### 灵活的 Handler 配置
+您可以将 MermaidTrace 添加到现有的日志设置中，或者追加多个 Handler。
+
+```python
+# 追加到现有的 Handler，而不是清除它们
+configure_flow("flow.mmd", append=True)
+```
+
 ## CLI 查看器
 
 要查看您的图表，请使用 CLI：

mermaid_trace-0.4.0/docs/zh/code_comments/src/mermaid_trace/__init__.md

@@ -0,0 +1,122 @@
+# 文件: src/mermaid_trace/__init__.py
+
+## 概览
+本文件是 `mermaid-trace` 包的入口点。它导出了主要的 API，如 `trace` 装饰器、`LogContext` 上下文管理器和 `configure_flow` 配置函数。
+
+## 核心功能分析
+
+### configure_flow
+这是配置日志系统的核心函数。它负责：
+1.  初始化专用的 Logger (`mermaid_trace.flow`)。
+2.  管理 Handler（处理器）的生命周期：
+    -   默认情况下，它会清除现有的 Handler，保证配置的幂等性。
+    -   通过 `append=True` 参数，允许用户追加新的 Handler 而不覆盖旧的。
+3.  **异步支持**：通过 `async_mode` 参数，它能够将实际的 Handler 包装在 `AsyncMermaidHandler` (QueueHandler) 中，从而将文件写入操作移至后台线程，避免阻塞主循环。
+
+## 源代码与中文注释
+
+```python
+"""
+MermaidTrace: 将 Python 代码执行流可视化为 Mermaid 时序图。
+
+该包提供了自动追踪函数调用并生成兼容 Mermaid 的时序图（.mmd 文件）的工具。
+旨在帮助开发者理解应用程序的流程、调试复杂的交互并记录系统行为。
+
+关键组件:
+- `trace`: 用于检测函数进行追踪的装饰器。它捕获参数、返回值和错误，并将它们记录为交互。
+- `LogContext`: 管理执行上下文（类似于线程本地存储），用于在异步任务和线程之间追踪调用者/被调用者关系。
+- `configure_flow`: 设置日志处理器以将图表写入文件。它处理处理器配置、文件模式和异步日志设置。
+"""
+
+from .core.decorators import trace_interaction, trace
+from .handlers.mermaid_handler import MermaidFileHandler
+from .handlers.async_handler import AsyncMermaidHandler
+from .core.events import FlowEvent
+from .core.context import LogContext
+from .core.formatter import MermaidFormatter
+
+# 默认不导入集成模块，以避免硬依赖
+# 如果需要，用户必须显式导入集成（如 FastAPI）。
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import List, Optional
+
+import logging
+
+def configure_flow(
+    output_file: str = "flow.mmd",
+    handlers: Optional[List[logging.Handler]] = None,
+    append: bool = False,
+    async_mode: bool = False
+) -> logging.Logger:
+    """
+    配置流程日志记录器以输出到 Mermaid 文件。
+    
+    此函数设置捕获追踪事件并将其写入指定输出文件所需的日志基础设施。
+    应在应用程序启动时调用一次以初始化追踪系统。
+    
+    参数:
+        output_file (str): 输出 .mmd 文件的绝对或相对路径。
+                           默认为当前目录下的 "flow.mmd"。
+                           如果文件不存在，将使用正确的头部创建它。
+        handlers (List[logging.Handler], optional): 自定义日志处理器列表。
+                                                    如果提供，'output_file' 将被忽略，除非
+                                                    你显式包含 MermaidFileHandler。
+                                                    如果你想将日志流式传输到其他目的地，这很有用。
+        append (bool): 如果为 True，则添加新处理器而不移除现有处理器。
+                       默认为 False（清除现有处理器以防止重复记录）。
+        async_mode (bool): 如果为 True，使用非阻塞后台线程进行日志记录 (QueueHandler)。
+                           推荐用于高性能生产环境，以避免在文件 I/O 期间阻塞主执行线程。
+                           默认为 False。
+    
+    返回:
+        logging.Logger: 用于流程追踪的已配置日志记录器实例。
+    """
+    # 获取追踪装饰器使用的特定日志记录器
+    # 此日志记录器与根日志记录器隔离，以防止污染
+    logger = logging.getLogger("mermaid_trace.flow")
+    logger.setLevel(logging.INFO)
+    
+    # 移除现有处理器以避免重复日志（如果配置了多次）
+    # 除非请求了 'append'。这确保了多次调用 configure_flow 时的幂等性。
+    if not append and logger.hasHandlers():
+        logger.handlers.clear()
+        
+    # 确定目标处理器
+    target_handlers = []
+    
+    if handlers:
+        # 如果可用，使用用户提供的处理器
+        target_handlers = handlers
+    else:
+        # 创建默认 Mermaid 处理器
+        # 此处理器知道如何写入 Mermaid 头部并格式化事件
+        handler = MermaidFileHandler(output_file)
+        handler.setFormatter(MermaidFormatter())
+        target_handlers = [handler]
+    
+    if async_mode:
+        # 将目标处理器包装在 AsyncMermaidHandler (QueueHandler) 中
+        # QueueListener 将从队列中提取日志并分发到目标处理器
+        # 这将应用程序执行与日志 I/O 解耦
+        async_handler = AsyncMermaidHandler(target_handlers)
+        logger.addHandler(async_handler)
+    else:
+        # 直接将处理器附加到日志记录器以进行同步日志记录
+        # 简单可靠，适用于调试或低吞吐量应用程序
+        for h in target_handlers:
+            logger.addHandler(h)
+    
+    return logger
+
+try:
+    # 尝试检索已安装的包版本
+    __version__ = version("mermaid-trace")
+except PackageNotFoundError:
+    # 如果包未安装（例如，本地开发），则使用回退版本
+    __version__ = "0.0.0"
+
+
+# 导出公共 API 以方便访问
+__all__ = ["trace_interaction", "trace", "configure_flow", "MermaidFileHandler", "AsyncMermaidHandler", "LogContext", "FlowEvent", "MermaidFormatter"]
+```