pyaccesskit.errors

pyaccesskit.errors

Exception and warning hierarchy.

Every exception PyAccessKit raises derives from :class:PyAccessKitError. Low-level COM failures are translated into specific subclasses; the original pywintypes.com_error is always kept as __cause__ and summarised in :attr:PyAccessKitError.details, so nothing is lost for debugging.

Several classes also inherit a matching built-in exception (FileNotFoundError, LookupError, ValueError...) so idiomatic except clauses keep working.

DaoError dataclass

DaoError(number: int, description: str, source: str)

One entry of DAO's DBEngine.Errors collection.

ErrorDetails dataclass

ErrorDetails(
    hresult: int | None = None,
    scode: int | None = None,
    number: int | None = None,
    source: str | None = None,
    description: str | None = None,
    dao_errors: tuple[DaoError, ...] = (),
)

Low-level details of the COM error behind a PyAccessKit exception.

Attributes:

Name	Type	Description
hresult	int | None	The HRESULT returned by IDispatch::Invoke (usually DISP_E_EXCEPTION).
scode	int | None	The exception's SCODE (for Access/DAO errors 0x800A0000 | number).
number	int | None	The Access/DAO error number (e.g. 3010), when the error came from Access or DAO.
source	str | None	Error source, e.g. "DAO.TableDefs" (None for Access application errors).
description	str | None	The error text reported by Access/DAO.
dao_errors	tuple[DaoError, ...]	Snapshot of DBEngine.Errors when it matched this error.

summary

summary() -> str

Return a one-line, human-readable summary.

DialogInfo dataclass

DialogInfo(
    title: str,
    text: str,
    buttons: tuple[str, ...] = (),
    action: str = "",
)

A modal dialog that Access showed during an automated call.

action class-attribute instance-attribute

action: str = ''

How PyAccessKit dealt with it (e.g. "closed", "clicked 'No'", "terminated Access").

summary

summary() -> str

Return a one-line summary such as 'Microsoft Access: The expression ... [OK]'.

PyAccessKitError

PyAccessKitError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: Exception

Base class of every exception raised by PyAccessKit.

Attributes:

Name	Type	Description
message		Human-readable description.
operation		What PyAccessKit was doing, e.g. "create table 'Customers'".
details		COM-level details when the error originated in Access/DAO.

PyAccessKitWarning

Bases: UserWarning

Base class of PyAccessKit warnings.

AccessNameWarning

Bases: PyAccessKitWarning

A name is legal but likely to cause trouble (reserved word, spaces, special characters...).

AccessDialogWarning

Bases: PyAccessKitWarning

Access showed a dialog that was dismissed automatically (dialog_policy="warn").

EnvironmentProblem

EnvironmentProblem(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: PyAccessKitError

The machine cannot do what was asked (missing software, bitness mismatch...).

EngineUnavailableError

EngineUnavailableError(
    message: str,
    *,
    diagnosis: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: EnvironmentProblem

No usable automation engine for the requested operation.

Attributes:

Name	Type	Description
diagnosis		Explanation and advice (installed products, bitness, what to try).

AccessNotInstalledError

AccessNotInstalledError(
    message: str,
    *,
    diagnosis: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: EngineUnavailableError

Microsoft Access (Access.Application) is not installed or cannot be started.

DaoNotAvailableError

DaoNotAvailableError(
    message: str,
    *,
    diagnosis: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: EngineUnavailableError

In-process DAO (DAO.DBEngine.120) cannot be loaded into this Python process.

AccessRuntimeOnlyError

AccessRuntimeOnlyError(
    message: str,
    *,
    diagnosis: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: EngineUnavailableError

Only the Access Runtime is installed; design features need full Microsoft Access.

SessionError

SessionError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: PyAccessKitError

The session cannot perform the operation in its current state.

SessionClosedError

SessionClosedError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: SessionError

The database session has been closed.

WrongThreadError

WrongThreadError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: SessionError

A session was used from a thread other than the one that created it (COM apartment rule).

CapabilityError

CapabilityError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: SessionError

The operation needs a capability the session does not have (e.g. forms with engine="dao").

ReadOnlyError

ReadOnlyError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: SessionError

A modification was attempted on a session opened with readonly=True.

DatabaseError

DatabaseError(
    message: str,
    *,
    path: Path | str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: PyAccessKitError

A problem with the database file itself.

Attributes:

Name	Type	Description
path		The database path involved, when known.

DatabaseNotFoundError

DatabaseNotFoundError(
    message: str,
    *,
    path: Path | str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: DatabaseError, FileNotFoundError

The database file does not exist.

DatabaseExistsError

DatabaseExistsError(
    message: str,
    *,
    path: Path | str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: DatabaseError, FileExistsError

The database file already exists (pass overwrite=True to replace it).

DatabaseLockedError

DatabaseLockedError(
    message: str,
    *,
    path: Path | str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: DatabaseError

The database is in use (opened exclusively elsewhere, or locked).

InvalidPasswordError

InvalidPasswordError(
    message: str,
    *,
    path: Path | str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: DatabaseError

The database password is wrong or missing.

UnrecognizedFormatError

UnrecognizedFormatError(
    message: str,
    *,
    path: Path | str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: DatabaseError

The file is not an Access database (or is damaged / from an unsupported version).

ObjectError

ObjectError(
    message: str,
    *,
    kind: ObjectKind | None = None,
    name: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: PyAccessKitError

A problem with a named database object.

Attributes:

Name	Type	Description
kind		Kind of object (table, query, form...).
name		Object name.

ObjectNotFoundError

ObjectNotFoundError(
    message: str,
    *,
    kind: ObjectKind | None = None,
    name: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: ObjectError, LookupError

The named object does not exist.

ObjectExistsError

ObjectExistsError(
    message: str,
    *,
    kind: ObjectKind | None = None,
    name: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: ObjectError

An object with that name already exists (tables and queries share one namespace).

ObjectInUseError

ObjectInUseError(
    message: str,
    *,
    kind: ObjectKind | None = None,
    name: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: ObjectError

The object is locked or open elsewhere.

SpecError

SpecError(
    message: str,
    *,
    problems: tuple[str, ...] = (),
    operation: str | None = None,
)

Bases: PyAccessKitError, ValueError

A specification is invalid. Raised by PyAccessKit before anything is sent to Access.

Attributes:

Name	Type	Description
problems		Individual problems (e.g. from Pydantic validation), each "location: message".

SchemaError

SchemaError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: PyAccessKitError

The database engine rejected a schema change.

RelationshipError

RelationshipError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: SchemaError

A relationship cannot be created as specified (types, keys, index budget...).

IntegrityViolationError

IntegrityViolationError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: SchemaError

Existing data violates the referential integrity rule being created.

QueryError

QueryError(
    message: str,
    *,
    sql: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: PyAccessKitError

A SQL statement or saved query failed.

Attributes:

Name	Type	Description
sql		The SQL text involved, when known.

SqlSyntaxError

SqlSyntaxError(
    message: str,
    *,
    sql: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: QueryError

Access SQL could not parse the statement.

MissingParameterError

MissingParameterError(
    message: str,
    *,
    sql: str | None = None,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: QueryError

The statement has parameters that were not supplied (DAO error 3061).

AccessApplicationError

AccessApplicationError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: PyAccessKitError

A problem with the Microsoft Access application process.

AccessDialogError

AccessDialogError(
    message: str,
    *,
    dialogs: tuple[DialogInfo, ...] = (),
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: AccessApplicationError

Access showed a modal dialog that would have blocked automation.

Attributes:

Name	Type	Description
dialogs		The dialogs that were observed (title, text, buttons, how they were handled).

AccessTimeoutError

AccessTimeoutError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: AccessApplicationError

An Access call exceeded call_timeout; the owned Access process was terminated.

AccessProcessDiedError

AccessProcessDiedError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: AccessApplicationError

The Access process exited or was terminated while PyAccessKit was using it.

CleanupError

CleanupError(
    message: str, *, errors: tuple[BaseException, ...] = ()
)

Bases: PyAccessKitError

One or more steps failed while closing a session (all remaining steps still ran).

Attributes:

Name	Type	Description
errors		The exceptions raised by the failing cleanup steps.

ComError

ComError(
    message: str,
    *,
    operation: str | None = None,
    details: ErrorDetails | None = None,
)

Bases: PyAccessKitError

A COM error PyAccessKit has no more specific translation for (details are preserved).