pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/_com/gateway.py

@@ -0,0 +1,199 @@
+# pyright: basic
+"""The COM call gateway: error translation, dialog monitoring and exact-argument invocation.
+
+Every group of COM calls made by a backend runs inside :meth:`Com.op`, which
+
+* tells the dialog watchdog that a call is in flight (so a modal dialog is detected, captured and
+  dismissed instead of hanging forever);
+* translates ``pywintypes.com_error`` into :mod:`pyaccesskit.errors` exceptions with context;
+* raises :class:`~pyaccesskit.errors.AccessDialogError` (or warns) if Access showed a dialog meanwhile.
+
+The ``get``/``put``/``call`` helpers invoke ``IDispatch`` by DISPID with *exactly* the given arguments.
+pywin32's dynamic wrappers cannot call indexed properties such as ``Form.Section(0)``, raise
+``AttributeError`` for members missing from a control's type info, and pad ``Application.Run``'s 30 optional
+arguments (spikes S6 and S8); these helpers avoid all three problems.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import warnings
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Protocol
+
+import pythoncom
+import pywintypes
+
+from pyaccesskit._com import constants as c
+from pyaccesskit._com.dispatch import wrap
+from pyaccesskit._com.errors import OpContext, translate
+from pyaccesskit._com.variants import normalize
+from pyaccesskit.enums import DialogPolicy, ObjectKind
+from pyaccesskit.errors import (
+    AccessDialogError,
+    AccessDialogWarning,
+    AccessTimeoutError,
+    DaoError,
+    DialogInfo,
+)
+
+__all__ = ["CallMonitor", "Com", "call", "get", "invoke", "put", "retry_busy"]
+
+logger = logging.getLogger("pyaccesskit.com")
+
+_LCID = 0
+_BUSY = frozenset({c.RPC_E_CALL_REJECTED, c.RPC_E_SERVERCALL_RETRYLATER})
+
+
+class CallMonitor(Protocol):
+    """Implemented by the dialog watchdog of an Access process."""
+
+    policy: DialogPolicy
+
+    def begin(self, description: str) -> None:
+        """An outermost COM operation starts."""
+        ...
+
+    def end(self) -> tuple[DialogInfo, ...]:
+        """The operation ended; return the dialogs observed while it ran."""
+        ...
+
+    @property
+    def termination(self) -> tuple[str, str] | None:
+        """``(kind, reason)`` if the monitor terminated Access (kind: timeout, dialog, interrupt)."""
+        ...
+
+
+# --------------------------------------------------------------------------------------- invocation
+def invoke(obj: Any, name: str, flags: int, *args: Any) -> Any:
+    """``IDispatch::Invoke`` ``name`` on ``obj`` with exactly ``args``; wraps/normalizes the result."""
+    ole = obj._oleobj_ if hasattr(obj, "_oleobj_") else obj
+    dispid = ole.GetIDsOfNames(name)
+    result = ole.Invoke(dispid, _LCID, flags, True, *args)
+    return normalize(wrap(result))
+
+
+def get(obj: Any, name: str, *args: Any) -> Any:
+    """Read a (possibly indexed) property: ``get(form, "Section", 0)``."""
+    return invoke(obj, name, pythoncom.DISPATCH_PROPERTYGET | pythoncom.DISPATCH_METHOD, *args)
+
+
+def call(obj: Any, name: str, *args: Any) -> Any:
+    """Call a method with exactly ``args`` (no padding of optional parameters)."""
+    return invoke(obj, name, pythoncom.DISPATCH_METHOD, *args)
+
+
+def put(obj: Any, name: str, value: Any) -> None:
+    """Set a property."""
+    ole = obj._oleobj_ if hasattr(obj, "_oleobj_") else obj
+    dispid = ole.GetIDsOfNames(name)
+    ole.Invoke(dispid, _LCID, pythoncom.DISPATCH_PROPERTYPUT, False, value)
+
+
+def retry_busy(fn: Callable[..., Any], *args: Any, timeout: float = 30.0) -> Any:
+    """Call ``fn`` and retry while the server rejects calls because it is busy (``RPC_E_CALL_REJECTED``).
+
+    A rejected call never started executing, so retrying is always safe.
+    """
+    deadline = time.monotonic() + timeout
+    delay = 0.05
+    while True:
+        try:
+            return fn(*args)
+        except pywintypes.com_error as exc:
+            if exc.args[0] not in _BUSY or time.monotonic() >= deadline:
+                raise
+            logger.debug("COM server busy; retrying in %.2fs", delay)
+            time.sleep(delay)
+            delay = min(delay * 2, 1.0)
+
+
+# ------------------------------------------------------------------------------------------ gateway
+class Com:
+    """Per-engine gateway: wraps operations with error translation and dialog monitoring."""
+
+    def __init__(
+        self,
+        *,
+        monitor: CallMonitor | None = None,
+        dao_errors: Callable[[], Sequence[DaoError]] | None = None,
+    ) -> None:
+        self._monitor = monitor
+        self._dao_errors = dao_errors
+        self._depth = 0
+
+    def _read_dao_errors(self) -> Sequence[DaoError]:
+        if self._dao_errors is None:
+            return ()
+        try:
+            return self._dao_errors()
+        except Exception:
+            return ()
+
+    @contextmanager
+    def op(
+        self,
+        action: str,
+        *,
+        kind: ObjectKind | None = None,
+        name: str | None = None,
+        path: Path | None = None,
+        sql: str | None = None,
+    ) -> Iterator[None]:
+        """Run a group of COM calls as one operation (see module docstring)."""
+        ctx = OpContext(action, kind, name, path, sql)
+        monitor = self._monitor
+        outermost = self._depth == 0
+        self._depth += 1
+        if monitor is not None and outermost:
+            monitor.begin(action)
+        ended = False
+
+        def finish() -> tuple[DialogInfo, ...]:
+            nonlocal ended
+            if ended or monitor is None or not outermost:
+                return ()
+            ended = True
+            return monitor.end()
+
+        try:
+            logger.debug("COM op: %s", action)
+            yield
+        except pywintypes.com_error as exc:
+            dialogs = finish()
+            error = translate(exc, ctx, self._read_dao_errors())
+            termination = monitor.termination if monitor is not None else None
+            if termination is not None and termination[0] == "timeout":
+                raise AccessTimeoutError(
+                    f"cannot {action}: {termination[1]}; the owned Access process was terminated",
+                    operation=action,
+                    details=error.details,
+                ) from error
+            if dialogs:
+                raise AccessDialogError(
+                    f"cannot {action}: Microsoft Access showed a dialog",
+                    dialogs=dialogs,
+                    operation=action,
+                ) from error
+            raise error from exc
+        except BaseException:
+            finish()
+            raise
+        finally:
+            self._depth -= 1
+        dialogs = finish()
+        if dialogs and monitor is not None:
+            if monitor.policy is DialogPolicy.FAIL:
+                raise AccessDialogError(
+                    f"{action}: Microsoft Access showed a dialog that was dismissed automatically",
+                    dialogs=dialogs,
+                    operation=action,
+                )
+            if monitor.policy is DialogPolicy.WARN:
+                for dialog in dialogs:
+                    warnings.warn(
+                        f"{action}: {dialog.summary()}", AccessDialogWarning, stacklevel=3
+                    )

pyaccesskit/_com/raw.py

@@ -0,0 +1,164 @@
+# pyright: basic
+"""Revocable proxies for the ``db.raw`` escape hatch.
+
+Raw COM objects handed to user code are wrapped so that closing (or upgrading) the session can *revoke*
+them: every proxy — including the ones derived from it (``db.raw.dao.TableDefs(0).Fields``...) — drops its
+COM reference and raises :class:`~pyaccesskit.errors.SessionClosedError` afterwards. User variables can
+therefore never keep an Access process alive or be used against a closed database.
+"""
+
+from __future__ import annotations
+
+import threading
+import weakref
+from collections.abc import Iterator
+from typing import Any
+
+from pyaccesskit.errors import SessionClosedError
+
+__all__ = ["ProxyRegistry", "RevocableIterator", "RevocableProxy"]
+
+_SLOTS = ("_pak_target", "_pak_registry", "_pak_label", "__weakref__")
+
+
+class ProxyRegistry:
+    """Tracks every proxy created for a session so they can all be revoked at once."""
+
+    def __init__(self) -> None:
+        self._proxies: weakref.WeakSet[RevocableProxy | RevocableIterator] = weakref.WeakSet()
+        self._lock = threading.Lock()
+        self.revoked = False
+
+    def track(self, proxy: RevocableProxy | RevocableIterator) -> None:
+        with self._lock:
+            self._proxies.add(proxy)
+
+    def revoke_all(self) -> int:
+        """Revoke every live proxy; returns how many were revoked."""
+        with self._lock:
+            proxies = list(self._proxies)
+            self._proxies.clear()
+            self.revoked = True
+        for proxy in proxies:
+            object.__setattr__(
+                proxy, "_pak_target", None
+            )  # iterators drop their COM enumerator too
+        return len(proxies)
+
+    def wrap(self, value: Any, label: str) -> Any:
+        """Wrap COM objects and bound COM methods; return plain values unchanged."""
+        if value is None or isinstance(value, (str, bytes, int, float, bool, tuple, list, dict)):
+            return value
+        if hasattr(value, "_oleobj_") or callable(value):
+            proxy = RevocableProxy(value, self, label)
+            self.track(proxy)
+            return proxy
+        return value
+
+
+def _unwrap(value: Any) -> Any:
+    if isinstance(value, RevocableProxy):
+        return value._pak_require()
+    if isinstance(value, (list, tuple)):
+        return type(value)(_unwrap(item) for item in value)
+    return value
+
+
+class RevocableProxy:
+    """A transparent, revocable stand-in for a COM object (or one of its methods)."""
+
+    __slots__ = _SLOTS
+
+    def __init__(self, target: Any, registry: ProxyRegistry, label: str) -> None:
+        object.__setattr__(self, "_pak_target", target)
+        object.__setattr__(self, "_pak_registry", registry)
+        object.__setattr__(self, "_pak_label", label)
+
+    def _pak_require(self) -> Any:
+        target = object.__getattribute__(self, "_pak_target")
+        if target is None:
+            label = object.__getattribute__(self, "_pak_label")
+            raise SessionClosedError(
+                f"raw COM object {label} was revoked because its PyAccessKit session was closed or upgraded"
+            )
+        return target
+
+    def __getattr__(self, name: str) -> Any:
+        target = self._pak_require()
+        label = object.__getattribute__(self, "_pak_label")
+        registry: ProxyRegistry = object.__getattribute__(self, "_pak_registry")
+        return registry.wrap(getattr(target, name), f"{label}.{name}")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        setattr(self._pak_require(), name, _unwrap(value))
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        target = self._pak_require()
+        label = object.__getattribute__(self, "_pak_label")
+        registry: ProxyRegistry = object.__getattribute__(self, "_pak_registry")
+        result = target(*_unwrap(args), **{k: _unwrap(v) for k, v in kwargs.items()})
+        return registry.wrap(result, f"{label}(...)")
+
+    def __iter__(self) -> Iterator[Any]:
+        target = self._pak_require()
+        label = object.__getattribute__(self, "_pak_label")
+        registry: ProxyRegistry = object.__getattribute__(self, "_pak_registry")
+        iterator = RevocableIterator(iter(target), registry, label)
+        registry.track(iterator)
+        return iterator
+
+    def __getitem__(self, key: Any) -> Any:
+        target = self._pak_require()
+        label = object.__getattribute__(self, "_pak_label")
+        registry: ProxyRegistry = object.__getattribute__(self, "_pak_registry")
+        return registry.wrap(target[_unwrap(key)], f"{label}[{key!r}]")
+
+    def __len__(self) -> int:
+        return len(self._pak_require())
+
+    def __bool__(self) -> bool:
+        return object.__getattribute__(self, "_pak_target") is not None
+
+    @property
+    def revoked(self) -> bool:
+        """Whether the underlying COM object has been released."""
+        return object.__getattribute__(self, "_pak_target") is None
+
+    def __repr__(self) -> str:
+        label = object.__getattribute__(self, "_pak_label")
+        state = "revoked" if self.revoked else "live"
+        return f"<pyaccesskit raw {label} ({state})>"
+
+
+class RevocableIterator:
+    """Iterates a raw COM collection; revoking it drops the enumerator, so resuming raises."""
+
+    __slots__ = ("_pak_index", *_SLOTS)
+
+    def __init__(self, target: Iterator[Any], registry: ProxyRegistry, label: str) -> None:
+        object.__setattr__(self, "_pak_target", target)
+        object.__setattr__(self, "_pak_registry", registry)
+        object.__setattr__(self, "_pak_label", label)
+        object.__setattr__(self, "_pak_index", 0)
+
+    def __iter__(self) -> RevocableIterator:
+        return self
+
+    def __next__(self) -> Any:
+        target = object.__getattribute__(self, "_pak_target")
+        label = object.__getattribute__(self, "_pak_label")
+        if target is None:
+            raise SessionClosedError(
+                f"iteration over raw COM object {label} was revoked because its PyAccessKit session was "
+                "closed or upgraded"
+            )
+        item = next(target)
+        index = object.__getattribute__(self, "_pak_index")
+        object.__setattr__(self, "_pak_index", index + 1)
+        registry: ProxyRegistry = object.__getattribute__(self, "_pak_registry")
+        return registry.wrap(item, f"{label}[{index}]")
+
+    @property
+    def revoked(self) -> bool:
+        """Whether the underlying enumerator has been released."""
+        return object.__getattribute__(self, "_pak_target") is None

pyaccesskit/_com/runtime.py

@@ -0,0 +1,39 @@
+# pyright: basic
+"""pywin32 availability and per-thread COM initialisation.
+
+This package (``pyaccesskit._com``) is the only place, together with ``_win``, ``_engines`` and the COM
+backends, that imports pywin32. It is imported lazily when a real engine is created, so
+``import pyaccesskit`` works on any platform.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+
+import pythoncom
+
+logger = logging.getLogger("pyaccesskit.com")
+
+__all__ = ["ensure_com_initialized"]
+
+_RPC_E_CHANGED_MODE = -2147417850  # 0x80010106
+_state = threading.local()
+
+
+def ensure_com_initialized() -> None:
+    """Initialise COM (single-threaded apartment) on the calling thread, once.
+
+    ``import pythoncom`` already initialises the importing thread; worker threads need this call. COM is
+    never uninitialised by PyAccessKit (other code on the thread may still hold COM objects). If the thread
+    was initialised as MTA by someone else, calls still work through COM marshalling.
+    """
+    if getattr(_state, "initialized", False):
+        return
+    try:
+        pythoncom.CoInitializeEx(pythoncom.COINIT_APARTMENTTHREADED)
+    except pythoncom.com_error as exc:
+        if exc.args[0] != _RPC_E_CHANGED_MODE:
+            raise
+        logger.debug("thread %s is already a multithreaded COM apartment", threading.get_ident())
+    _state.initialized = True

pyaccesskit/_com/variants.py

@@ -0,0 +1,72 @@
+# pyright: basic
+"""Conversion of values between Python and COM VARIANTs.
+
+Access date/times are *wall-clock* values without a time zone. pywin32, however, treats a naive ``datetime``
+as local time and converts it to UTC when it builds a ``VT_DATE`` — shifting the stored value by the UTC
+offset (an integration test caught a 13-hour shift). :func:`to_variant` therefore passes wall-clock values
+as UTC-tagged datetimes, which pywin32 stores unchanged; :func:`normalize` reads the wall-clock back.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, date, datetime, time
+from typing import Any
+
+import pywintypes
+
+__all__ = ["normalize", "to_variant"]
+
+_OLE_EPOCH = date(1899, 12, 30)
+
+
+def to_variant(value: Any) -> Any:
+    """Prepare a Python value for COM without time-zone shifts.
+
+    * naive ``datetime`` → the same wall-clock time, tagged UTC;
+    * aware ``datetime`` → converted to local wall-clock time first (Access has no time zones);
+    * ``date`` → midnight; ``time`` → a time on the OLE epoch day (how Access stores times of day).
+    """
+    if isinstance(value, (bytearray, memoryview)):
+        return bytes(value)
+    if isinstance(value, datetime):
+        if value.tzinfo is not None:
+            value = value.astimezone().replace(tzinfo=None)
+        return value.replace(tzinfo=UTC)
+    if isinstance(value, date):
+        return datetime(value.year, value.month, value.day, tzinfo=UTC)
+    if isinstance(value, time):
+        return datetime(
+            _OLE_EPOCH.year,
+            _OLE_EPOCH.month,
+            _OLE_EPOCH.day,
+            value.hour,
+            value.minute,
+            value.second,
+            tzinfo=UTC,
+        )
+    return value
+
+
+def normalize(value: Any) -> Any:
+    """Convert pywin32 return values to plain Python values.
+
+    * ``pywintypes.datetime`` (VT_DATE) → naive :class:`datetime` with the stored wall-clock time;
+    * byte arrays (OLE Object / binary fields arrive as ``memoryview``) → :class:`bytes`;
+    * tuples (SAFEARRAYs) are normalised recursively;
+    * everything else (``Decimal`` for currency/decimal, ``None`` for Null/Empty...) is returned unchanged.
+    """
+    if isinstance(value, memoryview):
+        return value.tobytes()
+    if isinstance(value, pywintypes.TimeType):
+        return datetime(
+            value.year,
+            value.month,
+            value.day,
+            value.hour,
+            value.minute,
+            value.second,
+            value.microsecond,
+        )
+    if isinstance(value, tuple):
+        return tuple(normalize(item) for item in value)
+    return value

pyaccesskit/_engines/__init__.py

@@ -0,0 +1,48 @@
+# pyright: basic
+"""Engine construction (COM). Imported lazily by :mod:`pyaccesskit._session`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyaccesskit._session.protocols import EnginePlan
+
+__all__ = ["open_engine"]
+
+
+def open_engine(plan: EnginePlan) -> Any:
+    """Create the engine described by ``plan`` (see :class:`EnginePlan`)."""
+    if plan.kind == "dao":
+        from pyaccesskit._engines.inproc import InProcDaoEngine
+
+        return InProcDaoEngine(
+            plan.path,
+            create=plan.create,
+            readonly=plan.readonly,
+            exclusive=plan.exclusive,
+            password=plan.password,
+            native_defaults=plan.options.apply_native_defaults,
+            on_created=plan.on_created,
+        )
+    from pyaccesskit._engines.access import AccessEngine
+    from pyaccesskit._win.access_process import AccessLaunchOptions
+
+    options = plan.options
+    return AccessEngine(
+        plan.path,
+        create=plan.create,
+        readonly=plan.readonly,
+        exclusive=plan.exclusive,
+        password=plan.password,
+        design=plan.design,
+        on_created=plan.on_created,
+        options=AccessLaunchOptions(
+            progid=options.access_progid,
+            visible=options.visible,
+            macro_security=options.macro_security,
+            dialog_policy=options.dialog_policy,
+            call_timeout=options.call_timeout,
+            quit_timeout=options.quit_timeout,
+            kill_on_parent_exit=options.kill_on_parent_exit,
+        ),
+    )