pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/cli/inspection.py

@@ -0,0 +1,223 @@
+"""``pyaccesskit inspect``: describe a database without changing it."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.markup import escape
+from rich.table import Table
+
+from pyaccesskit.cli._output import EXIT_OK, handle_errors, print_json, redact, stdout
+from pyaccesskit.database import AccessDatabase
+from pyaccesskit.enums import DataType, Engine, ObjectKind
+from pyaccesskit.errors import PyAccessKitError
+from pyaccesskit.schema import (
+    AutoNumberColumn,
+    ColumnBase,
+    DecimalColumn,
+    Expr,
+    LongTextColumn,
+    NumberColumn,
+    TableSpec,
+    TextColumn,
+    render_literal,
+)
+from pyaccesskit.schema.columns import UnsupportedColumn
+
+OTHER_OBJECTS = (ObjectKind.FORM, ObjectKind.REPORT, ObjectKind.MACRO, ObjectKind.MODULE)
+_TYPE_NAMES = {
+    DataType.TEXT: "Short Text",
+    DataType.LONG_TEXT: "Long Text",
+    DataType.NUMBER: "Number",
+    DataType.DECIMAL: "Decimal",
+    DataType.CURRENCY: "Currency",
+    DataType.AUTONUMBER: "AutoNumber",
+    DataType.DATE_TIME: "Date/Time",
+    DataType.YES_NO: "Yes/No",
+    DataType.HYPERLINK: "Hyperlink",
+    DataType.OLE_OBJECT: "OLE Object",
+}
+
+
+def inspect_database(
+    database: Annotated[Path, typer.Argument(help="The .accdb or .mdb file.", show_default=False)],
+    json_output: Annotated[bool, typer.Option("--json", help="Print the report as JSON.")] = False,
+    counts: Annotated[
+        bool, typer.Option("--counts", help="Also count the rows of every table.")
+    ] = False,
+    password: Annotated[
+        str | None,
+        typer.Option(
+            "--password",
+            envvar="PYACCESSKIT_PASSWORD",
+            help="Database password (prefer the PYACCESSKIT_PASSWORD environment variable).",
+            show_default=False,
+        ),
+    ] = None,
+    engine: Annotated[Engine, typer.Option(help="Engine to use.")] = Engine.AUTO,
+) -> None:
+    """Describe tables, relationships, queries and other objects (read-only; no startup code runs)."""
+    with handle_errors():
+        db = AccessDatabase.open(database, readonly=True, password=password, engine=engine)
+        with db:
+            report = describe(db, counts=counts)
+    if json_output:
+        print_json(report)
+    else:
+        render(report)
+    raise typer.Exit(EXIT_OK)
+
+
+def describe(db: AccessDatabase, *, counts: bool = False) -> dict[str, Any]:
+    """Everything ``inspect`` reports, as JSON-ready data. Problems with single objects become warnings.
+
+    Passwords in linked-table and pass-through connection strings are redacted.
+    """
+    warnings: list[str] = []
+    tables: list[dict[str, Any]] = []
+    for table in db.tables:
+        entry: dict[str, Any] = {"name": table.name, "linked": None, "rows": None, "spec": None}
+        try:
+            if table.is_linked:
+                entry["linked"] = {
+                    "connect": redact(table.connect),
+                    "source_table": table.source_table,
+                }
+            entry["spec"] = table.to_spec().model_dump(mode="json")
+            if counts:
+                entry["rows"] = table.record_count()
+        except PyAccessKitError as exc:
+            warnings.append(f"table {table.name!r}: {exc}")
+        tables.append(entry)
+
+    queries: list[dict[str, Any]] = []
+    for query in db.queries:
+        try:
+            spec = query.to_spec().model_dump(mode="json")
+            passthrough = spec.get("pass_through")
+            if isinstance(passthrough, dict):
+                passthrough["connect"] = redact(str(passthrough.get("connect")))  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
+            queries.append({"kind": query.kind.value, **spec})
+        except PyAccessKitError as exc:
+            warnings.append(f"query {query.name!r}: {exc}")
+
+    return {
+        "path": str(db.path),
+        "format_version": db.format_version,
+        "transport": db.transport.value,
+        "tables": tables,
+        "relationships": [spec.model_dump(mode="json") for spec in db.relationships.specs()],
+        "queries": queries,
+        **{f"{kind.value}s": db.objects.names(kind) for kind in OTHER_OBJECTS},
+        "warnings": warnings,
+    }
+
+
+# ------------------------------------------------------------------------------------ rendering
+def column_type(column: ColumnBase) -> str:
+    """How the Access table designer would describe a column's type."""
+    if isinstance(column, UnsupportedColumn):
+        return f"{column.detail} (unsupported)"
+    name = _TYPE_NAMES.get(column.data_type, column.data_type.value)
+    if isinstance(column, TextColumn):
+        return f"{name}({column.length})"
+    if isinstance(column, NumberColumn):
+        return f"{name} ({column.size.value.replace('_', ' ')})"
+    if isinstance(column, DecimalColumn):
+        return f"{name}({column.precision},{column.scale})"
+    if isinstance(column, AutoNumberColumn) and column.replication_id:
+        return f"{name} (replication ID)"
+    if isinstance(column, LongTextColumn):
+        flags = [
+            flag
+            for flag, on in (("rich text", column.rich_text), ("append only", column.append_only))
+            if on
+        ]
+        return f"{name} ({', '.join(flags)})" if flags else name
+    return name
+
+
+def _default_text(column: ColumnBase) -> str:
+    default = column.default
+    if default is None:
+        return ""
+    return default.expr if isinstance(default, Expr) else render_literal(default)
+
+
+def _render_table(entry: dict[str, Any]) -> None:
+    console = stdout()
+    details: list[str] = []
+    if entry["linked"]:
+        link = entry["linked"]
+        details.append(f"linked to {link['source_table']} ({link['connect']})")
+    if entry["rows"] is not None:
+        details.append(f"{entry['rows']} row{'' if entry['rows'] == 1 else 's'}")
+    suffix = f"  [dim]{escape('; '.join(details))}[/]" if details else ""
+    console.print(f"\n[bold cyan]Table {escape(entry['name'])}[/]{suffix}")
+    if entry["spec"] is None:
+        console.print("  [yellow]could not be read (see warnings)[/]")
+        return
+    spec = TableSpec.model_validate(entry["spec"])
+    grid = Table(box=None, padding=(0, 2), show_edge=False, header_style="dim")
+    for heading in ("Field", "Type", "Required", "Default", "Description"):
+        grid.add_column(heading)
+    for column in spec.columns:
+        grid.add_row(
+            escape(column.name),
+            escape(column_type(column)),
+            "yes" if column.required else "",
+            escape(_default_text(column)),
+            escape(column.description or ""),
+        )
+    console.print(grid)
+    for index in spec.indexes:
+        kind = "primary key" if index.primary else ("unique" if index.unique else "")
+        columns = ", ".join(f.name + (" DESC" if f.descending else "") for f in index.fields)
+        console.print(
+            f"  [dim]index[/] {escape(index.name)} ({escape(columns)})"
+            + (f" [dim]{kind}[/]" if kind else "")
+        )
+
+
+def render(report: dict[str, Any]) -> None:
+    """Print a human-readable report."""
+    console = stdout()
+    console.print(
+        f"[bold]{escape(report['path'])}[/]  "
+        f"[dim](format {report['format_version']}, via {report['transport']})[/]"
+    )
+    for entry in report["tables"]:
+        _render_table(entry)
+    if report["relationships"]:
+        console.print("\n[bold cyan]Relationships[/]")
+        for rel in report["relationships"]:
+            rules = [
+                rule
+                for rule, on in (
+                    ("enforced", rel["enforce_integrity"]),
+                    ("cascade update", rel["cascade_update"]),
+                    ("cascade delete", rel["cascade_delete"]),
+                    ("one-to-one", rel["one_to_one"]),
+                )
+                if on
+            ]
+            primary = f"{rel['primary_table']}({', '.join(rel['primary_columns'])})"
+            foreign = f"{rel['foreign_table']}({', '.join(rel['foreign_columns'])})"
+            console.print(
+                f"  {escape(rel['name'] or '')}: {escape(primary)} -> {escape(foreign)}"
+                + (f"  [dim]{', '.join(rules)}[/]" if rules else "")
+            )
+    if report["queries"]:
+        console.print("\n[bold cyan]Queries[/]")
+        for query in report["queries"]:
+            lines = query["sql"].strip().splitlines()
+            first = lines[0][:100] if lines else ""
+            console.print(f"  {escape(query['name'])} [dim]({query['kind']})[/]  {escape(first)}")
+    for kind in OTHER_OBJECTS:
+        names = report[f"{kind.value}s"]
+        if names:
+            console.print(f"\n[bold cyan]{kind.value.title()}s[/]  {escape(', '.join(names))}")
+    for warning in report["warnings"]:
+        console.print(f"\n[yellow]warning:[/] {escape(warning)}")

pyaccesskit/database.py

@@ -0,0 +1,296 @@
+"""The :class:`AccessDatabase` facade — the entry point of PyAccessKit."""
+
+from __future__ import annotations
+
+import os
+import threading
+import uuid
+import warnings
+import weakref
+from collections.abc import Mapping
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Self
+
+from pyaccesskit._backends.protocols import PropertyTarget
+from pyaccesskit._session.session import Session
+from pyaccesskit.enums import Engine, Transport
+from pyaccesskit.errors import (
+    DatabaseExistsError,
+    DatabaseLockedError,
+    DatabaseNotFoundError,
+    SpecError,
+)
+from pyaccesskit.forms.collection import FormCollection
+from pyaccesskit.modules import ModuleCollection
+from pyaccesskit.objects import AccessObjects
+from pyaccesskit.options import SessionOptions
+from pyaccesskit.properties import PropertyBag
+from pyaccesskit.queries import QueryCollection
+from pyaccesskit.relationships import RelationshipCollection
+from pyaccesskit.tables import TableCollection
+
+__all__ = ["AccessDatabase", "RawAccess"]
+
+MAX_PATH_LENGTH = 255
+_EXTENSIONS = (".accdb", ".mdb", ".accde", ".mde")
+
+
+def _resolve(path: str | os.PathLike[str]) -> Path:
+    resolved = Path(path).expanduser().resolve()
+    if resolved.suffix.lower() not in _EXTENSIONS:
+        raise SpecError(
+            f"{resolved.name!r} is not an Access database file name (expected .accdb or .mdb)"
+        )
+    if len(str(resolved)) > MAX_PATH_LENGTH:
+        raise SpecError(
+            f"database paths are limited to {MAX_PATH_LENGTH} characters by DAO: {resolved}"
+        )
+    return resolved
+
+
+def _abandon(session: Session) -> None:
+    """Finalizer for sessions that were never closed (garbage collection or interpreter exit)."""
+    if session.state != "open":
+        return
+    warnings.warn(
+        f"PyAccessKit session for {session.target} was not closed; use 'with AccessDatabase...' or call "
+        "close(). Newly created databases are discarded.",
+        ResourceWarning,
+        stacklevel=2,
+    )
+    if threading.get_ident() == session.thread_id:
+        try:
+            session.close(error=RuntimeError("session abandoned"))
+        except BaseException:
+            session.terminate()
+    else:
+        session.terminate()
+
+
+class RawAccess:
+    """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.
+    """
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    @property
+    def dao(self) -> Any:
+        """The DAO ``Database`` object."""
+        return self._session.raw("dao")
+
+    @property
+    def dbengine(self) -> Any:
+        """The DAO ``DBEngine`` object."""
+        return self._session.raw("dbengine")
+
+    @property
+    def access(self) -> Any:
+        """The ``Access.Application`` object (switches the session to a design session if needed)."""
+        return self._session.raw("access")
+
+
+class AccessDatabase:
+    """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:
+        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.
+    """
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+        self.tables = TableCollection(session)
+        self.relationships = RelationshipCollection(session)
+        self.queries = QueryCollection(session)
+        self.forms = FormCollection(session)
+        self.modules = ModuleCollection(session)
+        self.objects = AccessObjects(session)
+        self.properties = PropertyBag(session, PropertyTarget.database())
+        self.raw = RawAccess(session)
+        self._finalizer = weakref.finalize(self, _abandon, session)
+
+    # ----------------------------------------------------------------------------- construction
+    @classmethod
+    def create(
+        cls,
+        path: str | os.PathLike[str],
+        *,
+        overwrite: bool = False,
+        atomic: bool = True,
+        engine: Engine | str = Engine.AUTO,
+        options: SessionOptions | None = None,
+    ) -> AccessDatabase:
+        """Create a new ``.accdb`` database.
+
+        Args:
+            path: Where to create the database.
+            overwrite: Replace an existing file at ``path``.
+            atomic: 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.
+            engine: ``"auto"`` (default), ``"dao"`` or ``"access"`` — see :class:`~pyaccesskit.enums.Engine`.
+            options: Advanced session options.
+
+        Raises:
+            DatabaseExistsError: If ``path`` exists and ``overwrite`` is false.
+        """
+        target = _resolve(path)
+        if target.suffix.lower() != ".accdb":
+            raise SpecError("PyAccessKit creates .accdb databases (Access 2007 and later format)")
+        if not target.parent.is_dir():
+            raise DatabaseNotFoundError(f"folder {target.parent} does not exist", path=target)
+        if target.exists() and not overwrite:
+            raise DatabaseExistsError(
+                f"{target} already exists (pass overwrite=True to replace it)", path=target
+            )
+        if atomic:
+            working = target.with_name(f".{target.stem}.pak-{uuid.uuid4().hex[:8]}{target.suffix}")
+        else:
+            working = target
+            if target.exists():
+                try:
+                    target.unlink()
+                except PermissionError as exc:
+                    raise DatabaseLockedError(
+                        f"cannot overwrite {target}: it is in use", path=target
+                    ) from exc
+        session = Session(
+            target=target,
+            working=working,
+            create=True,
+            readonly=False,
+            exclusive=True,
+            password=None,
+            engine=Engine(engine),
+            options=options or SessionOptions(),
+            overwrite=overwrite,
+        )
+        return cls(session)
+
+    @classmethod
+    def open(
+        cls,
+        path: str | os.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.
+
+        Args:
+            path: The database file.
+            readonly: Open read-only (also allows opening a database that is open in Access elsewhere).
+            exclusive: Open exclusively (default: ``True`` unless ``readonly``). Design changes need it.
+            password: Database password, if any.
+            engine: ``"auto"`` (default), ``"dao"`` or ``"access"``.
+            options: Advanced session options.
+
+        Raises:
+            DatabaseNotFoundError: If the file does not exist.
+            DatabaseLockedError: If it is in use elsewhere.
+        """
+        target = _resolve(path)
+        if not target.is_file():
+            raise DatabaseNotFoundError(f"{target} does not exist", path=target)
+        session = Session(
+            target=target,
+            working=target,
+            create=False,
+            readonly=readonly,
+            exclusive=(not readonly) if exclusive is None else exclusive,
+            password=password,
+            engine=Engine(engine),
+            options=options or SessionOptions(),
+        )
+        return cls(session)
+
+    # ----------------------------------------------------------------------------------- facts
+    @property
+    def path(self) -> Path:
+        """The database file (for atomic creation: where it will be when the session closes)."""
+        return self._session.target
+
+    @property
+    def transport(self) -> Transport:
+        """How the database is currently reached (in-process DAO, Access-hosted DAO, design session)."""
+        return self._session.transport
+
+    @property
+    def format_version(self) -> str:
+        """The database engine format (DAO ``Database.Version``): ``"12.0"`` for ``.accdb``, ``"4.0"`` for Jet 4."""
+        return self._session.schema().database_info().version
+
+    @property
+    def readonly(self) -> bool:
+        """Whether the database was opened read-only."""
+        return self._session.readonly
+
+    @property
+    def is_open(self) -> bool:
+        """Whether the session is still open."""
+        return self._session.state == "open"
+
+    @property
+    def access_pid(self) -> int | None:
+        """PID of the owned ``MSACCESS.EXE`` (``None`` when no Access process is used)."""
+        return getattr(self._session.engine_handle, "pid", None)
+
+    # ------------------------------------------------------------------------------------- data
+    def execute(self, 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.
+        """
+        self._session.check_writable("run SQL")
+        return self._session.schema().execute(sql, params)
+
+    def fetch_all(
+        self, 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."""
+        return self._session.schema().fetch(sql, params, limit=limit).as_dicts()
+
+    # ------------------------------------------------------------------------------------ close
+    def close(self) -> None:
+        """Close the session and release everything (idempotent; only from the thread that opened it)."""
+        self._session.check_thread()
+        self._finalizer.detach()
+        self._session.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self._session.check_thread()
+        self._finalizer.detach()
+        self._session.close(error=exc)
+
+    def __repr__(self) -> str:
+        state = self.transport.value if self.is_open else "closed"
+        return f"<AccessDatabase {str(self.path)!r} ({state})>"