mhuixs 0.2.3__tar.gz

mhuixs-0.2.3/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: mhuixs
+Version: 0.2.3
+Summary: Mhuixs 内存数据结构服务端的 Python 客户端（MHP/1 协议）
+Author: HuJi
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/hujiyo/Mhuixs
+Project-URL: Repository, https://github.com/hujiyo/Mhuixs
+Project-URL: Issues, https://github.com/hujiyo/Mhuixs/issues
+Keywords: mhuixs,in-memory,database,client,redis-like
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# mhuixs
+
+Mhuixs 内存数据结构服务端的 Python 客户端。协议是 MHP/1 —— 请求带长度前缀的
+参数数组，响应是带长度前缀的 JSON 文档，二进制安全。
+
+包内只有标准库依赖，Python 3.8+。
+
+## 安装
+
+```bash
+pip install mhuixs
+```
+
+从源码安装：
+
+```bash
+pip install ./client/python
+# 或从仓库直接装：
+pip install "git+https://github.com/hujiyo/Mhuixs.git#subdirectory=client/python"
+```
+
+## 快速开始
+
+先起服务端（令牌来自环境变量或 `Mhuixs.config` 的 `authtoken`）：
+
+```bash
+MHUIXS_TOKEN=你的令牌 ./mhuixs server
+```
+
+然后在 Python 里：
+
+```python
+import mhuixs
+
+db = mhuixs.Mhuixs("127.0.0.1", 18185, token="你的令牌")
+
+db.create_list("todo")
+db.rpush("todo", "milk", 2)       # 字符串存字符串，数字存数字
+db.llen("todo")                   # -> 2
+db.lget("todo", 0)                # -> "milk"
+db.lget("todo", 1)                # -> 2
+
+db.create_table("users", ["id:int", "name:str"])
+db.tadd("users", 1, "张三")
+db.tget("users", 0, "name")       # -> "张三"
+
+db.create_kvalot("conf")
+db.kset("conf", "theme", "dark")
+db.kget("conf", "theme")          # -> "dark"
+
+db.create_bitmap("flags")
+db.bset("flags", 3, 1)            # -> True
+db.bcount("flags", 0, 7)          # -> 1
+
+db.save()                         # 让服务端落盘
+db.close()
+```
+
+也可以当上下文管理器：
+
+```python
+with mhuixs.Mhuixs(token="你的令牌") as db:
+    print(db.hooks())
+```
+
+## 方法一览
+
+| 分组 | 方法 | 返回 |
+|---|---|---|
+| 管理 | `create_list` / `create_bitmap` / `create_kvalot` / `create_table` | `None` |
+| 管理 | `drop` | `None` |
+| 管理 | `hooks` | `int` |
+| 管理 | `info` / `type` | `str` |
+| LIST | `rpush` / `lpush` | `int`（新长度） |
+| LIST | `lpop` / `rpop` / `lget` / `lrem` | 值 |
+| LIST | `llen` | `int` |
+| LIST | `lset` | `None` |
+| BITMAP | `bset` / `bget` | `bool` |
+| BITMAP | `bcount` / `bsize` | `int` |
+| KVALOT | `kset` / `kdel` / `klen` | `int` |
+| KVALOT | `kget` | 值 |
+| KVALOT | `kexists` | `bool` |
+| TABLE | `tadd` / `tdel` / `trows` | `int` |
+| TABLE | `tget` | 值或 `None`（空格子） |
+| TABLE | `tset` | `None` |
+| TABLE | `tfields` | `list[str]` |
+| 会话 | `ping` | `bool` |
+| 会话 | `save` / `shutdown` | `str` |
+
+`tfields` 受服务端类型化返回值 32 项上限约束；字段更多时用 `call()` 看
+`truncated`，或读 `info()` 的文本。
+
+## 参数类型规则
+
+类型化方法按 Python 类型决定值怎么存：
+
+| Python 值 | 存进去是什么 |
+|---|---|
+| `str` / `bytes` | 字符串（含换行的值也能原样存） |
+| `int` | 数字 |
+| `float` / `Decimal` | 数字（按十进制定点写入，不使用科学计数法） |
+| `bool` | 数字 `1` / `0` |
+| `None` | 不支持，抛 `ValueError` / `TypeError` |
+
+需要把数字样子的字符串强制存成字符串时，不需要额外包装 —— 类型化方法里的
+`str` 本来就是字符串：
+
+```python
+db.rpush("numbers", "123")        # 字符串 "123"
+db.rpush("numbers", 123)          # 数字 123
+```
+
+裸接口 `call()` / `execute()` 不做这层包装：普通 `str` 交给服务端自动判定
+（`"123"` 会变数字），要强制字符串时用 `mhuixs.Forced`：
+
+```python
+db.execute("rpush", "numbers", mhuixs.Forced("123"))   # 字符串
+```
+
+服务端单个参数上限 255 字节、单条命令 48 个参数；客户端会在发送前检查并给出
+明确错误。参数里不能有 NUL 字节，`Forced` 的值不能含 CR/LF（协议限制）。
+
+## 返回值类型
+
+| 服务端 kind | Python 类型 |
+|---|---|
+| `int` | `int` |
+| `num` 无小数点 | `int` |
+| `num` 有小数点 | `decimal.Decimal` |
+| `str` | `str` |
+| `bool` | `bool` |
+| `null` | `None` |
+| `list` | `list` |
+
+小数用 `Decimal` 是为了不丢精度。`call()` 返回的是原始 JSON 文档，小数按标准
+JSON 解析成 `float`；需要无损数值时用 `execute()` 或类型化方法。
+
+服务端返回的非 UTF-8 字节会以 `surrogateescape` 形式进入 Python 字符串，
+用 `value.encode("utf-8", "surrogateescape")` 可以还原原始字节。
+
+## 原始接口
+
+```python
+db.call("llen", "todo")
+# {'ok': True, 'code': 'ok', 'kind': 'int', 'value': 2, 'text': 'OK 2'}
+
+db.execute("llen", "todo")        # -> 2
+```
+
+- `call()` 永远返回完整 dict；服务端业务失败（`ok: false`）不抛异常。
+- `execute()` 在 `ok: false` 时抛对应异常，否则返回值。
+
+## 异常
+
+所有异常都继承 `mhuixs.MhuixsError`。服务端失败响应按稳定的 `code` 映射：
+
+| code | 异常 |
+|---|---|
+| `bad_usage` | `BadUsageError` |
+| `no_hook` | `NoHookError` |
+| `no_object` | `NoObjectError` |
+| `type_mismatch` | `TypeMismatchError` |
+| `out_of_range` | `OutOfRangeError` |
+| `no_key` | `NoKeyError` |
+| `no_field` | `NoFieldError` |
+| `empty` | `EmptyError` |
+| `name_taken` | `NameTakenError` |
+| `unknown_command` | `UnknownCommandError` |
+| 其他 | `CommandError` |
+
+连接断开或关闭抛 `ConnectionError`；认证失败抛 `AuthenticationError`；
+分帧损坏抛 `ProtocolError`。业务异常带 `.code` / `.text` 属性。
+
+## 命令行客户端
+
+安装后会有一个 `mhuixs-cli` 命令；在源码目录 `client/python` 下也可以用
+`python -m mhuixs`，参数完全一样：
+
+```bash
+mhuixs-cli                          # 交互模式
+mhuixs-cli 'llen todo'              # 执行一条命令
+mhuixs-cli - < script.mhx           # 从 stdin / 管道逐行读
+python -m mhuixs 'rpush todo milk'  # 等价写法
+```
+
+令牌按 `--token` > 环境变量 `MHUIXS_TOKEN` > `Mhuixs.config` 的 `authtoken`
+顺序回落。输出版式用 `--format value|pretty|text|json`（默认 `value`）。
+交互模式里 `:help` 看元命令，`:quit` 退出。
+
+## 线程与连接
+
+一个 `Mhuixs` 实例对应一条连接，内部有锁，多个线程共用一个实例时命令会串行
+执行。想并行请每个线程各建一个实例。服务端当前一次只服务一个连接，所以不做
+连接池和自动重连。
+
+## 测试
+
+```bash
+cd client/python
+python -m unittest discover -s tests -v
+```
+
+测试只用标准库，不依赖真实服务端：协议黄金字节、半包/粘包、认证、错误映射
+都由本地假服务端覆盖。
+
+## 协议与许可
+
+- 线格式规范：[`src/proto.h`](https://github.com/hujiyo/Mhuixs/blob/main/src/proto.h)
+- 项目主页：<https://github.com/hujiyo/Mhuixs>
+- 许可证：Apache License 2.0

mhuixs-0.2.3/README.md

@@ -0,0 +1,210 @@
+# mhuixs
+
+Mhuixs 内存数据结构服务端的 Python 客户端。协议是 MHP/1 —— 请求带长度前缀的
+参数数组，响应是带长度前缀的 JSON 文档，二进制安全。
+
+包内只有标准库依赖，Python 3.8+。
+
+## 安装
+
+```bash
+pip install mhuixs
+```
+
+从源码安装：
+
+```bash
+pip install ./client/python
+# 或从仓库直接装：
+pip install "git+https://github.com/hujiyo/Mhuixs.git#subdirectory=client/python"
+```
+
+## 快速开始
+
+先起服务端（令牌来自环境变量或 `Mhuixs.config` 的 `authtoken`）：
+
+```bash
+MHUIXS_TOKEN=你的令牌 ./mhuixs server
+```
+
+然后在 Python 里：
+
+```python
+import mhuixs
+
+db = mhuixs.Mhuixs("127.0.0.1", 18185, token="你的令牌")
+
+db.create_list("todo")
+db.rpush("todo", "milk", 2)       # 字符串存字符串，数字存数字
+db.llen("todo")                   # -> 2
+db.lget("todo", 0)                # -> "milk"
+db.lget("todo", 1)                # -> 2
+
+db.create_table("users", ["id:int", "name:str"])
+db.tadd("users", 1, "张三")
+db.tget("users", 0, "name")       # -> "张三"
+
+db.create_kvalot("conf")
+db.kset("conf", "theme", "dark")
+db.kget("conf", "theme")          # -> "dark"
+
+db.create_bitmap("flags")
+db.bset("flags", 3, 1)            # -> True
+db.bcount("flags", 0, 7)          # -> 1
+
+db.save()                         # 让服务端落盘
+db.close()
+```
+
+也可以当上下文管理器：
+
+```python
+with mhuixs.Mhuixs(token="你的令牌") as db:
+    print(db.hooks())
+```
+
+## 方法一览
+
+| 分组 | 方法 | 返回 |
+|---|---|---|
+| 管理 | `create_list` / `create_bitmap` / `create_kvalot` / `create_table` | `None` |
+| 管理 | `drop` | `None` |
+| 管理 | `hooks` | `int` |
+| 管理 | `info` / `type` | `str` |
+| LIST | `rpush` / `lpush` | `int`（新长度） |
+| LIST | `lpop` / `rpop` / `lget` / `lrem` | 值 |
+| LIST | `llen` | `int` |
+| LIST | `lset` | `None` |
+| BITMAP | `bset` / `bget` | `bool` |
+| BITMAP | `bcount` / `bsize` | `int` |
+| KVALOT | `kset` / `kdel` / `klen` | `int` |
+| KVALOT | `kget` | 值 |
+| KVALOT | `kexists` | `bool` |
+| TABLE | `tadd` / `tdel` / `trows` | `int` |
+| TABLE | `tget` | 值或 `None`（空格子） |
+| TABLE | `tset` | `None` |
+| TABLE | `tfields` | `list[str]` |
+| 会话 | `ping` | `bool` |
+| 会话 | `save` / `shutdown` | `str` |
+
+`tfields` 受服务端类型化返回值 32 项上限约束；字段更多时用 `call()` 看
+`truncated`，或读 `info()` 的文本。
+
+## 参数类型规则
+
+类型化方法按 Python 类型决定值怎么存：
+
+| Python 值 | 存进去是什么 |
+|---|---|
+| `str` / `bytes` | 字符串（含换行的值也能原样存） |
+| `int` | 数字 |
+| `float` / `Decimal` | 数字（按十进制定点写入，不使用科学计数法） |
+| `bool` | 数字 `1` / `0` |
+| `None` | 不支持，抛 `ValueError` / `TypeError` |
+
+需要把数字样子的字符串强制存成字符串时，不需要额外包装 —— 类型化方法里的
+`str` 本来就是字符串：
+
+```python
+db.rpush("numbers", "123")        # 字符串 "123"
+db.rpush("numbers", 123)          # 数字 123
+```
+
+裸接口 `call()` / `execute()` 不做这层包装：普通 `str` 交给服务端自动判定
+（`"123"` 会变数字），要强制字符串时用 `mhuixs.Forced`：
+
+```python
+db.execute("rpush", "numbers", mhuixs.Forced("123"))   # 字符串
+```
+
+服务端单个参数上限 255 字节、单条命令 48 个参数；客户端会在发送前检查并给出
+明确错误。参数里不能有 NUL 字节，`Forced` 的值不能含 CR/LF（协议限制）。
+
+## 返回值类型
+
+| 服务端 kind | Python 类型 |
+|---|---|
+| `int` | `int` |
+| `num` 无小数点 | `int` |
+| `num` 有小数点 | `decimal.Decimal` |
+| `str` | `str` |
+| `bool` | `bool` |
+| `null` | `None` |
+| `list` | `list` |
+
+小数用 `Decimal` 是为了不丢精度。`call()` 返回的是原始 JSON 文档，小数按标准
+JSON 解析成 `float`；需要无损数值时用 `execute()` 或类型化方法。
+
+服务端返回的非 UTF-8 字节会以 `surrogateescape` 形式进入 Python 字符串，
+用 `value.encode("utf-8", "surrogateescape")` 可以还原原始字节。
+
+## 原始接口
+
+```python
+db.call("llen", "todo")
+# {'ok': True, 'code': 'ok', 'kind': 'int', 'value': 2, 'text': 'OK 2'}
+
+db.execute("llen", "todo")        # -> 2
+```
+
+- `call()` 永远返回完整 dict；服务端业务失败（`ok: false`）不抛异常。
+- `execute()` 在 `ok: false` 时抛对应异常，否则返回值。
+
+## 异常
+
+所有异常都继承 `mhuixs.MhuixsError`。服务端失败响应按稳定的 `code` 映射：
+
+| code | 异常 |
+|---|---|
+| `bad_usage` | `BadUsageError` |
+| `no_hook` | `NoHookError` |
+| `no_object` | `NoObjectError` |
+| `type_mismatch` | `TypeMismatchError` |
+| `out_of_range` | `OutOfRangeError` |
+| `no_key` | `NoKeyError` |
+| `no_field` | `NoFieldError` |
+| `empty` | `EmptyError` |
+| `name_taken` | `NameTakenError` |
+| `unknown_command` | `UnknownCommandError` |
+| 其他 | `CommandError` |
+
+连接断开或关闭抛 `ConnectionError`；认证失败抛 `AuthenticationError`；
+分帧损坏抛 `ProtocolError`。业务异常带 `.code` / `.text` 属性。
+
+## 命令行客户端
+
+安装后会有一个 `mhuixs-cli` 命令；在源码目录 `client/python` 下也可以用
+`python -m mhuixs`，参数完全一样：
+
+```bash
+mhuixs-cli                          # 交互模式
+mhuixs-cli 'llen todo'              # 执行一条命令
+mhuixs-cli - < script.mhx           # 从 stdin / 管道逐行读
+python -m mhuixs 'rpush todo milk'  # 等价写法
+```
+
+令牌按 `--token` > 环境变量 `MHUIXS_TOKEN` > `Mhuixs.config` 的 `authtoken`
+顺序回落。输出版式用 `--format value|pretty|text|json`（默认 `value`）。
+交互模式里 `:help` 看元命令，`:quit` 退出。
+
+## 线程与连接
+
+一个 `Mhuixs` 实例对应一条连接，内部有锁，多个线程共用一个实例时命令会串行
+执行。想并行请每个线程各建一个实例。服务端当前一次只服务一个连接，所以不做
+连接池和自动重连。
+
+## 测试
+
+```bash
+cd client/python
+python -m unittest discover -s tests -v
+```
+
+测试只用标准库，不依赖真实服务端：协议黄金字节、半包/粘包、认证、错误映射
+都由本地假服务端覆盖。
+
+## 协议与许可
+
+- 线格式规范：[`src/proto.h`](https://github.com/hujiyo/Mhuixs/blob/main/src/proto.h)
+- 项目主页：<https://github.com/hujiyo/Mhuixs>
+- 许可证：Apache License 2.0

mhuixs-0.2.3/mhuixs/__init__.py

@@ -0,0 +1,57 @@
+"""Mhuixs 的 Python 客户端。
+
+    import mhuixs
+
+    db = mhuixs.Mhuixs("127.0.0.1", 18185, token="你的令牌")
+    db.create_list("todo")
+    db.rpush("todo", "milk", 2)     # 字符串存字符串，数字存数字
+    print(db.llen("todo"))          # -> 2
+    print(db.lget("todo", 0))       # -> "milk"
+    db.close()
+
+需要服务端原始 JSON 文档时用 ``db.call(...)``；要解包后的 Python 值用
+``db.execute(...)`` 或按数据结构分组的方法。协议参考实现见
+``mhuixs._protocol``。
+"""
+
+from ._version import __version__
+from ._client import Mhuixs
+from ._errors import (
+    AuthenticationError,
+    BadUsageError,
+    CommandError,
+    ConnectionError,
+    EmptyError,
+    MhuixsError,
+    NameTakenError,
+    NoFieldError,
+    NoHookError,
+    NoKeyError,
+    NoObjectError,
+    OutOfRangeError,
+    ProtocolError,
+    TypeMismatchError,
+    UnknownCommandError,
+)
+from ._protocol import Forced
+
+__all__ = [
+    "Mhuixs",
+    "Forced",
+    "MhuixsError",
+    "ConnectionError",
+    "ProtocolError",
+    "AuthenticationError",
+    "CommandError",
+    "BadUsageError",
+    "NoHookError",
+    "NoObjectError",
+    "TypeMismatchError",
+    "OutOfRangeError",
+    "NoKeyError",
+    "NoFieldError",
+    "EmptyError",
+    "NameTakenError",
+    "UnknownCommandError",
+    "__version__",
+]

mhuixs-0.2.3/mhuixs/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m mhuixs`` 等价于 ``mhuixs-cli``。"""
+
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()