dimine-python-sdk 0.2.3__py3-none-any.whl → 0.2.5__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.5"  # 由 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/dmd_file.md

@@ -1,196 +1,198 @@
-# DMD 钻孔数据库文件
-
-`dimine_python_sdk.lib.io` 提供 `DmdFile` 类用于读写 Dimine 钻孔数据库文件（`.dmd`）。DMD 是钻孔数据库的主引用文件，内部引用孔口表、测斜表、岩性表、样品表及扩展表的 `.dmt` 子表文件。API 将各表映射为 `pandas.DataFrame`，支持加载、修改、保存全流程操作。
-
----
-
-## 一、加载与保存
-
-### 从文件加载
-
-```python
-from dimine_python_sdk.lib.io import DmdFile
-
-dmd = DmdFile("钻孔数据.dmd")
-print(dmd.collar.head())
-print(dmd.info)
-```
-
-### 保存到文件
-
-```python
-dmd.collar = modified_collar_df
-dmd.save()                        # 覆盖原文件
-dmd.save("output.dmd")            # 另存为新文件
-```
-
-### 创建空文件并保存
-
-```python
-dmd = DmdFile()                   # 空构造，可直接设表
-dmd.collar = collar_df
-dmd.survey = survey_df
-dmd.lithology = lithology_df
-dmd.sample = sample_df
-dmd.save("新钻孔数据.dmd")
-```
-
-### 上下文管理器
-
-```python
-from dimine_python_sdk.lib.io import dmd_conn
-
-with dmd_conn("钻孔数据.dmd") as dmd:
-    print(dmd.info)
-    dmd.sample["CU"] = dmd.sample["CU"] * 1.1
-    dmd.save()
-```
-
----
-
-## 二、核心表访问
-
-DMD 文件包含四张核心表，均以 `pd.DataFrame` 形式读写：
-
-### 孔口表（collar）
-
-```python
-dmd.collar.head()
-#    工程号    横坐标    纵坐标    高程    勘探线  工程类型
-# 0  ZK001  1000.0  2000.0  500.0     L1   坑内钻
-
-dmd.collar = new_collar_df   # 替换整个表（自动校验列名）
-```
-
-### 测斜表（survey）
-
-```python
-dmd.survey.head()
-#    工程号  测斜深度  方位角  倾角
-# 0  ZK001    0.0   45.0  90.0
-
-dmd.survey = new_survey_df
-```
-
-### 岩性表（lithology）
-
-```python
-dmd.lithology.head()
-#    工程号  起始  结束  岩性编号
-# 0  ZK001  0.0  10.0   花岗岩
-
-dmd.lithology = new_lithology_df
-```
-
-### 样品表（sample）
-
-```python
-dmd.sample.head()
-#    工程号  样本编号  起始  结束  样长   CU
-# 0  ZK001   S001    0.0  2.0   2.0  0.85
-
-dmd.sample = new_sample_df
-```
-
-> **列名规范**：各表有必需的标准中文列名（孔口表需含 `工程号、横坐标、纵坐标、高程`，测斜表需含 `工程号、测斜深度、方位角、倾角` 等）。设置表数据时自动校验，缺列会抛出 `DmdError`。详细列名映射见 [钻孔数据库操作指南](../prospecting/drill_db.md#13-standard-column-mapping)。
-
-### 统一表访问
-
-```python
-dmd["collar"]      # 等价于 dmd.collar
-dmd["survey"]      # 等价于 dmd.survey
-dmd["lithology"]   # 等价于 dmd.lithology
-dmd["sample"]      # 等价于 dmd.sample
-
-"collar" in dmd    # True
-len(dmd)           # 表总数（含扩展表）
-```
-
----
-
-## 三、扩展表
-
-DMD 支持附加自定义扩展表（如分层表），以 `NativeExtendTable` 形式管理：
-
-```python
-# 查看扩展表
-for ext in dmd.extend_tables:
-    print(ext.table_name, ext.dmt_filename)
-    print(ext.df.head())
-
-# 通过表名访问扩展表数据
-ext_df = dmd["分层表"]
-```
-
-扩展表通过 `dmt_filename` 参数指定文件名（如 `分层表.dmt`），在 DMD 保存时一并写入伴随的 `.dmt` 文件。
-
----
-
-## 四、文件信息
-
-```python
-dmd.name           # "钻孔数据" — 文件名（不含扩展名）
-dmd.file_path      # "钻孔数据.dmd"
-dmd.table_names    # ["collar", "survey", "lithology", "sample", "分层表"]
-dmd.ref_dict       # .dmd 引用字典（只读）
-
-dmd.info
-# {
-#   "file": "钻孔数据.dmd",
-#   "name": "钻孔数据",
-#   "loaded": True,
-#   "tables": {
-#     "collar": {"columns": [...], "rows": 150},
-#     "survey": {"columns": [...], "rows": 300},
-#     "lithology": {"columns": [...], "rows": 80},
-#     "sample": {"columns": [...], "rows": 450},
-#   },
-#   "extend_table_count": 1,
-#   "extend_table_names": ["分层表"],
-#   "extend_tables": [...],
-# }
-```
-
----
-
-## 五、保存为 DMG
-
-可将钻孔数据库直接打包为三维可视化格式 DMG：
-
-```python
-dmd.save_as_dmg("output.dmg")
-```
-
-> 更多 DMG 操作见 [DMG 钻孔可视化指南](dmg_file.md)。
-
----
-
-## 六、异常处理
-
-```python
-from dimine_python_sdk.lib.io import DmdError, DmdLoadError, DmdSaveError
-
-try:
-    dmd = DmdFile("not_exist.dmd")
-except DmdLoadError as e:
-    print(f"加载失败: {e}")
-
-try:
-    dmd = DmdFile()
-    dmd.save()  # 未指定路径
-except DmdSaveError as e:
-    print(f"保存失败: {e}")
-```
-
-异常层次：
-- `DmdError(RuntimeError)` — 基类
-- `DmdLoadError(DmdError)` — 加载失败
-- `DmdSaveError(DmdError)` — 保存失败
-
----
-
-## 参考链接
-
-- [钻孔数据库操作指南](../prospecting/drill_db.md) — 完整的钻孔数据库使用场景（CSV 导入、列名映射、组合样、特高品位处理）
-- [DMG 钻孔可视化](dmg_file.md) — 将 DMD 转为三维可视化格式
-- [API 参考：dmd_file](../../../reference/lib/io/dmd_file.md)
+# DMD 钻孔数据库文件
+
+`dimine_python_sdk.lib.io` 提供 `DmdFile` 类用于读写 Dimine 钻孔数据库文件（`.dmd`）。DMD 是钻孔数据库的主引用文件，内部引用孔口表、测斜表、岩性表、样品表及扩展表的 `.dmt` 子表文件。API 将各表映射为 `pandas.DataFrame`，支持加载、修改、保存全流程操作。
+
+---
+
+## 一、加载与保存
+
+### 从文件加载
+
+```python
+from dimine_python_sdk.lib.io import DmdFile
+
+dmd = DmdFile("钻孔数据.dmd")
+print(dmd.collar.head())
+print(dmd.info)
+```
+
+### 保存到文件
+
+```python
+dmd.collar = modified_collar_df
+dmd.save()                        # 覆盖原文件
+dmd.save("output.dmd")            # 另存为新文件
+```
+
+### 创建空文件并保存
+
+```python
+dmd = DmdFile()                   # 空构造，可直接设表
+dmd.collar = collar_df
+dmd.survey = survey_df
+dmd.lithology = lithology_df
+dmd.sample = sample_df
+dmd.save("新钻孔数据.dmd")
+```
+
+### 上下文管理器
+
+```python
+from dimine_python_sdk.lib.io import dmd_conn
+
+with dmd_conn("钻孔数据.dmd") as dmd:
+    print(dmd.info)
+    dmd.sample["CU"] = dmd.sample["CU"] * 1.1
+    dmd.save()
+```
+
+---
+
+## 二、核心表访问
+
+DMD 文件包含四张核心表，均以 `pd.DataFrame` 形式读写：
+
+### 孔口表（collar）
+
+```python
+dmd.collar.head()
+#    工程号    横坐标    纵坐标    高程    勘探线  工程类型
+# 0  ZK001  1000.0  2000.0  500.0     L1   坑内钻
+
+dmd.collar = new_collar_df   # 替换整个表（自动校验列名）
+```
+
+### 测斜表（survey）
+
+```python
+dmd.survey.head()
+#    工程号  测斜深度  方位角  倾角
+# 0  ZK001    0.0   45.0  90.0
+
+dmd.survey = new_survey_df
+```
+
+### 岩性表（lithology）
+
+```python
+dmd.lithology.head()
+#    工程号  起始  结束  岩性编号
+# 0  ZK001  0.0  10.0   花岗岩
+
+dmd.lithology = new_lithology_df
+```
+
+### 样品表（sample）
+
+```python
+dmd.sample.head()
+#    工程号  样本编号  起始  结束  样长   CU
+# 0  ZK001   S001    0.0  2.0   2.0  0.85
+
+dmd.sample = new_sample_df
+```
+
+> **列名规范**：各表有必需的标准中文列名（孔口表需含 `工程号、横坐标、纵坐标、高程`，测斜表需含 `工程号、测斜深度、方位角、倾角` 等）。设置表数据时自动校验，缺列会抛出 `DmdError`。详细列名映射见 [钻孔数据库操作指南](../prospecting/drill_db.md#13-standard-column-mapping)。
+
+### 统一表访问
+
+```python
+dmd["collar"]      # 等价于 dmd.collar
+dmd["survey"]      # 等价于 dmd.survey
+dmd["lithology"]   # 等价于 dmd.lithology
+dmd["sample"]      # 等价于 dmd.sample
+
+"collar" in dmd    # True
+len(dmd)           # 表总数（含扩展表）
+```
+
+---
+
+## 三、扩展表
+
+DMD 支持附加自定义扩展表（如分层表），以 `NativeExtendTable` 形式管理：
+
+```python
+# 查看扩展表
+for ext in dmd.extend_tables:
+    print(ext.table_name, ext.dmt_filename)
+    print(ext.df.head())
+
+# 通过表名访问扩展表数据
+ext_df = dmd["分层表"]
+```
+
+扩展表通过 `dmt_filename` 参数指定文件名（如 `分层表.dmt`），在 DMD 保存时一并写入伴随的 `.dmt` 文件。
+
+---
+
+## 四、文件信息
+
+```python
+dmd.name           # "钻孔数据" — 文件名（不含扩展名）
+dmd.file_path      # "钻孔数据.dmd"
+dmd.table_names    # ["collar", "survey", "lithology", "sample", "分层表"]
+dmd.ref_dict       # .dmd 引用字典（只读）
+
+dmd.info
+# {
+#   "file": "钻孔数据.dmd",
+#   "name": "钻孔数据",
+#   "loaded": True,
+#   "tables": {
+#     "collar": {"columns": [...], "rows": 150},
+#     "survey": {"columns": [...], "rows": 300},
+#     "lithology": {"columns": [...], "rows": 80},
+#     "sample": {"columns": [...], "rows": 450},
+#   },
+#   "extend_table_count": 1,
+#   "extend_table_names": ["分层表"],
+#   "extend_tables": [...],
+# }
+```
+
+---
+
+## 五、保存为 DMG（可选）
+
+> **注意**：`.dmd` 文件可以直接在 Dimine 中打开并展示三维钻孔，无需转换。DMG 是另一种可视化格式，适用于需要特殊展示效果的场景。
+
+可将钻孔数据库打包为 DMG 格式：
+
+```python
+dmd.save_as_dmg("output.dmg")
+```
+
+> 更多 DMG 操作见 [DMG 钻孔可视化指南](dmg_file.md)。
+
+---
+
+## 六、异常处理
+
+```python
+from dimine_python_sdk.lib.io import DmdError, DmdLoadError, DmdSaveError
+
+try:
+    dmd = DmdFile("not_exist.dmd")
+except DmdLoadError as e:
+    print(f"加载失败: {e}")
+
+try:
+    dmd = DmdFile()
+    dmd.save()  # 未指定路径
+except DmdSaveError as e:
+    print(f"保存失败: {e}")
+```
+
+异常层次：
+- `DmdError(RuntimeError)` — 基类
+- `DmdLoadError(DmdError)` — 加载失败
+- `DmdSaveError(DmdError)` — 保存失败
+
+---
+
+## 参考链接
+
+- [钻孔数据库操作指南](../prospecting/drill_db.md) — 完整的钻孔数据库使用场景（CSV 导入、列名映射、组合样、特高品位处理）
+- [DMG 钻孔可视化](dmg_file.md) — 将 DMD 转为三维可视化格式
+- [API 参考：dmd_file](../../../reference/lib/io/dmd_file.md)