python-hwpx 3.2.0__py3-none-any.whl → 3.3.0__py3-none-any.whl

hwpx/visual/oracle.py

@@ -39,6 +39,7 @@ import shutil
 import subprocess
 import sys
 import tempfile
+import time
 from importlib import resources
 from pathlib import Path
 
@@ -64,6 +65,71 @@ _MAC_APP_CANDIDATES = (
     "/Applications/Hancom Office HWP 2024.app",
     "/Applications/Hancom Office HWP 2022.app",
 )
+_STRUCTURAL_ONLY_ENV = "HWPX_ORACLE_STRUCTURAL_ONLY"
+_TRUTHY_ENV_VALUES = frozenset({"1", "true", "yes", "on"})
+# The reachability probe must answer well under the customer E2E budget; a
+# TCC-blocked osascript otherwise hangs until the full render timeout.
+_MAC_PROBE_TIMEOUT = 5.0
+_MAC_PROBE_SCRIPT = 'tell application "System Events" to count processes'
+# Process-lifetime probe verdict per osascript binary: the TCC grant cannot
+# change for an already-running process, so one probe per process is honest.
+_MAC_PROBE_CACHE: dict[str, bool] = {}
+
+
+_BUDGET_ENV = "HWPX_ORACLE_BUDGET_SECONDS"
+
+
+def structural_only() -> bool:
+    """True when ``HWPX_ORACLE_STRUCTURAL_ONLY`` requests no-oracle operation.
+
+    In this mode every verification degrades to the labelled structural path:
+    ``resolve_oracle`` returns :class:`NullOracle` and the Mac GUI backend
+    reports ``available() == False`` even when Hancom is installed.
+    """
+
+    return os.environ.get(_STRUCTURAL_ONLY_ENV, "").strip().lower() in _TRUTHY_ENV_VALUES
+
+
+def env_budget_seconds() -> float | None:
+    """The externally-declared oracle budget, or ``None`` when unset/invalid.
+
+    ``HWPX_ORACLE_BUDGET_SECONDS`` is the single deadline a hosting process
+    (customer E2E, installed verify) declares once; ``resolve_oracle`` threads
+    it into every backend subprocess timeout. Non-numeric values are ignored;
+    zero or negative means the budget is already exhausted.
+    """
+
+    raw = os.environ.get(_BUDGET_ENV, "").strip()
+    if not raw:
+        return None
+    try:
+        value = float(raw)
+    except ValueError:
+        return None
+    return max(0.0, value)
+
+
+def _deadline_from(budget_seconds: float | None) -> float | None:
+    """Turn an optional budget into an absolute monotonic deadline."""
+
+    if budget_seconds is None:
+        return None
+    return time.monotonic() + max(0.0, budget_seconds)
+
+
+def _clamped_timeout(base: float, deadline: float | None) -> float | None:
+    """Clamp ``base`` to the remaining deadline budget.
+
+    ``None`` means the budget is already exhausted: the caller must degrade
+    without spawning the subprocess at all.
+    """
+
+    if deadline is None:
+        return base
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        return None
+    return min(base, remaining)
 
 
 class RenderBackend:
@@ -108,10 +174,14 @@ class WindowsComOracle(RenderBackend):
         powershell: str | None = None,
         timeout: float = 300.0,
         dpi: int = 150,
+        budget_seconds: float | None = None,
     ) -> None:
         self._powershell = powershell or "powershell"
         self.timeout = timeout
         self.dpi = dpi
+        # Single externally-propagated deadline: every subprocess timeout in
+        # one public call is clamped so the whole call fits this budget.
+        self.budget_seconds = budget_seconds
 
     def available(self) -> bool:
         """True only on Windows with the ``HWPFrame.HwpObject`` COM class registered."""
@@ -142,6 +212,10 @@ class WindowsComOracle(RenderBackend):
         result: dict[str, str | None] = {src: None for src, _ in pairs}
         if not pairs or not self.available():
             return result
+        deadline = _deadline_from(self.budget_seconds)
+        run_timeout = _clamped_timeout(self.timeout + 60.0 * len(pairs), deadline)
+        if run_timeout is None:
+            return result
 
         tmp = tempfile.mkdtemp(prefix="hwpx-render-")
         try:
@@ -159,7 +233,7 @@ class WindowsComOracle(RenderBackend):
                 ]
                 try:
                     subprocess.run(
-                        cmd, capture_output=True, timeout=self.timeout + 60.0 * len(pairs),
+                        cmd, capture_output=True, timeout=run_timeout,
                         check=False,
                     )
                 except (subprocess.TimeoutExpired, OSError):
@@ -230,6 +304,10 @@ class WindowsComOracle(RenderBackend):
             return []
         if not self.available():
             return [self._unverified_entry(p) for p in paths]
+        deadline = _deadline_from(self.budget_seconds)
+        run_timeout = _clamped_timeout(self.timeout + 60.0 * len(paths), deadline)
+        if run_timeout is None:
+            return [self._unverified_entry(p) for p in paths]
 
         abs_paths = [os.path.abspath(p) for p in paths]
         # path -> requested (original) string, for surfacing the caller's path.
@@ -251,7 +329,7 @@ class WindowsComOracle(RenderBackend):
                 try:
                     subprocess.run(
                         cmd, capture_output=True,
-                        timeout=self.timeout + 60.0 * len(paths), check=False,
+                        timeout=run_timeout, check=False,
                     )
                 except (subprocess.TimeoutExpired, OSError):
                     # Subprocess never finished: prefer the crash-safe checkpoint
@@ -285,11 +363,13 @@ class WindowsComOracle(RenderBackend):
 
         opened_raw = record.get("opened")
         opened = bool(opened_raw) if opened_raw is not None else None
-        text_length = record.get("textLength")
-        try:
-            text_length = int(text_length) if text_length is not None else None
-        except (TypeError, ValueError):
-            text_length = None
+        text_length: int | None = None
+        text_length_raw = record.get("textLength")
+        if isinstance(text_length_raw, (bool, int, float, str)):
+            try:
+                text_length = int(text_length_raw)
+            except (TypeError, ValueError):
+                text_length = None
         error = record.get("error")
         parsed: bool | None
         if opened is None:
@@ -345,13 +425,13 @@ class WindowsComOracle(RenderBackend):
                 by_path[os.path.abspath(src)] = norm
         out: list[dict[str, object]] = []
         for abs_path in abs_paths:
-            norm = by_path.get(abs_path)
-            if norm is None:
+            found = by_path.get(abs_path)
+            if found is None:
                 out.append(self._unverified_entry(requested.get(abs_path, abs_path)))
             else:
                 # Surface the caller's original path string.
-                norm["path"] = requested.get(abs_path, norm.get("path"))
-                out.append(norm)
+                found["path"] = requested.get(abs_path, found.get("path"))
+                out.append(found)
         return out
 
     def _merge_checkpoint(
@@ -409,10 +489,14 @@ class MacHancomOracle(RenderBackend):
         timeout: float = 300.0,
         dpi: int = 150,
         osascript: str = "osascript",
+        budget_seconds: float | None = None,
     ) -> None:
         self.timeout = timeout
         self.dpi = dpi
         self._osascript = osascript
+        # Single externally-propagated deadline: every subprocess timeout in
+        # one public call is clamped so the whole call fits this budget.
+        self.budget_seconds = budget_seconds
 
     def _app_path(self) -> str | None:
         for candidate in _MAC_APP_CANDIDATES:
@@ -433,12 +517,46 @@ class MacHancomOracle(RenderBackend):
                 return line
         return None
 
+    def _automation_reachable(self) -> bool:
+        """Fast preflight for GUI automation (System Events + Automation TCC).
+
+        An installed Hancom does NOT imply the GUI transport works: without a
+        logged-in GUI session or with Automation/Apple Events denied, osascript
+        blocks until its own timeout — far beyond any caller budget. This probe
+        answers within :data:`_MAC_PROBE_TIMEOUT` seconds and is cached for the
+        process lifetime (TCC grants cannot change for a running process).
+        """
+
+        cached = _MAC_PROBE_CACHE.get(self._osascript)
+        if cached is not None:
+            return cached
+        reachable = False
+        try:
+            proc = subprocess.run(
+                [self._osascript, "-e", _MAC_PROBE_SCRIPT],
+                capture_output=True, text=True,
+                timeout=_MAC_PROBE_TIMEOUT, check=False,
+            )
+            reachable = proc.returncode == 0
+        except (OSError, subprocess.TimeoutExpired):
+            reachable = False
+        _MAC_PROBE_CACHE[self._osascript] = reachable
+        return reachable
+
     def available(self) -> bool:
-        """True only on macOS with ``Hancom Office HWP.app`` installed."""
+        """True only on macOS with Hancom installed AND GUI automation reachable.
+
+        ``HWPX_ORACLE_STRUCTURAL_ONLY`` forces ``False`` so no caller can enter
+        GUI automation in structural-only operation.
+        """
 
+        if structural_only():
+            return False
         if sys.platform != "darwin":
             return False
-        return self._app_path() is not None
+        if self._app_path() is None:
+            return False
+        return self._automation_reachable()
 
     def render_pdf(self, hwpx_path: str, out_pdf: str | None = None) -> str | None:
         """Render a single ``.hwpx`` to PDF via the GUI; returns the path or ``None``."""
@@ -466,6 +584,14 @@ class MacHancomOracle(RenderBackend):
         except OSError:
             pass
 
+        deadline = _deadline_from(self.budget_seconds)
+        run_timeout = _clamped_timeout(self.timeout + 60.0, deadline)
+        if run_timeout is None:
+            return None
+        # The AppleScript receives its own internal wait limit; keep it inside
+        # the clamped subprocess timeout so the script never outlives the budget.
+        script_timeout = max(1, int(min(self.timeout, run_timeout)))
+
         cleanup_staged = False
         try:
             if not staged_is_source:
@@ -475,12 +601,12 @@ class MacHancomOracle(RenderBackend):
                 resources.files("hwpx.visual").joinpath(_MAC_BACKEND_SCRIPT)
             ) as script:
                 cmd = [
-                    self._osascript, str(script), staged, out_pdf, str(int(self.timeout)),
+                    self._osascript, str(script), staged, out_pdf, str(script_timeout),
                 ]
                 try:
                     subprocess.run(
                         cmd, capture_output=True, text=True,
-                        timeout=self.timeout + 60.0, check=False,
+                        timeout=run_timeout, check=False,
                     )
                 except (subprocess.TimeoutExpired, OSError):
                     return None
@@ -507,6 +633,11 @@ class MacHancomOracle(RenderBackend):
         """
         if not self.available():
             return False
+        deadline = _deadline_from(self.budget_seconds)
+        run_timeout = _clamped_timeout(self.timeout + 60.0, deadline)
+        if run_timeout is None:
+            return False
+        script_timeout = max(1, int(min(self.timeout, run_timeout)))
         src = os.path.abspath(hwpx_path)
         try:
             before = os.stat(src).st_mtime_ns
@@ -515,11 +646,11 @@ class MacHancomOracle(RenderBackend):
         with resources.as_file(
             resources.files("hwpx.visual").joinpath(_MAC_REFRESH_SCRIPT)
         ) as script:
-            cmd = [self._osascript, str(script), src, str(int(self.timeout))]
+            cmd = [self._osascript, str(script), src, str(script_timeout)]
             try:
                 proc = subprocess.run(
                     cmd, capture_output=True, text=True,
-                    timeout=self.timeout + 60.0, check=False,
+                    timeout=run_timeout, check=False,
                 )
             except (subprocess.TimeoutExpired, OSError):
                 return False
@@ -551,17 +682,29 @@ def resolve_oracle(
     timeout: float = 300.0,
     dpi: int = 150,
     osascript: str = "osascript",
+    budget_seconds: float | None = None,
 ) -> RenderBackend:
     """Return the best reachable render backend (Windows COM → Mac GUI → Null).
 
     Windows COM is canonical (CI/scale); Mac GUI is the dev/spot-check fallback;
     :class:`NullOracle` is the degrade sentinel when no Hancom is reachable.
+    ``HWPX_ORACLE_STRUCTURAL_ONLY`` short-circuits to :class:`NullOracle`, and
+    ``budget_seconds`` propagates one external deadline into every backend
+    subprocess timeout.
     """
 
-    windows = WindowsComOracle(powershell=powershell, timeout=timeout, dpi=dpi)
+    if structural_only():
+        return NullOracle()
+    if budget_seconds is None:
+        budget_seconds = env_budget_seconds()
+    windows = WindowsComOracle(
+        powershell=powershell, timeout=timeout, dpi=dpi, budget_seconds=budget_seconds,
+    )
     if windows.available():
         return windows
-    mac = MacHancomOracle(timeout=timeout, dpi=dpi, osascript=osascript)
+    mac = MacHancomOracle(
+        timeout=timeout, dpi=dpi, osascript=osascript, budget_seconds=budget_seconds,
+    )
     if mac.available():
         return mac
     return NullOracle()

{python_hwpx-3.2.0.dist-info → python_hwpx-3.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.2.0
+Version: 3.3.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -70,7 +70,7 @@ Dynamic: license-file
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.2.0`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.3.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.

{python_hwpx-3.2.0.dist-info → python_hwpx-3.3.0.dist-info}/RECORD

@@ -185,15 +185,15 @@ hwpx/visual/diff.py,sha256=0X5T9IgwRZU3td-7vnPrlowovtGud7P_ymq0KVehlKk,5677
 hwpx/visual/fixture_corpus.py,sha256=Bcy7nscf6RY7sHemGKaqzsyRrWp5ioQdP2wQFFoY20A,6676
 hwpx/visual/hancom_worker.py,sha256=r70lUnHSdIF4h3plIk_SIkoXpzuACJp1FBE1WMBt5Ic,10161
 hwpx/visual/masks.py,sha256=oXhgynAb4uKjJtZ2BGHHdAjyvWGqSFlZFQ-iJxzHiuo,1832
-hwpx/visual/oracle.py,sha256=VNO-tAB-lzTdW5XtSELxg_Aau369qRFBsJvNryHF_D8,31319
+hwpx/visual/oracle.py,sha256=f3JqplfB5cE_Tx7HaCUQ4aBv7DhMpsp79a4i3BYHr1A,37069
 hwpx/visual/page_qa.py,sha256=AuJCySfLIdXjPeekhAc3YnrIWOsN0sI35Pnz8BZ6Pro,7278
 hwpx/visual/qa_contracts.py,sha256=1cjoiRTAWgi7NgE8SPc6bKxdoUfKx9nyou1mgC47TxY,10506
 hwpx/visual/qa_metrics.py,sha256=I7RdybN-f1Fvcv2j-ceDPoek51nOkMui1Zrd7TEX_C8,9838
 hwpx/visual/report.py,sha256=2RhXN1KBYOZTim9FNpeUhaaDHR7oFxI6Z2DLUkDIiwE,1717
-python_hwpx-3.2.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-3.2.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
-python_hwpx-3.2.0.dist-info/METADATA,sha256=8nLPZJKUFUDSQWMnOr1dDQo4cJ71TQ_IsRY5vZeXu9I,12566
-python_hwpx-3.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_hwpx-3.2.0.dist-info/entry_points.txt,sha256=PVUBTBQtBHiflQ9XBjfd004w-LrDibgZjwzxgu8Tx7w,480
-python_hwpx-3.2.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-3.2.0.dist-info/RECORD,,
+python_hwpx-3.3.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-3.3.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
+python_hwpx-3.3.0.dist-info/METADATA,sha256=Sst0elBTS2Ns4JL3oOUS9uC9lvH-A2rAkIoGLMqouOE,12566
+python_hwpx-3.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_hwpx-3.3.0.dist-info/entry_points.txt,sha256=PVUBTBQtBHiflQ9XBjfd004w-LrDibgZjwzxgu8Tx7w,480
+python_hwpx-3.3.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-3.3.0.dist-info/RECORD,,