pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/_win/watchdog.py

@@ -0,0 +1,253 @@
+# pyright: basic
+"""The dialog watchdog: detects, reports and dismisses modal dialogs of *one owned* Access process.
+
+A modal dialog inside a hidden Access blocks the current COM call forever. pywin32 releases the GIL while
+it waits for the call, so this thread keeps running (spike S8). While a call is in flight it:
+
+1. looks for visible top-level windows belonging to **our PID only** (a hidden Access has no other visible
+   windows; in visible mode only standard dialog windows count);
+2. records title, text and buttons, then dismisses the dialog: ``WM_CLOSE`` first, then a click on
+   Cancel/No/OK (Yes/No boxes ignore ``WM_CLOSE``), and finally terminates our Access if nothing works;
+3. terminates our Access when a call exceeds ``call_timeout``.
+
+It implements :class:`~pyaccesskit._com.gateway.CallMonitor`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import threading
+import time
+from collections.abc import Callable, Iterator
+
+import win32con
+import win32gui
+import win32process
+
+from pyaccesskit._win.console import register_interrupt_callback, unregister_interrupt_callback
+from pyaccesskit.enums import DialogPolicy
+from pyaccesskit.errors import DialogInfo
+
+__all__ = ["DialogWatchdog"]
+
+logger = logging.getLogger("pyaccesskit.process")
+
+BM_CLICK = 0x00F5
+DIALOG_CLASS = "#32770"
+BUTTON_PREFERENCE = ("cancel", "no", "ok", "close", "abort", "ignore", "end")
+INTERRUPT_GRACE = 0.5
+
+
+def _plain(text: str) -> str:
+    return text.replace("&", "").strip().rstrip(".").lower()
+
+
+class DialogWatchdog:
+    """Watches one Access process for modal dialogs and runaway calls.
+
+    Args:
+        pid: PID of the owned Access process.
+        policy: What to do about dialogs (``OFF`` disables dialog handling; timeouts still apply).
+        call_timeout: Seconds a single operation may run before Access is terminated (``None`` = never).
+        visible: Whether the Access window is visible (then only standard dialogs are considered).
+        terminate: Callback that terminates the owned Access process (given a reason).
+        poll_interval: Seconds between window scans while a call is in flight.
+    """
+
+    def __init__(
+        self,
+        pid: int,
+        *,
+        policy: DialogPolicy,
+        call_timeout: float | None,
+        visible: bool,
+        terminate: Callable[[str], None],
+        poll_interval: float = 0.2,
+    ) -> None:
+        self.pid = pid
+        self.policy = policy
+        self._call_timeout = call_timeout
+        self._visible = visible
+        self._terminate = terminate
+        self._poll = poll_interval
+        self._lock = threading.Lock()
+        self._idle = threading.Condition(self._lock)
+        self._busy = 0
+        self._inflight_since: float | None = None
+        self._description = ""
+        self._events: list[DialogInfo] = []
+        self._handled: set[int] = set()
+        self._termination: tuple[str, str] | None = None
+        self._stop = threading.Event()
+        self._thread = threading.Thread(
+            target=self._run, name=f"pyaccesskit-watchdog-{pid}", daemon=True
+        )
+
+    # ----------------------------------------------------------------------------------- lifecycle
+    def start(self) -> None:
+        """Start the watchdog thread and hook Ctrl+C."""
+        self._thread.start()
+        register_interrupt_callback(self._on_interrupt)
+
+    def stop(self) -> None:
+        """Stop the watchdog thread."""
+        unregister_interrupt_callback(self._on_interrupt)
+        self._stop.set()
+        if self._thread.is_alive() and self._thread is not threading.current_thread():
+            self._thread.join(2.0)
+
+    # --------------------------------------------------------------------------------- CallMonitor
+    def begin(self, description: str) -> None:
+        with self._lock:
+            self._inflight_since = time.monotonic()
+            self._description = description
+            self._events = []
+
+    def end(self) -> tuple[DialogInfo, ...]:
+        with self._idle:
+            # A dismissed dialog unblocks the COM call immediately; wait until its handling is recorded.
+            self._idle.wait_for(lambda: self._busy == 0, timeout=10.0)
+            self._inflight_since = None
+            events = tuple(self._events)
+            self._events = []
+            return events
+
+    @property
+    def termination(self) -> tuple[str, str] | None:
+        """``(kind, reason)`` if the watchdog terminated Access; kind is timeout/dialog/interrupt."""
+        return self._termination
+
+    @contextlib.contextmanager
+    def watching(self, description: str) -> Iterator[None]:
+        """Monitor an operation whose dialogs are handled but not reported (e.g. shutdown)."""
+        self.begin(description)
+        try:
+            yield
+        finally:
+            self.end()
+
+    # ------------------------------------------------------------------------------------- thread
+    def _run(self) -> None:
+        while not self._stop.wait(self._poll):
+            with self._lock:
+                since = self._inflight_since
+                description = self._description
+            if since is None:
+                continue
+            try:
+                if self.policy is not DialogPolicy.OFF:
+                    for hwnd in self._dialog_windows():
+                        self._handle(hwnd)
+                if self._call_timeout is not None and time.monotonic() - since > self._call_timeout:
+                    self._kill(
+                        "timeout", f"'{description}' did not finish within {self._call_timeout:g}s"
+                    )
+                    with self._lock:
+                        self._inflight_since = None
+            except Exception:
+                logger.exception("dialog watchdog error")
+
+    def _dialog_windows(self) -> list[int]:
+        found: list[int] = []
+
+        def collect(hwnd: int, _extra: object) -> bool:
+            with contextlib.suppress(Exception):
+                if win32process.GetWindowThreadProcessId(hwnd)[1] != self.pid:
+                    return True
+                if not win32gui.IsWindowVisible(hwnd):
+                    return True
+                if self._visible and win32gui.GetClassName(hwnd) != DIALOG_CLASS:
+                    return True
+                found.append(hwnd)
+            return True
+
+        with contextlib.suppress(Exception):
+            win32gui.EnumWindows(collect, None)
+        return [hwnd for hwnd in found if hwnd not in self._handled]
+
+    @staticmethod
+    def _children(hwnd: int) -> list[tuple[int, str, str]]:
+        children: list[tuple[int, str, str]] = []
+
+        def collect(child: int, _extra: object) -> bool:
+            with contextlib.suppress(Exception):
+                children.append(
+                    (child, win32gui.GetClassName(child) or "", win32gui.GetWindowText(child) or "")
+                )
+            return True
+
+        with contextlib.suppress(Exception):
+            win32gui.EnumChildWindows(hwnd, collect, None)
+        return children
+
+    @staticmethod
+    def _gone(hwnd: int, wait: float) -> bool:
+        deadline = time.monotonic() + wait
+        while time.monotonic() < deadline:
+            if not win32gui.IsWindow(hwnd) or not win32gui.IsWindowVisible(hwnd):
+                return True
+            time.sleep(0.05)
+        return not win32gui.IsWindow(hwnd) or not win32gui.IsWindowVisible(hwnd)
+
+    def _handle(self, hwnd: int) -> None:
+        self._handled.add(hwnd)
+        title = win32gui.GetWindowText(hwnd)
+        children = self._children(hwnd)
+        buttons = [(h, text) for h, cls, text in children if cls == "Button" and text]
+        texts = [text for _h, cls, text in children if cls != "Button" and text.strip()]
+        with contextlib.suppress(Exception):
+            message = win32gui.GetDlgItemText(hwnd, 0xFFFF)
+            if message and message not in texts:
+                texts.insert(0, message)
+        logger.warning("Access (PID %s) showed a dialog: %r %r", self.pid, title, texts)
+
+        info = DialogInfo(
+            title=title,
+            text=" ".join(" ".join(texts).split()),
+            buttons=tuple(text.replace("&", "") for _h, text in buttons),
+            action="dismissing",
+        )
+        # Record the dialog *before* dismissing it: dismissal unblocks the COM call, whose end() must see it.
+        with self._idle:
+            self._busy += 1
+            events = self._events
+            events.append(info)
+            position = len(events) - 1
+        action = "dismissal failed"
+        try:
+            action = self._dismiss(hwnd, buttons)
+        finally:
+            with self._idle:
+                if position < len(events) and events[position] is info:
+                    events[position] = DialogInfo(info.title, info.text, info.buttons, action)
+                self._busy -= 1
+                self._idle.notify_all()
+
+    def _dismiss(self, hwnd: int, buttons: list[tuple[int, str]]) -> str:
+        with contextlib.suppress(Exception):
+            win32gui.PostMessage(hwnd, win32con.WM_CLOSE, 0, 0)
+        if self._gone(hwnd, 1.0):
+            return "closed"
+        by_text = {_plain(text): (button, text) for button, text in buttons}
+        for wanted in BUTTON_PREFERENCE:
+            if wanted in by_text:
+                button, text = by_text[wanted]
+                with contextlib.suppress(Exception):
+                    win32gui.PostMessage(button, BM_CLICK, 0, 0)
+                if self._gone(hwnd, 1.5):
+                    return f"clicked {text.replace('&', '')!r}"
+        self._kill("dialog", "a modal dialog could not be dismissed")
+        return "terminated Access"
+
+    def _kill(self, kind: str, reason: str) -> None:
+        if self._termination is None:
+            self._termination = (kind, reason)
+        logger.error("terminating owned Access process %s: %s", self.pid, reason)
+        self._terminate(reason)
+
+    def _on_interrupt(self) -> None:
+        with self._lock:
+            since = self._inflight_since
+        if since is not None and time.monotonic() - since > INTERRUPT_GRACE:
+            self._kill("interrupt", "interrupted by the user (Ctrl+C)")

pyaccesskit/cli/__init__.py

@@ -0,0 +1,10 @@
+"""Command-line interface (``pyaccesskit``). Heavy imports happen lazily inside :func:`main`."""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    """Entry point for the ``pyaccesskit`` console script."""
+    from pyaccesskit.cli.app import run  # noqa: PLC0415 - keep `import pyaccesskit` light
+
+    run()

pyaccesskit/cli/_output.py

@@ -0,0 +1,101 @@
+"""Console helpers shared by the commands: exit codes, error reporting, JSON output."""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+from pyaccesskit.errors import EnvironmentProblem, PyAccessKitError
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_ENVIRONMENT = 3
+
+_SECRET_KEYS = re.compile(r"(?i)PWD|PASSWORD")
+
+
+def stdout() -> Console:
+    """A console for normal output (created per call so tests can capture it)."""
+    return Console(highlight=False, soft_wrap=False)
+
+
+def stderr() -> Console:
+    """A console for errors."""
+    return Console(stderr=True, highlight=False)
+
+
+def _segments(connect: str) -> list[str]:
+    """Split a connection string at the ``;`` separators, honouring ODBC ``{...}`` values (``}}`` escapes)."""
+    segments: list[str] = []
+    current: list[str] = []
+    index, braced, at_value_start = 0, False, False
+    while index < len(connect):
+        char = connect[index]
+        if braced:
+            current.append(char)
+            if char == "}":
+                if connect[index + 1 : index + 2] == "}":  # escaped closing brace
+                    current.append("}")
+                    index += 1
+                else:
+                    braced = False
+        elif char == ";":
+            segments.append("".join(current))
+            current = []
+            at_value_start = False
+        else:
+            current.append(char)
+            if char == "{" and at_value_start:
+                braced = True
+            at_value_start = char == "=" and "=" not in "".join(current[:-1])
+        index += 1
+    segments.append("".join(current))
+    return segments
+
+
+def redact(connect: str | None) -> str | None:
+    """Hide password values (``PWD=``/``Password=``, including ``{brace;quoted}`` ones) in a connection string."""
+    if connect is None:
+        return None
+    parts: list[str] = []
+    for segment in _segments(connect):
+        key, sep, _value = segment.partition("=")
+        if sep and _SECRET_KEYS.fullmatch(key.strip()):
+            parts.append(f"{key}=***")
+        else:
+            parts.append(segment)
+    return ";".join(parts)
+
+
+def print_json(data: Any) -> None:
+    """Write ``data`` as ASCII-safe JSON (works whatever the console or pipe encoding)."""
+    sys.stdout.write(json.dumps(data, indent=2, default=str) + "\n")
+
+
+@contextmanager
+def handle_errors() -> Generator[None, None, None]:
+    """Report PyAccessKit errors without a traceback and exit with the documented code."""
+    try:
+        yield
+    except EnvironmentProblem as exc:
+        _report(exc)
+        raise typer.Exit(EXIT_ENVIRONMENT) from None
+    except PyAccessKitError as exc:
+        _report(exc)
+        raise typer.Exit(EXIT_ERROR) from None
+
+
+def _report(exc: PyAccessKitError) -> None:
+    console = stderr()
+    console.print(f"[bold red]error:[/] {escape(str(exc))}")  # includes any engine diagnosis
+    for note in getattr(exc, "__notes__", ()):
+        console.print(f"  [dim]{escape(str(note))}[/]")

pyaccesskit/cli/agent.py

@@ -0,0 +1,99 @@
+"""``pyaccesskit guide`` and ``pyaccesskit schema``: material for AI coding agents (and humans)."""
+
+from __future__ import annotations
+
+import sys
+from enum import StrEnum
+from typing import Annotated, Any
+
+import typer
+from pydantic import TypeAdapter
+
+from pyaccesskit.cli._output import EXIT_OK, print_json
+from pyaccesskit.forms import FormSpec
+from pyaccesskit.schema import ColumnSpec, IndexSpec, QuerySpec, RelationshipSpec, TableSpec
+
+GUIDE_RESOURCE = "AGENT_GUIDE.md"
+
+
+class SchemaKind(StrEnum):
+    """Spec types whose JSON Schema can be printed."""
+
+    ALL = "all"
+    TABLE = "table"
+    COLUMN = "column"
+    INDEX = "index"
+    RELATIONSHIP = "relationship"
+    QUERY = "query"
+    FORM = "form"
+
+
+_MODELS: dict[SchemaKind, Any] = {
+    SchemaKind.TABLE: TableSpec,
+    SchemaKind.COLUMN: TypeAdapter(ColumnSpec),
+    SchemaKind.INDEX: IndexSpec,
+    SchemaKind.RELATIONSHIP: RelationshipSpec,
+    SchemaKind.QUERY: QuerySpec,
+    SchemaKind.FORM: FormSpec,
+}
+
+
+def guide_text() -> str:
+    """The agent guide shipped inside the package."""
+    from importlib.resources import files  # noqa: PLC0415 - only needed here
+
+    return files("pyaccesskit").joinpath(GUIDE_RESOURCE).read_text(encoding="utf-8")
+
+
+def guide_path() -> str:
+    """Where the installed agent guide lives on disk."""
+    from importlib.resources import files  # noqa: PLC0415
+
+    return str(files("pyaccesskit").joinpath(GUIDE_RESOURCE))
+
+
+def json_schema(kind: SchemaKind) -> dict[str, Any]:
+    """The JSON Schema of one spec type, or of all of them keyed by kind."""
+    if kind is SchemaKind.ALL:
+        return {k.value: json_schema(k) for k in _MODELS}
+    model = _MODELS[kind]
+    if isinstance(model, TypeAdapter):
+        return model.json_schema()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
+    return model.model_json_schema()
+
+
+def guide(
+    path: Annotated[
+        bool, typer.Option("--path", help="Print where the guide file is instead of its text.")
+    ] = False,
+) -> None:
+    """Print the guide for AI agents that write Access software with PyAccessKit."""
+    if path:
+        typer.echo(guide_path())
+    else:
+        write_text(guide_text())
+    raise typer.Exit(EXIT_OK)
+
+
+def write_text(text: str) -> None:
+    """Write to stdout; when piped on Windows (ANSI code page) fall back to UTF-8 instead of failing."""
+    try:
+        text.encode(sys.stdout.encoding or "utf-8")
+    except (UnicodeEncodeError, LookupError):
+        buffer = getattr(sys.stdout, "buffer", None)
+        if buffer is not None:
+            sys.stdout.flush()
+            buffer.write(text.encode("utf-8"))
+            buffer.flush()
+            return
+    sys.stdout.write(text)
+
+
+def schema(
+    kind: Annotated[
+        SchemaKind, typer.Argument(help="Which spec to describe.", show_default=True)
+    ] = SchemaKind.ALL,
+) -> None:
+    """Print the JSON Schema of PyAccessKit specs (tables, columns, queries, forms...)."""
+    print_json(json_schema(kind))
+    raise typer.Exit(EXIT_OK)

pyaccesskit/cli/app.py

@@ -0,0 +1,54 @@
+"""The ``pyaccesskit`` command-line application.
+
+Exit codes: 0 success, 1 error, 2 usage error, 3 environment unusable (no engine, missing Access...).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from pyaccesskit._version import __version__
+from pyaccesskit.cli.agent import guide, schema
+from pyaccesskit.cli.cleanup import cleanup
+from pyaccesskit.cli.doctor import doctor
+from pyaccesskit.cli.inspection import inspect_database
+
+app = typer.Typer(
+    name="pyaccesskit",
+    help="Create, inspect and maintain Microsoft Access databases from Python.",
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_enable=False,
+)
+
+
+def _show_version(value: bool) -> None:
+    if value:
+        typer.echo(f"pyaccesskit {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_show_version, is_eager=True, help="Show the version and exit."
+        ),
+    ] = False,
+) -> None:
+    """Create, inspect and maintain Microsoft Access databases from Python."""
+
+
+app.command("doctor")(doctor)
+app.command("inspect")(inspect_database)
+app.command("cleanup")(cleanup)
+app.command("guide")(guide)
+app.command("schema")(schema)
+
+
+def run() -> None:
+    """Run the CLI (used by the ``pyaccesskit`` console script and ``python -m pyaccesskit``)."""
+    app(prog_name="pyaccesskit")

pyaccesskit/cli/cleanup.py

@@ -0,0 +1,56 @@
+"""``pyaccesskit cleanup``: end orphaned Access processes that PyAccessKit started."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.markup import escape
+
+from pyaccesskit.cli._output import EXIT_ERROR, EXIT_OK, handle_errors, print_json, stdout
+from pyaccesskit.maintenance import reap_orphans
+
+_DESCRIPTIONS = {
+    "terminated": "terminated (its Python owner had exited)",
+    "would-terminate": "would be terminated (its Python owner has exited)",
+    "already-exited": "already exited; ledger entry removed",
+    "owner-alive": "left alone: its Python owner is still running",
+    "failed": "could not be terminated",
+}
+
+
+def cleanup(
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Only report what would be terminated.")
+    ] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Print the result as JSON.")] = False,
+) -> None:
+    """End Access processes left behind by crashed PyAccessKit sessions.
+
+    Only processes recorded in PyAccessKit's ownership ledger are considered, and only when the Python
+    process that started them is gone. Access instances you or other tools started are never touched.
+    """
+    with handle_errors():
+        results = reap_orphans(dry_run=dry_run)
+    if json_output:
+        print_json(
+            [
+                {
+                    "pid": r.entry.pid,
+                    "owner_pid": r.entry.owner_pid,
+                    "database": r.entry.database,
+                    "action": r.action,
+                }
+                for r in results
+            ]
+        )
+    else:
+        console = stdout()
+        if not results:
+            console.print("No Access processes started by PyAccessKit are recorded. Nothing to do.")
+        for result in results:
+            where = f" ({escape(result.entry.database)})" if result.entry.database else ""
+            console.print(
+                f"PID {result.entry.pid}{where}: {_DESCRIPTIONS.get(result.action, result.action)}"
+            )
+    raise typer.Exit(EXIT_ERROR if any(r.action == "failed" for r in results) else EXIT_OK)

pyaccesskit/cli/doctor.py

@@ -0,0 +1,101 @@
+"""``pyaccesskit doctor``: which engines work on this machine, and why not."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.markup import escape
+from rich.table import Table
+
+from pyaccesskit import diagnostics
+from pyaccesskit.cli._output import EXIT_ENVIRONMENT, EXIT_OK, print_json, stdout
+
+_ENGINE_LABELS = {"dao": "in-process DAO", "access": "Microsoft Access"}
+
+
+def doctor(
+    json_output: Annotated[bool, typer.Option("--json", help="Print the report as JSON.")] = False,
+    probe: Annotated[
+        bool,
+        typer.Option(
+            "--probe",
+            help="Also build a scratch database with each available engine (starts and closes an owned, "
+            "hidden Access process).",
+        ),
+    ] = False,
+) -> None:
+    """Check which engines PyAccessKit can use here (exit code 3 if none works)."""
+    report = diagnostics.diagnose(probe=probe)
+    if json_output:
+        print_json(report.to_dict())
+    else:
+        render(report)
+    raise typer.Exit(EXIT_OK if report.usable else EXIT_ENVIRONMENT)
+
+
+def render(report: diagnostics.Diagnosis) -> None:
+    """Print a human-readable report."""
+    console = stdout()
+    console.print(f"[bold]PyAccessKit {report.pyaccesskit_version}[/] environment report\n")
+    facts = Table.grid(padding=(0, 2))
+    facts.add_column(style="bold")
+    facts.add_column()
+    facts.add_row(
+        "Python",
+        escape(f"{report.python_version} ({report.python_bits}-bit)  {report.python_executable}"),
+    )
+    facts.add_row("Windows", escape(report.operating_system))
+    facts.add_row("pywin32", report.pywin32_version or "[red]not installed[/]")
+    access = report.access
+    if access is None:
+        facts.add_row("Access", "[yellow]not registered[/]")
+    else:
+        edition = (
+            f"Click-to-Run: {', '.join(access.products) or 'unknown products'}"
+            if access.click_to_run
+            else "MSI"
+        )
+        facts.add_row(
+            "Access",
+            escape(f"{access.version or 'unknown version'} ({access.bits or '?'}-bit, {edition})"),
+        )
+        if access.executable:
+            facts.add_row("", escape(access.executable))
+    facts.add_row("ACE OLEDB", escape(", ".join(report.ace_oledb)) or "none for this bitness")
+    console.print(facts)
+
+    console.print("\n[bold]Engines[/]")
+    engines = Table.grid(padding=(0, 2))
+    for check in report.engines:
+        state = "[green]available[/]  " if check.available else "[red]unavailable[/]"
+        engines.add_row(f"  {_ENGINE_LABELS[check.engine]}", state, escape(check.detail))
+    console.print(engines)
+    auto = _ENGINE_LABELS[report.auto_engine] if report.auto_engine else "[red]nothing usable[/]"
+    console.print(f"  engine='auto' selects: [bold]{auto}[/]")
+
+    if report.probes:
+        console.print("\n[bold]Probes[/]")
+        for result in report.probes:
+            state = "[green]passed[/]" if result.ok else "[red]failed[/]"
+            console.print(
+                f"  {_ENGINE_LABELS[result.engine]}: {state} in {result.seconds:.1f}s - "
+                f"{escape(result.detail)}"
+            )
+    if report.owned_processes:
+        console.print("\n[bold]Access processes started by PyAccessKit[/]")
+        for entry in report.owned_processes:
+            console.print(
+                f"  PID {entry.pid} (owner PID {entry.owner_pid}): {entry.status}"
+                + (f" - {escape(entry.database)}" if entry.database else "")
+            )
+    if report.notes:
+        console.print("\n[bold]Notes[/]")
+        for note in report.notes:
+            console.print(f"  - {escape(note)}")
+    if report.problems:
+        console.print("\n[bold red]Problems[/]")
+        for problem in report.problems:
+            console.print(f"  - {escape(problem)}")
+    verdict = "[green]ready[/]" if report.usable else "[red]not usable[/]"
+    console.print(f"\nPyAccessKit is {verdict} on this machine.")