pythonparts-mcp 0.2.0__py3-none-any.whl

server/tools/_introspect_worker.py

@@ -0,0 +1,537 @@
+"""
+Self-contained worker script that introspects Python symbols and prints JSON
+results to stdout.
+
+This script is executed by the ALLPLAN-embedded interpreter (not the MCP server's
+interpreter). It must not import anything from the server package.
+
+Native (pybind11) modules such as ``NemAll_Python_IFW_ElementAdapter`` carry no
+usable signatures at runtime, so results are enriched from the matching ``.pyi``
+stub in ``InterfaceStubs`` whenever one is available.
+
+Protocol (persistent mode):
+  1. Caller writes one JSON init line to stdin:
+         {"sys_path": [...], "prg_plugins": "...", "allplan_paths_mock": "...",
+          "etc_pythonparts": "...", "stub_dirs": [...]}
+     Worker sets up the ALLPLAN runtime, then writes one JSON ack to stdout:
+         {"ok": true}  or  {"ok": false, "error": "..."}
+  2. For each symbol query the caller writes one JSON line:
+         {"symbol": "NemAll_Python_Geometry.Point3D"}
+     Worker writes one JSON result to stdout, then loops.
+  3. Caller closes stdin (EOF) to signal shutdown; the worker exits cleanly.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import importlib
+import importlib.util
+import json
+import os
+import re
+import sys
+import warnings
+from typing import Any
+
+_DLL_DIR_HANDLE: Any | None = None
+
+_STUB_DIRS: list[str] = []
+_STUB_CACHE: dict[str, dict | None] = {}
+
+# The generated stubs contain malformed defs such as ``def __init__(: object):``.
+_BROKEN_SELF_ARG = re.compile(r"(def\s+\w+\s*\()\s*:")
+
+# Boost-style cast parameters such as ``(Point2D)index`` inside a def line.
+_BROKEN_CAST_PARAM = re.compile(r"\(\s*([A-Za-z_][\w.]*)\s*\)\s*([A-Za-z_]\w*)")
+
+_DEF_LINE = re.compile(r"^(\s*)(?:async\s+)?def\s+(\w+)")
+
+_MAX_PARSE_REPAIRS = 25
+
+_OVERLOAD_PLACEHOLDER = "Overloaded function"
+
+
+
+
+def _read_line() -> dict | None:
+    """Return the next JSON object from stdin, or None on EOF."""
+    line = sys.stdin.readline()
+    if not line:
+        return None
+    return json.loads(line)
+
+
+def _setup_environment(params: dict) -> None:
+    """Inject DLL search path and sys.path, then patch AllplanPaths if possible."""
+    global _DLL_DIR_HANDLE
+
+    _DLL_DIR_HANDLE = os.add_dll_directory(params["prg_plugins"])
+
+    _STUB_DIRS.extend(params.get("stub_dirs") or [])
+
+
+    for path in reversed(params["sys_path"]):
+        if path not in sys.path:
+            sys.path.insert(0, path)
+
+    # Patch AllplanSettings.AllplanPaths so framework modules that call
+    # GetPathOfApplication() at import-time receive the real Prg path rather
+    # than the interpreter directory (Prg\Python\).
+    try:
+        mock_spec = importlib.util.spec_from_file_location(
+            "AllplanPathsMock", params["allplan_paths_mock"]
+        )
+        if mock_spec is None or mock_spec.loader is None:
+            raise ImportError("Could not load AllplanPathsMock spec")
+        mock_mod = importlib.util.module_from_spec(mock_spec)
+        mock_spec.loader.exec_module(mock_mod)  # type: ignore[union-attr]
+
+        import NemAll_Python_AllplanSettings as _AllplanSettings  # noqa: PLC0415
+        _AllplanSettings.AllplanPaths = mock_mod.AllplanPathsMock(
+            etc_path=params["etc_pythonparts"]
+        )
+    except Exception:  # noqa: BLE001 — AllplanPaths mock is optional; real errors surface below
+        pass
+
+
+def _determine_category(obj: Any) -> str:
+    if inspect.ismodule(obj):
+        return "module"
+    if inspect.isclass(obj):
+        return "class"
+    if inspect.isfunction(obj):
+        return "function"
+    if inspect.isbuiltin(obj):
+        return "builtin_function"
+    if inspect.ismethod(obj):
+        return "method"
+    if isinstance(obj, property):
+        return "property"
+    return "attribute"
+
+
+def _safe_signature(obj: Any) -> str | None:
+    try:
+        return str(inspect.signature(obj))
+    except (ValueError, TypeError):
+        return None
+
+
+# --------------------------------------------------------------------------- #
+# .pyi stub support                                                            #
+# --------------------------------------------------------------------------- #
+
+
+def _find_stub_file(module_name: str) -> str | None:
+    for directory in _STUB_DIRS:
+        candidate = os.path.join(directory, module_name.replace(".", os.sep) + ".pyi")
+        if os.path.isfile(candidate):
+            return candidate
+    return None
+
+
+def _repair_def_line(line: str) -> str:
+    line = _BROKEN_SELF_ARG.sub(r"\1__arg:", line)
+    counter = [0]
+
+    def rename_cast(match: re.Match) -> str:
+        counter[0] += 1
+        return f"{match.group(2)}_{counter[0]}: {match.group(1)}"
+
+    return _BROKEN_CAST_PARAM.sub(rename_cast, line)
+
+
+def _degrade_def_line(lines: list[str], lineno: int | None) -> bool:
+    """Replace the offending def line with ``def name(*args, **kwargs):``."""
+    if not lineno or lineno > len(lines):
+        return False
+    match = _DEF_LINE.match(lines[lineno - 1])
+    if match is None:
+        return False
+    indent, name = match.groups()
+    degraded = f"{indent}def {name}(*args, **kwargs):\n"
+    if lines[lineno - 1] == degraded:
+        return False
+    lines[lineno - 1] = degraded
+    return True
+
+
+def _parse_stub_source(source: str) -> ast.Module | None:
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", SyntaxWarning)
+        try:
+            return ast.parse(source)
+        except SyntaxError:
+            pass
+
+        # Repair known malformed patterns on def lines only, so docstrings
+        # containing similar text stay untouched.
+        lines = [
+            _repair_def_line(line) if _DEF_LINE.match(line) else line
+            for line in source.splitlines(keepends=True)
+        ]
+        for _ in range(_MAX_PARSE_REPAIRS):
+            try:
+                return ast.parse("".join(lines))
+            except SyntaxError as exc:
+                if not _degrade_def_line(lines, exc.lineno):
+                    return None
+        return None
+
+
+def _render_signature(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    try:
+        args = ast.unparse(node.args)
+    except Exception:  # noqa: BLE001 — unparse is best effort
+        args = "..."
+    returns = ""
+    if node.returns is not None:
+        try:
+            returns = f" -> {ast.unparse(node.returns)}"
+        except Exception:  # noqa: BLE001
+            returns = ""
+    return f"({args}){returns}"
+
+
+def _decorator_names(node: ast.FunctionDef | ast.AsyncFunctionDef) -> set[str]:
+    names = set()
+    for dec in node.decorator_list:
+        try:
+            names.add(ast.unparse(dec))
+        except Exception:  # noqa: BLE001
+            pass
+    return names
+
+
+def _stub_function_entry(nodes: list[ast.FunctionDef | ast.AsyncFunctionDef]) -> dict:
+    """Merge the definitions sharing one name into a single entry with overloads."""
+    overloads = [
+        {"signature": _render_signature(n), "docstring": ast.get_docstring(n)}
+        for n in nodes
+    ]
+    # pybind11 stubs append a dispatcher def whose docstring only points to the
+    # overloads; drop it when real overloads are present.
+    if len(overloads) > 1:
+        overloads = [
+            o for o in overloads
+            if not (o["docstring"] or "").strip().startswith(_OVERLOAD_PLACEHOLDER)
+        ] or overloads[:1]
+
+    decorators = set().union(*(_decorator_names(n) for n in nodes))
+    if "property" in decorators:
+        category = "property"
+    elif "staticmethod" in decorators:
+        category = "staticmethod"
+    elif "classmethod" in decorators:
+        category = "classmethod"
+    else:
+        category = "function"
+
+    return {
+        "category": category,
+        "docstring": next((o["docstring"] for o in overloads if o["docstring"]), None),
+        "signature": overloads[0]["signature"],
+        "overloads": overloads if len(overloads) > 1 else [],
+    }
+
+
+def _index_body(body: list[ast.stmt]) -> dict[str, dict]:
+    """Index the functions, classes and annotated attributes of one scope."""
+    functions: dict[str, list] = {}
+    entries: dict[str, dict] = {}
+
+    for node in body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.setdefault(node.name, []).append(node)
+        elif isinstance(node, ast.ClassDef):
+            entries[node.name] = {
+                "category": "class",
+                "docstring": ast.get_docstring(node),
+                "signature": None,
+                "overloads": [],
+                "bases": [_safe_unparse(b) for b in node.bases],
+                "members": _index_body(node.body),
+            }
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            entries[node.target.id] = {
+                "category": "attribute",
+                "docstring": None,
+                "signature": _safe_unparse(node.annotation),
+                "overloads": [],
+            }
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    entries[target.id] = {
+                        "category": "attribute",
+                        "docstring": None,
+                        "signature": None,
+                        "overloads": [],
+                    }
+
+    for name, nodes in functions.items():
+        entries[name] = _stub_function_entry(nodes)
+    return entries
+
+
+def _safe_unparse(node: ast.AST) -> str | None:
+    try:
+        return ast.unparse(node)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _load_stub(module_name: str) -> dict | None:
+    """Return the parsed index of ``<module_name>.pyi``, or None when unavailable."""
+    if module_name in _STUB_CACHE:
+        return _STUB_CACHE[module_name]
+
+    index: dict | None = None
+    path = _find_stub_file(module_name)
+    if path is not None:
+        try:
+            with open(path, "r", encoding="utf-8", errors="replace") as handle:
+                tree = _parse_stub_source(handle.read())
+        except OSError:
+            tree = None
+        if tree is not None:
+            index = {
+                "path": path,
+                "docstring": ast.get_docstring(tree),
+                "members": _index_body(tree.body),
+            }
+
+    _STUB_CACHE[module_name] = index
+    return index
+
+
+def _stub_lookup(module_name: str, attr_chain: list[str]) -> tuple[dict | None, dict | None]:
+    """Return (stub index of the module, entry for the attribute chain)."""
+    index = _load_stub(module_name)
+    if index is None:
+        return None, None
+
+    entry: dict | None = None
+    members: dict[str, dict] = index["members"]
+    for attr in attr_chain:
+        entry = members.get(attr)
+        if entry is None:
+            return index, None
+        members = entry.get("members", {})
+    return index, entry
+
+
+def _format_stub_members(members: dict[str, dict], magic: bool) -> list[str]:
+    """Render member names with their stub signatures, one entry per overload."""
+    rendered: list[str] = []
+    for name in sorted(members):
+        if name.startswith("__") and name.endswith("__") and not magic:
+            continue
+        if magic and not (name.startswith("__") and name.endswith("__")):
+            continue
+        if not magic and name.startswith("_"):
+            continue
+        entry = members[name]
+        if magic and entry["category"] == "attribute":
+            continue
+        if entry["category"] == "attribute":
+            rendered.append(f"{name}: {entry['signature']}" if entry["signature"] else name)
+            continue
+        if entry["category"] == "class":
+            rendered.append(f"{name} (class)")
+            continue
+        signatures = [o["signature"] for o in entry["overloads"]] or [entry["signature"]]
+        for signature in signatures:
+            rendered.append(f"{name}{signature}" if signature else name)
+    return rendered
+
+
+def _split_docstring(docstring: str | None) -> list[str] | None:
+    """Split a docstring into a list of lines for the JSON output."""
+    if docstring is None:
+        return None
+    return docstring.split("\n")
+
+
+def _split_overload_docstrings(overloads: list[dict]) -> list[dict]:
+    """Return copies of overload entries with docstrings split into lines."""
+    return [
+        {"signature": o["signature"], "docstring": _split_docstring(o["docstring"])}
+        for o in overloads
+    ]
+
+
+def _collect_module_member_names(mod: Any) -> list[str]:
+    if hasattr(mod, "__all__"):
+        return list(mod.__all__)
+    return [n for n in dir(mod) if not n.startswith("_")]
+
+
+def _collect_class_member_names(cls: Any) -> list[str]:
+    return [name for name in cls.__dict__ if not name.startswith("_")]
+
+
+def _collect_class_magic_methods(cls: Any) -> list[str]:
+    return sorted(
+        name for name in cls.__dict__
+        if name.startswith("__") and name.endswith("__")
+    )
+
+
+def _introspect(symbol: str) -> dict:
+    parts = symbol.split(".")
+
+    # Progressive import: try longest prefix first, fall back to shorter ones.
+    module = None
+    attr_chain: list[str] = []
+    last_errors: dict[str, str] = {}
+    for i in range(len(parts), 0, -1):
+        mod_name = ".".join(parts[:i])
+        try:
+            module = importlib.import_module(mod_name)
+            attr_chain = parts[i:]
+            break
+        except ImportError as exc:
+            last_errors[mod_name] = str(exc)
+        except Exception as exc:  # noqa: BLE001 — surface import errors as structured JSON
+            last_errors[mod_name] = f"{type(exc).__name__}: {exc}"
+
+    if module is None:
+        return _introspect_from_stub_only(symbol, parts, last_errors)
+
+    # Walk the attribute chain.
+    obj: Any = module
+    resolved_module = ".".join(parts[: len(parts) - len(attr_chain)])
+    for attr in attr_chain:
+        try:
+            obj = getattr(obj, attr)
+        except AttributeError:
+            return {
+                "ok": False,
+                "error": f"'{resolved_module}' has no attribute '{attr}'",
+            }
+
+    category = _determine_category(obj)
+    stub_index, stub_entry = _stub_lookup(resolved_module, attr_chain)
+
+    if category == "module":
+        members = _collect_module_member_names(obj)
+        magic_methods: list[str] = []
+    elif category == "class":
+        members = _collect_class_member_names(obj)
+        magic_methods = _collect_class_magic_methods(obj)
+    else:
+        members = []
+        magic_methods = []
+
+    docstring = inspect.getdoc(obj)
+    signature = _safe_signature(obj) if callable(obj) else None
+    overloads: list[dict] = []
+
+    if stub_entry is not None:
+        category = stub_entry["category"] if category == "attribute" else category
+        # The stub text is cleaner than the pybind/Boost-generated runtime docstring.
+        docstring = stub_entry["docstring"] or docstring
+        signature = stub_entry["signature"] or signature
+        overloads = stub_entry["overloads"]
+        if "members" in stub_entry:
+            members = _format_stub_members(stub_entry["members"], magic=False)
+            magic_methods = _format_stub_members(stub_entry["members"], magic=True)
+    elif stub_index is not None and not attr_chain:
+        docstring = stub_index["docstring"] or docstring
+        members = _format_stub_members(stub_index["members"], magic=False) or members
+
+    return {
+        "ok": True,
+        "data": {
+            "symbol": symbol,
+            "category": category,
+            "module": resolved_module,
+            "docstring": _split_docstring(docstring),
+            "signature": signature,
+            "overloads": _split_overload_docstrings(overloads),
+            "members": members,
+            "magic_methods": magic_methods,
+            "stub_file": (stub_index or {}).get("path"),
+        },
+    }
+
+
+def _introspect_from_stub_only(symbol: str, parts: list[str], import_errors: dict) -> dict:
+    """Resolve a symbol purely from its ``.pyi`` stub when the module cannot be imported."""
+    for i in range(len(parts), 0, -1):
+        module_name = ".".join(parts[:i])
+        index, entry = _stub_lookup(module_name, parts[i:])
+        if index is None:
+            continue
+        if parts[i:] and entry is None:
+            return {
+                "ok": False,
+                "error": f"'{module_name}' stub has no attribute '{'.'.join(parts[i:])}'",
+            }
+        source = entry or {
+            "category": "module",
+            "docstring": index["docstring"],
+            "signature": None,
+            "overloads": [],
+            "members": index["members"],
+        }
+        return {
+            "ok": True,
+            "data": {
+                "symbol": symbol,
+                "category": source["category"],
+                "module": module_name,
+                "docstring": _split_docstring(source["docstring"]),
+                "signature": source["signature"],
+                "overloads": _split_overload_docstrings(source["overloads"]),
+                "members": _format_stub_members(source.get("members", {}), magic=False),
+                "magic_methods": _format_stub_members(source.get("members", {}), magic=True),
+                "stub_file": index["path"],
+            },
+        }
+
+    return {
+        "ok": False,
+        "error": f"Cannot import any module from '{symbol}'",
+        "import_errors": import_errors,
+    }
+
+
+def _emit(obj: dict) -> None:
+    """Write one JSON line to stdout and flush immediately."""
+    sys.stdout.write(json.dumps(obj) + "\n")
+    sys.stdout.flush()
+
+
+def main() -> None:
+    # Stage 1: one-time environment setup.
+    init_params = _read_line()
+    if init_params is None:
+        return
+    try:
+        _setup_environment(init_params)
+        _emit({"ok": True})
+    except Exception as exc:  # noqa: BLE001
+        _emit({"ok": False, "error": str(exc)})
+        return
+
+    # Stage 2: query loop — one symbol per line until stdin closes.
+    while True:
+        query = _read_line()
+        if query is None:
+            break
+        try:
+            _emit(_introspect(query["symbol"]))
+        except Exception as exc:  # noqa: BLE001
+            _emit({"ok": False, "error": str(exc)})
+
+
+try:
+    main()
+except Exception as exc:  # noqa: BLE001 — top-level guard; must not crash the subprocess
+    try:
+        _emit({"ok": False, "error": str(exc)})
+    except Exception:  # noqa: BLE001
+        pass