pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/schema/expressions.py

@@ -0,0 +1,162 @@
+# pyright: reportUnnecessaryIsInstance=false
+# (dataclass __post_init__ and render_literal validate untyped input at runtime)
+"""Access expression literals: rendering Python values and parsing them back.
+
+Access stores properties such as ``DefaultValue`` as *expression text*. A classic mistake is setting a text
+default to ``Unknown`` instead of ``"Unknown"`` (Access then looks for a field or function called Unknown).
+PyAccessKit takes Python values and renders the right literal; raw expressions are passed with
+:class:`Expr`::
+
+    Column.text("Status", default="Unknown")          # stored as  "Unknown"
+    Column.date_time("CreatedAt", default=Expr("Now()"))
+    Column.currency("Total", default=0)                # stored as  0
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from datetime import date, datetime, time
+from decimal import Decimal, InvalidOperation
+
+from pyaccesskit.errors import SpecError
+
+__all__ = [
+    "DefaultValue",
+    "Expr",
+    "parse_literal",
+    "render_literal",
+]
+
+
+@dataclass(frozen=True)
+class Expr:
+    """A raw Access expression, passed through verbatim (e.g. ``Expr("Now()")``, ``Expr("[Qty]*2")``)."""
+
+    expr: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.expr, str) or not self.expr.strip():
+            raise SpecError("Expr requires a non-empty expression string")
+
+    def __str__(self) -> str:
+        return self.expr
+
+
+DefaultValue = Expr | bool | int | float | Decimal | datetime | date | time | str
+"""Types accepted as a column default: a Python literal or an :class:`Expr`."""
+
+
+def render_literal(value: DefaultValue) -> str:
+    """Render a Python value as Access expression text.
+
+    Raises:
+        SpecError: For values Access cannot represent (NaN, time-zone aware datetimes...).
+    """
+    if isinstance(value, Expr):
+        return value.expr
+    if isinstance(value, bool):
+        return "True" if value else "False"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise SpecError(f"cannot store non-finite number {value!r} in Access")
+        return repr(value)
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise SpecError(f"cannot store non-finite number {value!r} in Access")
+        return format(value, "f")
+    if isinstance(value, datetime):
+        if value.tzinfo is not None:
+            raise SpecError("Access date/times have no time zone; pass a naive datetime")
+        if value.microsecond:
+            raise SpecError("Access date/time literals have whole-second precision")
+        return f"#{value.year:04d}-{value:%m-%d %H:%M:%S}#"  # %Y is unpadded on Linux
+    if isinstance(value, date):
+        return f"#{value.year:04d}-{value:%m-%d}#"
+    if isinstance(value, time):
+        if value.tzinfo is not None or value.microsecond:
+            raise SpecError("Access time literals are naive and have whole-second precision")
+        return f"#{value:%H:%M:%S}#"
+    if isinstance(value, str):
+        return '"' + value.replace('"', '""') + '"'
+    raise SpecError(f"unsupported literal type {type(value).__name__}")  # pragma: no cover
+
+
+_NUMBER = re.compile(r"^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$")
+_BOOLEAN_WORDS = {"true": True, "yes": True, "on": True, "false": False, "no": False, "off": False}
+_DATE_FORMATS = (
+    "%Y-%m-%d %H:%M:%S",
+    "%Y-%m-%d %H:%M",
+    "%Y-%m-%d",
+    "%m/%d/%Y %H:%M:%S",
+    "%m/%d/%Y %I:%M:%S %p",
+    "%m/%d/%Y %H:%M",
+    "%m/%d/%Y",
+)
+_TIME_FORMATS = ("%H:%M:%S", "%H:%M", "%I:%M:%S %p", "%I:%M %p")
+
+
+def _unquote(text: str) -> str | None:
+    """Return the value of a single quoted string literal, or ``None`` if ``text`` is not exactly one."""
+    if len(text) < 2 or text[0] not in "\"'" or text[-1] != text[0]:
+        return None
+    quote = text[0]
+    body = text[1:-1]
+    # Every quote inside the body must be doubled; otherwise this is an expression like "a" & "b".
+    stripped = body.replace(quote * 2, "")
+    if quote in stripped:
+        return None
+    return body.replace(quote * 2, quote)
+
+
+def _parse_date_literal(body: str) -> datetime | date | time | None:
+    body = body.strip()
+    for fmt in _DATE_FORMATS:
+        try:
+            parsed = datetime.strptime(body, fmt)
+        except ValueError:
+            continue
+        has_time = "%H" in fmt or "%I" in fmt
+        return parsed if has_time else parsed.date()
+    for fmt in _TIME_FORMATS:
+        try:
+            return datetime.strptime(body, fmt).time()
+        except ValueError:
+            continue
+    return None
+
+
+def parse_literal(text: str | None) -> DefaultValue | None:
+    """Parse Access expression text into a Python literal, or an :class:`Expr` if it is not a literal.
+
+    Returns ``None`` for empty text. Understands quoted strings, numbers, ``True``/``False``/``Yes``/``No``/
+    ``On``/``Off`` and ``#date#`` literals (ISO or US ``m/d/yyyy`` order).
+    """
+    if text is None:
+        return None
+    stripped = text.strip()
+    if not stripped:
+        return None
+    unquoted = _unquote(stripped)
+    if unquoted is not None:
+        return unquoted
+    if _NUMBER.match(stripped):
+        if re.search(r"[.eE]", stripped) is None:
+            return int(stripped)
+        if "e" in stripped.lower():
+            return float(stripped)
+        try:
+            return Decimal(stripped)
+        except InvalidOperation:  # pragma: no cover - guarded by the regex
+            return Expr(stripped)
+    boolean = _BOOLEAN_WORDS.get(stripped.lower())
+    if boolean is not None:
+        return boolean
+    if len(stripped) >= 2 and stripped[0] == "#" and stripped[-1] == "#":
+        parsed = _parse_date_literal(stripped[1:-1])
+        if parsed is not None:
+            return parsed
+    return Expr(stripped)

pyaccesskit/schema/indexes.py

@@ -0,0 +1,114 @@
+"""Index specifications."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Self, cast
+
+from pydantic import Field, field_validator, model_validator
+
+from pyaccesskit.schema._base import Items, SpecModel, build
+from pyaccesskit.schema.names import check_name
+
+__all__ = ["PRIMARY_KEY_NAME", "IndexField", "IndexSpec"]
+
+PRIMARY_KEY_NAME = "PrimaryKey"
+"""The name Access gives primary-key indexes."""
+
+MAX_FIELDS_PER_INDEX = 10
+
+
+class IndexField(SpecModel):
+    """One column of an index, optionally in descending order."""
+
+    name: str
+    descending: bool = False
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, value: str) -> str:
+        return check_name(value, what="index column name")
+
+
+def _coerce_field(value: Any) -> Any:
+    if isinstance(value, str):
+        return {"name": value}
+    if isinstance(value, tuple):
+        pair = cast("tuple[Any, ...]", value)
+        if len(pair) == 2:
+            return {"name": pair[0], "descending": str(pair[1]).lower() in ("desc", "descending")}
+        return pair
+    return value
+
+
+class IndexSpec(SpecModel):
+    """An index on one or more columns.
+
+    Attributes:
+        name: Index name (Access names the primary key ``PrimaryKey``).
+        fields: Indexed columns; plain strings are accepted (``["LastName", "FirstName"]``) as are
+            ``("Col", "desc")`` pairs.
+        primary: This is the table's primary key (implies ``unique`` and ``required``).
+        unique: No two rows may have the same key.
+        required: Null values are not allowed in the indexed columns.
+        ignore_nulls: Rows with Null keys are left out of the index.
+    """
+
+    name: str
+    fields: Items[IndexField] = Field(min_length=1, max_length=MAX_FIELDS_PER_INDEX)
+    primary: bool = False
+    unique: bool = False
+    required: bool = False
+    ignore_nulls: bool = False
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, value: str) -> str:
+        return check_name(value, what="index name")
+
+    @field_validator("fields", mode="before")
+    @classmethod
+    def _coerce_fields(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return (_coerce_field(value),)
+        if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+            items = cast("Sequence[Any]", value)
+            return tuple(_coerce_field(item) for item in items)
+        return value
+
+    @model_validator(mode="before")
+    @classmethod
+    def _primary_implies_unique(cls, data: Any) -> Any:
+        if isinstance(data, Mapping):
+            fields = cast("Mapping[str, Any]", data)
+            if fields.get("primary"):
+                return {**fields, "unique": True, "required": True}
+            return fields
+        return data
+
+    @model_validator(mode="after")
+    def _check_duplicates(self) -> Self:
+        seen: set[str] = set()
+        for field in self.fields:
+            key = field.name.casefold()
+            if key in seen:
+                raise ValueError(f"index {self.name!r} lists column {field.name!r} twice")
+            seen.add(key)
+        return self
+
+    @property
+    def field_names(self) -> tuple[str, ...]:
+        """The indexed column names, in order."""
+        return tuple(field.name for field in self.fields)
+
+    @classmethod
+    def primary_key(cls, *columns: str, name: str = PRIMARY_KEY_NAME) -> IndexSpec:
+        """A primary-key index on ``columns`` (named ``PrimaryKey`` like Access does)."""
+        return build(cls, f"primary key {name!r}", name=name, fields=columns, primary=True)
+
+    @classmethod
+    def on(
+        cls, name: str, *columns: str | tuple[str, str], unique: bool = False, **options: bool
+    ) -> IndexSpec:
+        """Convenience constructor: ``IndexSpec.on("ix_Name", "LastName", "FirstName", unique=True)``."""
+        return build(cls, f"index {name!r}", name=name, fields=columns, unique=unique, **options)

pyaccesskit/schema/names.py

@@ -0,0 +1,122 @@
+"""Access naming rules, name comparison, identifier quoting and name linting.
+
+Hard rules (violations raise :class:`~pyaccesskit.errors.SpecError`) follow Microsoft's *Guidelines for
+naming fields, controls, and objects*: at most 64 characters; no period, exclamation point, accent grave or
+brackets; no leading space; no control characters.
+
+Soft rules (violations emit :class:`~pyaccesskit.errors.AccessNameWarning`) flag names that are legal but
+cause trouble later: reserved words, spaces/special characters, names that shadow common form properties.
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+
+from pyaccesskit.errors import AccessNameWarning, SpecError
+from pyaccesskit.schema._reserved_words import RESERVED_WORDS
+
+__all__ = [
+    "MAX_NAME_LENGTH",
+    "check_name",
+    "lint_name",
+    "name_key",
+    "names_equal",
+    "quote_identifier",
+    "warn_name",
+]
+
+MAX_NAME_LENGTH = 64
+_FORBIDDEN_CHARACTERS = frozenset(".!`[]")
+_PLAIN_IDENTIFIER = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
+_FORM_PROPERTY_NAMES = frozenset(
+    name.casefold()
+    for name in (
+        "Name",
+        "Caption",
+        "Text",
+        "Value",
+        "Section",
+        "Tag",
+        "Visible",
+        "Width",
+        "Height",
+        "Top",
+        "Left",
+    )
+)
+
+
+def check_name(name: object, *, what: str = "name") -> str:
+    """Validate ``name`` against Access's hard naming rules and return it unchanged.
+
+    Args:
+        name: The candidate name.
+        what: What is being named, used in error messages (``"table name"``...).
+
+    Raises:
+        SpecError: If the name is not a legal Access object name.
+    """
+    if not isinstance(name, str):
+        raise SpecError(f"{what} must be a string, got {type(name).__name__}")
+    problem = _hard_rule_violation(name)
+    if problem is not None:
+        raise SpecError(f"invalid {what} {name!r}: {problem}")
+    return name
+
+
+def _hard_rule_violation(name: str) -> str | None:
+    if not name:
+        return "names cannot be empty"
+    if len(name) > MAX_NAME_LENGTH:
+        return f"names are limited to {MAX_NAME_LENGTH} characters (this one has {len(name)})"
+    if name[0] == " ":
+        return "names cannot start with a space"
+    bad = sorted({ch for ch in name if ch in _FORBIDDEN_CHARACTERS})
+    if bad:
+        return "names cannot contain " + ", ".join(repr(ch) for ch in bad)
+    if any(ord(ch) < 32 for ch in name):
+        return "names cannot contain control characters"
+    return None
+
+
+def lint_name(name: str, *, what: str = "name") -> list[str]:
+    """Return human-readable warnings for a *legal* name that is likely to cause problems."""
+    messages: list[str] = []
+    key = name.casefold()
+    if key in RESERVED_WORDS:
+        messages.append(
+            f"{what} {name!r} is an Access reserved word; it must be written as [{name}] in SQL and "
+            f"expressions and can clash with built-in properties"
+        )
+    elif key in _FORM_PROPERTY_NAMES:
+        messages.append(f"{what} {name!r} shadows a common form/control property of the same name")
+    if name != name.rstrip():
+        messages.append(f"{what} {name!r} ends with whitespace")
+    elif not _PLAIN_IDENTIFIER.match(name):
+        messages.append(
+            f"{what} {name!r} contains spaces or special characters; it must be bracketed in SQL and VBA"
+        )
+    return messages
+
+
+def warn_name(name: str, *, what: str = "name", stacklevel: int = 3) -> None:
+    """Emit an :class:`AccessNameWarning` for every soft-rule problem found by :func:`lint_name`."""
+    for message in lint_name(name, what=what):
+        warnings.warn(message, AccessNameWarning, stacklevel=stacklevel)
+
+
+def name_key(name: str) -> str:
+    """Key for case-insensitive name comparison (Access object names are case-insensitive)."""
+    return name.casefold()
+
+
+def names_equal(left: str, right: str) -> bool:
+    """Whether two Access names refer to the same object."""
+    return left.casefold() == right.casefold()
+
+
+def quote_identifier(name: str) -> str:
+    """Bracket-quote a name for Access SQL and expressions: ``Order Details`` → ``[Order Details]``."""
+    check_name(name)
+    return f"[{name}]"

pyaccesskit/schema/queries.py

@@ -0,0 +1,192 @@
+"""Saved query specifications and Access SQL helpers.
+
+Access rewrites SQL when it saves a query (keywords upper-cased, one clause per line, a trailing ``;``,
+``DELETE`` becoming ``DELETE *``...). :func:`sql_equivalent` compares SQL modulo those cosmetic changes, which
+is what change detection needs.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Self
+
+from pydantic import Field, field_validator, model_validator
+
+from pyaccesskit.enums import QueryKind
+from pyaccesskit.schema._base import SpecModel
+from pyaccesskit.schema.names import check_name
+
+__all__ = [
+    "DAO_QUERY_KINDS",
+    "MAX_SQL_LENGTH",
+    "PassThroughOptions",
+    "QuerySpec",
+    "detect_query_kind",
+    "normalize_sql",
+    "sql_equivalent",
+]
+
+MAX_SQL_LENGTH = 64_000
+"""Approximate Access limit on the length of a SQL statement."""
+
+DAO_QUERY_KINDS: dict[int, QueryKind] = {
+    0: QueryKind.SELECT,
+    16: QueryKind.CROSSTAB,
+    32: QueryKind.DELETE,
+    48: QueryKind.UPDATE,
+    64: QueryKind.APPEND,
+    80: QueryKind.MAKE_TABLE,
+    96: QueryKind.DDL,
+    112: QueryKind.PASS_THROUGH,
+    128: QueryKind.UNION,
+    144: QueryKind.PASS_THROUGH_BULK,
+    160: QueryKind.COMPOUND,
+    224: QueryKind.PROCEDURE,
+    240: QueryKind.ACTION,
+}
+"""DAO ``QueryDefTypeEnum`` values (verified against the ACEDAO type library) → :class:`QueryKind`."""
+
+
+class PassThroughOptions(SpecModel):
+    """Settings of an ODBC pass-through query.
+
+    Attributes:
+        connect: ODBC connection string; must start with ``ODBC;``.
+        returns_records: Whether the statement returns rows.
+        timeout: ODBC timeout in seconds (0 = no timeout).
+    """
+
+    connect: str
+    returns_records: bool = True
+    timeout: int = Field(default=60, ge=0)
+
+    @field_validator("connect")
+    @classmethod
+    def _check_connect(cls, value: str) -> str:
+        if not value.upper().startswith("ODBC;"):
+            raise ValueError("pass-through connect strings must start with 'ODBC;'")
+        return value
+
+
+class QuerySpec(SpecModel):
+    """A saved query (Access QueryDef).
+
+    Attributes:
+        name: Query name (tables and queries share one namespace).
+        sql: The SQL text (Access SQL, or the server's dialect for pass-through queries).
+        description: Query *Description* property.
+        pass_through: Set for ODBC pass-through queries.
+    """
+
+    name: str
+    sql: str = Field(min_length=1, max_length=MAX_SQL_LENGTH)
+    description: str | None = None
+    pass_through: PassThroughOptions | None = None
+
+    @field_validator("name")
+    @classmethod
+    def _check_name(cls, value: str) -> str:
+        return check_name(value, what="query name")
+
+    @model_validator(mode="after")
+    def _check_sql(self) -> Self:
+        if not self.sql.strip():
+            raise ValueError("sql cannot be blank")
+        return self
+
+    @property
+    def kind(self) -> QueryKind:
+        """The query kind as implied by the SQL text (Access reports the authoritative kind after saving)."""
+        return detect_query_kind(self.sql, pass_through=self.pass_through is not None)
+
+    def normalized(self) -> QuerySpec:
+        """Canonical form (SQL line endings normalized to CRLF, as Access stores them)."""
+        sql = self.sql.replace("\r\n", "\n").replace("\r", "\n").replace("\n", "\r\n")
+        return self if sql == self.sql else self.model_copy(update={"sql": sql})
+
+
+# -------------------------------------------------------------------------------------- SQL helpers
+_TOKEN = re.compile(
+    r"""
+      (?P<string>'(?:[^']|'')*'|"(?:[^"]|"")*")
+    | (?P<bracket>\[[^\]]*\])
+    | (?P<date>\#[^#\r\n]*\#)
+    | (?P<space>\s+)
+    | (?P<punct>[(),;=<>+\-*/&^\\])
+    | (?P<word>[^\s'"\[\#(),;=<>+\-*/&^\\]+)
+    """,
+    re.VERBOSE,
+)
+
+
+def _tokens(sql: str) -> list[tuple[str, str]]:
+    tokens: list[tuple[str, str]] = []
+    for match in _TOKEN.finditer(sql):
+        kind = match.lastgroup or "word"
+        if kind == "space":
+            continue
+        tokens.append((kind, match.group()))
+    return tokens
+
+
+def normalize_sql(sql: str) -> str:
+    """A canonical single-line form of ``sql`` for comparisons.
+
+    Whitespace is collapsed and dropped around punctuation, words and bracketed identifiers are
+    upper-cased (Access identifiers are case-insensitive), string and date literals are preserved, trailing
+    semicolons are removed, and Access's ``DELETE * FROM`` rewrite is undone.
+    """
+    parts: list[str] = []
+    for kind, text in _tokens(sql):
+        parts.append(text if kind in ("string", "date") else text.upper())
+    while parts and parts[-1] == ";":
+        parts.pop()
+    if len(parts) >= 3 and parts[0] == "DELETE" and parts[1] == "*" and parts[2] == "FROM":
+        del parts[1]
+    return " ".join(parts)
+
+
+def sql_equivalent(left: str, right: str) -> bool:
+    """Whether two SQL texts differ only cosmetically (see :func:`normalize_sql`)."""
+    return normalize_sql(left) == normalize_sql(right)
+
+
+def detect_query_kind(sql: str, *, pass_through: bool = False) -> QueryKind:
+    """Infer the kind of query from its SQL text (used before Access has classified a saved query)."""
+    if pass_through:
+        return QueryKind.PASS_THROUGH
+    words = [text.upper() if kind == "word" else text for kind, text in _tokens(sql)]
+    if words and words[0] == "PARAMETERS":
+        words = words[words.index(";") + 1 :] if ";" in words else []
+    if not words:
+        return QueryKind.UNKNOWN
+    first = words[0].lstrip("(")
+    simple = {
+        "TRANSFORM": QueryKind.CROSSTAB,
+        "INSERT": QueryKind.APPEND,
+        "UPDATE": QueryKind.UPDATE,
+        "DELETE": QueryKind.DELETE,
+        "CREATE": QueryKind.DDL,
+        "ALTER": QueryKind.DDL,
+        "DROP": QueryKind.DDL,
+        "PROCEDURE": QueryKind.PROCEDURE,
+    }
+    if first in simple:
+        return simple[first]
+    if first not in ("SELECT", "("):
+        return QueryKind.UNKNOWN
+    depth = 0
+    seen_from = False
+    for word in words:
+        if word == "(":
+            depth += 1
+        elif word == ")":
+            depth -= 1
+        elif depth == 0:
+            if word == "UNION":
+                return QueryKind.UNION
+            if word == "FROM":
+                seen_from = True
+            elif word == "INTO" and not seen_from:
+                return QueryKind.MAKE_TABLE
+    return QueryKind.SELECT