pyquickbase 0.1.0a1__py3-none-any.whl

pyquickbase/_config.py

@@ -0,0 +1,93 @@
+"""Validation and normalization of client settings. No network access."""
+
+import platform
+import re
+from collections.abc import Collection
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._version import __version__
+from .errors import ConfigurationError, ReadOnlyError
+
+DEFAULT_BASE_URL = "https://api.quickbase.com/v1"
+DEFAULT_TIMEOUT = 30.0
+ENV_REALM = "QB_REALM"
+ENV_TOKEN = "QB_USER_TOKEN"
+
+_HOSTNAME = re.compile(r"[a-z0-9-]+(\.[a-z0-9-]+)+")
+_LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
+_READ_ONLY_POSTS = {"/records/query"}
+
+
+def normalize_realm(realm: str) -> str:
+    """Return the full realm hostname from `acme`, a hostname, or a realm URL."""
+    host = re.sub(r"^https?://", "", realm.strip().lower()).split("/", 1)[0]
+    if host and "." not in host:
+        host = f"{host}.quickbase.com"
+    if not _HOSTNAME.fullmatch(host):
+        raise ConfigurationError(f"Invalid realm {realm!r}. Expected e.g. 'acme.quickbase.com'.")
+    return host
+
+
+def validate_token(token: str) -> str:
+    """Reject values that can't be a token. The token is never included in the error."""
+    token = token.strip()
+    if not token or any(c.isspace() or not c.isprintable() for c in token):
+        raise ConfigurationError("The token is empty or contains whitespace or control characters.")
+    return token
+
+
+def validate_base_url(base_url: str) -> str:
+    """Require HTTPS so a token can't be sent in clear text, except to the local machine."""
+    parts = urlsplit(base_url)
+    if parts.scheme != "https" and not (
+        parts.scheme == "http" and parts.hostname in _LOOPBACK_HOSTS
+    ):
+        raise ConfigurationError(f"base_url must use https, got {base_url!r}.")
+    return base_url.rstrip("/")
+
+
+def build_url(base_url: str, path: str) -> str:
+    """Join a path to the base URL, refusing anything that could send the token to another host."""
+    if not path.startswith("/") or path.startswith("//") or any(c in path for c in "?#\\"):
+        raise ValueError(f"path must look like '/tables/abc', without a query string: {path!r}")
+    return f"{base_url}{path}"
+
+
+def normalize_allowed_writes(
+    read_only: bool, allowed_writes: Collection[tuple[str, str]] | None
+) -> frozenset[tuple[str, str]] | None:
+    """Return the writes a client may send, or None if it may send anything."""
+    if read_only and allowed_writes is not None:
+        raise ConfigurationError("Use read_only or allowed_writes, not both.")
+    if allowed_writes is not None:
+        return frozenset((method.upper(), path) for method, path in allowed_writes)
+    return frozenset() if read_only else None
+
+
+def check_allowed(method: str, path: str, allowed_writes: frozenset[tuple[str, str]]) -> None:
+    """Allow only known reads and listed writes. Queries are POSTs, so method alone isn't enough."""
+    if method == "GET" or (method == "POST" and path in _READ_ONLY_POSTS):
+        return
+    if (method, path) not in allowed_writes:
+        limit = "limited to reads and specific writes" if allowed_writes else "read-only"
+        raise ReadOnlyError(f"This client is {limit}, so it won't send {method} {path}.")
+
+
+def build_user_agent(prefix: str | None) -> str:
+    agent = (
+        f"pyquickbase/{__version__} python/{platform.python_version()} httpx/{httpx.__version__}"
+    )
+    return f"{prefix} {agent}" if prefix else agent
+
+
+def read_env(environ: dict[str, str] | None = None) -> tuple[str, str]:
+    """Read the realm and token from the environment, naming any that are missing."""
+    import os
+
+    env = os.environ if environ is None else environ
+    missing = [name for name in (ENV_REALM, ENV_TOKEN) if not env.get(name, "").strip()]
+    if missing:
+        raise ConfigurationError(f"Missing environment variables: {', '.join(missing)}")
+    return env[ENV_REALM], env[ENV_TOKEN]

pyquickbase/_models.py

@@ -0,0 +1,241 @@
+"""Typed views of Quickbase metadata and records. No network access."""
+
+import difflib
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any, TypeVar
+
+from .errors import InvalidResponseError, UnknownFieldError
+
+RECORD_ID_FIELD = 3
+
+
+T = TypeVar("T")
+
+
+def parse(parser: Callable[[Any], T], payload: Any, what: str) -> T:
+    """Run a parser, reporting a response of the wrong shape as a Quickbase-level error."""
+    try:
+        return parser(payload)
+    except (KeyError, TypeError, AttributeError, ValueError) as exc:
+        raise InvalidResponseError(f"Quickbase returned an unexpected {what} response.") from exc
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppInfo:
+    """An app's metadata. `raw` holds everything Quickbase returned."""
+
+    id: str
+    name: str
+    description: str
+    time_zone: str | None
+    date_format: str | None
+    raw: Mapping[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> "AppInfo":
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            description=data.get("description") or "",
+            time_zone=data.get("timeZone"),
+            date_format=data.get("dateFormat"),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TableInfo:
+    """A table's metadata. `raw` holds everything Quickbase returned."""
+
+    id: str
+    name: str
+    description: str
+    key_field_id: int | None
+    raw: Mapping[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> "TableInfo":
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            description=data.get("description") or "",
+            key_field_id=data.get("keyFieldId"),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Field:
+    """A field's metadata. `mode` is `formula`, `lookup`, `summary`, or None for plain fields."""
+
+    id: int
+    label: str
+    type: str
+    mode: str | None
+    required: bool
+    unique: bool
+    appears_by_default: bool
+    choices: tuple[str, ...]
+    allow_new_choices: bool
+    raw: Mapping[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> "Field":
+        properties: Mapping[str, Any] = data.get("properties") or {}
+        return cls(
+            id=data["id"],
+            label=data["label"],
+            type=data["fieldType"],
+            mode=data.get("mode") or None,
+            required=bool(data.get("required")),
+            unique=bool(data.get("unique")),
+            appears_by_default=bool(data.get("appearsByDefault")),
+            choices=tuple(properties.get("choices") or ()),
+            allow_new_choices=bool(properties.get("allowNewChoices")),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Relationship:
+    """A parent-child link between two tables."""
+
+    id: int
+    parent_table_id: str
+    child_table_id: str
+    foreign_key_field_id: int | None
+    lookup_field_ids: tuple[int, ...]
+    is_cross_app: bool
+    raw: Mapping[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> "Relationship":
+        foreign_key: Mapping[str, Any] = data.get("foreignKeyField") or {}
+        return cls(
+            id=data["id"],
+            parent_table_id=data["parentTableId"],
+            child_table_id=data["childTableId"],
+            foreign_key_field_id=foreign_key.get("id"),
+            lookup_field_ids=tuple(item["id"] for item in data.get("lookupFields") or ()),
+            is_cross_app=bool(data.get("isCrossApp")),
+            raw=data,
+        )
+
+
+class FieldIndex:
+    """Find a table's fields by label or ID."""
+
+    def __init__(self, fields: Iterable[Field]) -> None:
+        self._by_id = {item.id: item for item in fields}
+        self._by_label: dict[str, list[Field]] = {}
+        for item in self._by_id.values():
+            self._by_label.setdefault(item.label, []).append(item)
+
+    def has_label(self, label: str) -> bool:
+        return label in self._by_label
+
+    def resolve(self, ref: str | int) -> Field:
+        """Return the field for a label (`str`) or ID (`int`)."""
+        if isinstance(ref, str):
+            return self._resolve_label(ref)
+        found = None if isinstance(ref, bool) else self._by_id.get(ref)
+        if found is None:
+            raise UnknownFieldError(f"This table has no field with ID {ref!r}.")
+        return found
+
+    def _resolve_label(self, label: str) -> Field:
+        matches = self._by_label.get(label, [])
+        if len(matches) == 1:
+            return matches[0]
+        if matches:
+            ids = sorted(item.id for item in matches)
+            raise UnknownFieldError(f"Several fields are labeled {label!r}. Use an ID: {ids}.")
+        close = difflib.get_close_matches(label, self._by_label, n=3)
+        hint = f" Did you mean {' or '.join(repr(name) for name in close)}?" if close else ""
+        raise UnknownFieldError(f"This table has no field labeled {label!r}.{hint}")
+
+
+def _convert(value: Any, field_type: str) -> Any:
+    """Turn dates and timestamps into Python objects, leaving anything unexpected unchanged."""
+    if value == "" and field_type in ("date", "timestamp"):
+        return None  # how Quickbase returns an empty date
+    if isinstance(value, str):
+        try:
+            if field_type == "date":
+                return date.fromisoformat(value)
+            if field_type == "timestamp":
+                return datetime.fromisoformat(value)
+        except ValueError:
+            return value
+    return value
+
+
+class Record(Mapping[str | int, Any]):
+    """One record. Read values by field label or ID: `record["Status"]` or `record[7]`.
+
+    Iterating yields labels, so `dict(record)` gives `{label: value}`. Date fields are `date`
+    objects and timestamp fields are timezone-aware `datetime` objects, or None when empty.
+    """
+
+    __slots__ = ("_labels", "_values")
+
+    def __init__(self, values: Mapping[int, Any], labels: Mapping[str, int]) -> None:
+        self._values = values
+        self._labels = labels
+
+    @property
+    def id(self) -> int:
+        """The Record ID#, which queries always select."""
+        return self._values[RECORD_ID_FIELD]
+
+    def __getitem__(self, key: str | int) -> Any:
+        field_id = self._labels[key] if isinstance(key, str) else key
+        return self._values[field_id]
+
+    def __iter__(self) -> Iterator[str | int]:
+        return iter(label for label, field_id in self._labels.items() if field_id in self._values)
+
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
+
+    def __repr__(self) -> str:
+        # Values may be sensitive and reprs end up in logs, so show only the shape.
+        return f"Record(id={self._values.get(RECORD_ID_FIELD)!r}, fields={len(self)})"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Page:
+    """One page of query results. `total` counts every match, not just this page."""
+
+    records: tuple[Record, ...]
+    total: int
+    skip: int
+
+    @property
+    def has_more(self) -> bool:
+        return self.next_skip < self.total
+
+    @property
+    def next_skip(self) -> int:
+        """The `skip` that fetches the following page."""
+        return self.skip + len(self.records)
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> "Page":
+        fields = data["fields"]
+        labels: dict[str, int] = {item["label"]: item["id"] for item in fields}
+        types: dict[int, str] = {item["id"]: item["type"] for item in fields}
+        records = tuple(
+            Record(
+                {
+                    int(field_id): _convert(cell["value"], types.get(int(field_id), ""))
+                    for field_id, cell in row.items()
+                },
+                labels,
+            )
+            for row in data["data"]
+        )
+        metadata = data["metadata"]
+        return cls(records=records, total=metadata["totalRecords"], skip=metadata["skip"])

pyquickbase/_query.py

@@ -0,0 +1,315 @@
+"""Build and check `where` clauses and query bodies. No network access.
+
+Quickbase accepts many broken queries and answers with plausible results: a lowercase or unknown
+operator acts like "contains", and an unknown field matches nothing. Everything here exists so
+that those mistakes raise an error instead. See docs/api-notes.md for the tested behavior.
+"""
+
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any, ClassVar
+
+from ._models import RECORD_ID_FIELD, Field, FieldIndex
+from .errors import QueryError, UnknownFieldError
+
+FieldRef = str | int
+OPERATORS = frozenset(
+    {
+        "EX", "XEX", "CT", "XCT", "SW", "XSW", "LT", "LTE", "GT", "GTE",
+        "BF", "OBF", "AF", "OAF", "IR", "XIR", "HAS", "XHAS", "TV", "XTV",
+    }
+)  # fmt: skip
+_CONDITION = re.compile(
+    r"\{\s*(\d+)\s*\.\s*([A-Za-z]+)\s*\.\s*('(?:[^'{}\\]|\\[^{}])*'|[^'{}\\]*?)\s*\}"
+)
+_JOIN = re.compile(r"(?:AND|OR)\b")
+_ESCAPE = re.compile(r"\\(.)")
+_WHERE_HELP = (
+    "Each condition must be {fieldId.OPERATOR.'value'} in its own braces, joined outside the "
+    "braces with AND or OR in uppercase. Write an apostrophe in a value as \\'."
+)
+
+
+def format_value(value: Any) -> str:
+    """Render a Python value for use between the quotes of a condition.
+
+    Backslashes and quotes are escaped. Braces are rejected because Quickbase can't search for
+    them, and because every way we've found to break out of a value relies on one.
+    """
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float | Decimal):
+        return str(value)
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            raise QueryError("A datetime in a query needs a timezone, so its meaning is clear.")
+        return str(int(value.timestamp() * 1000))
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, str):
+        if "{" in value or "}" in value:
+            raise QueryError("Quickbase can't search for values containing { or }.")
+        return value.replace("\\", "\\\\").replace("'", "\\'")
+    raise QueryError(f"Can't use a value of type {type(value).__name__} in a query.")
+
+
+class Expression:
+    """A query condition. Combine with `&` and `|`, not `and` and `or`."""
+
+    __slots__ = ()
+
+    def __and__(self, other: "Expression") -> "Group":
+        return Group.of("AND", self, other)
+
+    def __or__(self, other: "Expression") -> "Group":
+        return Group.of("OR", self, other)
+
+    def __bool__(self) -> bool:
+        # `a and b` or `1 < F("x") < 5` would otherwise silently drop a condition.
+        raise QueryError(
+            "Combine conditions with & and |, not `and`, `or`, or chained comparisons."
+        )
+
+    def compile(self, fields: FieldIndex) -> str:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True, slots=True)
+class Condition(Expression):
+    field: FieldRef
+    operator: str
+    value: str
+
+    def compile(self, fields: FieldIndex) -> str:
+        return f"{{{fields.resolve(self.field).id}.{self.operator}.'{self.value}'}}"
+
+
+@dataclass(frozen=True, slots=True)
+class Group(Expression):
+    joiner: str
+    parts: tuple[Expression, ...]
+
+    @classmethod
+    def of(cls, joiner: str, *parts: Expression) -> "Group":
+        # Callers without a type checker can pass anything here.
+        if not all(isinstance(part, Expression) for part in parts):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise QueryError("Conditions can only be combined with other conditions.")
+        flat: list[Expression] = []
+        for part in parts:
+            if isinstance(part, Group) and part.joiner == joiner:
+                flat.extend(part.parts)
+            else:
+                flat.append(part)
+        return cls(joiner, tuple(flat))
+
+    def compile(self, fields: FieldIndex) -> str:
+        return self.joiner.join(
+            f"({part.compile(fields)})" if isinstance(part, Group) else part.compile(fields)
+            for part in self.parts
+        )
+
+
+class F:
+    """A field in a query, named by label (`str`) or ID (`int`).
+
+    `(F("Status") == "Done") & (F("Due Date") < date.today())`. Values are escaped for you, so
+    this is the safe way to use text you don't control. `== None` matches empty fields.
+    """
+
+    __slots__ = ("_field",)
+    __hash__: ClassVar[None] = None  # pyright: ignore[reportIncompatibleMethodOverride]
+
+    def __init__(self, field: FieldRef) -> None:
+        if isinstance(field, bool) or not isinstance(field, str | int):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise QueryError("F() takes a field label (str) or ID (int).")
+        self._field = field
+
+    def _condition(self, operator: str, value: Any) -> Condition:
+        return Condition(self._field, operator, format_value(value))
+
+    def _compare(self, operator: str, date_operator: str, value: Any) -> Condition:
+        return self._condition(date_operator if isinstance(value, date) else operator, value)
+
+    def __eq__(self, value: object) -> Condition:  # pyright: ignore[reportIncompatibleMethodOverride]
+        return self._condition("EX", value)
+
+    def __ne__(self, value: object) -> Condition:  # pyright: ignore[reportIncompatibleMethodOverride]
+        return self._condition("XEX", value)
+
+    def __lt__(self, value: Any) -> Condition:
+        return self._compare("LT", "BF", value)
+
+    def __le__(self, value: Any) -> Condition:
+        return self._compare("LTE", "OBF", value)
+
+    def __gt__(self, value: Any) -> Condition:
+        return self._compare("GT", "AF", value)
+
+    def __ge__(self, value: Any) -> Condition:
+        return self._compare("GTE", "OAF", value)
+
+    def contains(self, value: Any) -> Condition:
+        return self._condition("CT", value)
+
+    def not_contains(self, value: Any) -> Condition:
+        return self._condition("XCT", value)
+
+    def starts_with(self, value: Any) -> Condition:
+        return self._condition("SW", value)
+
+    def not_starts_with(self, value: Any) -> Condition:
+        return self._condition("XSW", value)
+
+    def is_in(self, values: Iterable[Any]) -> Expression:
+        """Match any of the values, as a series of `EX` conditions joined with `OR`."""
+        conditions = [self._condition("EX", value) for value in values]
+        if not conditions:
+            raise QueryError("is_in() needs at least one value.")
+        return conditions[0] if len(conditions) == 1 else Group.of("OR", *conditions)
+
+    def op(self, operator: str, value: Any) -> Condition:
+        """Use any Quickbase operator directly, such as `HAS` or `IR`."""
+        if operator not in OPERATORS:
+            raise QueryError(f"Unknown operator {operator!r}. Operators must be uppercase.")
+        return self._condition(operator, value)
+
+
+def _where_error(where: str, position: int, problem: str) -> QueryError:
+    return QueryError(
+        f"Invalid where clause: {problem} near `{where[position : position + 40]}`. {_WHERE_HELP}"
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class WhereCondition:
+    """One condition from a `where` string, with its value unquoted and unescaped."""
+
+    field_id: int
+    operator: str
+    value: str
+
+
+def _unquote(raw: str) -> str:
+    return _ESCAPE.sub(r"\1", raw[1:-1]) if raw.startswith("'") else raw
+
+
+def _scan_where(text: str, fields: FieldIndex) -> list[WhereCondition]:
+    found: list[WhereCondition] = []
+    position, depth, expect_condition = 0, 0, True
+    while position < len(text):
+        if text[position].isspace():
+            position += 1
+        elif expect_condition and text[position] == "(":
+            position, depth = position + 1, depth + 1
+        elif expect_condition:
+            match = _CONDITION.match(text, position)
+            if match is None:
+                raise _where_error(text, position, "expected a condition")
+            try:
+                fields.resolve(int(match[1]))
+            except UnknownFieldError:
+                raise _where_error(text, position, f"field {match[1]} doesn't exist") from None
+            if match[2] not in OPERATORS:
+                raise _where_error(
+                    text, position, f"unknown operator '{match[2]}', operators must be uppercase"
+                )
+            found.append(WhereCondition(int(match[1]), match[2], _unquote(match[3])))
+            position, expect_condition = match.end(), False
+        elif text[position] == ")":
+            if depth == 0:
+                raise _where_error(text, position, "unbalanced ')'")
+            position, depth = position + 1, depth - 1
+        else:
+            match = _JOIN.match(text, position)
+            if match is None:
+                raise _where_error(text, position, "expected AND or OR between conditions")
+            position, expect_condition = match.end(), True
+    if expect_condition:
+        raise _where_error(text, max(0, len(text) - 20), "clause is empty or ends with AND/OR")
+    if depth:
+        raise _where_error(text, 0, "unbalanced '('")
+    return found
+
+
+def validate_where(where: str, fields: FieldIndex) -> str:
+    """Check a hand-written `where` string and return it with outer whitespace removed.
+
+    This catches mistakes, not attacks: a string can legitimately contain several conditions, so
+    build queries with `F` when any of the text comes from someone else.
+    """
+    text = where.strip()
+    _scan_where(text, fields)
+    return text
+
+
+def parse_where(where: str, fields: Iterable[Field]) -> list[WhereCondition]:
+    """Check a hand-written `where` string and return its conditions.
+
+    Raises `QueryError` for the same mistakes that `table.query()` would. Useful for extra checks
+    of your own, or for finding out which fields a string refers to.
+    """
+    return _scan_where(where.strip(), FieldIndex(fields))
+
+
+def compile_where(where: Expression | str, fields: FieldIndex) -> str:
+    if isinstance(where, str):
+        return validate_where(where, fields)
+    if isinstance(where, Expression):  # pyright: ignore[reportUnnecessaryIsInstance]
+        return where.compile(fields)
+    raise QueryError("`where` must be a condition built with F, or a string.")
+
+
+def _as_list(refs: FieldRef | Sequence[FieldRef]) -> list[FieldRef]:
+    return [refs] if isinstance(refs, str | int) else list(refs)
+
+
+def _sort_field(ref: FieldRef, fields: FieldIndex) -> dict[str, Any]:
+    descending = False
+    if isinstance(ref, int) and not isinstance(ref, bool) and ref < 0:
+        ref, descending = -ref, True
+    elif isinstance(ref, str) and ref.startswith("-") and not fields.has_label(ref):
+        ref, descending = ref[1:], True
+    return {"fieldId": fields.resolve(ref).id, "order": "DESC" if descending else "ASC"}
+
+
+def _select_ids(
+    select: FieldRef | Sequence[FieldRef] | None, all_fields: Sequence[Field], fields: FieldIndex
+) -> list[int]:
+    if select is None:
+        ids = [item.id for item in all_fields if item.appears_by_default]
+    else:
+        ids = [fields.resolve(ref).id for ref in _as_list(select)]
+    return list(dict.fromkeys([RECORD_ID_FIELD, *ids]))
+
+
+def build_query_body(
+    table_id: str,
+    all_fields: Sequence[Field],
+    *,
+    where: Expression | str | None,
+    select: FieldRef | Sequence[FieldRef] | None,
+    order_by: FieldRef | Sequence[FieldRef] | None,
+) -> dict[str, Any]:
+    """Build the body of a records query, without its paging options.
+
+    Record ID# is always selected, and is always the last sort key so that pages stay stable
+    when other sort values tie.
+    """
+    fields = FieldIndex(all_fields)
+    refs = [] if order_by is None else _as_list(order_by)
+    sort = [_sort_field(ref, fields) for ref in refs]
+    if all(item["fieldId"] != RECORD_ID_FIELD for item in sort):
+        sort.append({"fieldId": RECORD_ID_FIELD, "order": "ASC"})
+    body: dict[str, Any] = {
+        "from": table_id,
+        "select": _select_ids(select, all_fields, fields),
+        "sortBy": sort,
+    }
+    if where is not None:
+        body["where"] = compile_where(where, fields)
+    return body