metamessage 0.1.0__tar.gz

metamessage-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include pyproject.toml
+recursive-include metamessage *.py
+recursive-include tests *.py
+recursive-include examples *

metamessage-0.1.0/PKG-INFO

@@ -0,0 +1,354 @@
+Metadata-Version: 2.4
+Name: metamessage
+Version: 0.1.0
+Summary: High-performance binary message encoding library with schema tag support
+Author: MetaMessage Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/metamessage/metamessage
+Project-URL: Repository, https://github.com/metamessage/metamessage
+Keywords: serialization,binary,encoding,metamessage,schema
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Archiving :: Packaging
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# MetaMessage
+
+MetaMessage - 高性能二进制消息编码库，支持模式标记（schema tags）、JSONC 注释语法，以及 Python 装饰器驱动的序列化。
+
+## 功能特性
+
+- **二进制编码/解码** — 将 Python 值高效编码为紧凑二进制格式
+- **`@mm` 装饰器** — 类似 Go 结构体标签的 Python 装饰器语法
+- **JSONC 支持** — 解析带 `// mm:` 注释的 JSON 格式
+- **Node 中间表示** — 通过 `value_to_node` / `node_to_value` 操作节点树
+- **类型自动推断** — 根据 Python 类型注解自动推断 MetaMessage 类型
+- **嵌套结构** — 支持字典、列表、类实例的递归转换
+
+## 安装
+
+### pip 安装
+
+```bash
+pip install metamessage
+```
+
+### 版本要求
+
+- Python 3.7 或更高版本
+
+## 快速开始
+
+### 基础编码/解码
+
+```python
+from metamessage import encode_from_value, decode_to_value
+
+# 编码 Python 值 → 二进制
+binary = encode_from_value({"name": "Alice", "age": 30})
+print(f"Encoded: {len(binary)} bytes")
+
+# 解码二进制 → Python 值
+result = decode_to_value(binary)
+print(result)  # {'name': 'Alice', 'age': 30}
+```
+
+### 字符串/数字/布尔值
+
+```python
+from metamessage import encode_from_value, decode_to_value
+
+for val in ["hello", 42, 3.14, True, b"bytes"]:
+    binary = encode_from_value(val)
+    result = decode_to_value(binary)
+    print(f"{val!r} → {result!r}")
+```
+
+## @mm 装饰器
+
+`@mm` 装饰器为 Python 类添加 MetaMessage 模式信息，类似 Go 的结构体标签。
+
+`mm` 支持两种用法：
+- **类级装饰器**：`@mm(desc="...")` 放在 `class` 定义上方
+- **字段级标记**：`field: type = mm(desc="...")` 作为字段默认值（推荐）
+
+### 类级 + 字段级装饰器（推荐）
+
+```python
+from metamessage import mm, ValueType, encode_from_value, decode_to_value
+
+@mm(desc="User information")
+class User:
+    id: int = mm(desc="User ID")
+    name: str = mm(desc="User name")
+    age: int = mm(desc="User age")
+
+    def __init__(self, id: int = 0, name: str = "", age: int = 0):
+        self.id = id
+        self.name = name
+        self.age = age
+
+user = User(id=1, name="Alice", age=30)
+binary = encode_from_value(user)
+# binary -> {'id': 1, 'name': 'Alice', 'age': 30}
+```
+
+### 带类型和约束
+
+```python
+@mm(desc="Product")
+class Product:
+    id: int = mm(desc="Product ID", type=ValueType.Int64, min=1)
+    name: str = mm(desc="Name", min=1, max=100)
+    price: float = mm(desc="Price", min=0.0, max=999999.99)
+
+    def __init__(self, id: int = 0, name: str = "", price: float = 0.0):
+        self.id = id
+        self.name = name
+        self.price = price
+```
+
+### 仅类级装饰器
+
+```python
+@mm(desc="User information")
+class User:
+    id: int
+    name: str
+    age: int
+
+    def __init__(self, id: int = 0, name: str = "", age: int = 0):
+        self.id = id
+        self.name = name
+        self.age = age
+```
+
+### 字符串标签语法
+
+```python
+@mm("desc=Product; type=i64")
+class Product:
+    id: int
+    name: str
+    price: float
+
+    def __init__(self, id: int = 0, name: str = "", price: float = 0.0):
+        self.id = id
+        self.name = name
+        self.price = price
+```
+
+## Node 中间表示
+
+MetaMessage 使用 Node 树作为中间表示（IR）：
+
+| 节点类型 | Python 类 | 描述 |
+|---------|----------|------|
+| `Val` | 值节点 | 存储标量值（字符串、数字、布尔等） |
+| `Obj` | 对象节点 | 键值对集合（对应 dict / 类实例） |
+| `Arr` | 数组节点 | 有序元素列表 |
+
+### value_to_node / node_to_value
+
+```python
+from metamessage import value_to_node, node_to_value
+
+# Python 值 → Node 树
+node = value_to_node({"x": 10, "y": 20})
+
+# Node 树 → Python 值
+result = node_to_value(node, dict)
+print(result)  # {'x': 10, 'y': 20}
+```
+
+### 手动构建 Node
+
+```python
+from metamessage import Tag, ValueType, Obj, Arr, Val, Field, Encoder, Decoder
+
+obj = Obj(
+    fields=[
+        Field(key="name", value=Val(data="John", text="John",
+                                     tag=Tag(type=ValueType.String))),
+        Field(key="age", value=Val(data=30, text="30",
+                                    tag=Tag(type=ValueType.Int))),
+    ],
+    tag=Tag(name="person")
+)
+
+encoder = Encoder()
+binary = encoder.encode(obj)
+decoder = Decoder(binary)
+result = decoder.decode()
+print(result)  # {'name': 'John', 'age': 30}
+```
+
+## JSONC 支持
+
+JSONC 是带 `// mm:` 注释的 JSON 格式，用于声明模式标记：
+
+### 解析 JSONC
+
+```python
+from metamessage import parse_jsonc, to_jsonc
+
+jsonc = """{
+    // mm: type=str; desc=姓名
+    "name": "Alice",
+    // mm: type=i; desc=年龄
+    "age": 30
+}"""
+
+node = parse_jsonc(jsonc)
+for field in node.fields:
+    print(f"{field.key}: type={field.value.tag.type}, desc={field.value.tag.desc}")
+
+# 转回 JSONC 字符串
+output = to_jsonc(node)
+print(output)
+```
+
+### JSONC -> 二进制 -> 解码
+
+```python
+from metamessage import parse_jsonc, encode_from_value, decode_to_value
+
+# 1. 解析 JSONC 获取 Node
+node = parse_jsonc(jsonc_source)
+
+# 2. 直接编码字典
+binary = encode_from_value({"name": "Alice", "age": 30})
+
+# 3. 解码
+result = decode_to_value(binary)
+```
+
+## 完整示例
+
+查看 `examples/python/` 目录下的示例代码：
+
+| 文件 | 说明 |
+|------|------|
+| `basic_encode_decode.py` | 基本编码/解码 |
+| `dict_and_list.py` | 字典和列表操作 |
+| `nested_structures.py` | 嵌套结构 |
+| `mm_decorator.py` | @mm 装饰器使用 |
+| `jsonc_roundtrip.py` | JSONC 完整流程 |
+| `value_to_node_api.py` | Node API 使用 |
+
+运行示例：
+
+```bash
+# 在 mm-py 目录下
+PYTHONPATH=. python3 examples/python/basic_encode_decode.py
+PYTHONPATH=. python3 examples/python/dict_and_list.py
+PYTHONPATH=. python3 examples/python/nested_structures.py
+```
+
+## Tag 参数说明
+
+### 基本参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `type` | `ValueType` | 数据类型 |
+| `desc` | `str` | 描述 |
+| `nullable` | `bool` | 是否可空 |
+| `allow_empty` | `bool` | 是否允许空值 |
+| `default` | `str` | 默认值 |
+| `raw` | `bool` | 是否原始模式 |
+| `example` | `bool` | 是否为示例 |
+| `unique` | `bool` | 是否唯一 |
+
+### 约束参数
+
+| 参数 | 适用类型 | 说明 |
+|------|---------|------|
+| `min` | int/float/bytes/string | 最小值/长度 |
+| `max` | int/float/bytes/string | 最大值/长度 |
+| `size` | array/bytes/string | 固定大小 |
+| `pattern` | string | 正则表达式 |
+| `enum` | enum | 枚举值列表（`"a\|b\|c"`） |
+| `version` | uuid/ip | 版本号 |
+| `mime` | bytes | MIME 类型 |
+| `location` | datetime | 时区偏移（-12 ~ +14） |
+
+### 子元素参数
+
+| 参数 | 说明 |
+|------|------|
+| `child_type` | 子元素类型 |
+| `child_desc` | 子元素描述 |
+| `child_raw` | 子元素原始模式 |
+| `child_nullable` | 子元素可空 |
+| `child_allow_empty` | 子元素允许空值 |
+| `child_unique` | 子元素唯一 |
+| `child_default` | 子元素默认值 |
+| `child_min` | 子元素最小值 |
+| `child_max` | 子元素最大值 |
+| `child_size` | 子元素大小 |
+| `child_enum` | 子元素枚举 |
+| `child_pattern` | 子元素模式 |
+| `child_version` | 子元素版本 |
+| `child_mime` | 子元素 MIME |
+
+## API 参考
+
+### 高层 API
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `encode_from_value` | `(value: Any) -> bytes` | Python 值 → 二进制 |
+| `decode_to_value` | `(data: bytes, target_type=Any) -> Any` | 二进制 → Python 值 |
+| `value_to_node` | `(value: Any, tag=None, depth=0, path="") -> Node` | Python 值 → Node 树 |
+| `node_to_value` | `(node: Node, target_type) -> Any` | Node 树 → Python 值 |
+
+### 核心类
+
+| 类 | 说明 |
+|------|------|
+| `Encoder` | 编码器：`Encoder().encode(node) -> bytes` |
+| `Decoder` | 解码器：`Decoder(data).decode() -> Any` |
+| `Tag` | 模式标记：类型、约束、描述等 |
+| `ValueType` | 类型枚举：`String`, `Int`, `Float64`, `Bool` 等 |
+
+### JSONC API
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `parse_jsonc` | `(source: str) -> Node` | 解析 JSONC 字符串为 Node |
+| `to_jsonc` | `(node: Node) -> str` | 将 Node 转回 JSONC 字符串 |
+
+### 装饰器
+
+| 装饰器 | 说明 |
+|--------|------|
+| `@mm(...)` | 类级标记装饰器 |
+
+## 测试
+
+```bash
+# 运行主测试套件
+python3 metamessage_test.py
+
+# 运行分类测试
+python3 tests/test_encoder.py
+python3 tests/test_decoder.py
+python3 tests/test_jsonc.py
+python3 tests/test_value_to_node.py
+```
+
+## 许可
+
+MIT

metamessage-0.1.0/README.md

@@ -0,0 +1,329 @@
+# MetaMessage
+
+MetaMessage - 高性能二进制消息编码库，支持模式标记（schema tags）、JSONC 注释语法，以及 Python 装饰器驱动的序列化。
+
+## 功能特性
+
+- **二进制编码/解码** — 将 Python 值高效编码为紧凑二进制格式
+- **`@mm` 装饰器** — 类似 Go 结构体标签的 Python 装饰器语法
+- **JSONC 支持** — 解析带 `// mm:` 注释的 JSON 格式
+- **Node 中间表示** — 通过 `value_to_node` / `node_to_value` 操作节点树
+- **类型自动推断** — 根据 Python 类型注解自动推断 MetaMessage 类型
+- **嵌套结构** — 支持字典、列表、类实例的递归转换
+
+## 安装
+
+### pip 安装
+
+```bash
+pip install metamessage
+```
+
+### 版本要求
+
+- Python 3.7 或更高版本
+
+## 快速开始
+
+### 基础编码/解码
+
+```python
+from metamessage import encode_from_value, decode_to_value
+
+# 编码 Python 值 → 二进制
+binary = encode_from_value({"name": "Alice", "age": 30})
+print(f"Encoded: {len(binary)} bytes")
+
+# 解码二进制 → Python 值
+result = decode_to_value(binary)
+print(result)  # {'name': 'Alice', 'age': 30}
+```
+
+### 字符串/数字/布尔值
+
+```python
+from metamessage import encode_from_value, decode_to_value
+
+for val in ["hello", 42, 3.14, True, b"bytes"]:
+    binary = encode_from_value(val)
+    result = decode_to_value(binary)
+    print(f"{val!r} → {result!r}")
+```
+
+## @mm 装饰器
+
+`@mm` 装饰器为 Python 类添加 MetaMessage 模式信息，类似 Go 的结构体标签。
+
+`mm` 支持两种用法：
+- **类级装饰器**：`@mm(desc="...")` 放在 `class` 定义上方
+- **字段级标记**：`field: type = mm(desc="...")` 作为字段默认值（推荐）
+
+### 类级 + 字段级装饰器（推荐）
+
+```python
+from metamessage import mm, ValueType, encode_from_value, decode_to_value
+
+@mm(desc="User information")
+class User:
+    id: int = mm(desc="User ID")
+    name: str = mm(desc="User name")
+    age: int = mm(desc="User age")
+
+    def __init__(self, id: int = 0, name: str = "", age: int = 0):
+        self.id = id
+        self.name = name
+        self.age = age
+
+user = User(id=1, name="Alice", age=30)
+binary = encode_from_value(user)
+# binary -> {'id': 1, 'name': 'Alice', 'age': 30}
+```
+
+### 带类型和约束
+
+```python
+@mm(desc="Product")
+class Product:
+    id: int = mm(desc="Product ID", type=ValueType.Int64, min=1)
+    name: str = mm(desc="Name", min=1, max=100)
+    price: float = mm(desc="Price", min=0.0, max=999999.99)
+
+    def __init__(self, id: int = 0, name: str = "", price: float = 0.0):
+        self.id = id
+        self.name = name
+        self.price = price
+```
+
+### 仅类级装饰器
+
+```python
+@mm(desc="User information")
+class User:
+    id: int
+    name: str
+    age: int
+
+    def __init__(self, id: int = 0, name: str = "", age: int = 0):
+        self.id = id
+        self.name = name
+        self.age = age
+```
+
+### 字符串标签语法
+
+```python
+@mm("desc=Product; type=i64")
+class Product:
+    id: int
+    name: str
+    price: float
+
+    def __init__(self, id: int = 0, name: str = "", price: float = 0.0):
+        self.id = id
+        self.name = name
+        self.price = price
+```
+
+## Node 中间表示
+
+MetaMessage 使用 Node 树作为中间表示（IR）：
+
+| 节点类型 | Python 类 | 描述 |
+|---------|----------|------|
+| `Val` | 值节点 | 存储标量值（字符串、数字、布尔等） |
+| `Obj` | 对象节点 | 键值对集合（对应 dict / 类实例） |
+| `Arr` | 数组节点 | 有序元素列表 |
+
+### value_to_node / node_to_value
+
+```python
+from metamessage import value_to_node, node_to_value
+
+# Python 值 → Node 树
+node = value_to_node({"x": 10, "y": 20})
+
+# Node 树 → Python 值
+result = node_to_value(node, dict)
+print(result)  # {'x': 10, 'y': 20}
+```
+
+### 手动构建 Node
+
+```python
+from metamessage import Tag, ValueType, Obj, Arr, Val, Field, Encoder, Decoder
+
+obj = Obj(
+    fields=[
+        Field(key="name", value=Val(data="John", text="John",
+                                     tag=Tag(type=ValueType.String))),
+        Field(key="age", value=Val(data=30, text="30",
+                                    tag=Tag(type=ValueType.Int))),
+    ],
+    tag=Tag(name="person")
+)
+
+encoder = Encoder()
+binary = encoder.encode(obj)
+decoder = Decoder(binary)
+result = decoder.decode()
+print(result)  # {'name': 'John', 'age': 30}
+```
+
+## JSONC 支持
+
+JSONC 是带 `// mm:` 注释的 JSON 格式，用于声明模式标记：
+
+### 解析 JSONC
+
+```python
+from metamessage import parse_jsonc, to_jsonc
+
+jsonc = """{
+    // mm: type=str; desc=姓名
+    "name": "Alice",
+    // mm: type=i; desc=年龄
+    "age": 30
+}"""
+
+node = parse_jsonc(jsonc)
+for field in node.fields:
+    print(f"{field.key}: type={field.value.tag.type}, desc={field.value.tag.desc}")
+
+# 转回 JSONC 字符串
+output = to_jsonc(node)
+print(output)
+```
+
+### JSONC -> 二进制 -> 解码
+
+```python
+from metamessage import parse_jsonc, encode_from_value, decode_to_value
+
+# 1. 解析 JSONC 获取 Node
+node = parse_jsonc(jsonc_source)
+
+# 2. 直接编码字典
+binary = encode_from_value({"name": "Alice", "age": 30})
+
+# 3. 解码
+result = decode_to_value(binary)
+```
+
+## 完整示例
+
+查看 `examples/python/` 目录下的示例代码：
+
+| 文件 | 说明 |
+|------|------|
+| `basic_encode_decode.py` | 基本编码/解码 |
+| `dict_and_list.py` | 字典和列表操作 |
+| `nested_structures.py` | 嵌套结构 |
+| `mm_decorator.py` | @mm 装饰器使用 |
+| `jsonc_roundtrip.py` | JSONC 完整流程 |
+| `value_to_node_api.py` | Node API 使用 |
+
+运行示例：
+
+```bash
+# 在 mm-py 目录下
+PYTHONPATH=. python3 examples/python/basic_encode_decode.py
+PYTHONPATH=. python3 examples/python/dict_and_list.py
+PYTHONPATH=. python3 examples/python/nested_structures.py
+```
+
+## Tag 参数说明
+
+### 基本参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `type` | `ValueType` | 数据类型 |
+| `desc` | `str` | 描述 |
+| `nullable` | `bool` | 是否可空 |
+| `allow_empty` | `bool` | 是否允许空值 |
+| `default` | `str` | 默认值 |
+| `raw` | `bool` | 是否原始模式 |
+| `example` | `bool` | 是否为示例 |
+| `unique` | `bool` | 是否唯一 |
+
+### 约束参数
+
+| 参数 | 适用类型 | 说明 |
+|------|---------|------|
+| `min` | int/float/bytes/string | 最小值/长度 |
+| `max` | int/float/bytes/string | 最大值/长度 |
+| `size` | array/bytes/string | 固定大小 |
+| `pattern` | string | 正则表达式 |
+| `enum` | enum | 枚举值列表（`"a\|b\|c"`） |
+| `version` | uuid/ip | 版本号 |
+| `mime` | bytes | MIME 类型 |
+| `location` | datetime | 时区偏移（-12 ~ +14） |
+
+### 子元素参数
+
+| 参数 | 说明 |
+|------|------|
+| `child_type` | 子元素类型 |
+| `child_desc` | 子元素描述 |
+| `child_raw` | 子元素原始模式 |
+| `child_nullable` | 子元素可空 |
+| `child_allow_empty` | 子元素允许空值 |
+| `child_unique` | 子元素唯一 |
+| `child_default` | 子元素默认值 |
+| `child_min` | 子元素最小值 |
+| `child_max` | 子元素最大值 |
+| `child_size` | 子元素大小 |
+| `child_enum` | 子元素枚举 |
+| `child_pattern` | 子元素模式 |
+| `child_version` | 子元素版本 |
+| `child_mime` | 子元素 MIME |
+
+## API 参考
+
+### 高层 API
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `encode_from_value` | `(value: Any) -> bytes` | Python 值 → 二进制 |
+| `decode_to_value` | `(data: bytes, target_type=Any) -> Any` | 二进制 → Python 值 |
+| `value_to_node` | `(value: Any, tag=None, depth=0, path="") -> Node` | Python 值 → Node 树 |
+| `node_to_value` | `(node: Node, target_type) -> Any` | Node 树 → Python 值 |
+
+### 核心类
+
+| 类 | 说明 |
+|------|------|
+| `Encoder` | 编码器：`Encoder().encode(node) -> bytes` |
+| `Decoder` | 解码器：`Decoder(data).decode() -> Any` |
+| `Tag` | 模式标记：类型、约束、描述等 |
+| `ValueType` | 类型枚举：`String`, `Int`, `Float64`, `Bool` 等 |
+
+### JSONC API
+
+| 函数 | 签名 | 说明 |
+|------|------|------|
+| `parse_jsonc` | `(source: str) -> Node` | 解析 JSONC 字符串为 Node |
+| `to_jsonc` | `(node: Node) -> str` | 将 Node 转回 JSONC 字符串 |
+
+### 装饰器
+
+| 装饰器 | 说明 |
+|--------|------|
+| `@mm(...)` | 类级标记装饰器 |
+
+## 测试
+
+```bash
+# 运行主测试套件
+python3 metamessage_test.py
+
+# 运行分类测试
+python3 tests/test_encoder.py
+python3 tests/test_decoder.py
+python3 tests/test_jsonc.py
+python3 tests/test_value_to_node.py
+```
+
+## 许可
+
+MIT