pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/forms/layout.py

@@ -0,0 +1,300 @@
+"""Form layout engine: turns a :class:`FormSpec` into exact control geometry.
+
+The engine is pure Python — it never talks to Access — so layouts can be unit-tested and previewed. Two
+automatic layouts mirror Access's own control layouts:
+
+* **stacked** (single/split forms): one control per row, attached label on the left;
+* **tabular** (continuous/datasheet forms): labels in the form header, one row of controls in the detail.
+
+Controls with an explicit ``at=`` keep their position; their attached label goes to their left.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pyaccesskit.enums import FormView, LayoutKind, Section
+from pyaccesskit.errors import SpecError
+from pyaccesskit.forms.controls import ButtonSpec, CheckBoxSpec, ControlSpec, LabelSpec
+from pyaccesskit.forms.spec import FormSpec, label_name_for
+from pyaccesskit.forms.vba import EventBinding
+from pyaccesskit.units import Length, cm, inch
+
+__all__ = [
+    "DEFAULT_METRICS",
+    "MAX_FORM_EXTENT",
+    "LayoutMetrics",
+    "Rect",
+    "ResolvedControl",
+    "ResolvedForm",
+    "ResolvedLabel",
+    "layout_form",
+]
+
+MAX_FORM_EXTENT = inch(22)
+"""Access limit for form width and for each section's height."""
+
+
+@dataclass(frozen=True)
+class LayoutMetrics:
+    """Spacing and default sizes used by the automatic layouts."""
+
+    margin: Length = field(default_factory=lambda: cm(0.5))
+    label_width: Length = field(default_factory=lambda: cm(3.5))
+    label_gap: Length = field(default_factory=lambda: cm(0.25))
+    control_width: Length = field(default_factory=lambda: cm(6))
+    row_height: Length = field(default_factory=lambda: cm(0.6))
+    row_gap: Length = field(default_factory=lambda: cm(0.2))
+    checkbox_size: Length = field(default_factory=lambda: cm(0.45))
+    button_width: Length = field(default_factory=lambda: cm(3))
+    button_height: Length = field(default_factory=lambda: cm(0.8))
+    column_gap: Length = field(default_factory=lambda: cm(0.25))
+    tabular_column_width: Length = field(default_factory=lambda: cm(3.5))
+
+
+DEFAULT_METRICS = LayoutMetrics()
+
+
+@dataclass(frozen=True)
+class Rect:
+    """A rectangle in twips-backed lengths."""
+
+    left: Length
+    top: Length
+    width: Length
+    height: Length
+
+    @property
+    def right(self) -> Length:
+        """Right edge."""
+        return self.left + self.width
+
+    @property
+    def bottom(self) -> Length:
+        """Bottom edge."""
+        return self.top + self.height
+
+    def overlaps(self, other: Rect) -> bool:
+        """Whether the two rectangles share any area."""
+        return (
+            self.left < other.right
+            and other.left < self.right
+            and self.top < other.bottom
+            and other.top < self.bottom
+        )
+
+
+@dataclass(frozen=True)
+class ResolvedLabel:
+    """An attached label with its final geometry."""
+
+    name: str
+    caption: str
+    section: Section
+    rect: Rect
+
+
+@dataclass(frozen=True)
+class ResolvedControl:
+    """A control with its final name, section and geometry."""
+
+    spec: ControlSpec
+    name: str
+    section: Section
+    rect: Rect
+    label: ResolvedLabel | None = None
+
+
+@dataclass(frozen=True)
+class ResolvedForm:
+    """Everything the Access materializer needs to build the form."""
+
+    spec: FormSpec
+    width: Length
+    detail_height: Length
+    header_height: Length | None
+    """``None`` means the form has no header/footer sections."""
+    footer_height: Length | None
+    controls: tuple[ResolvedControl, ...]
+    events: tuple[EventBinding, ...]
+    module_text: str | None
+
+    @property
+    def has_header(self) -> bool:
+        """Whether the form needs header/footer sections."""
+        return self.header_height is not None
+
+
+def _default_size(
+    control: ControlSpec, m: LayoutMetrics, *, tabular: bool
+) -> tuple[Length, Length]:
+    if isinstance(control, CheckBoxSpec):
+        width, height = m.checkbox_size, m.checkbox_size
+    elif isinstance(control, ButtonSpec):
+        width, height = m.button_width, m.button_height
+    elif isinstance(control, LabelSpec):
+        width = m.tabular_column_width if tabular else m.label_width + m.label_gap + m.control_width
+        height = m.row_height
+    else:
+        width, height = (m.tabular_column_width if tabular else m.control_width), m.row_height
+    return control.width or width, control.height or height
+
+
+def _effective_layout(spec: FormSpec) -> LayoutKind:
+    if spec.layout is not LayoutKind.AUTO:
+        return spec.layout
+    if spec.default_view in (FormView.CONTINUOUS, FormView.DATASHEET):
+        return LayoutKind.TABULAR
+    return LayoutKind.STACKED
+
+
+def layout_form(spec: FormSpec, metrics: LayoutMetrics = DEFAULT_METRICS) -> ResolvedForm:
+    """Compute the geometry of every control of ``spec``.
+
+    Raises:
+        SpecError: If a control cannot be placed or the form exceeds Access's size limits.
+    """
+    m = metrics
+    kind = _effective_layout(spec)
+    tabular = kind is LayoutKind.TABULAR
+    controls = spec.resolved_controls()
+    cursors: dict[Section, Length] = dict.fromkeys(Section, m.margin)
+    tab_x = m.margin
+    placed: list[ResolvedControl] = []
+    label_x = m.margin
+    control_x = m.margin + m.label_width + m.label_gap
+
+    for control in controls:
+        name = control.name or ""
+        width, height = _default_size(control, m, tabular=tabular)
+        caption = control.attached_label
+        section = control.section
+
+        if control.at is not None:
+            left, top = control.at
+            rect = Rect(left, top, width, height)
+            label = None
+            if caption is not None:
+                label_left = left - m.label_gap - m.label_width
+                if label_left.twips < 0:
+                    raise SpecError(
+                        f"no room for the label of {name!r} left of its position; move it right, "
+                        "pass label=False, or add a free-standing label"
+                    )
+                label = ResolvedLabel(
+                    label_name_for(name),
+                    caption,
+                    section,
+                    Rect(label_left, top, m.label_width, m.row_height),
+                )
+            placed.append(ResolvedControl(control, name, section, rect, label))
+            continue
+
+        if kind is LayoutKind.NONE:
+            raise SpecError(f"layout='none' requires at=(left, top) for control {name!r}")
+
+        if tabular and section is Section.DETAIL:
+            # A column is as wide as the wider of its header label and its control; narrow controls
+            # (check boxes) are centred in their column.
+            column_width = (
+                width if isinstance(control, ButtonSpec) else max(width, m.tabular_column_width)
+            )
+            header_label = None
+            if caption is not None or isinstance(control, LabelSpec):
+                label_rect = Rect(tab_x, m.margin, column_width, m.row_height)
+                if isinstance(control, LabelSpec):
+                    placed.append(ResolvedControl(control, name, Section.HEADER, label_rect))
+                    tab_x = tab_x + column_width + m.column_gap
+                    continue
+                header_label = ResolvedLabel(
+                    label_name_for(name), caption or name, Section.HEADER, label_rect
+                )
+            left = tab_x + Length((column_width.twips - width.twips) // 2)
+            placed.append(
+                ResolvedControl(
+                    control, name, section, Rect(left, m.row_gap, width, height), header_label
+                )
+            )
+            tab_x = tab_x + column_width + m.column_gap
+            continue
+
+        # stacked (or tabular header/footer controls, which stack within their section)
+        top = cursors[section]
+        row_height = max(height, m.row_height)
+        if isinstance(control, LabelSpec):
+            rect = Rect(label_x, top, width, height)
+            placed.append(ResolvedControl(control, name, section, rect))
+        else:
+            offset = (
+                Length((row_height.twips - height.twips) // 2)
+                if isinstance(control, CheckBoxSpec)
+                else Length(0)
+            )
+            rect = Rect(control_x, top + offset, width, height)
+            label = None
+            if caption is not None:
+                label = ResolvedLabel(
+                    label_name_for(name),
+                    caption,
+                    section,
+                    Rect(label_x, top, m.label_width, m.row_height),
+                )
+            placed.append(ResolvedControl(control, name, section, rect, label))
+        cursors[section] = top + row_height + m.row_gap
+
+    def extent(section: Section) -> Length | None:
+        rects = [c.rect for c in placed if c.section is section]
+        rects += [
+            c.label.rect for c in placed if c.label is not None and c.label.section is section
+        ]
+        if not rects:
+            return None
+        return max(r.bottom for r in rects) + (
+            m.row_gap if tabular and section is Section.DETAIL else m.margin
+        )
+
+    all_rects = [c.rect for c in placed] + [c.label.rect for c in placed if c.label is not None]
+    width = max([r.right for r in all_rects], default=Length(0)) + m.margin
+    if spec.width is not None and spec.width > width:
+        width = spec.width
+
+    detail = extent(Section.DETAIL) or m.margin * 2
+    header_needed = any(
+        c.section is not Section.DETAIL
+        or (c.label is not None and c.label.section is not Section.DETAIL)
+        for c in placed
+    )
+    if spec.header is False and header_needed:
+        raise SpecError(
+            f"form {spec.name!r} has header=False, but its layout puts labels in the form header "
+            "(tabular layouts label their columns there); allow the header, pass label=False on the "
+            "controls, or use layout='stacked'"
+        )
+    has_header = spec.header if spec.header is not None else header_needed
+    header_height: Length | None = None
+    footer_height: Length | None = None
+    if has_header:
+        header_height = extent(Section.HEADER) or Length(0)
+        footer_height = extent(Section.FOOTER) or Length(0)
+
+    for label, value in (
+        ("form width", width),
+        ("detail height", detail),
+        ("header height", header_height),
+        ("footer height", footer_height),
+    ):
+        if value is not None and value > MAX_FORM_EXTENT:
+            raise SpecError(
+                f"{label} {value.format('cm')} exceeds Access's limit of {MAX_FORM_EXTENT.format('cm')}"
+            )
+
+    return ResolvedForm(
+        spec=spec,
+        width=width,
+        detail_height=detail,
+        header_height=header_height,
+        footer_height=footer_height,
+        controls=tuple(placed),
+        events=spec.event_bindings(),
+        module_text=spec.module_text(),
+    )

pyaccesskit/forms/spec.py

@@ -0,0 +1,169 @@
+"""Form specifications."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Self
+
+from pydantic import Field, field_validator, model_validator
+
+from pyaccesskit.enums import FormView, LayoutKind, ScrollBars, Section
+from pyaccesskit.forms.controls import ButtonSpec, ControlSpec, LabelSpec
+from pyaccesskit.forms.vba import EventBinding, Vba, build_module, is_vba_identifier
+from pyaccesskit.schema._base import Items, PropertyValue, SpecModel
+from pyaccesskit.schema.names import check_name
+from pyaccesskit.units import Length
+
+__all__ = ["FormSpec", "label_name_for"]
+
+
+_LABEL_SUFFIX = "_Label"
+_MAX_NAME = 64
+
+
+def label_name_for(control_name: str) -> str:
+    """The name of a control's attached label (``CustomerName`` → ``CustomerName_Label``).
+
+    Access names are limited to 64 characters. For long control names the name is shortened and a hash of
+    the full control name keeps it unique and stable (collisions are still checked by :class:`FormSpec`).
+    """
+    name = f"{control_name}{_LABEL_SUFFIX}"
+    if len(name) <= _MAX_NAME:
+        return name
+    digest = hashlib.sha1(control_name.encode("utf-8"), usedforsecurity=False).hexdigest()[:8]
+    keep = _MAX_NAME - len(_LABEL_SUFFIX) - len(digest) - 1
+    return f"{control_name[:keep]}_{digest}{_LABEL_SUFFIX}"
+
+
+class FormSpec(SpecModel):
+    """A form built by PyAccessKit.
+
+    Attributes:
+        name: Form name.
+        record_source: Table, query or SQL the form is bound to (``None`` for an unbound form).
+        caption: Window caption.
+        default_view: Single, continuous, datasheet or split form.
+        layout: How controls without ``at=`` are placed (``AUTO`` picks stacked or tabular).
+        header: Show the form header/footer sections; ``None`` = automatically when needed.
+        width: Minimum form width (grown to fit the controls).
+        controls: Controls in tab order.
+        on_load: VBA run by the form's Load event.
+        on_current: VBA run by the form's Current event.
+        module_code: Extra VBA appended to the form's module (helper procedures...).
+        option_explicit: Put ``Option Explicit`` at the top of the generated module.
+        properties: Other Access form properties to set verbatim (escape hatch).
+    """
+
+    name: str
+    record_source: str | None = None
+    caption: str | None = None
+    default_view: FormView = FormView.SINGLE
+    layout: LayoutKind = LayoutKind.AUTO
+    header: bool | None = None
+    width: Length | None = None
+    allow_additions: bool = True
+    allow_edits: bool = True
+    allow_deletions: bool = True
+    data_entry: bool = False
+    navigation_buttons: bool = True
+    record_selectors: bool = True
+    dividing_lines: bool = False
+    scroll_bars: ScrollBars = ScrollBars.BOTH
+    auto_center: bool = True
+    pop_up: bool = False
+    modal: bool = False
+    controls: Items[ControlSpec] = ()
+    on_load: Vba | None = None
+    on_current: Vba | None = None
+    module_code: str | None = None
+    option_explicit: bool = True
+    properties: dict[str, PropertyValue] = Field(default_factory=dict)
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, value: str) -> str:
+        return check_name(value, what="form name")
+
+    @model_validator(mode="after")
+    def _check_form(self) -> Self:
+        seen: dict[str, str] = {}
+
+        def claim(name: str, what: str) -> None:
+            key = name.casefold()
+            if key in seen:
+                raise ValueError(f"{what} name {name!r} is already used by {seen[key]}")
+            seen[key] = what
+
+        for index, control in enumerate(self.resolved_controls()):
+            name = control.name or ""
+            claim(name, f"control #{index + 1}")
+            if control.attached_label is not None:
+                claim(label_name_for(name), f"the label of {name!r}")
+        uses_sections = any(c.section is not Section.DETAIL for c in self.controls)
+        if uses_sections and self.header is False:
+            raise ValueError("controls are placed in the header/footer but header=False")
+        for binding in self.event_bindings():
+            if binding.object_name != "Form" and not is_vba_identifier(binding.object_name):
+                raise ValueError(
+                    f"control {binding.object_name!r} has an event procedure, so its name must be a plain "
+                    "VBA identifier (letters, digits, underscores)"
+                )
+        return self
+
+    # --------------------------------------------------------------------------------- derived data
+    def resolved_controls(self) -> tuple[ControlSpec, ...]:
+        """Controls with default names filled in (bound field name, else ``<Kind><n>``)."""
+        resolved: list[ControlSpec] = []
+        counters: dict[str, int] = {}
+        for control in self.controls:
+            if control.name is not None:
+                resolved.append(control)
+                continue
+            field = control.bound_field
+            if field is not None:
+                name = field
+            elif isinstance(control, ButtonSpec):
+                raise ValueError(
+                    "buttons need an explicit name (it is used by their event procedures)"
+                )
+            else:
+                prefix = (
+                    "Label"
+                    if isinstance(control, LabelSpec)
+                    else control.control_kind.value.capitalize()
+                )
+                counters[prefix] = counters.get(prefix, 0) + 1
+                name = f"{prefix}{counters[prefix]}"
+            resolved.append(control.model_copy(update={"name": name}))
+        return tuple(resolved)
+
+    def event_bindings(self) -> tuple[EventBinding, ...]:
+        """Every event procedure the form needs, form events first."""
+        bindings: list[EventBinding] = []
+        if self.on_load is not None:
+            bindings.append(EventBinding("Form", "OnLoad", "Load", self.on_load))
+        if self.on_current is not None:
+            bindings.append(EventBinding("Form", "OnCurrent", "Current", self.on_current))
+        for control in self.resolved_controls():
+            name = control.name or ""
+            if isinstance(control, ButtonSpec):
+                if control.on_click is not None:
+                    bindings.append(EventBinding(name, "OnClick", "Click", control.on_click))
+            elif not isinstance(control, LabelSpec) and control.after_update is not None:
+                bindings.append(
+                    EventBinding(name, "AfterUpdate", "AfterUpdate", control.after_update)
+                )
+        return tuple(bindings)
+
+    @property
+    def has_module(self) -> bool:
+        """Whether the form needs a class module (event procedures or extra code)."""
+        return bool(self.event_bindings()) or bool(self.module_code and self.module_code.strip())
+
+    def module_text(self) -> str | None:
+        """The complete VBA text of the form's module, or ``None`` if it needs none."""
+        if not self.has_module:
+            return None
+        return build_module(
+            self.event_bindings(), self.module_code, option_explicit=self.option_explicit
+        )

pyaccesskit/forms/vba.py

@@ -0,0 +1,138 @@
+# pyright: reportUnnecessaryIsInstance=false
+# (dataclass __post_init__ and render_literal validate untyped input at runtime)
+"""VBA snippets for event procedures and helpers that assemble form modules."""
+
+from __future__ import annotations
+
+import re
+import textwrap
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from pyaccesskit.errors import SpecError
+
+__all__ = [
+    "VBA_IDENTIFIER",
+    "EventBinding",
+    "Vba",
+    "build_module",
+    "event_procedure",
+    "is_vba_identifier",
+]
+
+VBA_IDENTIFIER = re.compile(r"^[A-Za-z][A-Za-z0-9_]{0,254}$")
+
+
+def is_vba_identifier(name: str) -> bool:
+    """Whether ``name`` can be used as-is in a VBA procedure name (``cmdSave_Click``)."""
+    return bool(VBA_IDENTIFIER.match(name))
+
+
+@dataclass(frozen=True)
+class Vba:
+    """The body of a VBA event procedure, e.g. ``Vba("DoCmd.Close acForm, Me.Name")``.
+
+    Indentation is normalized; write the body only (no ``Sub``/``End Sub``).
+    """
+
+    code: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.code, str) or not self.code.strip():
+            raise SpecError("Vba requires non-empty code")
+        if re.search(r"^\s*(Private\s+|Public\s+)?Sub\s", self.code, re.IGNORECASE | re.MULTILINE):
+            raise SpecError("Vba holds a procedure *body*; do not include 'Sub ... End Sub'")
+
+    def lines(self) -> list[str]:
+        """The body lines, dedented, without trailing blank lines."""
+        text = textwrap.dedent(self.code.replace("\r\n", "\n").replace("\r", "\n")).strip("\n")
+        return [line.rstrip() for line in text.split("\n")]
+
+
+@dataclass(frozen=True)
+class EventBinding:
+    """An event wired to an ``[Event Procedure]``.
+
+    Attributes:
+        object_name: ``"Form"`` or a control name.
+        property_name: The Access event property, e.g. ``"OnClick"``.
+        event: The VBA event name, e.g. ``"Click"``.
+        body: The procedure body.
+    """
+
+    object_name: str
+    property_name: str
+    event: str
+    body: Vba
+
+    @property
+    def procedure_name(self) -> str:
+        """The VBA procedure name, e.g. ``cmdClose_Click``."""
+        return f"{self.object_name}_{self.event}"
+
+
+def event_procedure(binding: EventBinding) -> str:
+    """Render ``Private Sub <object>_<event>() ... End Sub`` (CRLF line endings)."""
+    body = "\r\n".join(f"    {line}" if line else "" for line in binding.body.lines())
+    return f"Private Sub {binding.procedure_name}()\r\n{body}\r\nEnd Sub\r\n"
+
+
+def build_module(
+    bindings: Sequence[EventBinding], extra_code: str | None = None, *, option_explicit: bool = True
+) -> str:
+    """Assemble a complete class-module text for a form: options, event procedures, extra code."""
+    header = ["Option Compare Database"]
+    if option_explicit:
+        header.append("Option Explicit")
+    declarations, procedures = split_declarations(extra_code or "")
+    parts = ["\r\n".join(header) + "\r\n"]
+    # VBA only accepts module-level declarations before the first procedure.
+    if declarations:
+        parts.append(_crlf(declarations))
+    parts.extend(event_procedure(binding) for binding in bindings)
+    if procedures:
+        parts.append(_crlf(procedures))
+    return "\r\n".join(parts)
+
+
+_PROCEDURE_START = re.compile(
+    r"^\s*(?:(?:Public|Private|Friend)\s+)?(?:Static\s+)?(?:Sub|Function|Property\s+(?:Get|Let|Set))\s",
+    re.IGNORECASE,
+)
+_DIRECTIVE_IF = re.compile(r"^\s*#If\b", re.IGNORECASE)
+_DIRECTIVE_END_IF = re.compile(r"^\s*#End\s*If\b", re.IGNORECASE)
+_OPTION_LINE = re.compile(r"^\s*Option\s+(?:Compare|Explicit)\b", re.IGNORECASE)
+
+
+def split_declarations(code: str) -> tuple[str, str]:
+    """Split VBA into its declarations section and its procedures (``Option`` lines are dropped).
+
+    Everything before the first ``Sub``/``Function``/``Property`` is the declarations section; comments
+    directly above that procedure stay with it. A ``#If ... #End If`` block containing that procedure is
+    never split: it moves to the procedures as a whole.
+    """
+    lines = [
+        line
+        for line in code.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+        if not _OPTION_LINE.match(line)
+    ]
+    start = len(lines)
+    depth, block_start = 0, 0
+    for index, line in enumerate(lines):
+        if _DIRECTIVE_IF.match(line):
+            if depth == 0:
+                block_start = index
+            depth += 1
+        elif _DIRECTIVE_END_IF.match(line):
+            depth = max(depth - 1, 0)
+        elif _PROCEDURE_START.match(line):
+            # Never split inside #If ... #End If: the whole conditional block goes with the procedures.
+            start = block_start if depth else index
+            break
+    while start > 0 and lines[start - 1].lstrip().startswith("'"):
+        start -= 1
+    return "\n".join(lines[:start]).strip("\n"), "\n".join(lines[start:]).strip("\n")
+
+
+def _crlf(code: str) -> str:
+    return code.replace("\n", "\r\n") + "\r\n"

pyaccesskit/maintenance.py

@@ -0,0 +1,32 @@
+"""Maintenance helpers: cleaning up orphaned Access processes."""
+
+from __future__ import annotations
+
+import sys
+
+from pyaccesskit import _ledger
+from pyaccesskit._ledger import OwnedProcess, ReapResult
+
+__all__ = ["OwnedProcess", "ReapResult", "owned_processes", "reap_orphans"]
+
+
+def owned_processes() -> list[OwnedProcess]:
+    """Access processes currently recorded in PyAccessKit's ownership ledger (from any Python process)."""
+    return [entry for _path, entry in _ledger.load_all()]
+
+
+def reap_orphans(*, dry_run: bool = False) -> list[ReapResult]:
+    """Terminate Access processes that PyAccessKit started but whose Python owner has died.
+
+    Only processes recorded in the ownership ledger are considered, and each one is terminated only if its
+    owner is gone *and* its PID, creation time and image (``MSACCESS.EXE``) still match. Access instances
+    started by the user or by other tools are never touched.
+
+    Args:
+        dry_run: Report what would be terminated without terminating anything.
+    """
+    if sys.platform != "win32":
+        return []  # Access only runs on Windows: nothing can have been started here
+    from pyaccesskit._win.inspector import Win32Inspector
+
+    return _ledger.reap_orphans(Win32Inspector(), dry_run=dry_run)