pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/forms/builder.py

@@ -0,0 +1,295 @@
+"""Fluent builder for :class:`FormSpec` objects.
+
+The builder never talks to Access. It accumulates controls and produces a validated :class:`FormSpec`;
+when obtained from ``db.forms.create(...)`` it also knows how to *save* itself, which builds the whole form
+in one atomic step (nothing is created in Access until then)::
+
+    with db.forms.create("frmCustomers", record_source="Customers") as form:
+        form.textbox("CustomerName", label="Customer name")
+        form.checkbox("IsActive")
+        form.button("cmdClose", caption="Close", on_click="DoCmd.Close acForm, Me.Name")
+    # saved here; if the block raises, nothing is created
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable, Sequence
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Generic, Literal, Self, TypeVar
+
+from pyaccesskit.enums import RowSourceType, Section
+from pyaccesskit.errors import PyAccessKitError
+from pyaccesskit.forms.controls import (
+    ButtonSpec,
+    CheckBoxSpec,
+    ComboBoxSpec,
+    ControlSpec,
+    LabelSpec,
+    TextBoxSpec,
+)
+from pyaccesskit.forms.spec import FormSpec
+from pyaccesskit.forms.vba import Vba
+from pyaccesskit.schema._base import PropertyValue, build
+from pyaccesskit.units import Length
+
+if TYPE_CHECKING:
+    from typing_extensions import TypedDict, Unpack
+
+    class _ControlOptions(TypedDict, total=False):
+        name: str | None
+        section: Section
+        at: tuple[Length, Length] | None
+        width: Length | None
+        height: Length | None
+        visible: bool
+        properties: dict[str, PropertyValue]
+
+
+__all__ = ["FormBuilder"]
+
+_R = TypeVar("_R")
+
+
+def _vba(code: str | Vba | None) -> Vba | None:
+    if code is None or isinstance(code, Vba):
+        return code
+    return Vba(code)
+
+
+class FormBuilder(Generic[_R]):
+    """Accumulates controls for a form and produces a :class:`FormSpec`.
+
+    Args:
+        name: Form name.
+        on_save: Called with the finished spec by :meth:`save` (set by ``db.forms.create``); its return
+            value is returned by :meth:`save`.
+        **form_options: Any other :class:`FormSpec` field (``record_source``, ``caption``,
+            ``default_view``...).
+    """
+
+    def __init__(
+        self, name: str, *, on_save: Callable[[FormSpec], _R] | None = None, **form_options: Any
+    ) -> None:
+        self._name = name
+        self._options: dict[str, Any] = dict(form_options)
+        self._controls: list[ControlSpec] = []
+        self._on_save = on_save
+        self._state: Literal["open", "saved", "discarded"] = "open"
+        # Validate the form-level options immediately so mistakes surface at the call site.
+        build(FormSpec, f"form {name!r}", name=name, **self._options)
+
+    # ------------------------------------------------------------------------------------ controls
+    def add(self, control: ControlSpec) -> Self:
+        """Append an already-built control spec."""
+        self._check_open()
+        self._controls.append(control)
+        return self
+
+    def textbox(
+        self,
+        field: str | None = None,
+        *,
+        label: str | Literal[False] | None = None,
+        control_source: str | None = None,
+        format: str | None = None,
+        enabled: bool = True,
+        locked: bool = False,
+        after_update: str | Vba | None = None,
+        **options: Unpack[_ControlOptions],
+    ) -> Self:
+        """Add a text box bound to ``field`` (or showing ``control_source="=..."``)."""
+        return self.add(
+            build(
+                TextBoxSpec,
+                f"text box {options.get('name') or field!r}",
+                field=field,
+                label=label,
+                control_source=control_source,
+                format=format,
+                enabled=enabled,
+                locked=locked,
+                after_update=_vba(after_update),
+                **options,
+            )
+        )
+
+    def checkbox(
+        self,
+        field: str | None = None,
+        *,
+        label: str | Literal[False] | None = None,
+        enabled: bool = True,
+        locked: bool = False,
+        after_update: str | Vba | None = None,
+        **options: Unpack[_ControlOptions],
+    ) -> Self:
+        """Add a check box bound to ``field``."""
+        return self.add(
+            build(
+                CheckBoxSpec,
+                f"check box {options.get('name') or field!r}",
+                field=field,
+                label=label,
+                enabled=enabled,
+                locked=locked,
+                after_update=_vba(after_update),
+                **options,
+            )
+        )
+
+    def combobox(
+        self,
+        field: str | None = None,
+        *,
+        row_source: str,
+        row_source_type: RowSourceType = RowSourceType.TABLE_QUERY,
+        bound_column: int = 1,
+        column_count: int = 1,
+        column_widths: Sequence[Length] | None = None,
+        limit_to_list: bool = True,
+        label: str | Literal[False] | None = None,
+        enabled: bool = True,
+        locked: bool = False,
+        after_update: str | Vba | None = None,
+        **options: Unpack[_ControlOptions],
+    ) -> Self:
+        """Add a combo box bound to ``field`` with rows from ``row_source``."""
+        return self.add(
+            build(
+                ComboBoxSpec,
+                f"combo box {options.get('name') or field!r}",
+                field=field,
+                row_source=row_source,
+                row_source_type=row_source_type,
+                bound_column=bound_column,
+                column_count=column_count,
+                column_widths=column_widths,
+                limit_to_list=limit_to_list,
+                label=label,
+                enabled=enabled,
+                locked=locked,
+                after_update=_vba(after_update),
+                **options,
+            )
+        )
+
+    def label(self, caption: str, **options: Unpack[_ControlOptions]) -> Self:
+        """Add a free-standing label."""
+        return self.add(build(LabelSpec, f"label {caption!r}", caption=caption, **options))
+
+    def button(
+        self,
+        name: str,
+        *,
+        caption: str,
+        on_click: str | Vba | None = None,
+        section: Section = Section.DETAIL,
+        at: tuple[Length, Length] | None = None,
+        width: Length | None = None,
+        height: Length | None = None,
+        visible: bool = True,
+        properties: dict[str, PropertyValue] | None = None,
+    ) -> Self:
+        """Add a command button; ``on_click`` is the VBA body of its Click event procedure."""
+        return self.add(
+            build(
+                ButtonSpec,
+                f"button {name!r}",
+                name=name,
+                caption=caption,
+                on_click=_vba(on_click),
+                section=section,
+                at=at,
+                width=width,
+                height=height,
+                visible=visible,
+                properties=properties or {},
+            )
+        )
+
+    # ---------------------------------------------------------------------------- form-level code
+    def on_load(self, code: str | Vba) -> Self:
+        """Set the VBA body of the form's Load event."""
+        self._check_open()
+        self._options["on_load"] = _vba(code)
+        return self
+
+    def on_current(self, code: str | Vba) -> Self:
+        """Set the VBA body of the form's Current event."""
+        self._check_open()
+        self._options["on_current"] = _vba(code)
+        return self
+
+    def module_code(self, code: str) -> Self:
+        """Append extra VBA (helper procedures, module-level declarations) to the form's module."""
+        self._check_open()
+        existing = self._options.get("module_code") or ""
+        self._options["module_code"] = f"{existing}\n{code}" if existing else code
+        return self
+
+    # ------------------------------------------------------------------------------------ results
+    def to_spec(self) -> FormSpec:
+        """Validate and return the finished :class:`FormSpec`."""
+        return build(
+            FormSpec,
+            f"form {self._name!r}",
+            name=self._name,
+            controls=tuple(self._controls),
+            **self._options,
+        )
+
+    def save(self) -> _R:
+        """Build the form in Access (atomically) and return the result of ``on_save``.
+
+        Raises:
+            PyAccessKitError: If the builder has no save target or was already saved/discarded.
+        """
+        self._check_open()
+        if self._on_save is None:
+            raise PyAccessKitError(
+                "this FormBuilder is standalone; use to_spec() or db.forms.create(...)"
+            )
+        spec = self.to_spec()
+        result = self._on_save(spec)
+        self._state = "saved"
+        return result
+
+    def discard(self) -> None:
+        """Abandon the builder without creating anything."""
+        self._state = "discarded"
+
+    @property
+    def is_saved(self) -> bool:
+        """Whether :meth:`save` completed."""
+        return self._state == "saved"
+
+    def _check_open(self) -> None:
+        if self._state != "open":
+            raise PyAccessKitError(f"form builder {self._name!r} was already {self._state}")
+
+    # ------------------------------------------------------------------------------ context manager
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        if exc_type is not None:
+            self.discard()
+        elif self._state == "open":
+            self.save()
+
+    def __del__(self) -> None:
+        if getattr(self, "_state", None) == "open" and getattr(self, "_on_save", None) is not None:
+            warnings.warn(
+                f"form {self._name!r} was never saved; call .save() or use 'with db.forms.create(...)'",
+                ResourceWarning,
+                stacklevel=2,
+            )
+
+    def __repr__(self) -> str:
+        return f"<FormBuilder {self._name!r} controls={len(self._controls)} state={self._state}>"

pyaccesskit/forms/collection.py

@@ -0,0 +1,117 @@
+"""Forms: the ``db.forms`` collection and :class:`Form` handles (building forms needs Microsoft Access)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
+
+from pyaccesskit._backends.protocols import ControlInfo
+from pyaccesskit._ops import design as design_ops
+from pyaccesskit.enums import ObjectKind
+from pyaccesskit.errors import ObjectNotFoundError
+from pyaccesskit.forms.builder import FormBuilder
+from pyaccesskit.forms.layout import ResolvedForm
+from pyaccesskit.forms.spec import FormSpec
+
+if TYPE_CHECKING:
+    from pyaccesskit._session.session import Session
+
+__all__ = ["Form", "FormCollection"]
+
+
+class Form:
+    """A saved form (a live, name-based handle)."""
+
+    def __init__(self, session: Session, name: str) -> None:
+        self._session = session
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        """The form name."""
+        return self._name
+
+    def controls(self) -> list[ControlInfo]:
+        """The form's controls as saved (opens the form hidden in Design view)."""
+        return self._session.design().form_controls(self._name)
+
+    def check_opens(self) -> None:
+        """Open the form in Form view (hidden) and close it; raises if Access reports a problem."""
+        self._session.design().check_form_opens(self._name)
+
+    def export_text(self) -> str:
+        """The form in Access's ``SaveAsText`` format."""
+        return design_ops.export_object(self._session.design(), ObjectKind.FORM, self._name)
+
+    def rename(self, new_name: str) -> None:
+        """Rename the form."""
+        self._session.check_writable(f"rename form {self._name!r}")
+        self._session.design().rename_object(ObjectKind.FORM, self._name, new_name)
+        self._name = new_name
+
+    def drop(self) -> None:
+        """Delete the form."""
+        self._session.check_writable(f"drop form {self._name!r}")
+        self._session.design().delete_object(ObjectKind.FORM, self._name)
+
+    def __repr__(self) -> str:
+        return f"<Form {self._name!r}>"
+
+
+class FormCollection:
+    """``db.forms``."""
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    def names(self) -> list[str]:
+        """Form names (read through DAO; does not need Microsoft Access)."""
+        return self._session.schema().list_documents(ObjectKind.FORM)
+
+    def __iter__(self) -> Iterator[Form]:
+        return iter([Form(self._session, name) for name in self.names()])
+
+    def __len__(self) -> int:
+        return len(self.names())
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and any(n.casefold() == name.casefold() for n in self.names())
+
+    def __getitem__(self, name: str) -> Form:
+        for actual in self.names():
+            if actual.casefold() == name.casefold():
+                return Form(self._session, actual)
+        raise ObjectNotFoundError(f"form {name!r} does not exist", kind=ObjectKind.FORM, name=name)
+
+    def create(self, name: str, *, replace: bool = False, **form_options: Any) -> FormBuilder[Form]:
+        """Start building a form; nothing is created in Access until the builder is saved.
+
+        Example::
+
+            with db.forms.create("frmCustomers", record_source="Customers") as form:
+                form.textbox("CustomerName")
+            # built atomically here
+
+        Args:
+            name: Form name.
+            replace: Rebuild the form if it already exists (atomically swapped in).
+            **form_options: Any :class:`~pyaccesskit.forms.FormSpec` field (``record_source``, ``caption``,
+                ``default_view``...).
+        """
+        return FormBuilder(
+            name, on_save=lambda spec: self.build(spec, replace=replace), **form_options
+        )
+
+    def build(self, spec: FormSpec, *, replace: bool = False) -> Form:
+        """Build a form from a finished :class:`FormSpec` (atomically)."""
+        self._session.check_writable(f"build form {spec.name!r}")
+        # design() may switch engines (closing in-process DAO), so resolve the schema backend afterwards.
+        design = self._session.design()
+        resolved: ResolvedForm = design_ops.build_form(
+            self._session.schema(), design, spec, replace=replace
+        )
+        return Form(self._session, resolved.spec.name)
+
+    def drop(self, name: str) -> None:
+        """Delete a form."""
+        self[name].drop()

pyaccesskit/forms/controls.py

@@ -0,0 +1,157 @@
+"""Specifications of form controls.
+
+Each control kind is its own spec class; together they form the discriminated union :data:`ControlSpec`
+(``kind`` is the discriminator). Positions and sizes are :class:`~pyaccesskit.units.Length` values and are
+optional: the layout engine places controls that have no explicit ``at=``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, Self
+
+from pydantic import Field, field_validator, model_validator
+
+from pyaccesskit.enums import ControlKind, RowSourceType, Section
+from pyaccesskit.forms.vba import Vba
+from pyaccesskit.schema._base import Items, PropertyValue, SpecModel
+from pyaccesskit.schema.names import check_name
+from pyaccesskit.units import Length
+
+__all__ = [
+    "ButtonSpec",
+    "CheckBoxSpec",
+    "ComboBoxSpec",
+    "ControlBase",
+    "ControlSpec",
+    "LabelSpec",
+    "TextBoxSpec",
+]
+
+
+class ControlBase(SpecModel):
+    """Options shared by all controls.
+
+    Attributes:
+        name: Control name. Bound controls default to their field name.
+        section: Form section holding the control.
+        at: Explicit ``(left, top)`` position; ``None`` lets the layout engine place it.
+        width: Explicit width (defaults depend on the control kind).
+        height: Explicit height.
+        visible: Whether the control is visible in Form view.
+        properties: Other Access control properties to set verbatim (escape hatch).
+    """
+
+    name: str | None = None
+    section: Section = Section.DETAIL
+    at: tuple[Length, Length] | None = None
+    width: Length | None = None
+    height: Length | None = None
+    visible: bool = True
+    properties: dict[str, PropertyValue] = Field(default_factory=dict)
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, value: str | None) -> str | None:
+        return None if value is None else check_name(value, what="control name")
+
+    @property
+    def control_kind(self) -> ControlKind:
+        """The kind of control."""
+        return ControlKind(getattr(self, "kind"))  # noqa: B009 - defined by each subclass
+
+    @property
+    def bound_field(self) -> str | None:
+        """The bound field name, if the control is bound to a field."""
+        return getattr(self, "field", None)
+
+    @property
+    def attached_label(self) -> str | None:
+        """The attached label caption, or ``None`` if the control has no attached label."""
+        return None
+
+
+class _BoundControl(ControlBase):
+    field: str | None = None
+    label: str | Literal[False] | None = None
+    """Attached label: ``None`` = the field name, ``False`` = no label, or explicit text."""
+    enabled: bool = True
+    locked: bool = False
+    after_update: Vba | None = None
+
+    @field_validator("field")
+    @classmethod
+    def _check_field(cls, value: str | None) -> str | None:
+        return None if value is None else check_name(value, what="field name")
+
+    @property
+    def attached_label(self) -> str | None:
+        """Label caption (defaults to the bound field or control name)."""
+        if self.label is False:
+            return None
+        if self.label is not None:
+            return self.label
+        return self.field or self.name
+
+
+class LabelSpec(ControlBase):
+    """A free-standing label."""
+
+    kind: Literal["label"] = "label"
+    caption: str
+
+
+class TextBoxSpec(_BoundControl):
+    """A text box bound to ``field`` or showing a calculated ``control_source`` (``"=[Qty]*[Price]"``)."""
+
+    kind: Literal["textbox"] = "textbox"
+    control_source: str | None = None
+    format: str | None = None
+
+    @model_validator(mode="after")
+    def _check_source(self) -> Self:
+        if self.field is not None and self.control_source is not None:
+            raise ValueError("give either field= or control_source=, not both")
+        if self.control_source is not None and not self.control_source.startswith("="):
+            raise ValueError("control_source expressions start with '=' (e.g. '=[Qty]*[Price]')")
+        return self
+
+
+class CheckBoxSpec(_BoundControl):
+    """A check box (typically bound to a Yes/No field)."""
+
+    kind: Literal["checkbox"] = "checkbox"
+
+
+class ComboBoxSpec(_BoundControl):
+    """A combo box whose rows come from a table/query/SQL statement or a value list."""
+
+    kind: Literal["combobox"] = "combobox"
+    row_source: str
+    row_source_type: RowSourceType = RowSourceType.TABLE_QUERY
+    bound_column: int = Field(default=1, ge=0)
+    column_count: int = Field(default=1, ge=1, le=255)
+    column_widths: Items[Length] | None = None
+    limit_to_list: bool = True
+
+    @model_validator(mode="after")
+    def _check_columns(self) -> Self:
+        if self.bound_column > self.column_count:
+            raise ValueError("bound_column cannot exceed column_count")
+        if self.column_widths is not None and len(self.column_widths) > self.column_count:
+            raise ValueError("more column_widths than column_count")
+        return self
+
+
+class ButtonSpec(ControlBase):
+    """A command button, optionally running VBA when clicked."""
+
+    kind: Literal["button"] = "button"
+    caption: str
+    on_click: Vba | None = None
+
+
+ControlSpec = Annotated[
+    LabelSpec | TextBoxSpec | CheckBoxSpec | ComboBoxSpec | ButtonSpec,
+    Field(discriminator="kind"),
+]
+"""Any control spec (a Pydantic discriminated union on ``kind``)."""