swforge 0.9.1__py3-none-any.whl

swforge/__init__.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+"""swforge —— SolidWorks 自动化工具箱。
+
+把两类能力合到一起：
+
+* **几何**：声明式 DSL → 生成 C# 早期绑定 → 编译执行（批量建模快 3~10 倍）
+* **出图**：委托 AssetMate_MechDog 做标注与自检，本地负责排版与成册
+
+快速开始
+--------
+>>> from swforge import PartBuilder, FaceRule, apply_rules
+>>> b = PartBuilder(r"D:\\out\\SWFORGE_支架.SLDPRT")
+>>> b.box("底板", 0, 200, 0, 10, 0, 200, "steel")
+>>> b.tube_y("立柱", 0, 1000, 0, 0, 150, 150, wall=6.3, color="yellow")
+>>> r = b.build()
+>>> r.ok, r.bodies
+"""
+
+from .session import SWSession, get_session, SWError, BridgeLost
+from .modeling import PartBuilder, BuildResult, Material, COLORS, preview_edges
+from .resources import (document_inventory, resource_status, sweep_documents,
+                        ensure_capacity)
+from .spec import builder_from_spec
+from .gb_materials import GB_MATERIALS, ensure_library, material_names
+from .assembly import AssemblyBuilder, list_components, check_interference
+from .interference import body_interference, check_all_pairs
+from .mates import MateBuilder, list_mates
+from .dims import add_overall_dimensions
+from .batch import batch_drawings, collect_models, write_report
+from .probe import probe_api
+from .colors import FaceRule, apply_rules, read_back
+from .cleanup import survey, delete_bodies, purge_giant, purge_small
+from .drawing import (have_mechdog, produce, export_pdf, normalize_layout,
+                      make_atlas, delivery_check, add_dimensions, count_dimensions)
+
+__version__ = "0.9.1"
+
+__all__ = [
+    "__version__",
+    # session
+    "SWSession", "get_session", "SWError", "BridgeLost",
+    # modeling
+    "PartBuilder", "BuildResult", "Material", "COLORS", "builder_from_spec", "preview_edges",
+    "document_inventory", "resource_status", "sweep_documents", "ensure_capacity",
+    "GB_MATERIALS", "material_names", "ensure_library",
+    # assembly
+    "AssemblyBuilder", "list_components", "check_interference", "body_interference", "check_all_pairs",
+    # mates / dims
+    "MateBuilder", "list_mates", "add_overall_dimensions",
+    # batch
+    "batch_drawings", "collect_models", "write_report", "probe_api",
+    # colors
+    "FaceRule", "apply_rules", "read_back",
+    # cleanup
+    "survey", "delete_bodies", "purge_giant", "purge_small",
+    # drawing
+    "have_mechdog", "produce", "export_pdf", "normalize_layout",
+    "make_atlas", "delivery_check", "add_dimensions", "count_dimensions",
+]
+

swforge/assembly.py

@@ -0,0 +1,322 @@
+# -*- coding: utf-8 -*-
+"""装配体：插入零件、固定基件、跑干涉检查。
+
+关键实测结论（本机 SW2025 SP5.0）
+--------------------------------
+1. **零件必须先打开**再 `AddComponent5`，否则返回 None（不报错，静默失败）。
+   这是本环境最反直觉的一条：直接传文件路径给一个未打开的零件，一律失败。
+2. `GetComponents(False)` 能拿到组件清单；组件的 `Name2` 形如 `a_base-1`。
+3. 干涉检查走 `IAssemblyDoc.GetInterferenceDetectionManager`，
+   读完必须调用 `Done()` 释放。
+
+配合（Mate）
+-----------
+`CreateMate` / `AddMate5` 需要先选中两个实体的面，本版**没有实现自动选面**，
+只提供 `list_components()` 与 `check_interference()` 这类不依赖选择的检查。
+配合请先在 SW 界面里建立，再用本模块做干涉验证。
+"""
+
+from __future__ import annotations
+
+import os
+
+from .session import get_session, _value, SWError
+
+__all__ = ["AssemblyBuilder", "list_components", "check_interference"]
+
+
+def _abs(path: str) -> str:
+    if not path or not os.path.isfile(path):
+        raise ValueError(f"零件文件不存在：{path}")
+    return os.path.abspath(path)
+
+
+def _default_asm_template() -> str:
+    cands = []
+    env = os.environ.get("SW_TEMPLATE_DIR")
+    if env:
+        cands.append(os.path.join(env, "Assembly.asmdot"))
+    base = os.environ.get("PROGRAMDATA") or r"C:\ProgramData"
+    for year in range(2026, 2019, -1):
+        for vendor in ("SOLIDWORKS", "SolidWorks"):
+            cands.append(os.path.join(base, vendor, f"SOLIDWORKS {year}",
+                                      "templates", "gb_assembly.asmdot"))
+            cands.append(os.path.join(base, vendor, f"SOLIDWORKS {year}",
+                                      "templates", "Assembly.asmdot"))
+    for p in cands:
+        if os.path.isfile(p):
+            return p
+    raise RuntimeError("找不到装配模板，请设置 SW_TEMPLATE_DIR")
+
+
+def _activate(sw, md):
+    """把指定文档设为活动文档。"""
+    from win32com.client import VARIANT
+    import pythoncom
+
+    title = str(_value(md, "GetTitle"))
+    err = VARIANT(pythoncom.VT_BYREF | pythoncom.VT_I4, 0)
+    sw.ActivateDoc3(title, False, 0, err)
+    return sw.ActiveDoc
+
+
+def _open_part(sw, path: str):
+    """打开零件并返回文档对象；已打开则直接复用。"""
+    target = os.path.normcase(os.path.abspath(path))
+    for d in (_value(sw, "GetDocuments") or []):
+        try:
+            cur = str(_value(d, "GetPathName"))
+        except Exception:                                # noqa: BLE001
+            continue
+        if cur and os.path.normcase(os.path.abspath(cur)) == target:
+            return d
+    from win32com.client import VARIANT
+    import pythoncom
+
+    err = VARIANT(pythoncom.VT_BYREF | pythoncom.VT_I4, 0)
+    warn = VARIANT(pythoncom.VT_BYREF | pythoncom.VT_I4, 0)
+    doc = sw.OpenDoc6(path, 1, 1, "", err, warn)         # 1 = swDocPART
+    if doc is None:
+        raise SWError(f"打开零件失败：{path}")
+    return doc
+
+
+def _fix_component(ad, comp) -> str:
+    """把组件固定。逐级尝试不同选择 API，返回实际生效的那条。"""
+    errors = []
+    try:
+        ad.ClearSelection2(True)
+    except Exception:                                    # noqa: BLE001
+        pass
+    for label, sel in (
+        ("Select4(True,None,False)", lambda: comp.Select4(True, None, False)),
+        ("Select4(True,None)",       lambda: comp.Select4(True, None)),
+        ("Select(True)",             lambda: comp.Select(True)),
+        ("Select2(True,0)",          lambda: comp.Select2(True, 0)),
+    ):
+        try:
+            sel()
+            ok = ad.FixComponent()
+            return f"{label} -> FixComponent={ok}"
+        except Exception as exc:                         # noqa: BLE001
+            errors.append(f"{label}: {type(exc).__name__}")
+    return "失败（" + "; ".join(errors) + "）"
+
+
+class AssemblyBuilder:
+    """按顺序插入零件并记录，最后一次性建出装配体。
+
+    用法::
+
+        a = AssemblyBuilder(r"D:\\out\\总装.SLDASM")
+        a.add(r"D:\\out\\底座.SLDPRT", x=0,  y=0, z=0, fixed=True)
+        a.add(r"D:\\out\\立柱.SLDPRT", x=0,  y=0, z=0)
+        r = a.build()
+        print(r["ok"], r["components"])
+        print(check_interference())
+    """
+
+    def __init__(self, path: str, template: str | None = None,
+                 keep_open: bool = True):
+        if not str(path).lower().endswith(".sldasm"):
+            raise ValueError("装配体输出必须使用 .SLDASM 扩展名")
+        self.path = os.path.abspath(path)
+        self.template = template
+        self.keep_open = keep_open
+        self._items = []                                  # (path, x, y, z, fixed)
+
+    def add(self, part_path: str, x: float = 0.0, y: float = 0.0, z: float = 0.0,
+            fixed: bool = False) -> "AssemblyBuilder":
+        """插入零件。**坐标单位是毫米**（与全项目一致）。
+
+        SolidWorks 的 `AddComponent5` 内部要米，这里统一换算；
+        v0.7 及以前直接把毫米当米传，导致零件被放到 60 米外。
+        """
+        self._items.append((_abs(part_path), float(x), float(y), float(z), bool(fixed)))
+        return self
+
+    # ------------------------------------------------------------------ 构建
+    def build(self, max_documents: int = 8) -> dict:
+        from .resources import ensure_capacity
+
+        if not self._items:
+            return {"ok": False, "error": "没有要插入的零件"}
+        cap = ensure_capacity(need=1, limit=max_documents)
+        if not cap["allowed"]:
+            return {"ok": False, "error": cap["error"], "resource": cap}
+
+        sw = get_session().sw()
+        log = []
+        asm = None
+
+        def L(msg):
+            log.append(str(msg))
+            print(msg)
+
+        try:
+            tpl = self.template or _default_asm_template()
+            L(f"模板: {tpl}")
+            asm = sw.NewDocument(tpl, 0, 0, 0)
+            if asm is None:
+                return {"ok": False, "error": "新建装配文档失败", "log": "\n".join(log)}
+
+            ad = asm                                        # 后期绑定同一个 dispatch
+            inserted = []
+            for path, x, y, z, fixed in self._items:
+                # ① 零件必须先打开，否则 AddComponent5 静默返回 None
+                _open_part(sw, path)
+                asm = _activate(sw, asm)
+                comp = None
+                try:
+                    comp = ad.AddComponent5(path, 0, "", False, "",
+                                            x / 1000.0, y / 1000.0, z / 1000.0)
+                except Exception as exc:                     # noqa: BLE001
+                    L(f"AddComponent5 异常 {os.path.basename(path)}: {exc}")
+                if comp is None:
+                    try:
+                        comp = ad.AddComponent4(path, "", x / 1000.0, y / 1000.0, z / 1000.0)
+                    except Exception:                        # noqa: BLE001
+                        pass
+                if comp is None:
+                    L(f"插入失败: {os.path.basename(path)}")
+                    continue
+                name = str(_value(comp, "Name2"))
+                L(f"插入 {name} @ ({x},{y},{z})")
+                if fixed:
+                    L(f"固定 {name} -> {_fix_component(ad, comp)}")
+                inserted.append({"part": path, "component": name,
+                                 "position": [x, y, z], "fixed": fixed})
+
+            comps = self._components(ad)
+            L(f"组件数 = {len(comps)}")
+            ok = len(inserted) == len(self._items) and len(comps) >= len(self._items)
+            saved = False
+            if ok:
+                from win32com.client import VARIANT
+                import pythoncom
+                err = VARIANT(pythoncom.VT_BYREF | pythoncom.VT_I4, 0)
+                warn = VARIANT(pythoncom.VT_BYREF | pythoncom.VT_I4, 0)
+                # ExportData 是 IDispatch 指针；直接传 None 会变成 VT_EMPTY 导致类型不匹配
+                export_data = VARIANT(pythoncom.VT_DISPATCH, None)
+                try:
+                    saved = bool(asm.Extension.SaveAs(self.path, 0, 1, export_data,
+                                                      err, warn))
+                    L(f"保存 {saved} err={err.value}")
+                except Exception as exc:                     # noqa: BLE001
+                    L(f"保存异常: {exc}")
+            return {
+                "ok": bool(ok and saved),
+                "path": self.path,
+                "components": comps,
+                "inserted": inserted,
+                "saved": saved,
+                "log": "\n".join(log),
+            }
+        finally:
+            if asm is not None and not self.keep_open:
+                try:
+                    sw.CloseDoc(str(_value(asm, "GetTitle")))
+                except Exception:                            # noqa: BLE001
+                    pass
+
+    @staticmethod
+    def _components(ad) -> list[dict]:
+        try:
+            raw = ad.GetComponents(False)
+        except Exception:                                    # noqa: BLE001
+            return []
+        out = []
+        for c in (raw or []):
+            try:
+                out.append({
+                    "name": str(_value(c, "Name2")),
+                    "path": str(_value(c, "GetPathName")),
+                    "suppressed": bool(_value(c, "IsSuppressed")),
+                })
+            except Exception:                                # noqa: BLE001
+                out.append({"name": str(c), "path": "", "suppressed": False})
+        return out
+
+
+# ---------------------------------------------------------------------- 只读接口
+def list_components(assembly_path: str | None = None) -> dict:
+    """列出当前（或指定）装配体的组件。"""
+    sw = get_session().sw()
+    md = sw.ActiveDoc
+    if assembly_path:
+        md = sw.OpenDoc(assembly_path, 2)                # 2 = swDocASSEMBLY
+        sw.ActivateDoc(assembly_path)
+        md = sw.ActiveDoc
+    if md is None or _value(md, "GetType") != 2:
+        raise RuntimeError("当前文档不是装配体")
+    comps = AssemblyBuilder._components(md)
+    return {"ok": True, "path": str(_value(md, "GetPathName")),
+            "count": len(comps), "components": comps}
+
+
+def check_interference(assembly_path: str | None = None,
+                       treat_coincident_as_interference: bool = False) -> dict:
+    """跑干涉检查并返回干涉清单。
+
+    读完后调用 `Done()` 释放管理器。
+    """
+    sw = get_session().sw()
+    md = sw.ActiveDoc
+    if assembly_path:
+        md = sw.OpenDoc(assembly_path, 2)
+        sw.ActivateDoc(assembly_path)
+        md = sw.ActiveDoc
+    if md is None or _value(md, "GetType") != 2:
+        return {"ok": False, "error": "当前文档不是装配体"}
+
+    # 后期绑定下这是**属性**（InterferenceDetectionManager），
+    # 方法名 GetInterferenceDetectionManager 取不到。
+    mgr = None
+    last = ""
+    for name in ("InterferenceDetectionManager", "GetInterferenceDetectionManager"):
+        try:
+            got = _value(md, name)
+            got = got() if callable(got) and not hasattr(got, "GetInterferenceCount") else got
+            if got is not None:
+                mgr = got
+                break
+        except Exception as exc:                         # noqa: BLE001
+            last = f"{name}: {type(exc).__name__}"
+    if mgr is None:
+        return {"ok": False, "error": f"取干涉管理器失败（{last}）"}
+    if mgr is None:
+        return {"ok": False, "error": "干涉管理器为空"}
+
+    try:
+        try:
+            mgr.TreatCoincidenceAsInterference = bool(treat_coincident_as_interference)
+        except Exception:                                # noqa: BLE001
+            pass
+        count = 0
+        items = []
+        try:
+            count = int(_value(mgr, "GetInterferenceCount") or 0)
+        except Exception:                                # noqa: BLE001
+            count = 0
+        if count:
+            try:
+                raw = mgr.GetInterferences()
+            except Exception:                            # noqa: BLE001
+                raw = None
+            for x in (raw or []):
+                try:
+                    items.append({
+                        "volume_mm3": round(float(_value(x, "Volume")) * 1e9, 3),
+                        "components": [str(_value(c, "Name2")) for c in
+                                       (x.Components if hasattr(x, "Components") else [])],
+                    })
+                except Exception:                        # noqa: BLE001
+                    items.append({"raw": str(x)})
+        try:
+            mgr.Done()
+        except Exception:                                # noqa: BLE001
+            pass
+        return {"ok": True, "interference_count": count, "interferences": items,
+                "note": "count=0 表示无干涉；重合面是否算干涉由参数控制"}
+    except Exception as exc:                             # noqa: BLE001
+        return {"ok": False, "error": f"{type(exc).__name__}: {exc}"}

swforge/batch.py

@@ -0,0 +1,263 @@
+# -*- coding: utf-8 -*-
+"""批量出图：一个文件夹的零件 → 一批带 GB 图框的工程图。
+
+为什么这个功能重要
+------------------
+单件出图只是"省一点手"，**批量出图才是质变**：
+
+    以前：50 个零件，每件 20~40 分钟出图 → 两三天
+    现在：50 个零件，一批跑完 → 十几分钟（还要人工补公差）
+
+而且它天然适合演示 —— 屏幕上不是"出了一张图"，是"刷出来一列图"。
+
+设计要点
+--------
+1. **走已有的 produce() 链路**，不重造轮子，所以图框、标注、排版、PDF 全都自动带上
+2. **逐件隔离失败**：一个零件崩了不能拖垮整批，失败原因单独记
+3. **资源守卫**：SolidWorks 默认 8 个文档上限，所以每件出完就关
+4. **可中断可续跑**：已经存在的图默认跳过（`--skip-existing`），断了能接着跑
+5. **进度可见**：每件打一行，长任务最怕没反馈
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import time
+from dataclasses import dataclass, field, asdict
+
+__all__ = ["batch_drawings", "collect_models"]
+
+
+# ---------------------------------------------------------------- 模型收集
+def collect_models(folder: str, pattern: str = "*.SLDPRT",
+                   recursive: bool = False) -> list[str]:
+    """收集待出图的模型路径。
+
+    pattern 不区分大小写（Windows 上 .SLDPRT / .sldprt 都存在）。
+    """
+    folder = os.path.abspath(folder)
+    if not os.path.isdir(folder):
+        raise ValueError(f"不是文件夹：{folder}")
+
+    pat = pattern.lower()
+    out: list[str] = []
+
+    if recursive:
+        for dirpath, dirnames, filenames in os.walk(folder):
+            dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+            for fn in filenames:
+                if fnmatch.fnmatch(fn.lower(), pat):
+                    out.append(os.path.join(dirpath, fn))
+    else:
+        for fn in os.listdir(folder):
+            full = os.path.join(folder, fn)
+            if os.path.isfile(full) and fnmatch.fnmatch(fn.lower(), pat):
+                out.append(full)
+
+    return sorted(out)
+
+
+def _release(*paths: str) -> None:
+    """关掉指向这些路径的已打开文档，释放 SolidWorks 文档名额。"""
+    try:
+        from .drawing import _close_open_document
+    except Exception:
+        return
+    for p in paths:
+        if not p:
+            continue
+        try:
+            _close_open_document(p)
+        except Exception:
+            continue
+
+
+# ---------------------------------------------------------------- 结果结构
+@dataclass
+class ItemResult:
+    model: str
+    drawing: str = ""
+    ok: bool = False
+    skipped: bool = False
+    dims: int = 0
+    overall_done: int = 0
+    pdf: str = ""
+    pdf_ok: bool = False
+    seconds: float = 0.0
+    error: str = ""
+
+    def to_dict(self):
+        return asdict(self)
+
+
+@dataclass
+class BatchResult:
+    ok: bool = True
+    folder: str = ""
+    total: int = 0
+    succeeded: int = 0
+    failed: int = 0
+    skipped: int = 0
+    pdf_ok: int = 0
+    seconds: float = 0.0
+    items: list = field(default_factory=list)
+    error: str = ""
+
+    def to_dict(self):
+        d = asdict(self)
+        return d
+
+    def summary_line(self) -> str:
+        return (f"{self.succeeded}/{self.total} 成功"
+                f"，失败 {self.failed}，跳过 {self.skipped}"
+                f"，PDF {self.pdf_ok}，耗时 {self.seconds:.1f} 秒")
+
+
+# ---------------------------------------------------------------- 主流程
+def batch_drawings(folder: str,
+                   out_dir: str | None = None,
+                   pattern: str = "*.SLDPRT",
+                   recursive: bool = False,
+                   paper: str = "A3",
+                   overall: bool = True,
+                   pdf: bool = False,
+                   skip_existing: bool = True,
+                   limit: int = 0,
+                   max_documents: int = 8,
+                   progress=None) -> dict:
+    """批量出图。
+
+    参数
+    ----
+    folder          模型所在文件夹
+    out_dir         输出文件夹（默认与模型同目录）
+    pattern         文件名通配，默认 `*.SLDPRT`
+    recursive       是否递归子目录
+    paper           纸张 A0~A4
+    overall         是否补总尺寸
+    pdf             是否同时导 PDF
+    skip_existing   目标图已存在时跳过（支持断点续跑）
+    limit           最多处理几个（0 = 不限，调试用）
+    max_documents   单批允许占用的 SW 文档数
+    progress        回调 fn(idx, total, item: ItemResult)，用于实时打印
+
+    返回 `BatchResult.to_dict()`。
+
+    注意
+    ----
+    这个函数**不吞异常**：单件失败会记进 items 并在 summary 里体现，
+    但不会中断整批 —— 批量任务里"一个坏件毁掉全部"是不可接受的。
+    """
+    from .drawing import produce, add_dimensions
+    from .resources import sweep_documents
+
+    started = time.monotonic()
+    folder = os.path.abspath(folder)
+    out_dir = os.path.abspath(out_dir) if out_dir else folder
+
+    models = collect_models(folder, pattern=pattern, recursive=recursive)
+    if limit and limit > 0:
+        models = models[:limit]
+
+    result = BatchResult(folder=folder, total=len(models))
+    if not models:
+        result.ok = False
+        result.error = f"在 {folder} 里没找到匹配 {pattern} 的文件"
+        result.seconds = round(time.monotonic() - started, 2)
+        return result.to_dict()
+
+    os.makedirs(out_dir, exist_ok=True)
+
+    for idx, model in enumerate(models, 1):
+        item = ItemResult(model=model)
+        t0 = time.monotonic()
+
+        stem = os.path.splitext(os.path.basename(model))[0]
+        dwg = os.path.join(out_dir, stem + ".SLDDRW")
+        pdf_path = os.path.join(out_dir, stem + ".pdf")
+        item.drawing = dwg
+
+        # ---- 已存在就跳过
+        if skip_existing and os.path.isfile(dwg):
+            item.skipped = True
+            item.ok = True
+            item.seconds = 0.0
+            result.skipped += 1
+            result.items.append(item.to_dict())
+            if progress:
+                progress(idx, result.total, item)
+            continue
+
+        try:
+            # 每件开始前清一次场：SolidWorks 默认 8 文档上限，
+            # 批量场景下不清就会在第 8 件之后全部「静默失败」
+            try:
+                sweep_documents(dry_run=False)
+            except Exception:
+                pass
+
+            r = produce(model, dwg, paper=paper,
+                        keep_open=True, max_documents=max_documents)
+            if not r.get("ok"):
+                item.error = str(r.get("error") or f"produce err={r.get('err')}")
+                item.seconds = round(time.monotonic() - t0, 2)
+                result.failed += 1
+                result.items.append(item.to_dict())
+                if progress:
+                    progress(idx, result.total, item)
+                continue
+
+            # 标注（含总尺寸）
+            try:
+                d = add_dimensions(dwg, overall=overall)
+                item.dims = int(d.get("after") or 0)
+                ov = d.get("overall") or {}
+                item.overall_done = int(ov.get("done") or 0)
+            except Exception as exc:                      # noqa: BLE001
+                item.error = f"标注失败：{type(exc).__name__}: {exc}"
+
+            # 可选 PDF
+            if pdf:
+                try:
+                    from .drawing import export_pdf
+                    pr = export_pdf(dwg, pdf_path)
+                    item.pdf = pdf_path
+                    item.pdf_ok = bool(pr.get("ok"))
+                    if item.pdf_ok:
+                        result.pdf_ok += 1
+                except Exception as exc:                  # noqa: BLE001
+                    item.error = (item.error + "；" if item.error else "") + \
+                                 f"PDF 失败：{type(exc).__name__}: {exc}"
+
+            item.ok = not item.error
+            if item.ok:
+                result.succeeded += 1
+            else:
+                result.failed += 1
+
+        except Exception as exc:                          # noqa: BLE001
+            item.error = f"{type(exc).__name__}: {exc}"
+            result.failed += 1
+        finally:
+            # 每件结束必须释放文档。SolidWorks 默认只允许 8 个文档同时打开，
+            # 批处理不清场会在第 8 件之后整批静默失败 —— 实测第 5 件就撞上了
+            # （模型 + 工程图各占一个，加上前一件残留）。
+            _release(model, dwg)
+            item.seconds = round(time.monotonic() - t0, 2)
+            result.items.append(item.to_dict())
+            if progress:
+                progress(idx, result.total, item)
+
+    result.seconds = round(time.monotonic() - started, 2)
+    result.ok = result.failed == 0 and result.succeeded > 0
+    return result.to_dict()
+
+
+def write_report(result: dict, path: str) -> str:
+    """把批量结果写成 JSON 报告，便于事后查哪件失败了。"""
+    os.makedirs(os.path.dirname(os.path.abspath(path)) or ".", exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(result, fh, ensure_ascii=False, indent=2)
+    return path