pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/_com/constants.py

@@ -0,0 +1,394 @@
+"""Access and DAO constants used by PyAccessKit's COM adapters (internal).
+
+Generated by ``scripts/gen_constants.py`` from the installed type libraries — do not edit by hand.
+
+* Microsoft Access 16.0 Object Library — ``{4AFFC9A0-5F99-101B-AF4E-00AA003F0F07}`` v9.0
+* Microsoft Office 16.0 Access database engine Object Library — ``{4AC9E1DA-5BAD-4AC7-86E3-24F4CDCECA28}`` v12.0
+"""
+
+# ruff: noqa: N815
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class AcCloseSave(IntEnum):
+    """``AcCloseSave`` (Microsoft Access 16.0 Object Library)."""
+
+    acSavePrompt = 0
+    acSaveYes = 1
+    acSaveNo = 2
+
+
+class AcControlType(IntEnum):
+    """``AcControlType`` (Microsoft Access 16.0 Object Library)."""
+
+    acLabel = 100
+    acRectangle = 101
+    acLine = 102
+    acImage = 103
+    acCommandButton = 104
+    acOptionButton = 105
+    acCheckBox = 106
+    acOptionGroup = 107
+    acBoundObjectFrame = 108
+    acTextBox = 109
+    acListBox = 110
+    acComboBox = 111
+    acSubform = 112
+    acObjectFrame = 114
+    acPageBreak = 118
+    acCustomControl = 119
+    acToggleButton = 122
+    acTabCtl = 123
+    acPage = 124
+    acAttachment = 126
+    acEmptyCell = 127
+    acWebBrowser = 128
+    acNavigationControl = 129
+    acNavigationButton = 130
+    acChart = 133
+    acEdgeBrowser = 134
+
+
+class AcDefView(IntEnum):
+    """``AcDefView`` (Microsoft Access 16.0 Object Library)."""
+
+    acDefViewSingle = 0
+    acDefViewContinuous = 1
+    acDefViewDatasheet = 2
+    acDefViewPivotTable = 3
+    acDefViewPivotChart = 4
+    acDefViewSplitForm = 5
+
+
+class AcFormOpenDataMode(IntEnum):
+    """``AcFormOpenDataMode`` (Microsoft Access 16.0 Object Library)."""
+
+    acFormPropertySettings = -1
+    acFormAdd = 0
+    acFormEdit = 1
+    acFormReadOnly = 2
+
+
+class AcFormView(IntEnum):
+    """``AcFormView`` (Microsoft Access 16.0 Object Library)."""
+
+    acNormal = 0
+    acDesign = 1
+    acPreview = 2
+    acFormDS = 3
+    acFormPivotTable = 4
+    acFormPivotChart = 5
+    acLayout = 6
+
+
+class AcModuleType(IntEnum):
+    """``AcModuleType`` (Microsoft Access 16.0 Object Library)."""
+
+    acStandardModule = 0
+    acClassModule = 1
+
+
+class AcNewDatabaseFormat(IntEnum):
+    """``AcNewDatabaseFormat`` (Microsoft Access 16.0 Object Library)."""
+
+    acNewDatabaseFormatUserDefault = 0
+    acNewDatabaseFormatAccess2000 = 9
+    acNewDatabaseFormatAccess2002 = 10
+    acNewDatabaseFormatAccess2007 = 12
+
+
+class AcObjectType(IntEnum):
+    """``AcObjectType`` (Microsoft Access 16.0 Object Library)."""
+
+    acDefault = -1
+    acTable = 0
+    acQuery = 1
+    acForm = 2
+    acReport = 3
+    acMacro = 4
+    acModule = 5
+    acDataAccessPage = 6
+    acServerView = 7
+    acDiagram = 8
+    acStoredProcedure = 9
+    acFunction = 10
+    acDatabaseProperties = 11
+    acTableDataMacro = 12
+
+
+class AcQuitOption(IntEnum):
+    """``AcQuitOption`` (Microsoft Access 16.0 Object Library)."""
+
+    acQuitPrompt = 0
+    acQuitSaveAll = 1
+    acQuitSaveNone = 2
+
+
+class AcSection(IntEnum):
+    """``AcSection`` (Microsoft Access 16.0 Object Library)."""
+
+    acDetail = 0
+    acHeader = 1
+    acFooter = 2
+    acPageHeader = 3
+    acPageFooter = 4
+    acGroupLevel1Header = 5
+    acGroupLevel1Footer = 6
+    acGroupLevel2Header = 7
+    acGroupLevel2Footer = 8
+
+
+class AcSysCmdAction(IntEnum):
+    """``AcSysCmdAction`` (Microsoft Access 16.0 Object Library)."""
+
+    acSysCmdInitMeter = 1
+    acSysCmdUpdateMeter = 2
+    acSysCmdRemoveMeter = 3
+    acSysCmdSetStatus = 4
+    acSysCmdClearStatus = 5
+    acSysCmdRuntime = 6
+    acSysCmdAccessVer = 7
+    acSysCmdIniFile = 8
+    acSysCmdAccessDir = 9
+    acSysCmdGetObjectState = 10
+    acSysCmdClearHelpTopic = 11
+    acSysCmdProfile = 12
+    acSysCmdGetWorkgroupFile = 13
+    acSysCmdCompile = 603
+    acSysCmdGetMsoBuildNumber = 715
+    acSysCmdGetFullVersion = 720
+    acSysCmdGetVersion = 721
+    acSysCmdGetFullBuildNumber = 722
+    acSysCmdGetChannelName = 723
+    acSysCmdGetBitness = 724
+    acSysCmdGetBuildNumber = 725
+
+
+class AcView(IntEnum):
+    """``AcView`` (Microsoft Access 16.0 Object Library)."""
+
+    acViewNormal = 0
+    acViewDesign = 1
+    acViewPreview = 2
+    acViewPivotTable = 3
+    acViewPivotChart = 4
+    acViewReport = 5
+    acViewLayout = 6
+    acViewSql = 7
+
+
+class AcWindowMode(IntEnum):
+    """``AcWindowMode`` (Microsoft Access 16.0 Object Library)."""
+
+    acWindowNormal = 0
+    acHidden = 1
+    acIcon = 2
+    acDialog = 3
+
+
+class DataTypeEnum(IntEnum):
+    """``DataTypeEnum`` (Microsoft Office 16.0 Access database engine Object Library)."""
+
+    dbBoolean = 1
+    dbByte = 2
+    dbInteger = 3
+    dbLong = 4
+    dbCurrency = 5
+    dbSingle = 6
+    dbDouble = 7
+    dbDate = 8
+    dbBinary = 9
+    dbText = 10
+    dbLongBinary = 11
+    dbMemo = 12
+    dbGUID = 15
+    dbBigInt = 16
+    dbVarBinary = 17
+    dbChar = 18
+    dbNumeric = 19
+    dbDecimal = 20
+    dbFloat = 21
+    dbTime = 22
+    dbTimeStamp = 23
+    dbDateTimeExtended = 26
+    dbAttachment = 101
+    dbComplexByte = 102
+    dbComplexInteger = 103
+    dbComplexLong = 104
+    dbComplexSingle = 105
+    dbComplexDouble = 106
+    dbComplexGUID = 107
+    dbComplexDecimal = 108
+    dbComplexText = 109
+
+
+class DatabaseTypeEnum(IntEnum):
+    """``DatabaseTypeEnum`` (Microsoft Office 16.0 Access database engine Object Library)."""
+
+    dbVersion10 = 1
+    dbEncrypt = 2
+    dbDecrypt = 4
+    dbVersion11 = 8
+    dbVersion20 = 16
+    dbVersion30 = 32
+    dbVersion40 = 64
+    dbVersion120 = 128
+    dbVersion140 = 256
+    dbVersion150 = 512
+    dbVersion167 = 1024
+
+
+class FieldAttributeEnum(IntEnum):
+    """``FieldAttributeEnum`` (Microsoft Office 16.0 Access database engine Object Library)."""
+
+    dbFixedField = 1
+    dbVariableField = 2
+    dbAutoIncrField = 16
+    dbUpdatableField = 32
+    dbSystemField = 8192
+    dbHyperlinkField = 32768
+    dbDescending = 1
+
+
+class QueryDefTypeEnum(IntEnum):
+    """``QueryDefTypeEnum`` (Microsoft Office 16.0 Access database engine Object Library)."""
+
+    dbQSelect = 0
+    dbQProcedure = 224
+    dbQAction = 240
+    dbQCrosstab = 16
+    dbQDelete = 32
+    dbQUpdate = 48
+    dbQAppend = 64
+    dbQMakeTable = 80
+    dbQDDL = 96
+    dbQSQLPassThrough = 112
+    dbQSetOperation = 128
+    dbQSPTBulk = 144
+    dbQCompound = 160
+
+
+class RecordsetOptionEnum(IntEnum):
+    """``RecordsetOptionEnum`` (Microsoft Office 16.0 Access database engine Object Library)."""
+
+    dbDenyWrite = 1
+    dbDenyRead = 2
+    dbReadOnly = 4
+    dbAppendOnly = 8
+    dbInconsistent = 16
+    dbConsistent = 32
+    dbSQLPassThrough = 64
+    dbFailOnError = 128
+    dbForwardOnly = 256
+    dbSeeChanges = 512
+    dbRunAsync = 1024
+    dbExecDirect = 2048
+
+
+class RecordsetTypeEnum(IntEnum):
+    """``RecordsetTypeEnum`` (Microsoft Office 16.0 Access database engine Object Library)."""
+
+    dbOpenTable = 1
+    dbOpenDynaset = 2
+    dbOpenSnapshot = 4
+    dbOpenForwardOnly = 8
+    dbOpenDynamic = 16
+
+
+class RelationAttributeEnum(IntEnum):
+    """``RelationAttributeEnum`` (Microsoft Office 16.0 Access database engine Object Library)."""
+
+    dbRelationUnique = 1
+    dbRelationDontEnforce = 2
+    dbRelationInherited = 4
+    dbRelationUpdateCascade = 256
+    dbRelationDeleteCascade = 4096
+    dbRelationLeft = 16777216
+    dbRelationRight = 33554432
+
+
+class TableDefAttributeEnum(IntEnum):
+    """``TableDefAttributeEnum`` (Microsoft Office 16.0 Access database engine Object Library)."""
+
+    dbAttachExclusive = 65536
+    dbAttachSavePWD = 131072
+    dbSystemObject = -2147483646
+    dbAttachedTable = 1073741824
+    dbAttachedODBC = 536870912
+    dbHiddenObject = 1
+
+
+# LanguageConstants (Microsoft Office 16.0 Access database engine Object Library)
+dbLangArabic = ';LANGID=0x0401;CP=1256;COUNTRY=0'
+dbLangCzech = ';LANGID=0x0405;CP=1250;COUNTRY=0'
+dbLangDutch = ';LANGID=0x0413;CP=1252;COUNTRY=0'
+dbLangGeneral = ';LANGID=0x0409;CP=1252;COUNTRY=0'
+dbLangGreek = ';LANGID=0x0408;CP=1253;COUNTRY=0'
+dbLangHebrew = ';LANGID=0x040D;CP=1255;COUNTRY=0'
+dbLangHungarian = ';LANGID=0x040E;CP=1250;COUNTRY=0'
+dbLangIcelandic = ';LANGID=0x040F;CP=1252;COUNTRY=0'
+dbLangNordic = ';LANGID=0x041D;CP=1252;COUNTRY=0'
+dbLangNorwDan = ';LANGID=0x0406;CP=1252;COUNTRY=0'
+dbLangPolish = ';LANGID=0x0415;CP=1250;COUNTRY=0'
+dbLangCyrillic = ';LANGID=0x0419;CP=1251;COUNTRY=0'
+dbLangSpanish = ';LANGID=0x040A;CP=1252;COUNTRY=0'
+dbLangSwedFin = ';LANGID=0x041D;CP=1252;COUNTRY=0'
+dbLangTurkish = ';LANGID=0x041F;CP=1254;COUNTRY=0'
+dbLangJapanese = ';LANGID=0x0411;CP=932;COUNTRY=0'
+dbLangChineseSimplified = ';LANGID=0x0804;CP=936;COUNTRY=0'
+dbLangChineseTraditional = ';LANGID=0x0404;CP=950;COUNTRY=0'
+dbLangKorean = ';LANGID=0x0412;CP=949;COUNTRY=0'
+dbLangThai = ';LANGID=0x041E;CP=874;COUNTRY=0'
+dbLangSlovenian = ';LANGID=0x0424;CP=1250;COUNTRY=0'
+dbLangJapaneseRadicalStrokeCount = ';LANGID=0x00040411;CP=65001;COUNTRY=0'
+dbLangHindi = ';LANGID=0x00000439;CP=65001;COUNTRY=0'
+
+
+class MsoAutomationSecurity(IntEnum):
+    """``Application.AutomationSecurity`` values (Office core type library)."""
+
+    msoAutomationSecurityLow = 1
+    msoAutomationSecurityByUI = 2
+    msoAutomationSecurityForceDisable = 3
+
+
+class AdoSchema(IntEnum):
+    """ADO ``SchemaEnum`` values used for column introspection."""
+
+    adSchemaColumns = 4
+    adSchemaIndexes = 12
+
+
+class FormScrollBars(IntEnum):
+    """Values of the Access ``Form.ScrollBars`` property."""
+
+    neither = 0
+    horizontal = 1
+    vertical = 2
+    both = 3
+
+
+class TextFormat(IntEnum):
+    """Values of the Access ``TextFormat`` field property (Long Text)."""
+
+    plain_text = 0
+    rich_text = 1
+
+
+# Well-known Win32/COM HRESULTs (as signed 32-bit integers, the way pywin32 reports them).
+def _hresult(value: int) -> int:
+    return value - 0x1_0000_0000 if value & 0x8000_0000 else value
+
+
+DISP_E_EXCEPTION = _hresult(0x80020009)
+REGDB_E_CLASSNOTREG = _hresult(0x80040154)
+CO_E_SERVER_EXEC_FAILURE = _hresult(0x80080005)
+RPC_E_CALL_REJECTED = _hresult(0x80010001)
+RPC_E_SERVERCALL_RETRYLATER = _hresult(0x8001010A)
+RPC_E_DISCONNECTED = _hresult(0x80010108)
+RPC_E_SERVERFAULT = _hresult(0x80010105)
+RPC_S_SERVER_UNAVAILABLE = _hresult(0x800706BA)
+RPC_S_CALL_FAILED = _hresult(0x800706BE)
+CO_E_OBJNOTCONNECTED = _hresult(0x800401FD)

pyaccesskit/_com/dispatch.py

@@ -0,0 +1,50 @@
+# pyright: basic, reportArgumentType=false, reportAttributeAccessIssue=false, reportIndexIssue=false
+# (the types-pywin32 stubs are stricter than the COM runtime, e.g. unkOuter=None is valid)
+"""Creation of COM objects — always late-bound, never attached to a running instance.
+
+* ``win32com.client.Dispatch(progid)`` first calls ``GetActiveObject`` and would *attach to a user's running
+  Access* (ADR 0001, F1). PyAccessKit always uses ``CoCreateInstanceEx`` instead.
+* ``Dispatch``/``DispatchEx`` return early- or late-bound wrappers depending on the machine's makepy cache.
+  ``win32com.client.dynamic.Dispatch`` keeps the whole object graph late-bound, so behaviour is identical
+  on every machine.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pythoncom
+import pywintypes
+from win32com.client import dynamic
+
+from pyaccesskit._com.runtime import ensure_com_initialized
+
+__all__ = ["create_inproc", "create_local_server", "wrap"]
+
+
+def wrap(obj: Any) -> Any:
+    """Wrap a raw ``PyIDispatch``/``PyIUnknown`` in a late-bound dispatch object."""
+    if isinstance(obj, pythoncom.TypeIIDs[pythoncom.IID_IDispatch]):
+        return dynamic.Dispatch(obj)
+    if isinstance(obj, pythoncom.TypeIIDs[pythoncom.IID_IUnknown]):
+        return dynamic.Dispatch(obj.QueryInterface(pythoncom.IID_IDispatch))
+    return obj
+
+
+def create_local_server(progid: str) -> Any:
+    """Start a **new** instance of an out-of-process COM server (e.g. ``Access.Application``)."""
+    ensure_com_initialized()
+    clsid = pywintypes.IID(progid)
+    unknown = pythoncom.CoCreateInstanceEx(
+        clsid, None, pythoncom.CLSCTX_LOCAL_SERVER, None, (pythoncom.IID_IDispatch,)
+    )[0]
+    return dynamic.Dispatch(unknown)
+
+
+def create_inproc(progid: str) -> Any:
+    """Load an in-process COM server (e.g. ``DAO.DBEngine.120``) into this Python process."""
+    ensure_com_initialized()
+    unknown = pythoncom.CoCreateInstance(
+        progid, None, pythoncom.CLSCTX_INPROC_SERVER, pythoncom.IID_IDispatch
+    )
+    return dynamic.Dispatch(unknown)

pyaccesskit/_com/errors.py

@@ -0,0 +1,184 @@
+# pyright: basic
+"""Translate ``pywintypes.com_error`` into PyAccessKit exceptions.
+
+Access and DAO report errors as ``DISP_E_EXCEPTION`` whose EXCEPINFO carries ``scode = 0x800A0000 | number``
+(FACILITY_CONTROL) — verified for every number below in spike S9. DAO errors have a ``DAO.<Collection>``
+source; Access application errors have no source but a filled description.
+"""
+
+from __future__ import annotations
+
+import traceback
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pyaccesskit._com import constants as c
+from pyaccesskit.enums import ObjectKind
+from pyaccesskit.errors import (
+    AccessProcessDiedError,
+    ComError,
+    DaoError,
+    DatabaseExistsError,
+    DatabaseLockedError,
+    DatabaseNotFoundError,
+    EngineUnavailableError,
+    ErrorDetails,
+    IntegrityViolationError,
+    InvalidPasswordError,
+    MissingParameterError,
+    ObjectExistsError,
+    ObjectInUseError,
+    ObjectNotFoundError,
+    PyAccessKitError,
+    ReadOnlyError,
+    RelationshipError,
+    SchemaError,
+    SqlSyntaxError,
+    UnrecognizedFormatError,
+)
+
+__all__ = ["OpContext", "details_from", "translate"]
+
+FACILITY_CONTROL = 0x0A
+
+NOT_FOUND = frozenset({3011, 3078, 3265, 2102, 2103, 2450, 2451, 2465, 7874})
+EXISTS = frozenset({3010, 3012, 3191, 3284, 3367, 3380})
+DB_EXISTS = frozenset({3204, 7865})
+DB_NOT_FOUND = frozenset({3024, 3044})
+LOCKED = frozenset({3006, 3045, 3050, 3356, 3734, 7866})
+IN_USE = frozenset({3008, 3009, 3211, 3262})
+PASSWORD = frozenset({3031})
+FORMAT = frozenset({3049, 3343})
+SQL_SYNTAX = frozenset(
+    {3075, 3122, 3129, 3131, 3134, 3141, 3144, 3145, 3292, 3293, 3306, 3319, 3346}
+)
+MISSING_PARAMETER = frozenset({3061})
+RELATIONSHIP = frozenset({3366, 3368, 3609})
+INTEGRITY = frozenset({3022, 3200, 3201})
+SCHEMA = frozenset({3125, 3259, 3280, 3283, 3303, 3375})
+READ_ONLY = frozenset({3027})
+PROCESS_DIED = frozenset(
+    {
+        c.RPC_E_DISCONNECTED,
+        c.RPC_S_SERVER_UNAVAILABLE,
+        c.RPC_S_CALL_FAILED,
+        c.RPC_E_SERVERFAULT,
+        c.CO_E_OBJNOTCONNECTED,
+    }
+)
+UNAVAILABLE = frozenset(
+    {c.REGDB_E_CLASSNOTREG, c.CO_E_SERVER_EXEC_FAILURE, -2147221005}
+)  # + CO_E_CLASSSTRING
+
+
+@dataclass(frozen=True)
+class OpContext:
+    """What PyAccessKit was doing when a COM call failed (used to build precise messages)."""
+
+    action: str
+    kind: ObjectKind | None = None
+    name: str | None = None
+    path: Path | None = None
+    sql: str | None = None
+
+
+def _signed(value: int | None) -> int | None:
+    if value is None:
+        return None
+    value &= 0xFFFFFFFF
+    return value - 0x1_0000_0000 if value & 0x8000_0000 else value
+
+
+def details_from(exc: Any, dao_errors: Sequence[DaoError] = ()) -> ErrorDetails:
+    """Extract :class:`ErrorDetails` from a ``pywintypes.com_error`` (or any exception with its ``args``)."""
+    args = tuple(getattr(exc, "args", ()))
+    hresult = _signed(args[0]) if args and isinstance(args[0], int) else None
+    message = args[1] if len(args) > 1 and isinstance(args[1], str) else None
+    excepinfo = args[2] if len(args) > 2 and isinstance(args[2], tuple) else None
+    source = description = None
+    scode = None
+    if excepinfo and len(excepinfo) >= 6:
+        source = excepinfo[1] or None
+        description = excepinfo[2] or None
+        scode = _signed(excepinfo[5]) if isinstance(excepinfo[5], int) else None
+    number = None
+    if scode is not None and ((scode >> 16) & 0x1FFF) == FACILITY_CONTROL:
+        number = scode & 0xFFFF
+    if description is None and scode is None:
+        description = message
+    matching: tuple[DaoError, ...] = ()
+    if dao_errors and number is not None and dao_errors[-1].number == number:
+        matching = tuple(
+            dao_errors
+        )  # DBEngine.Errors keeps stale entries; only trust a matching one
+    return ErrorDetails(
+        hresult=hresult,
+        scode=scode,
+        number=number,
+        source=source,
+        description=description.strip() if description else None,
+        dao_errors=matching,
+    )
+
+
+def _message(ctx: OpContext, details: ErrorDetails) -> str:
+    summary = details.summary() or "unknown COM error"
+    return f"cannot {ctx.action}: {summary}"
+
+
+def translate(
+    exc: BaseException, ctx: OpContext, dao_errors: Sequence[DaoError] = ()
+) -> PyAccessKitError:
+    """Map a COM error to the most specific :mod:`pyaccesskit.errors` exception.
+
+    The COM-holding locals of the original traceback are cleared (the traceback itself is kept for
+    debugging), so an exception kept alive by the caller cannot keep an Access process alive.
+    """
+    if exc.__traceback__ is not None:
+        traceback.clear_frames(exc.__traceback__)
+    details = details_from(exc, dao_errors)
+    number = details.number
+    message = _message(ctx, details)
+    common = {"operation": ctx.action, "details": details}
+
+    if number is not None:
+        if number in NOT_FOUND:
+            return ObjectNotFoundError(message, kind=ctx.kind, name=ctx.name, **common)
+        if number in EXISTS:
+            return ObjectExistsError(message, kind=ctx.kind, name=ctx.name, **common)
+        if number in DB_EXISTS:
+            return DatabaseExistsError(message, path=ctx.path, **common)
+        if number in DB_NOT_FOUND:
+            return DatabaseNotFoundError(message, path=ctx.path, **common)
+        if number in LOCKED:
+            return DatabaseLockedError(message, path=ctx.path, **common)
+        if number in IN_USE:
+            return ObjectInUseError(message, kind=ctx.kind, name=ctx.name, **common)
+        if number in PASSWORD:
+            return InvalidPasswordError(message, path=ctx.path, **common)
+        if number in FORMAT:
+            return UnrecognizedFormatError(message, path=ctx.path, **common)
+        if number in SQL_SYNTAX:
+            return SqlSyntaxError(message, sql=ctx.sql, **common)
+        if number in MISSING_PARAMETER:
+            return MissingParameterError(message, sql=ctx.sql, **common)
+        if number in RELATIONSHIP:
+            return RelationshipError(message, **common)
+        if number in INTEGRITY:
+            return IntegrityViolationError(message, **common)
+        if number in SCHEMA:
+            return SchemaError(message, **common)
+        if number in READ_ONLY:
+            return ReadOnlyError(message, **common)
+
+    for code in (details.scode, details.hresult):
+        if code in PROCESS_DIED:
+            return AccessProcessDiedError(
+                f"cannot {ctx.action}: the Microsoft Access process stopped responding or exited",
+                **common,
+            )
+        if code in UNAVAILABLE:
+            return EngineUnavailableError(message, **common)
+    return ComError(message, **common)