pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/_ledger.py

@@ -0,0 +1,158 @@
+"""The ownership ledger: a record of every Access process PyAccessKit started.
+
+Each live Access process owned by PyAccessKit has a small JSON file in
+``%LOCALAPPDATA%/PyAccessKit/owned``. It is deleted when the process is shut down cleanly. If Python died
+before that (and the kill-on-close job object could not be used), :func:`reap_orphans` finds the leftovers.
+
+A process is only ever terminated when **all** of these hold:
+
+* its owner (the Python process that started it) is gone — PID *and* creation time checked;
+* a process with the recorded PID *and* creation time still exists (so the PID was not recycled);
+* its image is ``MSACCESS.EXE`` (checked again by the inspector right before terminating).
+
+This module is pure Python; the Windows-specific inspector lives in ``_win.inspector``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from collections.abc import Iterator
+from dataclasses import asdict, dataclass
+from pathlib import Path, PureWindowsPath
+from typing import Literal, Protocol
+
+__all__ = [
+    "OwnedProcess",
+    "ProcessInspector",
+    "ReapResult",
+    "ledger_dir",
+    "load_all",
+    "reap_orphans",
+    "record",
+    "remove",
+]
+
+logger = logging.getLogger("pyaccesskit.process")
+
+LEDGER_ENV = "PYACCESSKIT_LEDGER_DIR"
+
+
+@dataclass(frozen=True)
+class OwnedProcess:
+    """One ledger entry."""
+
+    pid: int
+    creation_time: float
+    image: str
+    owner_pid: int
+    owner_creation_time: float
+    database: str | None
+    started_at: float
+    version: str
+
+    @property
+    def file_name(self) -> str:
+        """Ledger file name (unique per process identity)."""
+        return f"{self.pid}-{int(self.creation_time * 1000)}.json"
+
+
+class ProcessInspector(Protocol):
+    """Answers questions about processes; implemented with Win32 calls in ``_win.inspector``."""
+
+    def matches(self, pid: int, creation_time: float) -> bool:
+        """Whether a running process has exactly this PID and creation time."""
+        ...
+
+    def terminate(self, pid: int, creation_time: float, image_name: str) -> bool:
+        """Terminate the process if (re-verified) it has this identity and image; return success."""
+        ...
+
+
+@dataclass(frozen=True)
+class ReapResult:
+    """What :func:`reap_orphans` did with one ledger entry."""
+
+    entry: OwnedProcess
+    action: Literal["terminated", "would-terminate", "already-exited", "owner-alive", "failed"]
+
+
+def ledger_dir() -> Path:
+    """The ledger directory (``PYACCESSKIT_LEDGER_DIR`` overrides it, e.g. in tests)."""
+    override = os.environ.get(LEDGER_ENV)
+    if override:
+        return Path(override)
+    base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+    return Path(base) / "PyAccessKit" / "owned"
+
+
+def record(entry: OwnedProcess, directory: Path | None = None) -> Path:
+    """Write a ledger entry atomically; returns its path."""
+    folder = directory or ledger_dir()
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / entry.file_name
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(asdict(entry), indent=2), encoding="utf-8")
+    temporary.replace(path)
+    return path
+
+
+def remove(path: Path) -> None:
+    """Delete a ledger entry (missing files are fine)."""
+    try:
+        path.unlink(missing_ok=True)
+    except (
+        OSError
+    ) as exc:  # pragma: no cover - e.g. a locked file; the entry is simply reaped later
+        logger.debug("could not delete ledger entry %s: %s", path, exc)
+
+
+def load_all(directory: Path | None = None) -> Iterator[tuple[Path, OwnedProcess]]:
+    """Yield every readable ledger entry (unreadable files are skipped and logged)."""
+    folder = directory or ledger_dir()
+    if not folder.is_dir():
+        return
+    for path in sorted(folder.glob("*.json")):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            yield path, OwnedProcess(**data)
+        except (OSError, ValueError, TypeError) as exc:
+            logger.warning("ignoring unreadable ledger entry %s: %s", path, exc)
+
+
+def reap_orphans(
+    inspector: ProcessInspector, *, dry_run: bool = False, directory: Path | None = None
+) -> list[ReapResult]:
+    """Terminate Access processes whose PyAccessKit owner died without shutting them down.
+
+    Args:
+        inspector: Process inspector (Win32 implementation by default in the public API).
+        dry_run: Report what would be terminated without terminating anything.
+        directory: Ledger directory override.
+    """
+    results: list[ReapResult] = []
+    for path, entry in load_all(directory):
+        if inspector.matches(entry.owner_pid, entry.owner_creation_time):
+            results.append(ReapResult(entry, "owner-alive"))
+            continue
+        if not inspector.matches(entry.pid, entry.creation_time):
+            if not dry_run:
+                remove(path)
+            results.append(ReapResult(entry, "already-exited"))
+            continue
+        if dry_run:
+            results.append(ReapResult(entry, "would-terminate"))
+            continue
+        if inspector.terminate(entry.pid, entry.creation_time, PureWindowsPath(entry.image).name):
+            remove(path)
+            results.append(ReapResult(entry, "terminated"))
+        else:
+            results.append(ReapResult(entry, "failed"))
+    return results
+
+
+def now() -> float:
+    """Current time (seconds since the epoch); separated for tests."""
+    return time.time()

pyaccesskit/_ops/design.py

@@ -0,0 +1,127 @@
+"""Design operations (forms, modules, raw text objects): validation first, then the design backend."""
+
+from __future__ import annotations
+
+from pyaccesskit._backends.protocols import DesignBackend, SchemaBackend
+from pyaccesskit._ops.schema import find_query, find_table
+from pyaccesskit._text import codec
+from pyaccesskit.enums import ModuleKind, ObjectKind
+from pyaccesskit.errors import ObjectExistsError, ObjectNotFoundError, SpecError
+from pyaccesskit.forms.layout import ResolvedForm, layout_form
+from pyaccesskit.forms.spec import FormSpec
+from pyaccesskit.schema.names import check_name, warn_name
+
+__all__ = [
+    "DESIGN_KINDS",
+    "build_form",
+    "create_module",
+    "export_object",
+    "find_object",
+    "import_object",
+    "read_module",
+]
+
+DESIGN_KINDS = (ObjectKind.FORM, ObjectKind.REPORT, ObjectKind.MACRO, ObjectKind.MODULE)
+_SQL_PREFIXES = ("SELECT", "PARAMETERS", "TRANSFORM", "(")
+
+
+def _check_kind(kind: ObjectKind) -> None:
+    if kind not in DESIGN_KINDS and kind is not ObjectKind.QUERY:
+        raise SpecError(f"{kind.value} objects cannot be exported/imported as text")
+
+
+def find_object(design: DesignBackend, kind: ObjectKind, name: str) -> str | None:
+    """The actual name of a form/report/macro/module called ``name`` (case-insensitive), or ``None``."""
+    key = name.casefold()
+    return next((n for n in design.list_objects(kind) if n.casefold() == key), None)
+
+
+def build_form(
+    schema: SchemaBackend, design: DesignBackend, spec: FormSpec, *, replace: bool = False
+) -> ResolvedForm:
+    """Validate ``spec`` against the database, lay it out, and build it atomically."""
+    resolved = layout_form(spec)
+    existing = find_object(design, ObjectKind.FORM, spec.name)
+    if existing is not None and not replace:
+        raise ObjectExistsError(
+            f"a form named {existing!r} already exists (pass replace=True to rebuild it)",
+            kind=ObjectKind.FORM,
+            name=spec.name,
+        )
+    source = spec.record_source
+    if source is not None and not source.lstrip().upper().startswith(_SQL_PREFIXES):
+        table = find_table(schema, source)
+        if table is None and find_query(schema, source) is None:
+            raise ObjectNotFoundError(
+                f"record source {source!r} of form {spec.name!r} is neither a table nor a query",
+                kind=ObjectKind.TABLE,
+                name=source,
+            )
+        if table is not None:
+            columns = schema.read_table(table.name).column_names
+            known = {c.casefold() for c in columns}
+            for control in resolved.controls:
+                field = control.spec.bound_field
+                if field is not None and field.casefold() not in known:
+                    raise SpecError(
+                        f"control {control.name!r} of form {spec.name!r} is bound to {field!r}, which is not a "
+                        f"column of {table.name!r} (columns: {', '.join(columns)})"
+                    )
+    warn_name(spec.name, what="form name", stacklevel=4)
+    design.build_form(resolved, replace=existing is not None)
+    return resolved
+
+
+def create_module(
+    design: DesignBackend,
+    name: str,
+    code: str,
+    kind: ModuleKind = ModuleKind.STANDARD,
+    *,
+    replace: bool = False,
+) -> None:
+    """Create (or replace) a VBA module from source code."""
+    check_name(name, what="module name")
+    existing = find_object(design, ObjectKind.MODULE, name)
+    if existing is not None and not replace:
+        raise ObjectExistsError(
+            f"a module named {existing!r} already exists (pass replace=True to overwrite it)",
+            kind=ObjectKind.MODULE,
+            name=name,
+        )
+    text = codec.module_import_text(code, kind)
+    data = codec.encode_import(ObjectKind.MODULE, text)
+    design.import_text(ObjectKind.MODULE, existing or name, data)
+
+
+def read_module(design: DesignBackend, name: str) -> tuple[ModuleKind, str]:
+    """Return ``(kind, code)`` of a VBA module."""
+    actual = find_object(design, ObjectKind.MODULE, name)
+    if actual is None:
+        raise ObjectNotFoundError(
+            f"module {name!r} does not exist", kind=ObjectKind.MODULE, name=name
+        )
+    text = codec.decode_export(ObjectKind.MODULE, design.export_text(ObjectKind.MODULE, actual))
+    return codec.split_module_export(text)
+
+
+def export_object(design: DesignBackend, kind: ObjectKind, name: str) -> str:
+    """``SaveAsText`` an object and return its text (LF line endings)."""
+    _check_kind(kind)
+    return codec.decode_export(kind, design.export_text(kind, name))
+
+
+def import_object(
+    design: DesignBackend, kind: ObjectKind, name: str, text: str, *, replace: bool = False
+) -> None:
+    """``LoadFromText`` an object from text (encoded the way Access expects for ``kind``)."""
+    _check_kind(kind)
+    check_name(name, what=f"{kind.value} name")
+    existing = find_object(design, kind, name)
+    if existing is not None and not replace:  # LoadFromText would overwrite without asking
+        raise ObjectExistsError(
+            f"a {kind.value} named {existing!r} already exists (pass replace=True to overwrite it)",
+            kind=kind,
+            name=name,
+        )
+    design.import_text(kind, name, codec.encode_import(kind, text))