pyaccesskit.database¶

pyaccesskit.database ¶

The :class:AccessDatabase facade — the entry point of PyAccessKit.

RawAccess ¶

RawAccess(session: Session)

Escape hatch to the underlying COM objects.

Every object returned is a revocable proxy: it stops working (and releases its COM reference) when the session closes or switches engines. Save your own design changes; PyAccessKit quits Access without saving objects it did not manage.

dao `property` ¶

dao: Any

The DAO Database object.

dbengine `property` ¶

dbengine: Any

The DAO DBEngine object.

access `property` ¶

access: Any

The Access.Application object (switches the session to a design session if needed).

AccessDatabase ¶

AccessDatabase(session: Session)

An open Microsoft Access database.

Create or open one with :meth:create / :meth:open, ideally as a context manager so that everything (including the Access process) is cleaned up even if an exception occurs::

with AccessDatabase.create("crm.accdb") as db:
    db.tables.create("Customers", columns=[...])

Attributes:

Name	Type	Description
`tables`		The tables (:class:`~pyaccesskit.tables.TableCollection`).
`relationships`		The relationships.
`queries`		The saved queries.
`forms`		The forms (building forms needs Microsoft Access).
`modules`		The VBA modules (needs Microsoft Access).
`objects`		Text import/export and management of forms, reports, macros and modules.
`properties`		The database's DAO properties (`AppTitle`, `StartUpForm`...).
`raw`		Escape hatch to the underlying COM objects.

path `property` ¶

path: Path

The database file (for atomic creation: where it will be when the session closes).

transport `property` ¶

transport: Transport

How the database is currently reached (in-process DAO, Access-hosted DAO, design session).

format_version `property` ¶

format_version: str

The database engine format (DAO Database.Version): "12.0" for .accdb, "4.0" for Jet 4.

readonly `property` ¶

readonly: bool

Whether the database was opened read-only.

is_open `property` ¶

is_open: bool

Whether the session is still open.

access_pid `property` ¶

access_pid: int | None

PID of the owned MSACCESS.EXE (None when no Access process is used).

create `classmethod` ¶

create(
    path: str | PathLike[str],
    *,
    overwrite: bool = False,
    atomic: bool = True,
    engine: Engine | str = Engine.AUTO,
    options: SessionOptions | None = None,
) -> AccessDatabase

Create a new .accdb database.

Parameters:

Name	Type	Description	Default
`path`	`str \| PathLike[str]`	Where to create the database.	required
`overwrite`	`bool`	Replace an existing file at `path`.	`False`
`atomic`	`bool`	Build in a temporary sibling file and move it into place only when the session closes without an error; on error the target is left untouched.	`True`
`engine`	`Engine \| str`	`"auto"` (default), `"dao"` or `"access"` — see :class:`~pyaccesskit.enums.Engine`.	`AUTO`
`options`	`SessionOptions \| None`	Advanced session options.	`None`

Raises:

Type	Description
`DatabaseExistsError`	If `path` exists and `overwrite` is false.

open `classmethod` ¶

open(
    path: str | PathLike[str],
    *,
    readonly: bool = False,
    exclusive: bool | None = None,
    password: str | None = None,
    engine: Engine | str = Engine.AUTO,
    options: SessionOptions | None = None,
) -> AccessDatabase

Open an existing database.

Parameters:

Name	Type	Description	Default
`path`	`str \| PathLike[str]`	The database file.	required
`readonly`	`bool`	Open read-only (also allows opening a database that is open in Access elsewhere).	`False`
`exclusive`	`bool \| None`	Open exclusively (default: `True` unless `readonly`). Design changes need it.	`None`
`password`	`str \| None`	Database password, if any.	`None`
`engine`	`Engine \| str`	`"auto"` (default), `"dao"` or `"access"`.	`AUTO`
`options`	`SessionOptions \| None`	Advanced session options.	`None`

Raises:

Type	Description
`DatabaseNotFoundError`	If the file does not exist.
`DatabaseLockedError`	If it is in use elsewhere.

execute ¶

execute(
    sql: str, params: Mapping[str, Any] | None = None
) -> int

Run an action statement (INSERT/UPDATE/DELETE/DDL); returns the number of affected rows.

params binds parameters by name ([Name] references in the SQL); values are never interpolated into the SQL text.

fetch_all ¶

fetch_all(
    sql: str,
    params: Mapping[str, Any] | None = None,
    *,
    limit: int | None = None,
) -> list[dict[str, Any]]

Run a SELECT and return its rows as dictionaries.

close ¶

close() -> None

Close the session and release everything (idempotent; only from the thread that opened it).

pyaccesskit.database¶