dimine-python-sdk 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

dimine_python_sdk/__init__.py

@@ -4,7 +4,7 @@ from pathlib import Path
 from typing import Any
 
 DOCS_PATH = Path(__file__).parent / "docs"
-__VERSION__ = "0.2.3"  # 由 build.bat 中的 generate_version.py 自动更新
+__VERSION__ = "0.2.4"  # 由 build.bat 中的 generate_version.py 自动更新
 
 
 _LAZY_IMPORTS: dict[str, Any] = {}

dimine_python_sdk/cli/commands/file.py

@@ -1,12 +1,8 @@
 """文件相关 CLI 命令。"""
 
-import os
-
 from dimine_python_sdk.cli.utils._utils import (
-    close_client,
     get_client,
     handle_sdk_error,
-    open_client,
     output_error,
     output_result,
     raise_or_exit,
@@ -54,21 +50,20 @@ def cmd_file_save(fmt: str, output_path: str, file_id: str | None) -> None:
 
     async def _run():
         nonlocal file_id
+        client = await get_client()
         if not file_id:
-            async with open_client() as client:
-                files = await client.get_files()
-                if not files:
-                    raise_or_exit("没有打开的文件。请先在 Dimine 中打开文件，或提供 --file-id 参数。", fmt)
-                if len(files) == 1:
-                    file_id = files[0].id
-                else:
-                    file_list = "\n".join([f"  - id: {f.id}, name: {f.name}" for f in files])
-                    raise_or_exit(
-                        f"当前打开了 {len(files)} 个文件，请指定 --file-id：\n{file_list}",
-                        fmt,
-                    )
-        async with open_client() as client:
-            await client.export_file(file_id=file_id, file_path=save_path)
+            files = await client.get_files()
+            if not files:
+                raise_or_exit("没有打开的文件。请先在 Dimine 中打开文件，或提供 --file-id 参数。", fmt)
+            if len(files) == 1:
+                file_id = files[0].id
+            else:
+                file_list = "\n".join([f"  - id: {f.id}, name: {f.name}" for f in files])
+                raise_or_exit(
+                    f"当前打开了 {len(files)} 个文件，请指定 --file-id：\n{file_list}",
+                    fmt,
+                )
+        await client.export_file(file_id=file_id, file_path=save_path)
         return {
             "success": True,
             "file_id": file_id,
@@ -77,7 +72,7 @@ def cmd_file_save(fmt: str, output_path: str, file_id: str | None) -> None:
         }
 
     try:
-        result = asyncio.run(_run())
+        result = run_cli_async(_run())
         output_result(result, fmt)
     except SystemExit:
         raise

dimine_python_sdk/cli/commands/geometry.py

@@ -308,9 +308,9 @@ def _build_partial_geometry_objects(geometries: list) -> list:
     return result
 
 
-def cmd_geometry_get(fmt: str, file_id: str, layer_id: str | None,
-                     entity_types: str | None = None, features: str | None = None,
-                     with_geometry: bool = False) -> None:
+def cmd_geometry_list(fmt: str, file_id: str, layer_id: str | None,
+                      entity_types: str | None = None, features: str | None = None,
+                      with_geometry: bool = False) -> None:
     """获取图层中的几何体对象（需 Dimine 运行）。
 
     默认只返回几何体的基础信息（id、file、layer、feature、type、color、properties）。
@@ -610,7 +610,7 @@ def register_commands(subparsers, format_parent) -> None:
 
 
 COMMAND_HANDLERS = {
-    "geometry-list": lambda args: cmd_geometry_get(args.format, args.file_id, args.layer_id,
+    "geometry-list": lambda args: cmd_geometry_list(args.format, args.file_id, args.layer_id,
                                                    args.entity_types, args.features,
                                                    args.with_geometry),
     "geometry-create": lambda args: cmd_geometry_create(args.format, args.geometries,

dimine_python_sdk/cli/utils/_utils.py

@@ -26,17 +26,17 @@ if TYPE_CHECKING:
 _SDK_AVAILABLE: bool | None = None  # None = 尚未检查
 _local_sdk_available: bool | None = None  # None = 尚未检查
 _import_error: str = ""
-open_client = None  # type: ignore[assignment]
+_open_client: Any = None  # 惰性缓存的 open_client 函数（私有，勿直接 import）
 
 
 def _check_remote_sdk() -> bool:
     """惰性检查远程 SDK 是否可用。首次调用时导入 conn 模块链并缓存结果。"""
-    global _SDK_AVAILABLE, _import_error, open_client
+    global _SDK_AVAILABLE, _import_error, _open_client
     if _SDK_AVAILABLE is not None:
         return _SDK_AVAILABLE
     try:
-        from dimine_python_sdk.conn.conn_client import open_client as _open_client  # type: ignore[no-redef]
-        open_client = _open_client
+        from dimine_python_sdk.conn.conn_client import open_client as _conn_open_client
+        _open_client = _conn_open_client
         _SDK_AVAILABLE = True
     except ImportError as e:
         _import_error = str(e)
@@ -157,7 +157,7 @@ async def get_client()->ConnClient:
         _client_loop_id = None
 
     if _client_instance is None:
-        _client_ctx = open_client()
+        _client_ctx = _open_client()
         _client_instance = await _client_ctx.__aenter__()
         _client_loop_id = id(asyncio.get_running_loop())
     return _client_instance

dimine_python_sdk/conn/base_conn_client.py

@@ -19,6 +19,7 @@ class BaseConnClient:
     model_config = {"arbitrary_types_allowed": True}
 
     url: Optional[str] = "ws://127.0.0.1:8000"
+    max_size: Optional[int] = None
     is_connected: Optional[bool] = False
     pending_requests: Dict[str, Tuple[asyncio.Future, Callable]] = field(default_factory=dict)
     event_handlers: Dict[str, List[Callable]] = field(default_factory=dict)
@@ -106,7 +107,10 @@ class BaseConnClient:
 
     async def connect(self)-> bool:
         try:
-            self.websocket = await websockets.connect(self.url, close_timeout=1)
+            connect_kwargs: Dict[str, Any] = {"close_timeout": 1}
+            if self.max_size is not None:
+                connect_kwargs["max_size"] = self.max_size
+            self.websocket = await websockets.connect(self.url, **connect_kwargs)
             self.is_connected = True
             logger.info("success connected to %s", self.url)
             if self.receive_task is None or self.receive_task.done():

dimine_python_sdk/conn/conn_client.py

@@ -744,8 +744,8 @@ class ConnClient(BaseConnClient):
 
 
 @asynccontextmanager
-async def open_client(url:Optional[str]=None)->AsyncGenerator[ConnClient,None]:
-    client = ConnClient(url=url or "ws://127.0.0.1:8000")
+async def open_client(url:Optional[str]=None, max_size:Optional[int]=None)->AsyncGenerator[ConnClient,None]:
+    client = ConnClient(url=url or "ws://127.0.0.1:8000", max_size=max_size)
     await client.connect()
     yield client
     await client.close()

dimine_python_sdk/docs/guides/lib/io/SUMMARY.md

@@ -6,5 +6,6 @@
 * [DMG 钻孔可视化](dmg_file.md)
 * [DMT 数据表文件](dmt_file.md)
 * [DMB 块段模型](dmb_file.md)
+* [DMO 炮孔数据库](dmo_file.md)
 
 > 完整的钻孔数据库使用流程（CSV 导入、列名映射、组合样等）见 **[地质勘探 / 钻孔数据库](../prospecting/drill_db.md)**。

dimine_python_sdk/docs/guides/lib/io/dmo_file.md

@@ -0,0 +1,159 @@
+# DMO 炮孔数据库文件
+
+`dimine_python_sdk.lib.io` 提供 `DmoFile` 类用于读写 Dimine 炮孔数据库文件（`.dmo`）。DMO 本质上是带固定表头（炮孔数据库标准字段，新版 26 列）的 DMT 数据表文件，API 将其映射为 `pandas.DataFrame`，加载时对表头做**宽松校验**（缺列/多列/类型不符只记录告警、不抛异常），保存时按固定表头还原字段类型，避免 pandas dtype 推断丢失 `long`/`binary` 等类型。
+
+---
+
+## 一、加载与保存
+
+### 从文件加载
+
+```python
+from dimine_python_sdk.lib.io import DmoFile
+
+dmo = DmoFile("炮孔数据库-data.dmo")
+print(dmo.columns)          # 26 列标准字段
+print(dmo.record_count)     # 炮孔数量
+print(dmo.data.head())
+print(dmo.header_warnings)  # 表头非标准告警（如有）
+```
+
+### 保存到文件
+
+```python
+dmo.data.loc[0, "孔径"] = 250.0
+dmo.save("output.dmo")   # 另存为新文件（无扩展名时自动追加 .dmo）
+dmo.save()               # 覆盖原文件
+```
+
+### 从 DataFrame 创建并保存
+
+```python
+import pandas as pd
+from dimine_python_sdk.lib.io import DmoFile
+
+df = pd.DataFrame({
+    "爆破区域": ["M01", "M01"],
+    "炮孔编号": ["BH-01", "BH-02"],
+    "孔径": [220.0, 220.0],
+    "孔深": [12.0, 13.5],
+})
+DmoFile(data=df).save("new.dmo")
+```
+
+### 上下文管理器
+
+```python
+from dimine_python_sdk.lib.io import dmo_conn
+
+with dmo_conn("炮孔数据库.dmo") as dmo:
+    print(dmo.info)
+    dmo.data["孔径"] = dmo.data["孔径"] * 1.1
+    dmo.save()
+```
+
+---
+
+## 二、固定表头 schema
+
+DMO 文件拥有固定的 26 列标准字段，定义于模块常量 `DMO_FIELD_SCHEMA`：
+
+```python
+from dimine_python_sdk.lib.io import DMO_FIELD_NAMES, DMO_FIELD_TYPES
+
+print(DMO_FIELD_NAMES)   # 字段名列表（26 项）
+print(DMO_FIELD_TYPES)   # {'爆破区域': 'string', '炮孔Handle': 'long', ...}
+
+dmo.schema               # [{"name": "爆破区域", "type": "string"}, ...]
+```
+
+字段类型支持 `string` / `long` / `int` / `double` / `binary`。标准字段覆盖：
+
+- 标识：`爆破区域`、`炮孔编号`、`虚拟炮孔`、`起爆点炮孔`、`炮孔Handle`
+- 起爆参数：`起爆延时`、`所属爆堆`、`地表起爆时间`、`孔内起爆时间`、`孔内分段起爆`
+- 孔口/孔底坐标：`孔口坐标X/Y/Z`、`孔底坐标X/Y/Z`
+- 孔参数：`孔径`、`孔深`、`方位角`、`倾角`
+- 装药参数：`装药半径相对孔径的收缩比例`、`装药重量`、`装药长度`、`单耗面积`、`装药结构`、`连线信息`
+
+---
+
+## 三、表头宽松校验
+
+加载时 `DmoFile` 会对表头做宽松校验，非标准列或缺列**不会**抛异常，而是记录到 `header_warnings`：
+
+```python
+dmo = DmoFile("旧版炮孔数据.dmo")
+
+for w in dmo.header_warnings:
+    print(w)
+# 缺少标准列: ['孔内分段起爆', '连线信息']
+# 含非标准列: ['孔内延时']
+# 字段 '炮孔Handle' 类型不符: 期望 long, 实际 double
+```
+
+校验规则：
+- **缺标准列**：记录告警，缺失列在 DataFrame 中不存在
+- **含非标准列**：记录告警，非标准列在保存时按 pandas dtype 回退推断类型
+- **类型不符**：记录告警，保存时仍按 schema 中的标准类型还原
+
+`dmo.info` 在继承 `DmtFile` 摘要信息的基础上，额外附带 `header_warnings`。
+
+---
+
+## 四、数据访问
+
+`DmoFile` 继承 `DmtFile`，拥有完整的数据表操作接口：
+
+```python
+dmo.name          # "炮孔数据库" — 文件名（不含扩展名）
+dmo.columns       # 字段名列表
+dmo.shape         # (行数, 列数)
+dmo.record_count  # 炮孔行数
+dmo.empty         # 是否为空
+
+# DataFrame 访问
+df = dmo.data            # 内部 DataFrame 引用（修改会影响 dmo）
+df = dmo.to_dataframe()  # 独立副本
+
+# 行操作
+row = dmo.get_record(0)       # 单行字典
+dmo.set_value(0, "孔径", 250.0)  # 设置单元格
+dmo.add_record({"炮孔编号": "BH-03"})  # 追加一行，返回新索引
+
+# 列访问
+dmo["孔径"]        # 整列列表
+"孔径" in dmo      # True
+```
+
+更完整的数据访问说明见 [DMT 数据表文件](dmt_file.md)。
+
+---
+
+## 五、异常处理
+
+```python
+from dimine_python_sdk.lib.io import DmoError, DmoLoadError, DmoSaveError
+
+try:
+    dmo = DmoFile("not_exist.dmo")
+except DmoLoadError as e:
+    print(f"加载失败: {e}")
+
+try:
+    dmo = DmoFile()
+    dmo.save()   # 未指定路径
+except DmoSaveError as e:
+    print(f"保存失败: {e}")
+```
+
+异常层次：
+- `DmoError(RuntimeError)` — 基类
+- `DmoLoadError(DmoError)` — 加载失败
+- `DmoSaveError(DmoError)` — 保存失败
+
+---
+
+## 参考链接
+
+- [DMT 数据表文件](dmt_file.md) — 基础数据表访问接口
+- [API 参考：dmo_file](../../../reference/lib/io/dmo_file.md)

dimine_python_sdk/docs/reference/SUMMARY.md

@@ -23,6 +23,7 @@
 * [dmd_file](lib/io/dmd_file.md)
 * [dmg_file](lib/io/dmg_file.md)
 * [dmt_file](lib/io/dmt_file.md)
+* [dmo_file](lib/io/dmo_file.md)
 * [file_converter](lib/io/file_converter.md)
 * [models](lib/io/models.md)
 * [algorithm](lib/native/algorithm.md)

dimine_python_sdk/docs/reference/lib/io/dmo_file.md

@@ -0,0 +1,3 @@
+# dmo_file
+
+::: dimine_python_sdk.lib.io.dmo_file

dimine_python_sdk/lib/io/__init__.py

@@ -25,6 +25,16 @@ from dimine_python_sdk.lib.io.dmg_file import (
     DmgValidationError,
     dmg_conn,
 )
+from dimine_python_sdk.lib.io.dmo_file import (
+    DMO_FIELD_NAMES,
+    DMO_FIELD_SCHEMA,
+    DMO_FIELD_TYPES,
+    DmoError,
+    DmoFile,
+    DmoLoadError,
+    DmoSaveError,
+    dmo_conn,
+)
 from dimine_python_sdk.lib.io.dmt_file import (
     DmtError,
     DmtFile,
@@ -91,4 +101,13 @@ __all__ = [
     "DmtError",
     "DmtLoadError",
     "DmtSaveError",
+    # DMO 文件操作
+    "DmoFile",
+    "dmo_conn",
+    "DmoError",
+    "DmoLoadError",
+    "DmoSaveError",
+    "DMO_FIELD_SCHEMA",
+    "DMO_FIELD_NAMES",
+    "DMO_FIELD_TYPES",
 ]