pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/schema/__init__.py

@@ -0,0 +1,73 @@
+"""Immutable, validated specifications of database schema objects.
+
+Specs are plain Python values (Pydantic models): they never touch Access. Collections such as
+``db.tables`` turn them into real objects, and introspection turns real objects back into specs.
+"""
+
+from pyaccesskit.schema._base import PropertyValue
+from pyaccesskit.schema.columns import (
+    AutoNumberColumn,
+    Column,
+    ColumnBase,
+    ColumnSpec,
+    CurrencyColumn,
+    DateTimeColumn,
+    DecimalColumn,
+    HyperlinkColumn,
+    LongTextColumn,
+    NumberColumn,
+    OleObjectColumn,
+    TextColumn,
+    UnsupportedColumn,
+    YesNoColumn,
+)
+from pyaccesskit.schema.expressions import DefaultValue, Expr, parse_literal, render_literal
+from pyaccesskit.schema.indexes import PRIMARY_KEY_NAME, IndexField, IndexSpec
+from pyaccesskit.schema.names import check_name, lint_name, name_key, names_equal, quote_identifier
+from pyaccesskit.schema.queries import (
+    PassThroughOptions,
+    QuerySpec,
+    detect_query_kind,
+    normalize_sql,
+    sql_equivalent,
+)
+from pyaccesskit.schema.relationships import ColumnRef, RelationshipSpec
+from pyaccesskit.schema.tables import TableSpec
+
+__all__ = [
+    "PRIMARY_KEY_NAME",
+    "AutoNumberColumn",
+    "Column",
+    "ColumnBase",
+    "ColumnRef",
+    "ColumnSpec",
+    "CurrencyColumn",
+    "DateTimeColumn",
+    "DecimalColumn",
+    "DefaultValue",
+    "Expr",
+    "HyperlinkColumn",
+    "IndexField",
+    "IndexSpec",
+    "LongTextColumn",
+    "NumberColumn",
+    "OleObjectColumn",
+    "PassThroughOptions",
+    "PropertyValue",
+    "QuerySpec",
+    "RelationshipSpec",
+    "TableSpec",
+    "TextColumn",
+    "UnsupportedColumn",
+    "YesNoColumn",
+    "check_name",
+    "detect_query_kind",
+    "lint_name",
+    "name_key",
+    "names_equal",
+    "normalize_sql",
+    "parse_literal",
+    "quote_identifier",
+    "render_literal",
+    "sql_equivalent",
+]

pyaccesskit/schema/_base.py

@@ -0,0 +1,55 @@
+"""Shared base model and helpers for specification models."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from datetime import datetime
+from decimal import Decimal
+from typing import Annotated, Any, TypeVar
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, ValidationError
+
+from pyaccesskit.errors import SpecError
+
+PropertyValue = str | bool | int | float | Decimal | datetime | None
+"""Values accepted in ``properties={...}`` escape-hatch dictionaries (raw Access/DAO properties)."""
+
+_T = TypeVar("_T")
+
+
+def _as_tuple(value: Sequence[Any]) -> tuple[Any, ...]:
+    return tuple(value)
+
+
+Items = Annotated[Sequence[_T], AfterValidator(_as_tuple)]
+"""A list-like spec field: any sequence is accepted (lists included), and it is stored as a tuple.
+
+Type checkers derive a model's ``__init__`` from its annotations, so a ``tuple[...]`` field would reject the
+lists people naturally write; this keeps the input type friendly and the stored value immutable.
+"""
+
+
+class SpecModel(BaseModel):
+    """Base class of every PyAccessKit spec: immutable, strict about unknown fields."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", validate_default=True)
+
+
+def spec_error(exc: ValidationError, what: str) -> SpecError:
+    """Convert a Pydantic ``ValidationError`` into a :class:`SpecError` with readable problems."""
+    problems: list[str] = []
+    for error in exc.errors(include_url=False):
+        location = ".".join(str(part) for part in error["loc"]) or what
+        message = error["msg"]
+        if message.startswith("Value error, "):
+            message = message.removeprefix("Value error, ")
+        problems.append(f"{location}: {message}")
+    return SpecError(f"invalid {what}", problems=tuple(problems))
+
+
+def build(factory: Callable[..., _T], what: str, /, **kwargs: Any) -> _T:
+    """Call ``factory(**kwargs)``, converting validation failures into :class:`SpecError`."""
+    try:
+        return factory(**kwargs)
+    except ValidationError as exc:
+        raise spec_error(exc, what) from exc

pyaccesskit/schema/_reserved_words.py

@@ -0,0 +1,55 @@
+"""Access and Access database engine reserved words.
+
+Source: Microsoft Support, "Learn about Access reserved words and symbols" (retrieved 2026-09-26). Using
+these as object or field names is legal but causes errors in expressions, SQL and VBA unless every
+reference is bracketed, so PyAccessKit warns about them (``AccessNameWarning``).
+"""
+
+from __future__ import annotations
+
+_ACCESS = """
+ADD ALL Alphanumeric ALTER AND ANY Application AS ASC Assistant AUTOINCREMENT Avg BETWEEN BINARY BIT
+BOOLEAN BY BYTE CHAR CHARACTER COLUMN CompactDatabase CONSTRAINT Container Count COUNTER CREATE
+CreateDatabase CreateField CreateGroup CreateIndex CreateObject CreateProperty CreateRelation
+CreateTableDef CreateUser CreateWorkspace CURRENCY CurrentUser DATABASE DATE DATETIME DELETE DESC
+Description DISALLOW DISTINCT DISTINCTROW Document DOUBLE DROP Echo Else End Eqv Error EXISTS Exit FALSE
+Field Fields FillCache FLOAT FLOAT4 FLOAT8 FOREIGN Form Forms FROM Full FUNCTION GENERAL GetObject
+GetOption GotoPage GROUP GUID HAVING Idle IEEEDOUBLE IEEESINGLE If IGNORE Imp IN INDEX Indexes INNER
+INSERT InsertText INT INTEGER INTEGER1 INTEGER2 INTEGER4 INTO IS JOIN KEY LastModified LEFT Level Like
+LOGICAL LOGICAL1 LONG LONGBINARY LONGTEXT Macro Match Max Min Mod MEMO Module MONEY Move NAME
+NewPassword NO Not Note NULL NUMBER NUMERIC Object OLEOBJECT OFF ON OpenRecordset OPTION OR ORDER
+Orientation Outer OWNERACCESS Parameter PARAMETERS Partial PERCENT PIVOT PRIMARY PROCEDURE Property
+Queries Query Quit REAL Recalc Recordset REFERENCES Refresh RefreshLink RegisterDatabase Relation Repaint
+RepairDatabase Report Reports Requery RIGHT SCREEN SECTION SELECT SET SetFocus SetOption SHORT SINGLE
+SMALLINT SOME SQL StDev StDevP STRING Sum TABLE TableDef TableDefs TableID TEXT TIME TIMESTAMP TOP
+TRANSFORM TRUE Type UNION UNIQUE UPDATE USER VALUE VALUES Var VarP VARBINARY VARCHAR WHERE WITH Workspace
+Xor Year YES YESNO
+"""
+
+_ENGINE = """
+ABSOLUTE ACTION ADD ADMINDB ALL ALLOCATE ALPHANUMERIC ALTER AND ANY ARE AS ASC ASSERTION AT AUTHORIZATION
+AUTOINCREMENT AVG BAND BEGIN BETWEEN BINARY BIT BIT_LENGTH BNOT BOR BOTH BXOR BY BYTE CASCADE CASCADED
+CASE CAST CATALOG CHAR CHARACTER CHAR_LENGTH CHARACTER_LENGTH CHECK CLOSE COALESCE COLLATE COLLATION
+COLUMN COMMIT COMP COMPRESSION CONNECT CONNECTION CONSTRAINT CONSTRAINTS CONTAINER CONTINUE CONVERT
+CORRESPONDING COUNT COUNTER CREATE CREATEDB CROSS CURRENCY CURRENT CURRENT_DATE CURRENT_TIME
+CURRENT_TIMESTAMP CURRENT_USER CURSOR DATABASE DATE DATETIME DAY DEALLOCATE DEC DECIMAL DECLARE DEFAULT
+DEFERRABLE DEFERRED DELETE DESC DESCRIBE DESCRIPTOR DIAGNOSTICS DISALLOW DISCONNECT DISTINCT DOMAIN
+DOUBLE DROP ELSE END END-EXEC ESCAPE EXCEPT EXCEPTION EXCLUSIVECONNECT EXEC EXECUTE EXISTS EXTERNAL
+EXTRACT FALSE FETCH FIRST FLOAT FLOAT4 FLOAT8 FOR FOREIGN FOUND FROM FULL GENERAL GET GLOBAL GO GOTO
+GRANT GROUP GUID HAVING HOUR IDENTITY IEEEDOUBLE IEEESINGLE IGNORE IMAGE IMMEDIATE IN INDEX INDICATOR
+INHERITABLE INITIALLY INNER INPUT INSENSITIVE INSERT INT INTEGER INTEGER1 INTEGER2 INTEGER4 INTERSECT
+INTERVAL INTO IS ISOLATION JOIN KEY LANGUAGE LAST LEADING LEFT LEVEL LIKE LOCAL LOGICAL LOGICAL1 LONG
+LONGBINARY LONGCHAR LONGTEXT LOWER MATCH MAX MEMO MIN MINUTE MODULE MONEY MONTH NAMES NATIONAL NATURAL
+NCHAR NEXT NO NOT NOTE NULL NULLIF NUMBER NUMERIC OBJECT OCTET_LENGTH OF OLEOBJECT ON ONLY OPEN OPTION
+OR ORDER OUTER OUTPUT OVERLAPS OWNERACCESS PAD PARAMETERS PARTIAL PASSWORD PERCENT PIVOT POSITION
+PRECISION PREPARE PRESERVE PRIMARY PRIOR PRIVILEGES PROC PROCEDURE PUBLIC READ REAL REFERENCES RELATIVE
+RESTRICT REVOKE RIGHT ROLLBACK ROWS SCHEMA SCROLL SECOND SECTION SELECT SELECTSCHEMA SELECTSECURITY
+SESSION SESSION_USER SET SHORT SINGLE SIZE SMALLINT SOME SPACE SQL SQLCODE SQLERROR SQLSTATE STRING
+SUBSTRING SUM SYSTEM_USER TABLE TABLEID TEMPORARY TEXT THEN TIME TIMESTAMP TIMEZONE_HOUR TIMEZONE_MINUTE
+TO TOP TRAILING TRANSACTION TRANSFORM TRANSLATE TRANSLATION TRIM TRUE UNION UNIQUE UNIQUEIDENTIFIER
+UNKNOWN UPDATE UPDATEIDENTITY UPDATEOWNER UPDATESECURITY UPPER USAGE USER USING VALUE VALUES VARBINARY
+VARCHAR VARYING VIEW WHEN WHENEVER WHERE WITH WORK WRITE YEAR YESNO ZONE
+"""
+
+RESERVED_WORDS: frozenset[str] = frozenset(word.casefold() for word in (_ACCESS + _ENGINE).split())
+"""Case-folded Access + Access database engine reserved words."""