pyoq-sql 1.0.2__py3-none-any.whl

pyoq/schema/postgres/records.py

@@ -0,0 +1,384 @@
+"""Typed PostgreSQL catalog row records."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import cast
+
+from pyoq.errors import SchemaInspectionError
+from pyoq.schema.models import (
+    GeneratedKind,
+    Identifier,
+    KeyKind,
+    ObjectReference,
+    ReferentialAction,
+)
+
+_IDENTITY_KINDS = {
+    "a": GeneratedKind.IDENTITY_ALWAYS,
+    "d": GeneratedKind.IDENTITY_BY_DEFAULT,
+}
+_COMPUTED_KINDS = {
+    "s": GeneratedKind.COMPUTED_STORED,
+    "v": GeneratedKind.COMPUTED_VIRTUAL,
+}
+_KEY_KINDS = {"p": KeyKind.PRIMARY, "u": KeyKind.UNIQUE}
+_REFERENTIAL_ACTIONS = {
+    "a": ReferentialAction.NO_ACTION,
+    "r": ReferentialAction.RESTRICT,
+    "c": ReferentialAction.CASCADE,
+    "n": ReferentialAction.SET_NULL,
+    "d": ReferentialAction.SET_DEFAULT,
+}
+_DESCENDING_OPTION = 1
+
+
+@dataclass(frozen=True, slots=True)
+class ObjectRecord:
+    schema: str
+    name: str
+    kind: str
+    comment: str | None
+    definition: str | None
+
+    @property
+    def is_table(self) -> bool:
+        return self.kind in {"r", "p"}
+
+    @property
+    def is_materialized(self) -> bool:
+        return self.kind == "m"
+
+
+@dataclass(frozen=True, slots=True)
+class ColumnRecord:
+    schema: str
+    table: str
+    name: str
+    data_type: str
+    nullable: bool
+    type_kind: str
+    """What the column's own type is: a base type, a domain, or an enum."""
+
+    type_schema: str
+    type_name: str
+    domain_base: str | None
+    default: str | None
+    identity: str
+    computed: str
+    comment: str | None
+
+    @property
+    def generated_kind(self) -> GeneratedKind | None:
+        identity = _IDENTITY_KINDS.get(self.identity.strip())
+        if identity is not None:
+            return identity
+        return _COMPUTED_KINDS.get(self.computed.strip())
+
+
+@dataclass(frozen=True, slots=True)
+class ConstraintRecord:
+    schema: str
+    table: str
+    name: str
+    kind: str
+    definition: str
+    columns: tuple[str, ...]
+    target_schema: str | None
+    target_table: str | None
+    target_columns: tuple[str, ...]
+    on_update: str
+    on_delete: str
+
+    @property
+    def key_kind(self) -> KeyKind | None:
+        return _KEY_KINDS.get(self.kind)
+
+    @property
+    def target_reference(self) -> ObjectReference | None:
+        if self.target_schema is None or self.target_table is None:
+            return None
+        return ObjectReference(
+            Identifier(self.target_table),
+            Identifier(self.target_schema),
+        )
+
+    @property
+    def update_action(self) -> ReferentialAction:
+        return _referential_action(self.on_update)
+
+    @property
+    def delete_action(self) -> ReferentialAction:
+        return _referential_action(self.on_delete)
+
+
+@dataclass(frozen=True, slots=True)
+class IndexRecord:
+    schema: str
+    table: str
+    name: str
+    unique: bool
+    method: str
+    predicate: str | None
+    attribute_numbers: tuple[int, ...]
+    column_names: tuple[str | None, ...]
+    definitions: tuple[str, ...]
+    options: tuple[int, ...]
+
+    def descending(self, position: int) -> bool:
+        return bool(self.options[position] & _DESCENDING_OPTION)
+
+
+def _referential_action(code: str) -> ReferentialAction:
+    action = _REFERENTIAL_ACTIONS.get(code.strip())
+    if action is None:
+        message = f"unsupported PostgreSQL referential action: {code!r}"
+        raise SchemaInspectionError(message)
+    return action
+
+
+def read_object(row: tuple[object, ...]) -> ObjectRecord:
+    values = _row(row, 5)
+    return ObjectRecord(
+        _text(values[0]),
+        _text(values[1]),
+        _text(values[2]),
+        _optional_text(values[3]),
+        _optional_text(values[4]),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class EnumRecord:
+    schema: str
+    name: str
+    label: str
+    comment: str | None
+
+
+def read_enum(row: tuple[object, ...]) -> EnumRecord:
+    values = _row(row, 4)
+    return EnumRecord(
+        _text(values[0]),
+        _text(values[1]),
+        _text(values[2]),
+        _optional_text(values[3]),
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class DomainRecord:
+    schema: str
+    name: str
+    base_type: str
+    not_null: bool
+    default: str | None
+    comment: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class DomainCheckRecord:
+    schema: str
+    domain: str
+    name: str
+    definition: str
+
+
+@dataclass(frozen=True, slots=True)
+class RoutineRecord:
+    schema: str
+    name: str
+    kind: str
+    identifier: int
+    """What the database calls this routine, which separates two of a name."""
+
+    returns: str | None
+    position: int | None
+    parameter_name: str | None
+    mode: str
+    parameter_type: str | None
+    return_type_schema: str | None
+    return_type_name: str | None
+    return_type_kind: str | None
+    return_base_type: str | None
+    return_is_array: bool
+    parameter_type_schema: str | None
+    parameter_type_name: str | None
+    parameter_type_kind: str | None
+    parameter_base_type: str | None
+    parameter_is_array: bool
+    parameter_forbids_null: bool = False
+    """Whether the parameter's own type refuses a null, which a domain can."""
+    default_count: int = 0
+
+
+def read_domain(row: tuple[object, ...]) -> DomainRecord:
+    values = _row(row, 6)
+    return DomainRecord(
+        _text(values[0]),
+        _text(values[1]),
+        _text(values[2]),
+        _flag(values[3]),
+        _optional_text(values[4]),
+        _optional_text(values[5]),
+    )
+
+
+def read_domain_check(row: tuple[object, ...]) -> DomainCheckRecord:
+    values = _row(row, 4)
+    return DomainCheckRecord(
+        _text(values[0]),
+        _text(values[1]),
+        _text(values[2]),
+        _text(values[3]),
+    )
+
+
+def read_routine(row: tuple[object, ...]) -> RoutineRecord:
+    values = _row(row, 21)
+    return RoutineRecord(
+        _text(values[0]),
+        _text(values[1]),
+        _text(values[2]),
+        _number(values[3]),
+        _optional_text(values[4]),
+        None if values[5] is None else _number(values[5]),
+        _optional_text(values[6]),
+        _text(values[7]),
+        _optional_text(values[8]),
+        _optional_text(values[9]),
+        _optional_text(values[10]),
+        _optional_text(values[11]),
+        _optional_text(values[12]),
+        _flag(values[13]),
+        _optional_text(values[14]),
+        _optional_text(values[15]),
+        _optional_text(values[16]),
+        _optional_text(values[17]),
+        _flag(values[18]),
+        _flag(values[19]),
+        _number(values[20]),
+    )
+
+
+def read_column(row: tuple[object, ...]) -> ColumnRecord:
+    values = _row(row, 13)
+    return ColumnRecord(
+        _text(values[0]),
+        _text(values[1]),
+        _text(values[2]),
+        _text(values[3]),
+        _flag(values[4]),
+        _text(values[5]),
+        _text(values[6]),
+        _text(values[7]),
+        _optional_text(values[8]),
+        _optional_text(values[9]),
+        _text(values[10]),
+        _text(values[11]),
+        _optional_text(values[12]),
+    )
+
+
+def read_constraint(row: tuple[object, ...]) -> ConstraintRecord:
+    values = _row(row, 11)
+    return ConstraintRecord(
+        _text(values[0]),
+        _text(values[1]),
+        _text(values[2]),
+        _text(values[3]),
+        _text(values[4]),
+        _names(values[5]),
+        _optional_text(values[6]),
+        _optional_text(values[7]),
+        _names(values[8]),
+        _text(values[9]),
+        _text(values[10]),
+    )
+
+
+def read_index(row: tuple[object, ...]) -> IndexRecord:
+    values = _row(row, 10)
+    return IndexRecord(
+        _text(values[0]),
+        _text(values[1]),
+        _text(values[2]),
+        _flag(values[3]),
+        _text(values[4]),
+        _optional_text(values[5]),
+        _numbers(values[6]),
+        _optional_names(values[7]),
+        _names(values[8]),
+        _numbers(values[9]),
+    )
+
+
+def _row(row: tuple[object, ...], width: int) -> tuple[object, ...]:
+    if len(row) != width:
+        message = "PostgreSQL catalog row has an unexpected shape"
+        raise SchemaInspectionError(message)
+    return row
+
+
+def _text(value: object) -> str:
+    if not isinstance(value, str):
+        message = f"PostgreSQL catalog value is not text: {value!r}"
+        raise SchemaInspectionError(message)
+    return value
+
+
+def _optional_text(value: object) -> str | None:
+    return None if value is None else _text(value)
+
+
+def _flag(value: object) -> bool:
+    if not isinstance(value, bool):
+        message = f"PostgreSQL catalog value is not a flag: {value!r}"
+        raise SchemaInspectionError(message)
+    return value
+
+
+def _names(value: object) -> tuple[str, ...]:
+    return tuple(_text(item) for item in _sequence(value))
+
+
+def _optional_names(value: object) -> tuple[str | None, ...]:
+    return tuple(_optional_text(item) for item in _sequence(value))
+
+
+def _numbers(value: object) -> tuple[int, ...]:
+    return tuple(_number(item) for item in _sequence(value))
+
+
+def _number(value: object) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        message = f"PostgreSQL catalog value is not a number: {value!r}"
+        raise SchemaInspectionError(message)
+    return value
+
+
+def _sequence(value: object) -> list[object]:
+    if not isinstance(value, list):
+        message = f"PostgreSQL catalog value is not an array: {value!r}"
+        raise SchemaInspectionError(message)
+    return cast("list[object]", value)
+
+
+__all__ = (
+    "ColumnRecord",
+    "ConstraintRecord",
+    "DomainCheckRecord",
+    "DomainRecord",
+    "EnumRecord",
+    "IndexRecord",
+    "ObjectRecord",
+    "RoutineRecord",
+    "read_column",
+    "read_constraint",
+    "read_domain",
+    "read_domain_check",
+    "read_enum",
+    "read_index",
+    "read_object",
+    "read_routine",
+)