pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/_engines/access.py

@@ -0,0 +1,300 @@
+# pyright: basic
+"""Engine: Microsoft Access automation (works with any Python/Office bitness combination).
+
+Schema work uses **Access-hosted DAO** (``app.DBEngine.OpenDatabase``): the database is *not* opened in the
+Access UI, so AutoExec macros and startup forms never run. The first design feature (forms, modules, text
+import/export, Decimal DDL) upgrades the engine to a **design session** (``OpenCurrentDatabase``).
+New databases are created with ``NewCurrentDatabase`` and start in design mode (native Access defaults).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Literal
+
+import pywintypes
+
+from pyaccesskit._backends.access.design import AccessDesignBackend
+from pyaccesskit._backends.dao.schema import DaoSchemaBackend
+from pyaccesskit._backends.protocols import DesignBackend, SchemaBackend
+from pyaccesskit._com import constants as c
+from pyaccesskit._com.errors import OpContext, details_from, translate
+from pyaccesskit._com.gateway import call, get, put
+from pyaccesskit._win.access_process import AccessLaunchOptions, AccessProcess
+from pyaccesskit.enums import Transport
+from pyaccesskit.errors import AccessRuntimeOnlyError, CapabilityError, DatabaseLockedError
+
+__all__ = ["AccessEngine"]
+
+_STARTUP_FORM = "StartUpForm"
+_PROPERTY_NOT_FOUND = 3270
+_DB_TEXT = int(c.DataTypeEnum.dbText)
+
+
+def _same_path(left: str, right: Path) -> bool:
+    return os.path.normcase(str(Path(left).resolve())) == os.path.normcase(str(right.resolve()))
+
+
+class AccessEngine:
+    """Owns one Access process and the database opened in it."""
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        create: bool,
+        readonly: bool,
+        exclusive: bool,
+        password: str | None,
+        design: bool,
+        options: AccessLaunchOptions,
+        on_created: Callable[[], None] | None = None,
+    ) -> None:
+        self._path = path
+        self._readonly = readonly
+        self._exclusive = exclusive
+        self._password = password
+        self._mode: Literal["hosted", "design"] = "hosted"
+        self._db: Any = None
+        self._design: AccessDesignBackend | None = None
+        self._on_created = on_created
+        self._process = AccessProcess.launch(options, database=str(path))
+        try:
+            if create:
+                self._new_current()
+            elif design and not readonly:
+                self._open_current()
+            else:
+                self._open_hosted()
+        except BaseException:
+            self._process.shutdown()
+            raise
+        self._schema = DaoSchemaBackend(
+            com=self._process.com,
+            database=lambda: self._db,
+            path=path,
+            transport=lambda: self.transport,
+            run_ddl=self._run_ddl,
+        )
+
+    @property
+    def _app(self) -> Any:
+        return self._process.app
+
+    @property
+    def transport(self) -> Transport:
+        return Transport.ACCESS_DESIGN if self._mode == "design" else Transport.ACCESS_HOSTED
+
+    @property
+    def supports_design(self) -> bool:
+        return not self._readonly and not self._process.is_runtime
+
+    @property
+    def pid(self) -> int | None:
+        return self._process.pid
+
+    # ------------------------------------------------------------------------------ open / create
+    def _connect(self) -> str:
+        return f";PWD={self._password}" if self._password else ""
+
+    def _open_hosted(self) -> None:
+        with self._process.com.op(f"open database {self._path}", path=self._path):
+            dbengine = get(self._app, "DBEngine")
+            self._db = call(
+                dbengine,
+                "OpenDatabase",
+                str(self._path),
+                self._exclusive,
+                self._readonly,
+                self._connect(),
+            )
+        self._mode = "hosted"
+
+    def _new_current(self) -> None:
+        with self._process.com.op(f"create database {self._path}", path=self._path):
+            call(
+                self._app,
+                "NewCurrentDatabase",
+                str(self._path),
+                int(c.AcNewDatabaseFormat.acNewDatabaseFormatAccess2007),
+            )
+        self._verify_current()  # confirms Access created *this* file and it is now its current database
+        if self._on_created is not None:
+            self._on_created()
+
+    def _open_current(self) -> None:
+        """Open the database for design without running its startup form (ADR 0002).
+
+        ``macro_security`` stops VBA and ``AutoExec``, but Access still opens the ``StartUpForm``; with code
+        disabled that form can raise dialogs. The property is set aside through DAO (which runs nothing)
+        and restored as soon as the database is open.
+        """
+        startup_form = self._suspend_startup_form()
+        try:
+            with self._process.com.op(f"open database {self._path} in Access", path=self._path):
+                call(
+                    self._app,
+                    "OpenCurrentDatabase",
+                    str(self._path),
+                    self._exclusive,
+                    self._password or "",
+                )
+            self._verify_current()
+        except BaseException as exc:
+            if startup_form is not None:
+                try:
+                    self._restore_startup_form(startup_form)
+                except Exception as restore_error:  # reported on the original error
+                    exc.add_note(
+                        f"PyAccessKit could not restore StartUpForm={startup_form!r} ({restore_error}); "
+                        "set it again in Access (File > Options > Current Database > Display Form)"
+                    )
+            raise
+        if startup_form is not None:
+            self._restore_startup_form(startup_form)
+
+    def _startup_property(self, db: Any) -> Any:
+        try:
+            return get(get(db, "Properties"), "Item", _STARTUP_FORM)
+        except pywintypes.com_error as exc:
+            if details_from(exc).number == _PROPERTY_NOT_FOUND:
+                return None
+            raise
+
+    def _suspend_startup_form(self) -> str | None:
+        with self._process.com.op(f"read startup settings of {self._path}", path=self._path):
+            db = call(
+                get(self._app, "DBEngine"),
+                "OpenDatabase",
+                str(self._path),
+                self._exclusive,
+                False,
+                self._connect(),
+            )
+            try:
+                prop = self._startup_property(db)
+                value = str(get(prop, "Value") or "") if prop is not None else ""
+                if value:
+                    call(get(db, "Properties"), "Delete", _STARTUP_FORM)
+                del prop
+            finally:
+                call(db, "Close")
+        return value or None
+
+    def _restore_startup_form(self, value: str) -> None:
+        with self._process.com.op(f"restore startup settings of {self._path}", path=self._path):
+            reopened = self._db is None  # opening failed: restore through DAO instead of CurrentDb
+            db = self._db or call(
+                get(self._app, "DBEngine"),
+                "OpenDatabase",
+                str(self._path),
+                self._exclusive,
+                False,
+                self._connect(),
+            )
+            try:
+                prop = self._startup_property(db)
+                if prop is not None:
+                    put(prop, "Value", value)
+                else:
+                    new = call(db, "CreateProperty", _STARTUP_FORM, _DB_TEXT, value)
+                    call(get(db, "Properties"), "Append", new)
+            finally:
+                if reopened:
+                    call(db, "Close")
+
+    def _verify_current(self) -> None:
+        """``OpenCurrentDatabase`` can fail *silently* (ADR 0001, S9b): check, and explain failures."""
+        with self._process.com.op(f"open database {self._path} in Access", path=self._path):
+            full_name = str(get(get(self._app, "CurrentProject"), "FullName") or "")
+            db = call(self._app, "CurrentDb") if full_name else None
+        if full_name and db is not None and _same_path(full_name, self._path):
+            self._db = db
+            self._mode = "design"
+            self._process.database_opened()
+            return
+        # Ask DAO why Access refused: it reports locked / unrecognized format / missing precisely.
+        try:
+            probe = call(
+                get(self._app, "DBEngine"),
+                "OpenDatabase",
+                str(self._path),
+                False,
+                True,
+                self._connect(),
+            )
+        except pywintypes.com_error as exc:
+            raise translate(
+                exc, OpContext(f"open database {self._path} in Access", path=self._path)
+            ) from exc
+        with contextlib.suppress(pywintypes.com_error):
+            call(probe, "Close")
+        raise DatabaseLockedError(
+            f"Microsoft Access could not open {self._path} as its current database (it may be open "
+            "exclusively in another Access instance)",
+            path=self._path,
+        )
+
+    def upgrade(self) -> None:
+        """Switch from Access-hosted DAO to a design session (``OpenCurrentDatabase``)."""
+        if self._mode == "design":
+            return
+        if self._readonly:
+            raise CapabilityError(
+                "read-only sessions cannot use design features (forms, modules, DDL)"
+            )
+        if self._process.is_runtime:
+            raise AccessRuntimeOnlyError(
+                "only the Access Runtime is installed; design features need full Microsoft Access",
+                diagnosis="Install Microsoft Access (not the Runtime) to build forms, reports and modules.",
+            )
+        with self._process.com.op(f"release database {self._path}", path=self._path):
+            call(self._db, "Close")
+        self._db = None
+        self._open_current()
+
+    def _run_ddl(self, sql: str) -> None:
+        self.upgrade()
+        with self._process.com.op("run DDL", sql=sql, path=self._path):
+            connection = get(get(self._app, "CurrentProject"), "Connection")
+            call(connection, "Execute", sql)
+
+    # ------------------------------------------------------------------------------------ engine
+    def schema(self) -> SchemaBackend:
+        return self._schema
+
+    def design(self) -> DesignBackend:
+        self.upgrade()
+        if self._design is None:
+            self._design = AccessDesignBackend(
+                com=lambda: self._process.com, app=lambda: self._process.app
+            )
+        return self._design
+
+    def raw(self, which: str) -> Any:
+        if which == "dao":
+            return self._db
+        if which == "dbengine":
+            return get(self._app, "DBEngine")
+        self.upgrade()
+        return self._app
+
+    def close(self) -> list[BaseException]:
+        errors: list[BaseException] = []
+        if self._design is not None:
+            self._design.cleanup()
+            self._design = None
+        if self._db is not None and self._mode == "hosted":
+            try:
+                call(self._db, "Close")
+            except pywintypes.com_error as exc:
+                errors.append(exc)
+        self._db = None
+        errors.extend(self._process.shutdown())
+        return errors
+
+    def terminate(self) -> None:
+        self._process.terminate("the PyAccessKit session was abandoned")

pyaccesskit/_engines/inproc.py

@@ -0,0 +1,148 @@
+# pyright: basic
+"""Engine: DAO loaded into the Python process (fastest; needs Python bitness = Office/ACE bitness)."""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import pywintypes
+
+from pyaccesskit._backends.dao.profile import apply_native_defaults
+from pyaccesskit._backends.dao.schema import DaoSchemaBackend
+from pyaccesskit._backends.protocols import DesignBackend, SchemaBackend
+from pyaccesskit._com import constants as c
+from pyaccesskit._com.dispatch import create_inproc
+from pyaccesskit._com.gateway import Com
+from pyaccesskit._engines.probe import DAO_PROGID, inproc_dao
+from pyaccesskit._win.access_process import read_dao_errors
+from pyaccesskit.enums import Transport
+from pyaccesskit.errors import CapabilityError, DaoNotAvailableError
+
+__all__ = ["InProcDaoEngine"]
+
+_ACE_PROVIDERS = ("Microsoft.ACE.OLEDB.16.0", "Microsoft.ACE.OLEDB.12.0")
+
+
+class InProcDaoEngine:
+    """Owns an in-process ``DBEngine`` and one open ``Database``."""
+
+    transport = Transport.DAO_INPROC
+    supports_design = False
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        create: bool,
+        readonly: bool,
+        exclusive: bool,
+        password: str | None,
+        native_defaults: bool = True,
+        on_created: Callable[[], None] | None = None,
+    ) -> None:
+        self._path = path
+        self._readonly = readonly
+        self._exclusive = exclusive
+        self._password = password
+        try:
+            self._dbengine: Any = create_inproc(DAO_PROGID)
+        except pywintypes.com_error as exc:
+            raise DaoNotAvailableError(
+                "in-process DAO is not available in this Python process",
+                diagnosis=inproc_dao().reason or str(exc),
+            ) from exc
+        self._com = Com(dao_errors=lambda: read_dao_errors(self._dbengine))
+        self._db: Any = None
+        verb = "create" if create else "open"
+        with self._com.op(f"{verb} database {path}", path=path):
+            if create:
+                locale = c.dbLangGeneral + (f";pwd={password}" if password else "")
+                # CreateDatabase fails if the file exists, so a returned database is ours.
+                self._db = self._dbengine.CreateDatabase(
+                    str(path), locale, int(c.DatabaseTypeEnum.dbVersion120)
+                )
+                if on_created is not None:
+                    on_created()
+                if native_defaults:
+                    try:
+                        apply_native_defaults(self._db)
+                    except BaseException:
+                        self.close()  # release the file so the session can delete it
+                        raise
+            else:
+                self._db = self._open()
+        self._schema = DaoSchemaBackend(
+            com=self._com,
+            database=lambda: self._db,
+            path=path,
+            transport=lambda: Transport.DAO_INPROC,
+            run_ddl=self._run_ddl,
+        )
+
+    def _open(self) -> Any:
+        connect = f";PWD={self._password}" if self._password else ""
+        return self._dbengine.OpenDatabase(
+            str(self._path), self._exclusive, self._readonly, connect
+        )
+
+    def _run_ddl(self, sql: str) -> None:
+        """Run ANSI-92 DDL (e.g. DECIMAL(p,s)) with ADO; DAO must release its exclusive handle meanwhile."""
+        with self._com.op("run DDL", sql=sql, path=self._path):
+            self._db.Close()
+            self._db = None
+            try:
+                last_error: Exception | None = None
+                for provider in _ACE_PROVIDERS:
+                    connection = create_inproc("ADODB.Connection")
+                    extra = (
+                        f"Jet OLEDB:Database Password={self._password};" if self._password else ""
+                    )
+                    try:
+                        connection.Open(f"Provider={provider};Data Source={self._path};{extra}")
+                    except pywintypes.com_error as exc:
+                        last_error = exc
+                        continue
+                    try:
+                        connection.Execute(sql)
+                    finally:
+                        with contextlib.suppress(pywintypes.com_error):
+                            connection.Close()
+                    return
+                assert last_error is not None
+                raise last_error
+            finally:
+                self._db = self._open()
+
+    # ------------------------------------------------------------------------------------ engine
+    def schema(self) -> SchemaBackend:
+        return self._schema
+
+    def design(self) -> DesignBackend:
+        raise CapabilityError(
+            "forms, reports, modules and text import/export need Microsoft Access; open the database with "
+            "engine='access' (or engine='auto') instead of engine='dao'"
+        )
+
+    def raw(self, which: str) -> Any:
+        if which == "dao":
+            return self._db
+        if which == "dbengine":
+            return self._dbengine
+        raise CapabilityError("this session uses in-process DAO; there is no Access.Application")
+
+    def close(self) -> list[BaseException]:
+        errors: list[BaseException] = []
+        if self._db is not None:
+            try:
+                self._db.Close()
+            except pywintypes.com_error as exc:
+                errors.append(exc)
+            self._db = None
+        self._dbengine = None
+        return errors
+
+    def terminate(self) -> None:
+        """Nothing to terminate: in-process DAO has no separate process."""

pyaccesskit/_engines/probe.py

@@ -0,0 +1,231 @@
+# pyright: basic
+"""Environment probing: which engines can this Python process use, and why not?
+
+Registry checks use the standard library (``winreg``); the in-process DAO check actually loads
+``DAO.DBEngine.120`` (cheap, no process is started). Results are cached per process.
+"""
+
+from __future__ import annotations
+
+import functools
+import os
+import struct
+import winreg
+from dataclasses import dataclass
+
+import pywintypes
+
+from pyaccesskit._com.dispatch import create_inproc
+
+__all__ = [
+    "ACE_OLEDB_PROGIDS",
+    "DAO_PROGID",
+    "AccessFacts",
+    "ClickToRunFacts",
+    "ProbeResult",
+    "access_facts",
+    "access_registered",
+    "click_to_run",
+    "dao_registration",
+    "file_version",
+    "inproc_dao",
+    "inproc_registration",
+    "pe_bits",
+    "python_bits",
+]
+
+DAO_PROGID = "DAO.DBEngine.120"
+ACE_OLEDB_PROGIDS = ("Microsoft.ACE.OLEDB.16.0", "Microsoft.ACE.OLEDB.12.0")
+_APP_PATHS = r"SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\MSACCESS.EXE"
+_C2R_CONFIGURATION = r"SOFTWARE\Microsoft\Office\ClickToRun\Configuration"
+_PE_MACHINE_BITS = {0x014C: 32, 0x8664: 64, 0xAA64: 64}
+
+
+@dataclass(frozen=True)
+class ProbeResult:
+    """Whether something is usable, with a human explanation when it is not."""
+
+    available: bool
+    reason: str = ""
+
+
+def python_bits() -> int:
+    """Bitness of this Python interpreter (32 or 64)."""
+    return struct.calcsize("P") * 8
+
+
+def _clsid(progid: str) -> str | None:
+    try:
+        with winreg.OpenKey(winreg.HKEY_CLASSES_ROOT, rf"{progid}\CLSID") as key:
+            return str(winreg.QueryValueEx(key, "")[0])
+    except OSError:
+        return None
+
+
+def _inproc_server(clsid: str, view: int) -> str | None:
+    try:
+        with winreg.OpenKey(
+            winreg.HKEY_CLASSES_ROOT, rf"CLSID\{clsid}\InprocServer32", 0, winreg.KEY_READ | view
+        ) as key:
+            value = str(winreg.QueryValueEx(key, "")[0])
+            return value or None
+    except OSError:
+        return None
+
+
+def inproc_registration(progid: str) -> dict[int, str | None]:
+    """In-process server path registered for ``progid``, for 32- and 64-bit processes."""
+    clsid = _clsid(progid)
+    if clsid is None:
+        return {32: None, 64: None}
+    return {
+        32: _inproc_server(clsid, winreg.KEY_WOW64_32KEY),
+        64: _inproc_server(clsid, winreg.KEY_WOW64_64KEY),
+    }
+
+
+def dao_registration() -> dict[int, str | None]:
+    """Native in-process DAO server path registered for 32- and 64-bit processes."""
+    return inproc_registration(DAO_PROGID)
+
+
+def access_registered(progid: str = "Access.Application") -> bool:
+    """Whether ``Access.Application`` (or the given ProgID) is registered."""
+    return _clsid(progid) is not None
+
+
+@functools.cache
+def inproc_dao() -> ProbeResult:
+    """Whether this Python process can load DAO in-process (cached)."""
+    try:
+        engine = create_inproc(DAO_PROGID)
+    except pywintypes.com_error:
+        registered = dao_registration()
+        bits = python_bits()
+        other = 64 if bits == 32 else 32
+        if registered[bits]:
+            reason = f"DAO is registered for {bits}-bit processes but could not be loaded"
+        elif registered[other]:
+            reason = (
+                f"DAO (Access database engine) is installed for {other}-bit programs only, but this Python is "
+                f"{bits}-bit. Use a {other}-bit Python for in-process DAO, or engine='access'."
+            )
+        else:
+            reason = "the Access database engine (DAO.DBEngine.120) is not installed"
+        return ProbeResult(False, reason)
+    del engine
+    return ProbeResult(True)
+
+
+# ------------------------------------------------------------------------------ installation facts
+@dataclass(frozen=True)
+class AccessFacts:
+    """What the registry says about Microsoft Access (nothing is started)."""
+
+    progid: str
+    registered: bool
+    current_version: str | None
+    executable: str | None
+    version: str | None
+    bits: int | None
+
+
+@dataclass(frozen=True)
+class ClickToRunFacts:
+    """Microsoft 365 / Click-to-Run installation details."""
+
+    platform: str | None
+    version: str | None
+    products: tuple[str, ...]
+
+
+def _read_value(root: int, path: str, name: str, view: int) -> str | None:
+    try:
+        with winreg.OpenKey(root, path, 0, winreg.KEY_READ | view) as key:
+            value = winreg.QueryValueEx(key, name)[0]
+    except OSError:
+        return None
+    return str(value) if value not in (None, "") else None
+
+
+def _executable_from_command(command: str) -> str | None:
+    command = command.strip()
+    if command.startswith('"'):
+        end = command.find('"', 1)
+        return command[1:end] if end > 1 else None
+    lowered = command.lower()
+    end = lowered.find(".exe")
+    return command[: end + 4] if end >= 0 else command or None
+
+
+def _local_server(clsid: str) -> str | None:
+    for view in (winreg.KEY_WOW64_64KEY, winreg.KEY_WOW64_32KEY):
+        command = _read_value(winreg.HKEY_CLASSES_ROOT, rf"CLSID\{clsid}\LocalServer32", "", view)
+        if command:
+            return _executable_from_command(command)
+    return None
+
+
+def pe_bits(path: str) -> int | None:
+    """Bitness of a Windows executable, read from its PE header (``None`` if unreadable)."""
+    try:
+        with open(path, "rb") as handle:  # noqa: PTH123 - plain binary read of a header
+            header = handle.read(64)
+            if header[:2] != b"MZ" or len(header) < 64:
+                return None
+            handle.seek(int.from_bytes(header[0x3C:0x40], "little"))
+            signature = handle.read(6)
+    except OSError:
+        return None
+    if signature[:4] != b"PE\0\0":
+        return None
+    return _PE_MACHINE_BITS.get(int.from_bytes(signature[4:6], "little"))
+
+
+def file_version(path: str) -> str | None:
+    """The file version resource of an executable (e.g. ``16.0.19127.20264``)."""
+    try:
+        import win32api
+
+        info = win32api.GetFileVersionInfo(path, "\\")
+    except Exception:
+        return None
+    ms, ls = int(info["FileVersionMS"]), int(info["FileVersionLS"])
+    return f"{ms >> 16}.{ms & 0xFFFF}.{ls >> 16}.{ls & 0xFFFF}"
+
+
+def access_facts(progid: str = "Access.Application") -> AccessFacts:
+    """Locate the Access executable registered for automation (registry only)."""
+    clsid = _clsid(progid)
+    current = _read_value(winreg.HKEY_CLASSES_ROOT, rf"{progid}\CurVer", "", winreg.KEY_WOW64_64KEY)
+    executable = _local_server(clsid) if clsid else None
+    if executable is None:
+        for view in (winreg.KEY_WOW64_64KEY, winreg.KEY_WOW64_32KEY):
+            executable = _read_value(winreg.HKEY_LOCAL_MACHINE, _APP_PATHS, "", view)
+            if executable:
+                break
+    if executable and not os.path.isfile(executable):  # noqa: PTH113 - registry path strings
+        executable = None
+    return AccessFacts(
+        progid=progid,
+        registered=clsid is not None,
+        current_version=current,
+        executable=executable,
+        version=file_version(executable) if executable else None,
+        bits=pe_bits(executable) if executable else None,
+    )
+
+
+def click_to_run() -> ClickToRunFacts | None:
+    """Click-to-Run configuration, or ``None`` for MSI installations / no Office."""
+    view = winreg.KEY_WOW64_64KEY
+    platform = _read_value(winreg.HKEY_LOCAL_MACHINE, _C2R_CONFIGURATION, "Platform", view)
+    version = _read_value(winreg.HKEY_LOCAL_MACHINE, _C2R_CONFIGURATION, "VersionToReport", view)
+    products = _read_value(winreg.HKEY_LOCAL_MACHINE, _C2R_CONFIGURATION, "ProductReleaseIds", view)
+    if platform is None and version is None and products is None:
+        return None
+    return ClickToRunFacts(
+        platform=platform,
+        version=version,
+        products=tuple(p for p in (products or "").split(",") if p),
+    )