pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/schema/relationships.py

@@ -0,0 +1,132 @@
+# pyright: reportUnnecessaryIsInstance=false
+# (parse_column_ref validates untyped user input at runtime)
+"""Relationship specifications."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, Self
+
+from pydantic import Field, field_validator, model_validator
+
+from pyaccesskit.enums import JoinType
+from pyaccesskit.errors import SpecError
+from pyaccesskit.schema._base import Items, SpecModel, build
+from pyaccesskit.schema.names import check_name
+
+__all__ = ["ColumnRef", "RelationshipSpec", "parse_column_ref"]
+
+ColumnRef = str | tuple[str, str | Sequence[str]]
+"""A relationship end: ``"Table.Column"``, ``("Table", "Column")`` or ``("Table", ["Col1", "Col2"])``."""
+
+
+def parse_column_ref(ref: ColumnRef, *, what: str) -> tuple[str, tuple[str, ...]]:
+    """Split a :data:`ColumnRef` into ``(table, columns)``.
+
+    Raises:
+        SpecError: If the reference is malformed.
+    """
+    if isinstance(ref, str):
+        table, sep, column = ref.partition(".")
+        if not sep or not table or not column or "." in column:
+            raise SpecError(f"{what} must look like 'Table.Column', got {ref!r}")
+        return check_name(table, what=f"{what} table"), (check_name(column, what=f"{what} column"),)
+    if isinstance(ref, tuple) and len(ref) == 2:
+        table, columns = ref
+        names = (columns,) if isinstance(columns, str) else tuple(columns)
+        if not names:
+            raise SpecError(f"{what} needs at least one column")
+        return check_name(table, what=f"{what} table"), tuple(
+            check_name(c, what=f"{what} column") for c in names
+        )
+    raise SpecError(f"{what} must be 'Table.Column' or (table, columns), got {ref!r}")
+
+
+class RelationshipSpec(SpecModel):
+    """A relationship between a primary ("one") table and a foreign ("many") table.
+
+    Attributes:
+        name: Relationship name. Defaults to Access's convention: primary table name + foreign table name.
+        primary_table: The table on the "one" side (its columns need a primary key or unique index).
+        primary_columns: Referenced columns of the primary table.
+        foreign_table: The table on the "many" side.
+        foreign_columns: Referencing columns of the foreign table (same count and compatible types).
+        enforce_integrity: Enforce referential integrity (the default; creates a hidden index).
+        cascade_update: Cascade updates of the primary key to related rows.
+        cascade_delete: Cascade deletes to related rows.
+        one_to_one: Declare a one-to-one relationship.
+        join: Default join type used by the query designer.
+    """
+
+    name: str | None = None
+    primary_table: str
+    primary_columns: Items[str] = Field(min_length=1, max_length=10)
+    foreign_table: str
+    foreign_columns: Items[str] = Field(min_length=1, max_length=10)
+    enforce_integrity: bool = True
+    cascade_update: bool = False
+    cascade_delete: bool = False
+    one_to_one: bool = False
+    join: JoinType = JoinType.INNER
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, value: str | None) -> str | None:
+        return None if value is None else check_name(value, what="relationship name")
+
+    @field_validator("primary_table", "foreign_table")
+    @classmethod
+    def _check_table(cls, value: str) -> str:
+        return check_name(value, what="table name")
+
+    @field_validator("primary_columns", "foreign_columns", mode="before")
+    @classmethod
+    def _coerce_columns(cls, value: Any) -> Any:
+        return (value,) if isinstance(value, str) else value
+
+    @field_validator("primary_columns", "foreign_columns")
+    @classmethod
+    def _check_columns(cls, value: Sequence[str]) -> tuple[str, ...]:
+        return tuple(check_name(column, what="column name") for column in value)
+
+    @model_validator(mode="after")
+    def _check_relationship(self) -> Self:
+        if len(self.primary_columns) != len(self.foreign_columns):
+            raise ValueError(
+                f"primary side has {len(self.primary_columns)} column(s) but foreign side has "
+                f"{len(self.foreign_columns)}; relationships pair columns one to one"
+            )
+        if (self.cascade_update or self.cascade_delete) and not self.enforce_integrity:
+            raise ValueError("cascade_update/cascade_delete require enforce_integrity=True")
+        return self
+
+    @property
+    def effective_name(self) -> str:
+        """``name`` or Access's default name (primary table + foreign table)."""
+        return self.name if self.name is not None else f"{self.primary_table}{self.foreign_table}"
+
+    def normalized(self) -> RelationshipSpec:
+        """Canonical form with the name filled in."""
+        if self.name is not None:
+            return self
+        return self.model_copy(update={"name": self.effective_name})
+
+    @classmethod
+    def between(cls, primary: ColumnRef, foreign: ColumnRef, **options: Any) -> RelationshipSpec:
+        """Build a relationship from ``"Table.Column"`` references.
+
+        Example::
+
+        RelationshipSpec.between("Customers.CustomerID", "Orders.CustomerID", cascade_delete=True)
+        """
+        primary_table, primary_columns = parse_column_ref(primary, what="primary")
+        foreign_table, foreign_columns = parse_column_ref(foreign, what="foreign")
+        return build(
+            cls,
+            f"relationship {primary_table}->{foreign_table}",
+            primary_table=primary_table,
+            primary_columns=primary_columns,
+            foreign_table=foreign_table,
+            foreign_columns=foreign_columns,
+            **options,
+        )

pyaccesskit/schema/tables.py

@@ -0,0 +1,178 @@
+"""Table specifications."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import Field, field_validator, model_validator
+
+from pyaccesskit.enums import DataType
+from pyaccesskit.schema._base import Items, PropertyValue, SpecModel
+from pyaccesskit.schema.columns import ColumnBase, ColumnSpec
+from pyaccesskit.schema.indexes import PRIMARY_KEY_NAME, IndexField, IndexSpec
+from pyaccesskit.schema.names import check_name
+
+__all__ = ["MAX_COLUMNS", "MAX_INDEXES", "TableSpec"]
+
+MAX_COLUMNS = 255
+MAX_INDEXES = 32
+"""Access limit per table, *including* the hidden indexes created for enforced relationships."""
+
+
+class TableSpec(SpecModel):
+    """A local Access table.
+
+    Indexes can be declared explicitly in ``indexes`` or with shorthands: ``primary_key=`` here, or
+    ``primary_key=``/``unique=``/``indexed=`` on individual columns. :meth:`normalized` expands every
+    shorthand into explicit :class:`IndexSpec` objects; that canonical form is what introspection returns.
+
+    Attributes:
+        name: Table name.
+        columns: Columns in order (1-255).
+        indexes: Explicit indexes.
+        primary_key: Shorthand for a (possibly composite) primary key.
+        description: Table *Description* property.
+        validation_rule: Table-level *Validation Rule* (can reference several columns).
+        validation_text: Message shown when the table validation rule fails.
+        properties: Other Access/DAO table properties to set verbatim (escape hatch).
+    """
+
+    name: str
+    columns: Items[ColumnSpec] = Field(min_length=1, max_length=MAX_COLUMNS)
+    indexes: Items[IndexSpec] = ()
+    primary_key: Items[str] | None = None
+    description: str | None = None
+    validation_rule: str | None = None
+    validation_text: str | None = None
+    properties: dict[str, PropertyValue] = Field(default_factory=dict)
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, value: str) -> str:
+        return check_name(value, what="table name")
+
+    @field_validator("primary_key", mode="before")
+    @classmethod
+    def _coerce_primary_key(cls, value: object) -> object:
+        return (value,) if isinstance(value, str) else value
+
+    @model_validator(mode="after")
+    def _check_table(self) -> Self:
+        names: dict[str, str] = {}
+        for column in self.columns:
+            key = column.name.casefold()
+            if key in names:
+                raise ValueError(
+                    f"duplicate column name {column.name!r} (names are case-insensitive)"
+                )
+            names[key] = column.name
+        autonumbers = [c.name for c in self.columns if c.data_type is DataType.AUTONUMBER]
+        if len(autonumbers) > 1:
+            raise ValueError(f"a table can have only one AutoNumber column, got {autonumbers}")
+        if self.validation_text is not None and self.validation_rule is None:
+            raise ValueError("validation_text requires a validation_rule")
+
+        indexes = self._expand_indexes()
+        if len(indexes) > MAX_INDEXES:
+            raise ValueError(f"a table can have at most {MAX_INDEXES} indexes, got {len(indexes)}")
+        index_names: set[str] = set()
+        for index in indexes:
+            key = index.name.casefold()
+            if key in index_names:
+                raise ValueError(f"duplicate index name {index.name!r}")
+            index_names.add(key)
+            for field_name in index.field_names:
+                column = self._find(field_name)
+                if column is None:
+                    raise ValueError(
+                        f"index {index.name!r} refers to unknown column {field_name!r}"
+                    )
+                if not column.indexable:
+                    raise ValueError(
+                        f"{column.data_type.value} column {column.name!r} cannot be indexed"
+                    )
+        return self
+
+    # ------------------------------------------------------------------------------------ helpers
+    def _find(self, name: str) -> ColumnBase | None:
+        key = name.casefold()
+        return next((c for c in self.columns if c.name.casefold() == key), None)
+
+    def column(self, name: str) -> ColumnBase:
+        """Return the column called ``name`` (case-insensitive).
+
+        Raises:
+            KeyError: If there is no such column.
+        """
+        column = self._find(name)
+        if column is None:
+            raise KeyError(name)
+        return column
+
+    @property
+    def column_names(self) -> tuple[str, ...]:
+        """Column names in order."""
+        return tuple(column.name for column in self.columns)
+
+    def _expand_indexes(self) -> tuple[IndexSpec, ...]:
+        explicit = list(self.indexes)
+        primary_sources = [
+            label
+            for label, present in (
+                ("indexes", any(index.primary for index in explicit)),
+                ("primary_key=", self.primary_key is not None),
+                ("column primary_key=True", any(column.primary_key for column in self.columns)),
+            )
+            if present
+        ]
+        if len(primary_sources) > 1:
+            raise ValueError(f"primary key declared more than once ({', '.join(primary_sources)})")
+        if sum(1 for index in explicit if index.primary) > 1:
+            raise ValueError("a table can have only one primary key")
+
+        derived: list[IndexSpec] = []
+        pk_columns = tuple(self.primary_key or (c.name for c in self.columns if c.primary_key))
+        if pk_columns:
+            derived.append(
+                IndexSpec(
+                    name=PRIMARY_KEY_NAME,
+                    fields=tuple(IndexField(name=name) for name in pk_columns),
+                    primary=True,
+                )
+            )
+        pk_keys = {name.casefold() for name in pk_columns}
+        for primary in (index for index in explicit if index.primary):
+            pk_keys = {name.casefold() for name in primary.field_names}
+        single_pk = len(pk_keys) == 1
+        for column in self.columns:
+            if not (column.unique or column.indexed):
+                continue
+            if single_pk and column.name.casefold() in pk_keys:
+                continue  # the primary key already indexes it uniquely
+            derived.append(
+                IndexSpec(
+                    name=column.name, fields=(IndexField(name=column.name),), unique=column.unique
+                )
+            )
+
+        combined = explicit + derived
+        return tuple(sorted(combined, key=lambda index: (not index.primary, index.name.casefold())))
+
+    def effective_indexes(self) -> tuple[IndexSpec, ...]:
+        """All indexes with shorthands expanded, primary key first, then by name."""
+        return self._expand_indexes()
+
+    @property
+    def primary_index(self) -> IndexSpec | None:
+        """The primary-key index, if any (shorthands included)."""
+        return next((index for index in self._expand_indexes() if index.primary), None)
+
+    def normalized(self) -> TableSpec:
+        """The canonical form: shorthands expanded into ``indexes`` and cleared from columns."""
+        return self.model_copy(
+            update={
+                "columns": tuple(column.normalized() for column in self.columns),
+                "indexes": self._expand_indexes(),
+                "primary_key": None,
+            }
+        )

pyaccesskit/tables.py

@@ -0,0 +1,333 @@
+"""Tables, fields and indexes: the ``db.tables`` collection and its handles."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from typing import TYPE_CHECKING, overload
+
+from pyaccesskit._backends.protocols import PropertyTarget, TableInfo
+from pyaccesskit._ops import schema as ops
+from pyaccesskit.enums import DataType, ObjectKind
+from pyaccesskit.errors import ObjectNotFoundError
+from pyaccesskit.properties import PropertyBag
+from pyaccesskit.schema import (
+    ColumnBase,
+    ColumnSpec,
+    IndexSpec,
+    PropertyValue,
+    TableSpec,
+    quote_identifier,
+)
+from pyaccesskit.schema._base import build
+
+if TYPE_CHECKING:
+    from pyaccesskit._session.session import Session
+
+__all__ = ["Field", "FieldCollection", "Table", "TableCollection"]
+
+
+class Field:
+    """A column of a table (a live, name-based handle)."""
+
+    def __init__(self, session: Session, table: Table, name: str) -> None:
+        self._session = session
+        self._table = table
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        """The field name."""
+        return self._name
+
+    @property
+    def spec(self) -> ColumnBase:
+        """The current definition of the field."""
+        return self._table.to_spec().column(self._name)
+
+    @property
+    def data_type(self) -> DataType:
+        """The Access data type."""
+        return self.spec.data_type
+
+    @property
+    def size(self) -> int | None:
+        """Text length for Short Text fields, else ``None``."""
+        length: int | None = getattr(self.spec, "length", None)
+        return length
+
+    @property
+    def required(self) -> bool:
+        """Whether Null is disallowed."""
+        return self.spec.required
+
+    @property
+    def properties(self) -> PropertyBag:
+        """The field's DAO properties."""
+        return PropertyBag(self._session, PropertyTarget.column(self._table.name, self._name))
+
+    def rename(self, new_name: str) -> None:
+        """Rename the field."""
+        self._session.check_writable(f"rename column {self._name!r}")
+        ops.rename_column(self._session.schema(), self._table.name, self._name, new_name)
+        self._name = new_name
+
+    def drop(self) -> None:
+        """Delete the field."""
+        self._session.check_writable(f"drop column {self._name!r}")
+        ops.drop_column(self._session.schema(), self._table.name, self._name)
+
+    def __repr__(self) -> str:
+        return f"<Field {self._table.name}.{self._name}>"
+
+
+class FieldCollection:
+    """The fields of a table, in order."""
+
+    def __init__(self, session: Session, table: Table) -> None:
+        self._session = session
+        self._table = table
+
+    def names(self) -> list[str]:
+        """Field names in order."""
+        return list(self._table.to_spec().column_names)
+
+    def __iter__(self) -> Iterator[Field]:
+        return iter([Field(self._session, self._table, 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) -> Field:
+        for actual in self.names():
+            if actual.casefold() == name.casefold():
+                return Field(self._session, self._table, actual)
+        raise ObjectNotFoundError(
+            f"table {self._table.name!r} has no field {name!r}", kind=ObjectKind.FIELD, name=name
+        )
+
+
+class Table:
+    """A table (a live, name-based handle). ``to_spec()`` returns an immutable snapshot."""
+
+    def __init__(self, session: Session, name: str) -> None:
+        self._session = session
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        """The table name."""
+        return self._name
+
+    def _info(self) -> TableInfo:
+        return ops.require_table(self._session.schema(), self._name)
+
+    def to_spec(self) -> TableSpec:
+        """The table's current definition as a normalized :class:`TableSpec`."""
+        return self._session.schema().read_table(self._name)
+
+    @property
+    def fields(self) -> FieldCollection:
+        """The table's fields."""
+        return FieldCollection(self._session, self)
+
+    @property
+    def indexes(self) -> tuple[IndexSpec, ...]:
+        """The table's indexes (excluding the hidden ones owned by relationships)."""
+        return tuple(self.to_spec().indexes)
+
+    @property
+    def primary_key(self) -> IndexSpec | None:
+        """The primary-key index, if any."""
+        return self.to_spec().primary_index
+
+    @property
+    def description(self) -> str | None:
+        """The table *Description*."""
+        return self.to_spec().description
+
+    @description.setter
+    def description(self, value: str | None) -> None:
+        if value is None:
+            if "Description" in self.properties:
+                self.properties.delete("Description")
+        else:
+            self.properties["Description"] = value
+
+    @property
+    def is_linked(self) -> bool:
+        """Whether this is a linked table."""
+        return self._info().is_linked
+
+    @property
+    def connect(self) -> str | None:
+        """A linked table's connection string (``None`` for local tables). It may contain credentials."""
+        return self._info().connect
+
+    @property
+    def source_table(self) -> str | None:
+        """A linked table's name in its source database (``None`` for local tables)."""
+        return self._info().source_table
+
+    @property
+    def is_system(self) -> bool:
+        """Whether this is a system table (``MSys*``)."""
+        return self._info().is_system
+
+    @property
+    def properties(self) -> PropertyBag:
+        """The table's DAO properties."""
+        return PropertyBag(self._session, PropertyTarget.table(self._name))
+
+    def record_count(self) -> int:
+        """Number of rows (runs ``SELECT COUNT(*)``)."""
+        rows = self._session.schema().fetch(
+            f"SELECT COUNT(*) AS N FROM {quote_identifier(self._name)}"
+        )
+        return int(rows.rows[0][0])
+
+    # ------------------------------------------------------------------------------- mutation
+    def add_column(self, column: ColumnSpec) -> Field:
+        """Append a column (``unique=``/``indexed=``/``primary_key=`` also create the index)."""
+        self._session.check_writable(f"add column to {self._name!r}")
+        ops.add_column(self._session.schema(), self._name, column)
+        return Field(self._session, self, column.name)
+
+    def drop_column(self, name: str) -> None:
+        """Delete a column (drop its indexes and relationships first)."""
+        self.fields[name].drop()
+
+    def rename_column(self, old: str, new: str) -> None:
+        """Rename a column."""
+        self.fields[old].rename(new)
+
+    def create_index(self, index: IndexSpec) -> None:
+        """Create an index."""
+        self._session.check_writable(f"create index on {self._name!r}")
+        ops.create_index(self._session.schema(), self._name, index)
+
+    def drop_index(self, name: str) -> None:
+        """Delete an index."""
+        self._session.check_writable(f"drop index of {self._name!r}")
+        ops.drop_index(self._session.schema(), self._name, name)
+
+    def rename(self, new_name: str) -> None:
+        """Rename the table."""
+        self._session.check_writable(f"rename table {self._name!r}")
+        self._name = ops.rename_table(self._session.schema(), self._name, new_name)
+
+    def drop(self, *, drop_relationships: bool = False) -> None:
+        """Delete the table (with ``drop_relationships=True``, its relationships first)."""
+        self._session.check_writable(f"drop table {self._name!r}")
+        ops.drop_table(self._session.schema(), self._name, drop_relationships=drop_relationships)
+
+    def __repr__(self) -> str:
+        return f"<Table {self._name!r}>"
+
+
+class TableCollection:
+    """``db.tables``: every local and linked table (system tables are hidden unless asked for)."""
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    def _infos(self, include_system: bool) -> list[TableInfo]:
+        return [
+            info
+            for info in self._session.schema().list_tables()
+            if include_system or not (info.is_system or info.is_hidden)
+        ]
+
+    def names(self, *, include_system: bool = False) -> list[str]:
+        """Table names."""
+        return [info.name for info in self._infos(include_system)]
+
+    def __iter__(self) -> Iterator[Table]:
+        return iter([Table(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 self.get(name) is not None
+
+    def get(self, name: str) -> Table | None:
+        """The table called ``name`` (case-insensitive), or ``None``."""
+        info = ops.find_table(self._session.schema(), name)
+        return Table(self._session, info.name) if info is not None else None
+
+    def __getitem__(self, name: str) -> Table:
+        table = self.get(name)
+        if table is None:
+            raise ObjectNotFoundError(
+                f"table {name!r} does not exist", kind=ObjectKind.TABLE, name=name
+            )
+        return table
+
+    @overload
+    def create(self, spec: TableSpec, /) -> Table: ...
+
+    @overload
+    def create(
+        self,
+        name: str,
+        /,
+        *,
+        columns: Sequence[ColumnSpec],
+        indexes: Sequence[IndexSpec] = (),
+        primary_key: Sequence[str] | str | None = None,
+        description: str | None = None,
+        validation_rule: str | None = None,
+        validation_text: str | None = None,
+        properties: Mapping[str, PropertyValue] | None = None,
+    ) -> Table: ...
+
+    def create(
+        self,
+        spec_or_name: TableSpec | str,
+        /,
+        *,
+        columns: Sequence[ColumnSpec] | None = None,
+        indexes: Sequence[IndexSpec] = (),
+        primary_key: Sequence[str] | str | None = None,
+        description: str | None = None,
+        validation_rule: str | None = None,
+        validation_text: str | None = None,
+        properties: Mapping[str, PropertyValue] | None = None,
+    ) -> Table:
+        """Create a table from a :class:`TableSpec` or from keyword arguments.
+
+        Creation is atomic: if any step fails, the partially created table is removed.
+        """
+        if isinstance(spec_or_name, TableSpec):
+            spec = spec_or_name
+        else:
+            spec = build(
+                TableSpec,
+                f"table {spec_or_name!r}",
+                name=spec_or_name,
+                columns=tuple(columns or ()),
+                indexes=tuple(indexes),
+                primary_key=primary_key,
+                description=description,
+                validation_rule=validation_rule,
+                validation_text=validation_text,
+                properties=dict(properties or {}),
+            )
+        self._session.check_writable(f"create table {spec.name!r}")
+        created = ops.create_table(self._session.schema(), spec)
+        return Table(self._session, created.name)
+
+    def drop(self, name: str, *, drop_relationships: bool = False) -> None:
+        """Delete a table."""
+        self[name].drop(drop_relationships=drop_relationships)
+
+    def specs(self) -> list[TableSpec]:
+        """Specs of every (non-system, non-linked) table."""
+        return [
+            self._session.schema().read_table(info.name)
+            for info in self._infos(False)
+            if not info.is_linked
+        ]