pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/_win/access_process.py

@@ -0,0 +1,348 @@
+# pyright: basic
+"""An ``MSACCESS.EXE`` process that PyAccessKit started and therefore owns.
+
+Launch (ADR 0001, spike S1):
+
+1. ``CoCreateInstanceEx(CLSCTX_LOCAL_SERVER)`` — always a *new* process, never a user's running Access;
+2. ``hWndAccessApp()`` → PID → an open process handle; identity = PID + creation time + image;
+3. assignment to a kill-on-close job object (Access dies with Python, whatever kills Python);
+4. an ownership-ledger entry (for ``pyaccesskit cleanup`` should everything else fail);
+5. the dialog watchdog; then ``AutomationSecurity``, ``Visible`` and ``SetWarnings``.
+
+Shutdown closes open forms/reports without saving, closes the database, calls
+``Quit(acQuitSaveNone)``, waits for the process to exit and — only for *this* process, identified by the
+handle we hold — terminates it if it lingers. Every step runs even if an earlier one failed.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import gc
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import pywintypes
+import win32process
+
+from pyaccesskit import _ledger
+from pyaccesskit._com import constants as c
+from pyaccesskit._com.dispatch import create_local_server
+from pyaccesskit._com.errors import OpContext, translate
+from pyaccesskit._com.gateway import Com, call, get, put, retry_busy
+from pyaccesskit._version import __version__
+from pyaccesskit._win.job import KillOnCloseJob
+from pyaccesskit._win.processes import (
+    ProcessIdentity,
+    close_handle,
+    current_identity,
+    identity_of,
+    is_alive,
+    open_process,
+    terminate,
+    wait_for_exit,
+)
+from pyaccesskit._win.watchdog import DialogWatchdog
+from pyaccesskit.enums import DialogPolicy, MacroSecurity
+from pyaccesskit.errors import AccessNotInstalledError, DaoError
+
+__all__ = ["AccessLaunchOptions", "AccessProcess", "read_dao_errors"]
+
+logger = logging.getLogger("pyaccesskit.process")
+
+_MACRO_SECURITY = {
+    MacroSecurity.DISABLE: c.MsoAutomationSecurity.msoAutomationSecurityForceDisable,
+    MacroSecurity.USE_UI: c.MsoAutomationSecurity.msoAutomationSecurityByUI,
+    MacroSecurity.ENABLE: c.MsoAutomationSecurity.msoAutomationSecurityLow,
+}
+_NO_CURRENT_DATABASE = 2467
+
+
+@dataclass(frozen=True)
+class AccessLaunchOptions:
+    """How to start and supervise Access."""
+
+    progid: str = "Access.Application"
+    visible: bool = False
+    macro_security: MacroSecurity = MacroSecurity.DISABLE
+    dialog_policy: DialogPolicy = DialogPolicy.FAIL
+    call_timeout: float | None = 600.0
+    quit_timeout: float = 30.0
+    kill_on_parent_exit: bool = True
+
+
+def read_dao_errors(dbengine: Any) -> list[DaoError]:
+    """Snapshot ``DBEngine.Errors`` (used to enrich error messages)."""
+    errors: list[DaoError] = []
+    collection = dbengine.Errors
+    for index in range(collection.Count):
+        item = get(collection, "Item", index)
+        errors.append(DaoError(int(item.Number), str(item.Description), str(item.Source)))
+    return errors
+
+
+class AccessProcess:
+    """A hidden Access instance owned by one PyAccessKit session."""
+
+    def __init__(self, options: AccessLaunchOptions) -> None:
+        self.options = options
+        self.app: Any = None
+        self.identity: ProcessIdentity | None = None
+        self.watchdog: DialogWatchdog | None = None
+        self.is_runtime = False
+        self._handle: Any = None
+        self._job: KillOnCloseJob | None = None
+        self._ledger_path: Any = None
+        self._lock = threading.Lock()
+        self._closed = False
+        self.com = Com(dao_errors=self._dao_errors)
+
+    # ------------------------------------------------------------------------------------- launch
+    @classmethod
+    def launch(cls, options: AccessLaunchOptions, *, database: str | None = None) -> AccessProcess:
+        """Start and configure a new, owned Access process.
+
+        Raises:
+            AccessNotInstalledError: If ``Access.Application`` cannot be started.
+        """
+        process = cls(options)
+        try:
+            process.app = create_local_server(options.progid)
+        except pywintypes.com_error as exc:
+            error = translate(exc, OpContext("start Microsoft Access"))
+            raise AccessNotInstalledError(
+                f"Microsoft Access ({options.progid}) could not be started: {error.details.summary() if error.details else exc}",
+                diagnosis=(
+                    "Install Microsoft Access (Microsoft 365, 2016 or later), or use engine='dao' with the "
+                    "Microsoft 365 Access Runtime and a Python of the same bitness. Run 'pyaccesskit doctor'."
+                ),
+                details=error.details,
+            ) from exc
+        try:
+            process._take_ownership(database)
+            process._configure()
+        except BaseException:
+            process.shutdown()
+            raise
+        return process
+
+    def _take_ownership(self, database: str | None) -> None:
+        try:
+            hwnd = retry_busy(call, self.app, "hWndAccessApp")
+            _thread, pid = win32process.GetWindowThreadProcessId(int(hwnd))
+            self._handle = open_process(pid)
+            identity = identity_of(self._handle, pid)
+        except (pywintypes.error, pywintypes.com_error, OSError) as exc:
+            logger.warning(
+                "could not identify the Access process (%s); it will be shut down with Quit() only",
+                exc,
+            )
+            return
+        if identity.image_name.lower() != "msaccess.exe":
+            logger.warning(
+                "hWndAccessApp resolved to %s, not MSACCESS.EXE; not taking ownership",
+                identity.image,
+            )
+            close_handle(self._handle)
+            self._handle = None
+            return
+        self.identity = identity
+        logger.info("started Microsoft Access (PID %s)", identity.pid)
+
+        self.watchdog = DialogWatchdog(
+            identity.pid,
+            policy=self.options.dialog_policy,
+            call_timeout=self.options.call_timeout,
+            visible=self.options.visible,
+            terminate=self.terminate,
+        )
+        self.watchdog.start()
+        self.com = Com(monitor=self.watchdog, dao_errors=self._dao_errors)
+
+        if self.options.kill_on_parent_exit:
+            job = KillOnCloseJob()
+            if job.assign(self._handle):
+                self._job = job
+            else:
+                job.close()
+        try:
+            owner = current_identity()
+            entry = _ledger.OwnedProcess(
+                pid=identity.pid,
+                creation_time=identity.creation_time,
+                image=identity.image,
+                owner_pid=owner.pid,
+                owner_creation_time=owner.creation_time,
+                database=database,
+                started_at=time.time(),
+                version=__version__,
+            )
+            self._ledger_path = _ledger.record(entry)
+        except (OSError, pywintypes.error) as exc:
+            logger.warning("could not write the ownership ledger entry: %s", exc)
+
+    def _configure(self) -> None:
+        with self.com.op("configure Microsoft Access"):
+            put(self.app, "AutomationSecurity", int(_MACRO_SECURITY[self.options.macro_security]))
+            if self.options.visible:
+                put(self.app, "Visible", True)
+            with contextlib.suppress(pywintypes.com_error):
+                self.is_runtime = bool(
+                    call(self.app, "SysCmd", int(c.AcSysCmdAction.acSysCmdRuntime))
+                )
+
+    def database_opened(self) -> None:
+        """Session settings that need an open current database (``SetWarnings`` fails without one)."""
+        with contextlib.suppress(pywintypes.com_error):
+            call(get(self.app, "DoCmd"), "SetWarnings", False)
+
+    def _dao_errors(self) -> list[DaoError]:
+        return read_dao_errors(get(self.app, "DBEngine")) if self.app is not None else []
+
+    # --------------------------------------------------------------------------------------- state
+    @property
+    def pid(self) -> int | None:
+        """PID of the owned process (``None`` if ownership could not be established)."""
+        return self.identity.pid if self.identity else None
+
+    @property
+    def alive(self) -> bool:
+        """Whether the process is still running (``True`` if unknown)."""
+        return is_alive(self._handle) if self._handle is not None else self.app is not None
+
+    def terminate(self, reason: str) -> None:
+        """Terminate the owned process immediately (safe from any thread)."""
+        with self._lock:
+            handle = self._handle
+        if handle is None:
+            logger.error(
+                "cannot terminate Access (%s): its process could not be identified", reason
+            )
+            return
+        with contextlib.suppress(pywintypes.error):
+            if is_alive(handle):
+                logger.warning("terminating owned Access process %s: %s", self.pid, reason)
+                terminate(handle)
+
+    # ------------------------------------------------------------------------------------ shutdown
+    def close_open_objects(self) -> None:
+        """Close every open form and report without saving (avoids 'Save As' prompts)."""
+        if self.app is None:
+            return
+        for collection, object_type in (
+            ("Forms", c.AcObjectType.acForm),
+            ("Reports", c.AcObjectType.acReport),
+        ):
+            try:
+                opened = get(self.app, collection)
+                names = [
+                    get(get(opened, "Item", index), "Name") for index in range(get(opened, "Count"))
+                ]
+            except pywintypes.com_error:
+                continue
+            for name in names:
+                with contextlib.suppress(pywintypes.com_error):
+                    call(
+                        get(self.app, "DoCmd"),
+                        "Close",
+                        int(object_type),
+                        name,
+                        int(c.AcCloseSave.acSaveNo),
+                    )
+
+    def close_database(self) -> None:
+        """Close the current database, if any (ignoring 'no database open')."""
+        if self.app is None:
+            return
+        try:
+            call(self.app, "CloseCurrentDatabase")
+        except pywintypes.com_error as exc:
+            excepinfo = exc.args[2] if len(exc.args) > 2 else None
+            scode = excepinfo[5] if excepinfo else None
+            if scode is None or (scode & 0xFFFF) != _NO_CURRENT_DATABASE:
+                raise
+
+    def shutdown(self, timeout: float | None = None) -> list[BaseException]:
+        """Quit Access and make sure the owned process is gone. Returns the errors of failed steps."""
+        errors: list[BaseException] = []
+        with self._lock:
+            if self._closed:
+                return errors
+            self._closed = True
+        wait = self.options.quit_timeout if timeout is None else timeout
+        # Release unreachable COM proxies while Access is still alive: releasing them after it exits makes
+        # COM raise (and handle) RPC_E_DISCONNECTED, which faulthandler reports as a "fatal exception".
+        gc.collect()
+        watch = (
+            self.watchdog.watching("shut down Microsoft Access")
+            if self.watchdog
+            else contextlib.nullcontext()
+        )
+        # If the process is already gone (e.g. terminated by the watchdog), COM steps can only fail.
+        dead = self._handle is not None and not is_alive(self._handle)
+        try:
+            with watch:
+                for step in (
+                    () if dead else (self.close_open_objects, self.close_database, self._quit)
+                ):
+                    try:
+                        step()
+                    except Exception as exc:
+                        errors.append(exc)
+                self.app = None
+                self.com = Com()
+                if self._handle is not None and not wait_for_exit(self._handle, wait):
+                    logger.warning(
+                        "Access (PID %s) did not exit %.0fs after Quit; terminating it",
+                        self.pid,
+                        wait,
+                    )
+                    self.terminate("did not exit after Quit")
+                    wait_for_exit(self._handle, 10)
+        finally:
+            self._release()
+        return errors
+
+    def _quit(self) -> None:
+        if self.app is None:
+            return
+        with contextlib.suppress(pywintypes.com_error):
+            call(self.app, "Quit", int(c.AcQuitOption.acQuitSaveNone))
+
+    def _release(self) -> None:
+        if self.watchdog is not None:
+            self.watchdog.stop()
+        if self._job is not None:
+            self._job.close()
+            self._job = None
+        exited = self._handle is None or not is_alive(self._handle)
+        if self._ledger_path is not None and exited:
+            _ledger.remove(self._ledger_path)
+            self._ledger_path = None
+        if self._handle is not None:
+            close_handle(self._handle)
+            self._handle = None
+
+    def detach(self) -> None:
+        """Hand the process over to the user: it keeps running after this Python process exits."""
+        if self.app is not None:
+            put(self.app, "Visible", True)
+            put(self.app, "UserControl", True)
+        if self._job is not None:
+            self._job.release()
+        self.app = None
+        with self._lock:
+            self._closed = True
+        if self.watchdog is not None:
+            self.watchdog.stop()
+        if self._ledger_path is not None:
+            _ledger.remove(self._ledger_path)
+            self._ledger_path = None
+        if self._job is not None:
+            self._job.close()
+            self._job = None
+        if self._handle is not None:
+            close_handle(self._handle)
+            self._handle = None

pyaccesskit/_win/console.py

@@ -0,0 +1,56 @@
+# pyright: basic
+"""Make Ctrl+C effective while Python is blocked inside a long COM call.
+
+Python only raises ``KeyboardInterrupt`` when the main thread runs bytecode again, which does not happen
+while it waits for Access. A console control handler (called by Windows on its own thread) lets the
+watchdogs terminate the *owned* Access process whose call is in flight; the COM call then returns and the
+interrupt surfaces immediately. The handler returns ``False`` so Python's default handling still runs.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+
+import win32api
+import win32con
+
+__all__ = ["register_interrupt_callback", "unregister_interrupt_callback"]
+
+logger = logging.getLogger("pyaccesskit.process")
+
+_lock = threading.Lock()
+_callbacks: set[Callable[[], None]] = set()
+_installed = False
+
+
+def _handler(ctrl_type: int) -> bool:
+    if ctrl_type in (win32con.CTRL_C_EVENT, win32con.CTRL_BREAK_EVENT):
+        with _lock:
+            callbacks = list(_callbacks)
+        for callback in callbacks:
+            try:
+                callback()
+            except Exception:
+                logger.exception("interrupt callback failed")
+    return False
+
+
+def register_interrupt_callback(callback: Callable[[], None]) -> None:
+    """Call ``callback`` (from a Windows-owned thread) when the user presses Ctrl+C or Ctrl+Break."""
+    global _installed  # noqa: PLW0603 - one process-wide console handler
+    with _lock:
+        _callbacks.add(callback)
+        if not _installed:
+            try:
+                win32api.SetConsoleCtrlHandler(_handler, True)
+                _installed = True
+            except Exception as exc:
+                logger.debug("console control handler unavailable: %s", exc)
+
+
+def unregister_interrupt_callback(callback: Callable[[], None]) -> None:
+    """Remove a callback registered with :func:`register_interrupt_callback`."""
+    with _lock:
+        _callbacks.discard(callback)

pyaccesskit/_win/inspector.py

@@ -0,0 +1,53 @@
+# pyright: basic
+"""Win32 implementation of the ledger's :class:`~pyaccesskit._ledger.ProcessInspector`."""
+
+from __future__ import annotations
+
+from pathlib import PureWindowsPath
+
+import pywintypes
+
+from pyaccesskit._win.processes import (
+    PROCESS_QUERY_LIMITED_INFORMATION,
+    PROCESS_TERMINATE,
+    SYNCHRONIZE,
+    ProcessIdentity,
+    close_handle,
+    identity_matches,
+    is_alive,
+    open_process,
+    query_image,
+    terminate,
+    wait_for_exit,
+)
+from pyaccesskit._win.processes import creation_time as process_creation_time
+
+__all__ = ["Win32Inspector"]
+
+
+class Win32Inspector:
+    """Checks and terminates processes by *identity* (PID + creation time + image name)."""
+
+    def matches(self, pid: int, creation_time: float) -> bool:
+        return identity_matches(ProcessIdentity(pid, creation_time, ""))
+
+    def terminate(self, pid: int, creation_time: float, image_name: str) -> bool:
+        try:
+            handle = open_process(
+                pid, PROCESS_TERMINATE | SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION
+            )
+        except pywintypes.error:
+            return False
+        try:
+            if not is_alive(handle):
+                return True
+            same_process = abs(process_creation_time(handle) - creation_time) < 0.001
+            same_image = PureWindowsPath(query_image(handle)).name.lower() == image_name.lower()
+            if not (same_process and same_image):
+                return False
+            terminate(handle)
+            return wait_for_exit(handle, 10)
+        except (pywintypes.error, OSError):
+            return False
+        finally:
+            close_handle(handle)

pyaccesskit/_win/job.py

@@ -0,0 +1,65 @@
+# pyright: basic
+"""A Windows job object that kills its processes when PyAccessKit's Python process dies.
+
+Once our Access process is assigned to the job, closing the job handle — which Windows does automatically
+when Python exits for *any* reason (crash, ``os._exit``, Task Manager) — terminates it. Verified in spike S1
+for DCOM-launched Access. Assignment is best effort; the ownership ledger covers the rest.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import pywintypes
+import win32job
+
+from pyaccesskit._win.processes import close_handle
+
+__all__ = ["KillOnCloseJob"]
+
+logger = logging.getLogger("pyaccesskit.process")
+
+
+class KillOnCloseJob:
+    """A job object with ``JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE``."""
+
+    def __init__(self) -> None:
+        self._handle: Any = win32job.CreateJobObject(None, "")
+        self._set_kill_on_close(True)
+        self.assigned = False
+
+    def _set_kill_on_close(self, enabled: bool) -> None:
+        info = win32job.QueryInformationJobObject(
+            self._handle, win32job.JobObjectExtendedLimitInformation
+        )
+        flags = info["BasicLimitInformation"]["LimitFlags"]
+        if enabled:
+            flags |= win32job.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+        else:
+            flags &= ~win32job.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+        info["BasicLimitInformation"]["LimitFlags"] = flags
+        win32job.SetInformationJobObject(
+            self._handle, win32job.JobObjectExtendedLimitInformation, info
+        )
+
+    def assign(self, process_handle: Any) -> bool:
+        """Put the process in the job; returns ``False`` (and logs) if Windows refuses."""
+        try:
+            win32job.AssignProcessToJobObject(self._handle, process_handle)
+        except pywintypes.error as exc:
+            logger.warning("could not assign the Access process to a kill-on-close job: %s", exc)
+            return False
+        self.assigned = True
+        return True
+
+    def release(self) -> None:
+        """Stop killing the processes when the job closes (used when handing Access over to the user)."""
+        if self._handle is not None:
+            self._set_kill_on_close(False)
+
+    def close(self) -> None:
+        """Close the job handle (kills remaining processes unless :meth:`release` was called)."""
+        if self._handle is not None:
+            close_handle(self._handle)
+            self._handle = None

pyaccesskit/_win/processes.py

@@ -0,0 +1,159 @@
+# pyright: basic
+"""Win32 process helpers: identity (PID + creation time + image), liveness, termination.
+
+A process is identified by PID **and** creation time: PIDs are recycled by Windows, so a PID alone could
+point at an unrelated process later. While PyAccessKit holds an open handle, the PID cannot be reused.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+from ctypes import wintypes
+from dataclasses import dataclass
+from pathlib import PureWindowsPath
+from typing import Any
+
+import pywintypes
+import win32api
+import win32event
+import win32process
+
+__all__ = [
+    "ProcessIdentity",
+    "access_process_ids",
+    "creation_time",
+    "identity_of",
+    "is_alive",
+    "open_process",
+    "query_image",
+    "wait_for_exit",
+]
+
+SYNCHRONIZE = 0x0010_0000
+PROCESS_TERMINATE = 0x0001
+PROCESS_SET_QUOTA = 0x0100
+PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+OWNED_PROCESS_RIGHTS = (
+    SYNCHRONIZE | PROCESS_TERMINATE | PROCESS_SET_QUOTA | PROCESS_QUERY_LIMITED_INFORMATION
+)
+
+_kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+_QueryFullProcessImageNameW = _kernel32.QueryFullProcessImageNameW
+_QueryFullProcessImageNameW.argtypes = [
+    wintypes.HANDLE,
+    wintypes.DWORD,
+    wintypes.LPWSTR,
+    ctypes.POINTER(wintypes.DWORD),
+]
+_QueryFullProcessImageNameW.restype = wintypes.BOOL
+
+
+@dataclass(frozen=True)
+class ProcessIdentity:
+    """A process pinned down by PID, creation time (seconds since the epoch) and image path."""
+
+    pid: int
+    creation_time: float
+    image: str
+
+    @property
+    def image_name(self) -> str:
+        """The executable file name, e.g. ``MSACCESS.EXE``."""
+        return PureWindowsPath(self.image).name
+
+
+def open_process(pid: int, rights: int = OWNED_PROCESS_RIGHTS) -> Any:
+    """Open a handle to ``pid`` (raises ``pywintypes.error`` if it no longer exists or access is denied)."""
+    return win32api.OpenProcess(rights, False, pid)
+
+
+def query_image(handle: Any) -> str:
+    """Full path of the process image (works with ``PROCESS_QUERY_LIMITED_INFORMATION``)."""
+    size = wintypes.DWORD(1024)
+    buffer = ctypes.create_unicode_buffer(size.value)
+    if not _QueryFullProcessImageNameW(int(handle), 0, buffer, ctypes.byref(size)):
+        raise ctypes.WinError(ctypes.get_last_error())
+    return buffer.value
+
+
+def creation_time(handle: Any) -> float:
+    """Process creation time as a POSIX timestamp."""
+    created = win32process.GetProcessTimes(handle)["CreationTime"]
+    return float(created.timestamp())
+
+
+def identity_of(handle: Any, pid: int) -> ProcessIdentity:
+    """Build the identity of an open process."""
+    return ProcessIdentity(pid, creation_time(handle), query_image(handle))
+
+
+def is_alive(handle: Any) -> bool:
+    """Whether the process behind ``handle`` is still running."""
+    return win32event.WaitForSingleObject(handle, 0) == win32event.WAIT_TIMEOUT
+
+
+def wait_for_exit(handle: Any, timeout: float) -> bool:
+    """Wait up to ``timeout`` seconds for the process to exit; returns whether it exited."""
+    milliseconds = max(0, int(timeout * 1000))
+    return win32event.WaitForSingleObject(handle, milliseconds) == win32event.WAIT_OBJECT_0
+
+
+def current_identity() -> ProcessIdentity:
+    """Identity of the running Python process."""
+    pid = os.getpid()
+    handle = open_process(pid, PROCESS_QUERY_LIMITED_INFORMATION)
+    try:
+        return identity_of(handle, pid)
+    finally:
+        win32api.CloseHandle(handle)
+
+
+def identity_matches(expected: ProcessIdentity) -> bool:
+    """Whether a live process still has exactly this identity (same PID *and* creation time)."""
+    try:
+        # SYNCHRONIZE is required by the liveness check (WaitForSingleObject), not just query rights.
+        handle = open_process(expected.pid, SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION)
+    except pywintypes.error:
+        return False
+    try:
+        if not is_alive(handle):
+            return False
+        return abs(creation_time(handle) - expected.creation_time) < 0.001
+    except (pywintypes.error, OSError):
+        return False
+    finally:
+        win32api.CloseHandle(handle)
+
+
+def access_process_ids() -> set[int]:
+    """PIDs of every running ``MSACCESS.EXE`` visible to this user (used for diagnostics and tests only)."""
+    pids: set[int] = set()
+    for pid in win32process.EnumProcesses():
+        if pid == 0:
+            continue
+        try:
+            handle = open_process(pid, PROCESS_QUERY_LIMITED_INFORMATION)
+        except pywintypes.error:
+            continue
+        try:
+            if PureWindowsPath(query_image(handle)).name.lower() == "msaccess.exe":
+                pids.add(pid)
+        except OSError:
+            pass
+        finally:
+            win32api.CloseHandle(handle)
+    return pids
+
+
+def terminate(handle: Any, exit_code: int = 1) -> None:
+    """Terminate the process behind an **owned** handle."""
+    win32api.TerminateProcess(handle, exit_code)
+
+
+def close_handle(handle: Any) -> None:
+    """Close a Win32 handle, ignoring errors."""
+    try:
+        win32api.CloseHandle(handle)
+    except pywintypes.error:
+        pass