mqttxx 3.1.2__py3-none-any.whl → 3.2.1__py3-none-any.whl

{mqttxx-3.1.2.dist-info → mqttxx-3.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mqttxx
-Version: 3.1.2
+Version: 3.2.1
 Summary: 基于 aiomqtt 的高级 MQTT 客户端和 RPC 框架
 Author: MQTTX Team
 License: MIT
@@ -12,13 +12,14 @@ Requires-Dist: loguru >=0.7.0
 Provides-Extra: dev
 Requires-Dist: pytest ; extra == 'dev'
 Requires-Dist: pytest-asyncio ; extra == 'dev'
+Requires-Dist: pytest-rich ; extra == 'dev'
 Requires-Dist: ruff ; extra == 'dev'
 Requires-Dist: build ; extra == 'dev'
 Requires-Dist: twine ; extra == 'dev'
 
 # MQTTX
 
-[![PyPI version](https://img.shields.io/badge/version-3.0.0-blue.svg)](https://pypi.org/project/mqttxx/)
+[![PyPI version](https://img.shields.io/badge/version-3.2.0-blue.svg)](https://pypi.org/project/mqttxx/)
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
@@ -34,7 +35,6 @@ Requires-Dist: twine ; extra == 'dev'
 - ✅ **Event Channel** - 高吞吐事件广播，支持通配符订阅
 - ✅ **TLS/SSL 支持** - 安全连接、双向认证
 - ✅ **完善异常系统** - 统一错误码、清晰的异常层次
-- ✅ **可插拔编解码器** - 支持 JSON/MessagePack/Protobuf 等自定义协议
 - ✅ **生产级可靠性** - 修复所有 P0 缺陷（任务泄漏、资源泄漏、并发竞态）
 
 ---
@@ -50,11 +50,12 @@ Requires-Dist: twine ; extra == 'dev'
   - [传统 RPC](#4-rpc-基础用法传统模式)
   - [RPC 权限控制](#5-rpc-权限控制)
   - [TLS/SSL 和认证](#6-tlsssl-和认证)
+- [架构与实现](#架构与实现)
 - [API 速查](#api-速查)
 - [配置对象](#配置对象)
 - [异常系统](#异常系统)
 - [RPC 消息协议](#rpc-消息协议)
-- [版本变更](#v200-重大变更)
+- [版本变更](#版本变更)
 - [开发](#开发)
 - [示例项目](#示例项目)
 - [常见问题](#常见问题)
@@ -72,47 +73,23 @@ MQTTX 遵循严格的分层架构，确保职责清晰、代码简洁、易于
   - 不导入 `json` 或 `protocol` 模块
   - 不理解消息内容
   - `publish()` 只接受 `bytes`
-  - `subscribe_raw()` handler 接收 `bytes`
+  - `subscribe()` handler 接收 `bytes`
 
 ### 2. Protocol（协议层）
-- **职责**：定义消息格式和编解码
+- **职责**：定义消息格式和 JSON 编解码
 - **核心**：
-  - `encode()` 方法：object → bytes
-  - `decode()` 方法：bytes → object
-  - JSON 只在这里出现
+  - `encode()` 方法：object → bytes（使用 JSON）
+  - `decode()` 方法：bytes → object（使用 JSON）
+  - 所有 JSON 操作只在这一层
 
 ### 3. RPCManager/EventChannelManager（应用层）
 - **职责**：业务逻辑处理
 - **约束**：
-  - 内部永远使用类型化对象（RPCRequest/RPCResponse）
+  - 内部永远使用类型化对象（RPCRequest/RPCResponse/EventMessage）
   - 调用 `encode()`/`decode()` 处理编解码
   - 不直接使用 `json.dumps()`/`json.loads()`
 
-### 可插拔编解码器
-
-支持自定义编解码器（例如 MessagePack）：
-
-```python
-import msgpack
-from mqttxx.protocol import Codec
-
-class MessagePackCodec:
-    @staticmethod
-    def encode(obj) -> bytes:
-        if hasattr(obj, 'to_dict'):
-            data = obj.to_dict()
-        else:
-            data = obj
-        return msgpack.packb(data)
-
-    @staticmethod
-    def decode(data: bytes) -> dict:
-        return msgpack.unpackb(data, raw=False)
-
-# 使用
-from mqttxx import RPCManager
-rpc = RPCManager(client, codec=MessagePackCodec)
-```
+**设计理念**：固定使用 JSON 编解码，简化架构，降低复杂度。如需自定义协议，可在传输层直接使用 `MQTTClient.subscribe()` 处理 bytes。
 
 ---
 
@@ -163,10 +140,10 @@ asyncio.run(main())
 
 ### 2. 约定式 RPC（零配置）
 
-**推荐**：使用 `ConventionalRPCManager`，自动订阅 + 自动注入 reply_to。
+**推荐**：使用 `RPCManager` 的 `my_topic` 参数，自动订阅 + 自动注入 reply_to。
 
 ```python
-from mqttxx import MQTTClient, MQTTConfig, ConventionalRPCManager
+from mqttxx import MQTTClient, MQTTConfig, RPCManager
 
 # 边缘设备
 async def edge_device():
@@ -178,7 +155,7 @@ async def edge_device():
 
     async with MQTTClient(config) as client:
         # 自动订阅 edge/device_123
-        rpc = ConventionalRPCManager(client, my_topic=f"edge/{client_id}")
+        rpc = RPCManager(client, my_topic=f"edge/{client_id}")
 
         @rpc.register("get_status")
         async def get_status(params):
@@ -200,7 +177,7 @@ async def cloud_service():
 
     async with MQTTClient(config) as client:
         # 自动订阅 cloud/config-service
-        rpc = ConventionalRPCManager(client, my_topic=f"cloud/{client_id}")
+        rpc = RPCManager(client, my_topic=f"cloud/{client_id}")
 
         @rpc.register("get_device_config")
         async def get_device_config(params):
@@ -220,7 +197,7 @@ asyncio.run(edge_device())  # 或 asyncio.run(cloud_service())
 
 | 场景 | 传统 RPC | 约定式 RPC |
 |-----|---------|-----------|
-| 初始化 | `rpc = RPCManager(client)`<br>`client.subscribe("edge/123", rpc.handle_rpc_message)` | `rpc = ConventionalRPCManager(client, my_topic="edge/123")`<br>→ 自动订阅 |
+| 初始化 | `rpc = RPCManager(client)`<br>`client.subscribe("edge/123", rpc.handle_rpc_message)` | `rpc = RPCManager(client, my_topic="edge/123")`<br>→ 自动订阅 |
 | 调用 | `await rpc.call(topic="cloud/svc", method="get", reply_to="edge/123")` | `await rpc.call("cloud/svc", "get")` |
 | 代码量 | 100% | **60%** ↓ |
 
@@ -293,7 +270,7 @@ asyncio.run(main())
 
 ```python
 # 同时使用 RPC 和 Event Channel
-rpc = ConventionalRPCManager(client, my_topic="device/device_001")
+rpc = RPCManager(client, my_topic="device/device_001")
 events = EventChannelManager(client)
 
 # RPC: 获取配置（需要返回值）
@@ -400,6 +377,17 @@ async with MQTTClient(config) as client:
 
 ---
 
+## 架构与实现
+
+深入了解 MQTTX 的技术实现细节：
+
+- **[消息路由实现逻辑](docs/routing_flow.md)** - 使用 Mermaid 图表说明从 MQTT Broker 到最终处理器的完整消息流程、订阅注册机制、通配符匹配算法，以及关键代码位置
+- **[约定式 RPC 用法详解](docs/约定式RPC用法.md)** - 深入解析零配置 RPC 调用的设计原理、自动订阅机制、reply_to 自动注入，以及与传统 RPC 的对比
+
+**推荐阅读顺序**：先通过上方的"快速开始"掌握基本用法，再深入技术文档了解底层实现。
+
+---
+
 ## API 速查
 
 ### MQTTClient
@@ -422,7 +410,13 @@ class MQTTClient:
 
 ```python
 class RPCManager:
-    def __init__(self, client: MQTTClient, config: RPCConfig = None, auth_callback: AuthCallback = None)
+    def __init__(
+        self,
+        client: MQTTClient,
+        my_topic: Optional[str] = None,
+        config: RPCConfig = None,
+        auth_callback: AuthCallback = None
+    )
 
     def register(self, method_name: str)  # 装饰器
     def unregister(self, method_name: str) -> None
@@ -440,14 +434,14 @@ class RPCManager:
 
 ---
 
-### ConventionalRPCManager（约定式 RPC）
+### RPCManager（约定式用法）
 
 ```python
-class ConventionalRPCManager(RPCManager):
+class RPCManager:
     def __init__(
         self,
         client: MQTTClient,
-        my_topic: str,  # 本节点 topic（自动订阅，自动注入到 reply_to）
+        my_topic: Optional[str] = None,  # 本节点 topic（自动订阅，自动注入到 reply_to）
         config: RPCConfig = None,
         auth_callback: AuthCallback = None,
     )
@@ -458,26 +452,26 @@ class ConventionalRPCManager(RPCManager):
         method: str,
         params: Any = None,
         timeout: float = None,
-        reply_to: str = None,  # 可选，默认使用 my_topic
+        reply_to: Optional[str] = None,  # 可选，默认使用 my_topic
     ) -> Any
 
     # 属性
-    my_topic: str      # 当前 topic（只读）
+    my_topic: Optional[str]      # 当前 topic（只读）
 ```
 
 **使用示例：**
 
 ```python
 # 边缘设备
-rpc = ConventionalRPCManager(client, my_topic="edge/device_123")
+rpc = RPCManager(client, my_topic="edge/device_123")
 config = await rpc.call("cloud/config-service", "get_config")
 
 # 云端服务
-rpc = ConventionalRPCManager(client, my_topic="cloud/config-service")
+rpc = RPCManager(client, my_topic="cloud/config-service")
 status = await rpc.call("edge/device_123", "execute_command")
 
 # 微服务
-rpc = ConventionalRPCManager(client, my_topic="auth-service")
+rpc = RPCManager(client, my_topic="auth-service")
 user = await rpc.call("user-service", "get_user", params={"id": 123})
 ```
 
@@ -704,7 +698,34 @@ except RPCRemoteError as e:
 
 ---
 
-## v2.0.0 重大变更
+## 版本变更
+
+### v3.2.0（当前版本）
+
+**架构简化**：
+- ✅ **移除可插拔编解码器** - 固定使用 JSON 编解码，简化架构设计
+- ✅ **整合约定式 RPC** - `my_topic` 参数集成到 `RPCManager`，移除独立的 `ConventionalRPCManager`
+- ✅ **整合传输层 API** - `RawAPI` 功能整合到 `MQTTClient`，统一接口
+
+**迁移指南（从 v3.1.x）**：
+1. **移除 Codec 相关代码** - 不再支持自定义编解码器（如 MessagePack），统一使用 JSON
+   ```python
+   # ❌ 旧代码（不再支持）
+   rpc = RPCManager(client, codec=MessagePackCodec)
+
+   # ✅ 新代码（固定 JSON）
+   rpc = RPCManager(client)
+   ```
+2. **使用约定式 RPC** - 推荐使用 `my_topic` 参数简化代码
+   ```python
+   # ✅ 推荐写法
+   rpc = RPCManager(client, my_topic="edge/device_123")
+   result = await rpc.call("cloud/server", "get_config")  # 自动注入 reply_to
+   ```
+
+---
+
+### v2.0.0 重大变更
 
 从 v2.0.0 开始，完全重写为基于 aiomqtt（纯 async/await），**不兼容** v0.x.x（gmqtt）。
 
@@ -712,13 +733,13 @@ except RPCRemoteError as e:
 - ✅ aiomqtt 替代 gmqtt
 - ✅ 原生 dataclass 替代 python-box（性能提升 6 倍）
 - ✅ **修复所有 P0 缺陷**（详见下方）
-- ✅ 新增约定式 RPC（`ConventionalRPCManager`）
+- ✅ 新增约定式 RPC（`RPCManager` 的 `my_topic` 参数）
 - ✅ 新增权限控制（`auth_callback`）
 - ✅ 新增 TLS/SSL 支持
 
 **P0 缺陷修复（v3.0）**：
 1. **任务泄漏 + 消息处理模型** - Queue + Worker 模式，可控并发
-2. **RawAPI.unsubscribe 缺失** - 实现完整的取消订阅功能
+2. **取消订阅功能缺失** - 实现完整的取消订阅功能
 3. **重连竞态条件** - 快照模式避免并发修改
 4. **连接资源泄漏** - 显式关闭连接
 

mqttxx-3.2.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+mqttxx/__init__.py,sha256=_WoU5oZfMOJetRH1JkLuICp8PlqxpN3BWyXeZEjXeVo,1908
+mqttxx/client.py,sha256=7umy-hJ-TUW9XD_rMdTh71q9Z7rlifnVPvHA80aIbcI,18794
+mqttxx/config.py,sha256=A4AK54FL3eNyOCQ4E5IowIkC34zpT43d1bJzX0VOAHk,5986
+mqttxx/events.py,sha256=bs7Khp6ygDK_aEOXftb74HO3SMqOY_Ln9Se_ro6ryiE,11747
+mqttxx/exceptions.py,sha256=EC9NZmvZbfrK9iEdSyoYt4pUl0dp7yVup8mjOfgBaMw,3704
+mqttxx/protocol.py,sha256=EwXJQ0Ic25oJx55coAfvntOxWh5FYYlBSMV93Cm6hHU,7445
+mqttxx/rpc.py,sha256=KBu2006o9NukqbUk7ehvyIwgrdbO1CqY4rdo-OKr1KM,15831
+mqttxx-3.2.1.dist-info/LICENSE,sha256=tfwCF8HPjAvvq_veljjH3_YL90X6ttkjTpRl3BGcXTg,1067
+mqttxx-3.2.1.dist-info/METADATA,sha256=wFasvCdIOFRVZLnYEM84gxbRLE9uWd4CYa0VEtOFMGE,25544
+mqttxx-3.2.1.dist-info/WHEEL,sha256=Z4pYXqR_rTB7OWNDYFOm1qRk0RX6GFP2o8LgvP453Hk,91
+mqttxx-3.2.1.dist-info/top_level.txt,sha256=4SNRXgOpGCT6ThBzAb8zhUmTyZwnIracAIJWAdXXzw0,7
+mqttxx-3.2.1.dist-info/RECORD,,

mqttxx/conventions.py

@@ -1,148 +0,0 @@
-# 约定式 RPC 管理器 - 去角色设计
-
-from typing import Any, Optional, Type
-from loguru import logger
-
-from .client import MQTTClient
-from .config import RPCConfig
-from .rpc import RPCManager, AuthCallback
-from .protocol import Codec, JSONCodec
-
-
-class ConventionalRPCManager(RPCManager):
-    """约定式 RPC 管理器
-
-    设计原则：
-    - 约定优于配置
-    - 自动订阅本地 topic
-    - 自动注入 reply_to
-
-    核心功能：
-    1. 初始化时自动订阅 `my_topic`
-    2. 调用时自动将 `my_topic` 注入到 `reply_to`
-
-    适用场景：
-    - 边缘设备 ↔ 云端（edge/xxx ↔ cloud/xxx）
-    - 微服务之间（auth-service ↔ user-service）
-    - IoT 网关 ↔ 设备（gateway/001 ↔ device/123）
-    - 任何需要简化 RPC 调用的场景
-
-    示例:
-        # 边缘设备
-        rpc = ConventionalRPCManager(client, my_topic="edge/device_123")
-
-        @rpc.register("get_status")
-        async def get_status(params):
-            return {"status": "online"}
-
-        # 调用云端（自动注入 reply_to="edge/device_123"）
-        config = await rpc.call("cloud/config-service", "get_config")
-
-        # 云端服务
-        rpc = ConventionalRPCManager(client, my_topic="cloud/config-service")
-
-        # 调用边缘设备（自动注入 reply_to="cloud/config-service"）
-        status = await rpc.call("edge/device_123", "execute_command")
-    """
-
-    def __init__(
-        self,
-        client: MQTTClient,
-        my_topic: str,
-        config: Optional[RPCConfig] = None,
-        auth_callback: Optional[AuthCallback] = None,
-        codec: Type[Codec] = JSONCodec,  # 新增
-    ):
-        """初始化约定式 RPC 管理器
-
-        Args:
-            client: MQTTClient 实例
-            my_topic: 本节点的 topic（自动订阅，自动注入到 reply_to）
-            config: RPC 配置（可选）
-            auth_callback: 权限检查回调（可选）
-            codec: 编解码器（默认 JSONCodec）
-
-        自动行为：
-        - 自动订阅 my_topic（接收请求和响应）
-        - 自动绑定消息处理器
-
-        示例:
-            # 边缘设备
-            rpc = ConventionalRPCManager(client, my_topic="edge/device_123")
-
-            # 云端服务
-            rpc = ConventionalRPCManager(client, my_topic="cloud/server_001")
-
-            # 微服务
-            rpc = ConventionalRPCManager(client, my_topic="auth-service")
-
-            # 多层级
-            rpc = ConventionalRPCManager(client, my_topic="region/zone/device")
-        """
-        super().__init__(client, config, auth_callback, codec)
-
-        self._my_topic = my_topic
-
-        # 自动设置（订阅响应主题）
-        self.setup(my_topic)
-
-        logger.info(f"ConventionalRPCManager 已初始化 - my_topic: {my_topic}")
-
-    async def call(
-        self,
-        topic: str,
-        method: str,
-        params: Any = None,
-        timeout: Optional[float] = None,
-        reply_to: Optional[str] = None,
-    ) -> Any:
-        """调用远程方法（自动注入 reply_to）
-
-        Args:
-            topic: 对方的 topic
-            method: 方法名
-            params: 参数（可选）
-            timeout: 超时时间（可选）
-            reply_to: 响应 topic（可选，默认使用 my_topic）
-
-        Returns:
-            方法返回值
-
-        Raises:
-            MQTTXError: 客户端未连接
-            RPCTimeoutError: 调用超时
-            RPCRemoteError: 远程执行失败
-
-        示例:
-            # 边缘设备调用云端
-            rpc = ConventionalRPCManager(client, my_topic="edge/device_123")
-            result = await rpc.call("cloud/server_001", "get_config")
-            # 等价于：await super().call("cloud/server_001", "get_config", reply_to="edge/device_123")
-
-            # 云端调用边缘设备
-            rpc = ConventionalRPCManager(client, my_topic="cloud/server_001")
-            result = await rpc.call("edge/device_123", "execute_command", params={"cmd": "restart"})
-
-            # 微服务调用
-            rpc = ConventionalRPCManager(client, my_topic="auth-service")
-            user = await rpc.call("user-service", "get_user", params={"id": 123})
-        """
-        # 自动注入 reply_to
-        reply_to = reply_to or self._my_topic
-
-        return await super().call(
-            topic=topic,
-            method=method,
-            params=params,
-            timeout=timeout,
-            reply_to=reply_to,
-        )
-
-    @property
-    def my_topic(self) -> str:
-        """获取当前节点的 topic
-
-        Returns:
-            当前节点订阅的 topic
-        """
-        return self._my_topic

mqttxx-3.1.2.dist-info/RECORD

@@ -1,13 +0,0 @@
-mqttxx/__init__.py,sha256=bNvLfcG5AgCpOrS1B4LEsDeVi-cKLuw0fYTOdlJoxS8,2072
-mqttxx/client.py,sha256=lc1V6yPqq15PhmmU6L1Tspikg1b18jPLTkZe7ElmSTE,21807
-mqttxx/config.py,sha256=A4AK54FL3eNyOCQ4E5IowIkC34zpT43d1bJzX0VOAHk,5986
-mqttxx/conventions.py,sha256=ZP5FkYBCJiee1co041pbPv4x31i9HuG9KbeUFaDsoBs,4683
-mqttxx/events.py,sha256=IG6ca4Gmm1P4sJUmZXTw6I2lHjVawJkpBjzX1GNerBM,11368
-mqttxx/exceptions.py,sha256=EC9NZmvZbfrK9iEdSyoYt4pUl0dp7yVup8mjOfgBaMw,3704
-mqttxx/protocol.py,sha256=GZYL2Fvi4-R0Tuyxrcp8-ttLWx9wyoH4-ZtzNq1wYxo,10034
-mqttxx/rpc.py,sha256=6syEzmDZr2BQE2_LbdtrdTeWkrz3MAlAebbuX9O5-pY,15197
-mqttxx-3.1.2.dist-info/LICENSE,sha256=tfwCF8HPjAvvq_veljjH3_YL90X6ttkjTpRl3BGcXTg,1067
-mqttxx-3.1.2.dist-info/METADATA,sha256=ncDgBLxFEkCYeQhIz1nO3Mt5SUrodJq89U2ONATVoOg,24337
-mqttxx-3.1.2.dist-info/WHEEL,sha256=Z4pYXqR_rTB7OWNDYFOm1qRk0RX6GFP2o8LgvP453Hk,91
-mqttxx-3.1.2.dist-info/top_level.txt,sha256=4SNRXgOpGCT6ThBzAb8zhUmTyZwnIracAIJWAdXXzw0,7
-mqttxx-3.1.2.dist-info/RECORD,,