pyaccesskit 0.1.0__py3-none-any.whl

pyaccesskit/modules.py

@@ -0,0 +1,101 @@
+"""VBA modules: the ``db.modules`` collection (creating and reading code needs Microsoft Access)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+from pyaccesskit._ops import design as design_ops
+from pyaccesskit.enums import ModuleKind, ObjectKind
+from pyaccesskit.errors import ObjectNotFoundError
+
+if TYPE_CHECKING:
+    from pyaccesskit._session.session import Session
+
+__all__ = ["Module", "ModuleCollection"]
+
+
+class Module:
+    """A standard or class module (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 module name."""
+        return self._name
+
+    @property
+    def kind(self) -> ModuleKind:
+        """Standard or class module."""
+        return design_ops.read_module(self._session.design(), self._name)[0]
+
+    @property
+    def code(self) -> str:
+        """The module's VBA source (without Access's class-module header)."""
+        return design_ops.read_module(self._session.design(), self._name)[1]
+
+    @code.setter
+    def code(self, value: str) -> None:
+        self._session.check_writable(f"update module {self._name!r}")
+        design_ops.create_module(self._session.design(), self._name, value, self.kind, replace=True)
+
+    def rename(self, new_name: str) -> None:
+        """Rename the module."""
+        self._session.check_writable(f"rename module {self._name!r}")
+        self._session.design().rename_object(ObjectKind.MODULE, self._name, new_name)
+        self._name = new_name
+
+    def drop(self) -> None:
+        """Delete the module."""
+        self._session.check_writable(f"drop module {self._name!r}")
+        self._session.design().delete_object(ObjectKind.MODULE, self._name)
+
+    def __repr__(self) -> str:
+        return f"<Module {self._name!r}>"
+
+
+class ModuleCollection:
+    """``db.modules``: standard and class modules (form/report modules are managed with their object)."""
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    def names(self) -> list[str]:
+        """Module names (read through DAO; does not need Microsoft Access)."""
+        return self._session.schema().list_documents(ObjectKind.MODULE)
+
+    def __iter__(self) -> Iterator[Module]:
+        return iter([Module(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) -> Module:
+        for actual in self.names():
+            if actual.casefold() == name.casefold():
+                return Module(self._session, actual)
+        raise ObjectNotFoundError(
+            f"module {name!r} does not exist", kind=ObjectKind.MODULE, name=name
+        )
+
+    def create(
+        self, name: str, code: str, *, kind: ModuleKind = ModuleKind.STANDARD, replace: bool = False
+    ) -> Module:
+        """Create a VBA module from source code.
+
+        ``Option Compare Database`` is added if missing (as Access does); the code is otherwise stored as
+        given. VBA source uses the Windows ANSI code page: characters outside it raise ``SpecError``.
+        """
+        self._session.check_writable(f"create module {name!r}")
+        design_ops.create_module(self._session.design(), name, code, kind, replace=replace)
+        return Module(self._session, name)
+
+    def drop(self, name: str) -> None:
+        """Delete a module."""
+        self[name].drop()

pyaccesskit/objects.py

@@ -0,0 +1,81 @@
+"""Generic management of Access objects and ``SaveAsText``/``LoadFromText`` text I/O (``db.objects``)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pyaccesskit._ops import design as design_ops
+from pyaccesskit.enums import ObjectKind
+from pyaccesskit.errors import SpecError
+
+if TYPE_CHECKING:
+    from pyaccesskit._session.session import Session
+
+__all__ = ["AccessObjects"]
+
+
+class AccessObjects:
+    """Forms, reports, macros and modules as Access sees them, including raw text import/export.
+
+    Text is exchanged as ``str`` with LF line endings and stored on disk as UTF-8; PyAccessKit converts to and
+    from the encodings Access requires (UTF-16 for forms/reports/queries/macros, ANSI for VBA modules).
+    """
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    @staticmethod
+    def _kind(kind: ObjectKind | str) -> ObjectKind:
+        value = ObjectKind(kind)
+        if value not in (*design_ops.DESIGN_KINDS, ObjectKind.QUERY):
+            raise SpecError(f"{value.value} objects are not supported here")
+        return value
+
+    def names(self, kind: ObjectKind | str) -> list[str]:
+        """Names of all objects of ``kind`` (read through DAO where possible)."""
+        value = self._kind(kind)
+        if value is ObjectKind.QUERY:
+            return [q.name for q in self._session.schema().list_queries()]
+        return self._session.schema().list_documents(value)
+
+    def export_text(self, kind: ObjectKind | str, name: str) -> str:
+        """``SaveAsText`` an object."""
+        return design_ops.export_object(self._session.design(), self._kind(kind), name)
+
+    def import_text(
+        self, kind: ObjectKind | str, name: str, text: str, *, replace: bool = False
+    ) -> None:
+        """``LoadFromText`` an object (Access replaces an existing object only when ``replace=True``)."""
+        self._session.check_writable(f"import {name!r}")
+        design_ops.import_object(
+            self._session.design(), self._kind(kind), name, text, replace=replace
+        )
+
+    def save_text(self, kind: ObjectKind | str, name: str, path: str | os.PathLike[str]) -> Path:
+        """Export an object to a UTF-8 text file; returns the path."""
+        target = Path(path)
+        target.write_text(self.export_text(kind, name), encoding="utf-8", newline="\n")
+        return target
+
+    def load_text(
+        self,
+        kind: ObjectKind | str,
+        name: str,
+        path: str | os.PathLike[str],
+        *,
+        replace: bool = False,
+    ) -> None:
+        """Import an object from a UTF-8 text file."""
+        self.import_text(kind, name, Path(path).read_text(encoding="utf-8"), replace=replace)
+
+    def delete(self, kind: ObjectKind | str, name: str) -> None:
+        """Delete a form, report, macro or module."""
+        self._session.check_writable(f"delete {name!r}")
+        self._session.design().delete_object(self._kind(kind), name)
+
+    def rename(self, kind: ObjectKind | str, old: str, new: str) -> None:
+        """Rename a form, report, macro or module."""
+        self._session.check_writable(f"rename {old!r}")
+        self._session.design().rename_object(self._kind(kind), old, new)

pyaccesskit/options.py

@@ -0,0 +1,40 @@
+"""Session options (how PyAccessKit starts and supervises Microsoft Access)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pyaccesskit.enums import DialogPolicy, MacroSecurity
+
+__all__ = ["SessionOptions"]
+
+
+@dataclass(frozen=True)
+class SessionOptions:
+    """Advanced settings for a database session. The defaults are right for build scripts.
+
+    Attributes:
+        visible: Show the Access window (useful for debugging). Dialog detection then only considers
+            standard dialog windows.
+        macro_security: What Access may run when it opens a database as its current database. The default,
+            ``DISABLE``, never runs AutoExec macros, startup-form code or VBA — whatever the user's Trust
+            Center says.
+        dialog_policy: What to do when Access shows a modal dialog during an automated call.
+        call_timeout: Seconds one operation may take before the owned Access process is terminated
+            (``None`` = no limit).
+        quit_timeout: Seconds to wait for Access to exit after ``Quit`` before terminating it.
+        kill_on_parent_exit: Put Access in a Windows job object so it dies with this Python process.
+        access_progid: ProgID used to start Access (e.g. ``"Access.Application.16"`` on multi-version
+            machines).
+        apply_native_defaults: When DAO creates a database, add the properties Access itself writes to new
+            databases (tabbed documents, themed controls...), so the result matches ``engine="access"``.
+    """
+
+    visible: bool = False
+    macro_security: MacroSecurity = MacroSecurity.DISABLE
+    dialog_policy: DialogPolicy = DialogPolicy.FAIL
+    call_timeout: float | None = 600.0
+    quit_timeout: float = 30.0
+    kill_on_parent_exit: bool = True
+    access_progid: str = "Access.Application"
+    apply_native_defaults: bool = True

pyaccesskit/properties.py

@@ -0,0 +1,74 @@
+"""Access to DAO property collections (the escape hatch for properties PyAccessKit does not model)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyaccesskit._backends.protocols import PropertyTarget
+from pyaccesskit.enums import PropertyType
+from pyaccesskit.errors import ObjectNotFoundError
+from pyaccesskit.schema import PropertyValue
+
+if TYPE_CHECKING:
+    from pyaccesskit._session.session import Session
+
+__all__ = ["PropertyBag"]
+
+
+class PropertyBag:
+    """The DAO ``Properties`` of a database, table, field or query.
+
+    Reading a property that does not exist raises :class:`~pyaccesskit.errors.ObjectNotFoundError` (a
+    ``LookupError``); :meth:`get` returns a default instead. Setting a missing property creates it — with the
+    DAO type Access itself uses for well-known properties (``Description``, ``AppTitle``, ``UseMDIMode``...)
+    or one inferred from the value, unless ``type`` is given::
+
+        db.properties["AppTitle"] = "Customer Manager"
+        db.tables["Customers"].properties.set("SubdatasheetName", "[None]")
+    """
+
+    def __init__(self, session: Session, target: PropertyTarget) -> None:
+        self._session = session
+        self._target = target
+
+    def __getitem__(self, name: str) -> PropertyValue:
+        return self._session.schema().get_property(self._target, name)
+
+    def get(self, name: str, default: PropertyValue = None) -> PropertyValue:
+        """The property value, or ``default`` if it does not exist."""
+        try:
+            return self[name]
+        except ObjectNotFoundError:
+            return default
+
+    def __contains__(self, name: object) -> bool:
+        if not isinstance(name, str):
+            return False
+        try:
+            self[name]
+        except ObjectNotFoundError:
+            return False
+        return True
+
+    def __setitem__(self, name: str, value: PropertyValue) -> None:
+        self.set(name, value)
+
+    def set(self, name: str, value: PropertyValue, type: PropertyType | None = None) -> None:
+        """Set (creating if necessary) a property; ``type`` forces the DAO type of a new property."""
+        self._session.check_writable(f"set property {name!r}")
+        self._session.schema().set_property(self._target, name, value, type)
+
+    def __delitem__(self, name: str) -> None:
+        self.delete(name)
+
+    def delete(self, name: str) -> None:
+        """Delete a user-defined property."""
+        self._session.check_writable(f"delete property {name!r}")
+        self._session.schema().delete_property(self._target, name)
+
+    def to_dict(self) -> dict[str, PropertyValue]:
+        """All readable properties."""
+        return self._session.schema().list_properties(self._target)
+
+    def __repr__(self) -> str:
+        return f"<PropertyBag of {self._target.describe()}>"

pyaccesskit/queries.py

@@ -0,0 +1,190 @@
+"""Saved queries: the ``db.queries`` collection and :class:`Query` handles."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import TYPE_CHECKING, Any, overload
+
+from pyaccesskit._backends.protocols import ParameterInfo, PropertyTarget
+from pyaccesskit._ops import schema as ops
+from pyaccesskit.enums import ObjectKind, QueryKind
+from pyaccesskit.errors import ObjectNotFoundError
+from pyaccesskit.properties import PropertyBag
+from pyaccesskit.schema import PassThroughOptions, QuerySpec
+from pyaccesskit.schema._base import build
+
+if TYPE_CHECKING:
+    from pyaccesskit._session.session import Session
+
+__all__ = ["Query", "QueryCollection"]
+
+
+class Query:
+    """A saved query (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 query name."""
+        return self._name
+
+    def to_spec(self) -> QuerySpec:
+        """The query's current definition (SQL as Access stored it)."""
+        return self._session.schema().read_query(self._name)
+
+    @property
+    def sql(self) -> str:
+        """The SQL text (Access reformats SQL when saving it)."""
+        return self.to_spec().sql
+
+    @sql.setter
+    def sql(self, value: str) -> None:
+        self._session.check_writable(f"update query {self._name!r}")
+        spec = build(QuerySpec, f"query {self._name!r}", name=self._name, sql=value)
+        self._session.schema().set_query_sql(self._name, spec.normalized().sql)
+
+    @property
+    def kind(self) -> QueryKind:
+        """Select, update, append, crosstab... as classified by Access."""
+        for info in self._session.schema().list_queries():
+            if info.name.casefold() == self._name.casefold():
+                return info.kind
+        raise ObjectNotFoundError(
+            f"query {self._name!r} does not exist", kind=ObjectKind.QUERY, name=self._name
+        )
+
+    @property
+    def parameters(self) -> list[ParameterInfo]:
+        """Declared and implicit parameters."""
+        return self._session.schema().query_parameters(self._name)
+
+    @property
+    def description(self) -> str | None:
+        """The query *Description*."""
+        return self.to_spec().description
+
+    @property
+    def properties(self) -> PropertyBag:
+        """The query's DAO properties."""
+        return PropertyBag(self._session, PropertyTarget.query(self._name))
+
+    def execute(self, params: Mapping[str, Any] | None = None) -> int:
+        """Run an action query; returns the number of affected rows."""
+        self._session.check_writable(f"run query {self._name!r}")
+        return self._session.schema().execute_saved(self._name, params)
+
+    def fetch(
+        self, params: Mapping[str, Any] | None = None, *, limit: int | None = None
+    ) -> list[dict[str, Any]]:
+        """Return the rows of a select query as dictionaries."""
+        return self._session.schema().fetch_saved(self._name, params, limit=limit).as_dicts()
+
+    def rename(self, new_name: str) -> None:
+        """Rename the query."""
+        self._session.check_writable(f"rename query {self._name!r}")
+        self._name = ops.rename_query(self._session.schema(), self._name, new_name)
+
+    def drop(self) -> None:
+        """Delete the query."""
+        self._session.check_writable(f"drop query {self._name!r}")
+        ops.drop_query(self._session.schema(), self._name)
+
+    def __repr__(self) -> str:
+        return f"<Query {self._name!r}>"
+
+
+class QueryCollection:
+    """``db.queries``: saved queries (hidden ``~`` queries are excluded unless asked for)."""
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    def names(self, *, include_hidden: bool = False) -> list[str]:
+        """Query names."""
+        return [
+            q.name
+            for q in self._session.schema().list_queries()
+            if include_hidden or not q.is_hidden
+        ]
+
+    def __iter__(self) -> Iterator[Query]:
+        return iter([Query(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) -> Query | None:
+        """The query called ``name`` (case-insensitive), or ``None``."""
+        actual = ops.find_query(self._session.schema(), name)
+        return Query(self._session, actual) if actual is not None else None
+
+    def __getitem__(self, name: str) -> Query:
+        query = self.get(name)
+        if query is None:
+            raise ObjectNotFoundError(
+                f"query {name!r} does not exist", kind=ObjectKind.QUERY, name=name
+            )
+        return query
+
+    @overload
+    def create(self, spec: QuerySpec, /, *, replace: bool = False) -> Query: ...
+
+    @overload
+    def create(
+        self, name: str, sql: str, /, *, description: str | None = None, replace: bool = False
+    ) -> Query: ...
+
+    def create(
+        self,
+        spec_or_name: QuerySpec | str,
+        sql: str | None = None,
+        /,
+        *,
+        description: str | None = None,
+        replace: bool = False,
+    ) -> Query:
+        """Create a saved query (``replace=True`` updates the SQL of an existing one)."""
+        if isinstance(spec_or_name, QuerySpec):
+            spec = spec_or_name
+        else:
+            spec = build(
+                QuerySpec,
+                f"query {spec_or_name!r}",
+                name=spec_or_name,
+                sql=sql or "",
+                description=description,
+            )
+        self._session.check_writable(f"create query {spec.name!r}")
+        ops.create_or_replace_query(self._session.schema(), spec, replace=replace)
+        return self[spec.name]
+
+    def create_pass_through(
+        self,
+        name: str,
+        sql: str,
+        *,
+        connect: str,
+        returns_records: bool = True,
+        timeout: int = 60,
+        replace: bool = False,
+    ) -> Query:
+        """Create an ODBC pass-through query (``connect`` must start with ``ODBC;``)."""
+        options = build(
+            PassThroughOptions,
+            f"pass-through query {name!r}",
+            connect=connect,
+            returns_records=returns_records,
+            timeout=timeout,
+        )
+        spec = build(QuerySpec, f"query {name!r}", name=name, sql=sql, pass_through=options)
+        return self.create(spec, replace=replace)
+
+    def drop(self, name: str) -> None:
+        """Delete a saved query."""
+        self[name].drop()

pyaccesskit/relationships.py

@@ -0,0 +1,143 @@
+"""Relationships: the ``db.relationships`` collection."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, overload
+
+from pyaccesskit._ops import schema as ops
+from pyaccesskit.enums import JoinType, ObjectKind
+from pyaccesskit.errors import ObjectNotFoundError
+from pyaccesskit.schema import ColumnRef, RelationshipSpec
+
+if TYPE_CHECKING:
+    from pyaccesskit._session.session import Session
+
+__all__ = ["Relationship", "RelationshipCollection"]
+
+
+class Relationship:
+    """A relationship (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 relationship name."""
+        return self._name
+
+    def to_spec(self) -> RelationshipSpec:
+        """The relationship's definition."""
+        for spec in self._session.schema().list_relationships():
+            if spec.effective_name.casefold() == self._name.casefold():
+                return spec
+        raise ObjectNotFoundError(
+            f"relationship {self._name!r} does not exist",
+            kind=ObjectKind.RELATIONSHIP,
+            name=self._name,
+        )
+
+    def drop(self) -> None:
+        """Delete the relationship."""
+        self._session.check_writable(f"drop relationship {self._name!r}")
+        ops.drop_relationship(self._session.schema(), self._name)
+
+    def __repr__(self) -> str:
+        return f"<Relationship {self._name!r}>"
+
+
+class RelationshipCollection:
+    """``db.relationships``."""
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    def specs(self) -> list[RelationshipSpec]:
+        """Every relationship as a spec."""
+        return self._session.schema().list_relationships()
+
+    def names(self) -> list[str]:
+        """Relationship names."""
+        return [spec.effective_name for spec in self.specs()]
+
+    def __iter__(self) -> Iterator[Relationship]:
+        return iter([Relationship(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) -> Relationship:
+        for actual in self.names():
+            if actual.casefold() == name.casefold():
+                return Relationship(self._session, actual)
+        raise ObjectNotFoundError(
+            f"relationship {name!r} does not exist", kind=ObjectKind.RELATIONSHIP, name=name
+        )
+
+    @overload
+    def create(self, spec: RelationshipSpec, /) -> Relationship: ...
+
+    @overload
+    def create(
+        self,
+        primary: ColumnRef,
+        foreign: ColumnRef,
+        /,
+        *,
+        name: str | None = None,
+        enforce_integrity: bool = True,
+        cascade_update: bool = False,
+        cascade_delete: bool = False,
+        one_to_one: bool = False,
+        join: JoinType = JoinType.INNER,
+    ) -> Relationship: ...
+
+    def create(
+        self,
+        primary: RelationshipSpec | ColumnRef,
+        foreign: ColumnRef | None = None,
+        /,
+        *,
+        name: str | None = None,
+        enforce_integrity: bool = True,
+        cascade_update: bool = False,
+        cascade_delete: bool = False,
+        one_to_one: bool = False,
+        join: JoinType = JoinType.INNER,
+    ) -> Relationship:
+        """Create a relationship from the primary ("one") side to the foreign ("many") side.
+
+        Example::
+
+            db.relationships.create("Customers.CustomerID", "Orders.CustomerID", cascade_delete=True)
+
+        The primary columns need a primary key or unique index. The default name follows Access's
+        convention (primary table + foreign table).
+        """
+        if isinstance(primary, RelationshipSpec):
+            spec = primary
+        else:
+            if foreign is None:
+                raise TypeError("create() needs both the primary and the foreign side")
+            spec = RelationshipSpec.between(
+                primary,
+                foreign,
+                name=name,
+                enforce_integrity=enforce_integrity,
+                cascade_update=cascade_update,
+                cascade_delete=cascade_delete,
+                one_to_one=one_to_one,
+                join=join,
+            )
+        self._session.check_writable(f"create relationship {spec.effective_name!r}")
+        created = ops.create_relationship(self._session.schema(), spec)
+        return Relationship(self._session, created.effective_name)
+
+    def drop(self, name: str) -> None:
+        """Delete a relationship."""
+        self[name].drop()