pyoq-sql 1.0.2__py3-none-any.whl

pyoq/schema/codec.py

@@ -0,0 +1,711 @@
+"""Versioned schema snapshot JSON codec."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from enum import StrEnum
+from typing import TypeVar, cast
+
+from pyoq.config import DatabaseDialect
+from pyoq.errors import SchemaSerializationError, SchemaValidationError
+from pyoq.schema import (
+    Capability,
+    CapabilitySet,
+    Catalog,
+    CheckConstraint,
+    Column,
+    Domain,
+    EnumType,
+    GeneratedKind,
+    GeneratedValue,
+    Identifier,
+    Index,
+    IndexTerm,
+    JsonValue,
+    Key,
+    KeyKind,
+    MetadataEntry,
+    ObjectReference,
+    ParameterMode,
+    ReferentialAction,
+    Relation,
+    Routine,
+    RoutineKind,
+    RoutineParameter,
+    Schema,
+    SchemaSnapshot,
+    SqlExpression,
+    SqlType,
+    Table,
+    TypeKind,
+    View,
+)
+
+JsonObject = dict[str, JsonValue]
+DecodedValue = TypeVar("DecodedValue")
+EnumValue = TypeVar("EnumValue", bound=StrEnum)
+
+
+def encode_snapshot(snapshot: SchemaSnapshot) -> str:
+    capabilities: list[JsonValue] = [
+        capability.value
+        for capability in sorted(
+            snapshot.capabilities.values, key=lambda item: item.value
+        )
+    ]
+    payload: JsonObject = {
+        "capabilities": capabilities,
+        "catalogs": [_encode_catalog(catalog) for catalog in snapshot.catalogs],
+        "dialect": snapshot.dialect.value,
+        "format_version": snapshot.format_version,
+    }
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def decode_snapshot(value: str) -> SchemaSnapshot:
+    try:
+        decoded: object = json.loads(value)
+        return _decode_snapshot(_object(decoded, "snapshot"))
+    except SchemaSerializationError:
+        raise
+    except (json.JSONDecodeError, SchemaValidationError, ValueError) as error:
+        message = "serialized schema snapshot is invalid"
+        raise SchemaSerializationError(message) from error
+
+
+def _encode_catalog(catalog: Catalog) -> JsonObject:
+    return {
+        "comment": catalog.comment,
+        "name": _encode_identifier(catalog.name),
+        "schemas": [_encode_schema(schema) for schema in catalog.schemas],
+    }
+
+
+def _encode_schema(schema: Schema) -> JsonObject:
+    return {
+        "comment": schema.comment,
+        "domains": [_encode_domain(domain) for domain in schema.domains],
+        "enums": [_encode_enum(enum) for enum in schema.enums],
+        "name": _encode_identifier(schema.name),
+        "routines": [_encode_routine(routine) for routine in schema.routines],
+        "tables": [_encode_table(table) for table in schema.tables],
+        "views": [_encode_view(view) for view in schema.views],
+    }
+
+
+def _encode_domain(domain: Domain) -> JsonObject:
+    return {
+        "checks": [_encode_check(check) for check in domain.checks],
+        "comment": domain.comment,
+        "data-type": _encode_sql_type(domain.data_type),
+        "default": None if domain.default is None else domain.default.text,
+        "name": domain.name.value,
+        "nullable": domain.nullable,
+    }
+
+
+def _encode_routine(routine: Routine) -> JsonObject:
+    return {
+        "comment": routine.comment,
+        "kind": routine.kind.value,
+        "name": routine.name.value,
+        "overload": routine.overload,
+        "parameters": [
+            _encode_parameter(parameter) for parameter in routine.parameters
+        ],
+        "returns": (
+            None if routine.returns is None else _encode_sql_type(routine.returns)
+        ),
+    }
+
+
+def _encode_parameter(parameter: RoutineParameter) -> JsonObject:
+    return {
+        "data-type": _encode_sql_type(parameter.data_type),
+        "has-default": parameter.has_default,
+        "mode": parameter.mode.value,
+        "name": _encode_identifier(parameter.name),
+        "nullable": parameter.nullable,
+    }
+
+
+def _encode_table(table: Table) -> JsonObject:
+    return {
+        "checks": [_encode_check(check) for check in table.checks],
+        "columns": [_encode_column(column) for column in table.columns],
+        "comment": table.comment,
+        "indexes": [_encode_index(index) for index in table.indexes],
+        "keys": [_encode_key(key) for key in table.keys],
+        "metadata": [_encode_metadata(entry) for entry in table.metadata],
+        "name": table.name.value,
+        "relations": [_encode_relation(relation) for relation in table.relations],
+    }
+
+
+def _encode_view(view: View) -> JsonObject:
+    return {
+        "columns": [_encode_column(column) for column in view.columns],
+        "comment": view.comment,
+        "definition": _encode_expression(view.definition),
+        "materialized": view.materialized,
+        "metadata": [_encode_metadata(entry) for entry in view.metadata],
+        "name": view.name.value,
+    }
+
+
+def _encode_enum(enum: EnumType) -> JsonObject:
+    return {
+        "comment": enum.comment,
+        "name": enum.name.value,
+        "values": list(enum.values),
+    }
+
+
+def _encode_column(column: Column) -> JsonObject:
+    return {
+        "comment": column.comment,
+        "data_type": _encode_sql_type(column.data_type),
+        "default": _encode_expression(column.default),
+        "generated": _encode_generated(column.generated),
+        "metadata": [_encode_metadata(entry) for entry in column.metadata],
+        "name": column.name.value,
+        "nullable": column.nullable,
+    }
+
+
+def _encode_sql_type(data_type: SqlType) -> JsonObject:
+    return {
+        "element_type": (
+            None
+            if data_type.element_type is None
+            else _encode_sql_type(data_type.element_type)
+        ),
+        "kind": data_type.kind.value,
+        "length": data_type.length,
+        "metadata": [_encode_metadata(entry) for entry in data_type.metadata],
+        "named_type": _encode_reference(data_type.named_type),
+        "precision": data_type.precision,
+        "scale": data_type.scale,
+        "source_name": data_type.source_name,
+    }
+
+
+def _encode_generated(value: GeneratedValue | None) -> JsonObject | None:
+    if value is None:
+        return None
+    return {
+        "expression": _encode_expression(value.expression),
+        "kind": value.kind.value,
+    }
+
+
+def _encode_key(key: Key) -> JsonObject:
+    return {
+        "columns": [column.value for column in key.columns],
+        "kind": key.kind.value,
+        "name": _encode_identifier(key.name),
+    }
+
+
+def _encode_relation(relation: Relation) -> JsonObject:
+    return {
+        "columns": [column.value for column in relation.columns],
+        "name": _encode_identifier(relation.name),
+        "on_delete": relation.on_delete.value,
+        "on_update": relation.on_update.value,
+        "target": _encode_reference(relation.target),
+        "target_columns": [column.value for column in relation.target_columns],
+    }
+
+
+def _encode_index(index: Index) -> JsonObject:
+    return {
+        "method": index.method,
+        "name": index.name.value,
+        "predicate": _encode_expression(index.predicate),
+        "terms": [_encode_index_term(term) for term in index.terms],
+        "unique": index.unique,
+    }
+
+
+def _encode_index_term(term: IndexTerm) -> JsonObject:
+    return {
+        "column": _encode_identifier(term.column),
+        "descending": term.descending,
+        "expression": _encode_expression(term.expression),
+    }
+
+
+def _encode_check(check: CheckConstraint) -> JsonObject:
+    return {
+        "expression": check.expression.text,
+        "name": _encode_identifier(check.name),
+    }
+
+
+def _encode_reference(reference: ObjectReference | None) -> JsonObject | None:
+    if reference is None:
+        return None
+    return {
+        "catalog": _encode_identifier(reference.catalog),
+        "name": reference.name.value,
+        "schema": _encode_identifier(reference.schema),
+    }
+
+
+def _encode_metadata(entry: MetadataEntry) -> JsonObject:
+    return {"key": entry.key, "value": entry.value}
+
+
+def _encode_identifier(identifier: Identifier | None) -> str | None:
+    return None if identifier is None else identifier.value
+
+
+def _encode_expression(expression: SqlExpression | None) -> str | None:
+    return None if expression is None else expression.text
+
+
+def _decode_snapshot(value: JsonObject) -> SchemaSnapshot:
+    location = "snapshot"
+    _require_fields(
+        value,
+        {"capabilities", "catalogs", "dialect", "format_version"},
+        location,
+    )
+    capabilities = frozenset(
+        _enum(Capability, item, f"{location}.capabilities")
+        for item in _array(value["capabilities"], f"{location}.capabilities")
+    )
+    catalogs = _decode_array(value["catalogs"], f"{location}.catalogs", _decode_catalog)
+    return SchemaSnapshot(
+        dialect=_enum(DatabaseDialect, value["dialect"], f"{location}.dialect"),
+        catalogs=catalogs,
+        capabilities=CapabilitySet(capabilities),
+        format_version=_integer(value["format_version"], f"{location}.format_version"),
+    )
+
+
+def _decode_catalog(value: JsonValue, location: str) -> Catalog:
+    record = _record(value, {"comment", "name", "schemas"}, location)
+    return Catalog(
+        name=_optional_identifier(record["name"], f"{location}.name"),
+        schemas=_decode_array(record["schemas"], f"{location}.schemas", _decode_schema),
+        comment=_optional_string(record["comment"], f"{location}.comment"),
+    )
+
+
+def _decode_schema(value: JsonValue, location: str) -> Schema:
+    record = _record(
+        value,
+        {"comment", "domains", "enums", "name", "routines", "tables", "views"},
+        location,
+    )
+    return Schema(
+        name=_optional_identifier(record["name"], f"{location}.name"),
+        tables=_decode_array(record["tables"], f"{location}.tables", _decode_table),
+        views=_decode_array(record["views"], f"{location}.views", _decode_view),
+        enums=_decode_array(record["enums"], f"{location}.enums", _decode_enum),
+        domains=_decode_array(record["domains"], f"{location}.domains", _decode_domain),
+        routines=_decode_array(
+            record["routines"], f"{location}.routines", _decode_routine
+        ),
+        comment=_optional_string(record["comment"], f"{location}.comment"),
+    )
+
+
+def _decode_domain(value: JsonValue, location: str) -> Domain:
+    record = _record(
+        value,
+        {"checks", "comment", "data-type", "default", "name", "nullable"},
+        location,
+    )
+    default = _optional_string(record["default"], f"{location}.default")
+    return Domain(
+        name=_identifier(record["name"], f"{location}.name"),
+        data_type=_decode_sql_type(record["data-type"], f"{location}.data-type"),
+        nullable=_boolean(record["nullable"], f"{location}.nullable"),
+        default=None if default is None else SqlExpression(default),
+        checks=_decode_array(record["checks"], f"{location}.checks", _decode_check),
+        comment=_optional_string(record["comment"], f"{location}.comment"),
+    )
+
+
+def _decode_routine(value: JsonValue, location: str) -> Routine:
+    record = _record(
+        value,
+        {"comment", "kind", "name", "overload", "parameters", "returns"},
+        location,
+    )
+    returns = record["returns"]
+    return Routine(
+        name=_identifier(record["name"], f"{location}.name"),
+        kind=_routine_kind(record["kind"], f"{location}.kind"),
+        parameters=_decode_array(
+            record["parameters"], f"{location}.parameters", _decode_parameter
+        ),
+        returns=(
+            None
+            if returns is None
+            else _decode_sql_type(returns, f"{location}.returns")
+        ),
+        overload=_optional_string(record["overload"], f"{location}.overload"),
+        comment=_optional_string(record["comment"], f"{location}.comment"),
+    )
+
+
+def _decode_parameter(value: JsonValue, location: str) -> RoutineParameter:
+    record = _record(
+        value, {"data-type", "has-default", "mode", "name", "nullable"}, location
+    )
+    return RoutineParameter(
+        name=_optional_identifier(record["name"], f"{location}.name"),
+        data_type=_decode_sql_type(record["data-type"], f"{location}.data-type"),
+        mode=_parameter_mode(record["mode"], f"{location}.mode"),
+        has_default=_boolean(record["has-default"], f"{location}.has-default"),
+        nullable=_boolean(record["nullable"], f"{location}.nullable"),
+    )
+
+
+def _routine_kind(value: JsonValue, location: str) -> RoutineKind:
+    return _enum(RoutineKind, value, location)
+
+
+def _parameter_mode(value: JsonValue, location: str) -> ParameterMode:
+    return _enum(ParameterMode, value, location)
+
+
+def _decode_table(value: JsonValue, location: str) -> Table:
+    record = _record(
+        value,
+        {
+            "checks",
+            "columns",
+            "comment",
+            "indexes",
+            "keys",
+            "metadata",
+            "name",
+            "relations",
+        },
+        location,
+    )
+    return Table(
+        name=_identifier(record["name"], f"{location}.name"),
+        columns=_decode_array(record["columns"], f"{location}.columns", _decode_column),
+        keys=_decode_array(record["keys"], f"{location}.keys", _decode_key),
+        relations=_decode_array(
+            record["relations"],
+            f"{location}.relations",
+            _decode_relation,
+        ),
+        indexes=_decode_array(record["indexes"], f"{location}.indexes", _decode_index),
+        checks=_decode_array(record["checks"], f"{location}.checks", _decode_check),
+        comment=_optional_string(record["comment"], f"{location}.comment"),
+        metadata=_decode_array(
+            record["metadata"],
+            f"{location}.metadata",
+            _decode_metadata,
+        ),
+    )
+
+
+def _decode_view(value: JsonValue, location: str) -> View:
+    record = _record(
+        value,
+        {"columns", "comment", "definition", "materialized", "metadata", "name"},
+        location,
+    )
+    return View(
+        name=_identifier(record["name"], f"{location}.name"),
+        columns=_decode_array(record["columns"], f"{location}.columns", _decode_column),
+        definition=_optional_expression(record["definition"], f"{location}.definition"),
+        materialized=_boolean(record["materialized"], f"{location}.materialized"),
+        comment=_optional_string(record["comment"], f"{location}.comment"),
+        metadata=_decode_array(
+            record["metadata"],
+            f"{location}.metadata",
+            _decode_metadata,
+        ),
+    )
+
+
+def _decode_enum(value: JsonValue, location: str) -> EnumType:
+    record = _record(value, {"comment", "name", "values"}, location)
+    values = tuple(
+        _string(item, f"{location}.values")
+        for item in _array(record["values"], f"{location}.values")
+    )
+    return EnumType(
+        name=_identifier(record["name"], f"{location}.name"),
+        values=values,
+        comment=_optional_string(record["comment"], f"{location}.comment"),
+    )
+
+
+def _decode_column(value: JsonValue, location: str) -> Column:
+    record = _record(
+        value,
+        {
+            "comment",
+            "data_type",
+            "default",
+            "generated",
+            "metadata",
+            "name",
+            "nullable",
+        },
+        location,
+    )
+    return Column(
+        name=_identifier(record["name"], f"{location}.name"),
+        data_type=_decode_sql_type(record["data_type"], f"{location}.data_type"),
+        nullable=_boolean(record["nullable"], f"{location}.nullable"),
+        default=_optional_expression(record["default"], f"{location}.default"),
+        generated=_decode_generated(record["generated"], f"{location}.generated"),
+        comment=_optional_string(record["comment"], f"{location}.comment"),
+        metadata=_decode_array(
+            record["metadata"],
+            f"{location}.metadata",
+            _decode_metadata,
+        ),
+    )
+
+
+def _decode_sql_type(value: JsonValue, location: str) -> SqlType:
+    record = _record(
+        value,
+        {
+            "element_type",
+            "kind",
+            "length",
+            "metadata",
+            "named_type",
+            "precision",
+            "scale",
+            "source_name",
+        },
+        location,
+    )
+    element = record["element_type"]
+    named = record["named_type"]
+    return SqlType(
+        kind=_enum(TypeKind, record["kind"], f"{location}.kind"),
+        source_name=_string(record["source_name"], f"{location}.source_name"),
+        length=_optional_integer(record["length"], f"{location}.length"),
+        precision=_optional_integer(record["precision"], f"{location}.precision"),
+        scale=_optional_integer(record["scale"], f"{location}.scale"),
+        element_type=(
+            None
+            if element is None
+            else _decode_sql_type(element, f"{location}.element_type")
+        ),
+        named_type=(
+            None
+            if named is None
+            else _decode_reference(named, f"{location}.named_type")
+        ),
+        metadata=_decode_array(
+            record["metadata"],
+            f"{location}.metadata",
+            _decode_metadata,
+        ),
+    )
+
+
+def _decode_generated(value: JsonValue, location: str) -> GeneratedValue | None:
+    if value is None:
+        return None
+    record = _record(value, {"expression", "kind"}, location)
+    return GeneratedValue(
+        kind=_enum(GeneratedKind, record["kind"], f"{location}.kind"),
+        expression=_optional_expression(record["expression"], f"{location}.expression"),
+    )
+
+
+def _decode_key(value: JsonValue, location: str) -> Key:
+    record = _record(value, {"columns", "kind", "name"}, location)
+    return Key(
+        kind=_enum(KeyKind, record["kind"], f"{location}.kind"),
+        columns=_decode_identifiers(record["columns"], f"{location}.columns"),
+        name=_optional_identifier(record["name"], f"{location}.name"),
+    )
+
+
+def _decode_relation(value: JsonValue, location: str) -> Relation:
+    record = _record(
+        value,
+        {"columns", "name", "on_delete", "on_update", "target", "target_columns"},
+        location,
+    )
+    return Relation(
+        columns=_decode_identifiers(record["columns"], f"{location}.columns"),
+        target=_decode_reference(record["target"], f"{location}.target"),
+        target_columns=_decode_identifiers(
+            record["target_columns"],
+            f"{location}.target_columns",
+        ),
+        name=_optional_identifier(record["name"], f"{location}.name"),
+        on_update=_enum(
+            ReferentialAction,
+            record["on_update"],
+            f"{location}.on_update",
+        ),
+        on_delete=_enum(
+            ReferentialAction,
+            record["on_delete"],
+            f"{location}.on_delete",
+        ),
+    )
+
+
+def _decode_index(value: JsonValue, location: str) -> Index:
+    record = _record(
+        value,
+        {"method", "name", "predicate", "terms", "unique"},
+        location,
+    )
+    return Index(
+        name=_identifier(record["name"], f"{location}.name"),
+        terms=_decode_array(record["terms"], f"{location}.terms", _decode_index_term),
+        unique=_boolean(record["unique"], f"{location}.unique"),
+        predicate=_optional_expression(record["predicate"], f"{location}.predicate"),
+        method=_optional_string(record["method"], f"{location}.method"),
+    )
+
+
+def _decode_index_term(value: JsonValue, location: str) -> IndexTerm:
+    record = _record(value, {"column", "descending", "expression"}, location)
+    return IndexTerm(
+        column=_optional_identifier(record["column"], f"{location}.column"),
+        expression=_optional_expression(record["expression"], f"{location}.expression"),
+        descending=_boolean(record["descending"], f"{location}.descending"),
+    )
+
+
+def _decode_check(value: JsonValue, location: str) -> CheckConstraint:
+    record = _record(value, {"expression", "name"}, location)
+    return CheckConstraint(
+        expression=SqlExpression(
+            _string(record["expression"], f"{location}.expression")
+        ),
+        name=_optional_identifier(record["name"], f"{location}.name"),
+    )
+
+
+def _decode_reference(value: JsonValue, location: str) -> ObjectReference:
+    record = _record(value, {"catalog", "name", "schema"}, location)
+    return ObjectReference(
+        name=_identifier(record["name"], f"{location}.name"),
+        schema=_optional_identifier(record["schema"], f"{location}.schema"),
+        catalog=_optional_identifier(record["catalog"], f"{location}.catalog"),
+    )
+
+
+def _decode_metadata(value: JsonValue, location: str) -> MetadataEntry:
+    record = _record(value, {"key", "value"}, location)
+    return MetadataEntry(
+        key=_string(record["key"], f"{location}.key"),
+        value=_string(record["value"], f"{location}.value"),
+    )
+
+
+def _decode_identifiers(value: JsonValue, location: str) -> tuple[Identifier, ...]:
+    return tuple(_identifier(item, location) for item in _array(value, location))
+
+
+def _decode_array(
+    value: JsonValue,
+    location: str,
+    decoder: Callable[[JsonValue, str], DecodedValue],
+) -> tuple[DecodedValue, ...]:
+    return tuple(
+        decoder(item, f"{location}[{index}]")
+        for index, item in enumerate(_array(value, location))
+    )
+
+
+def _record(value: JsonValue, fields: set[str], location: str) -> JsonObject:
+    record = _object(value, location)
+    _require_fields(record, fields, location)
+    return record
+
+
+def _object(value: object, location: str) -> JsonObject:
+    if not isinstance(value, dict):
+        message = f"{location} must be an object"
+        raise SchemaSerializationError(message)
+    return cast(JsonObject, value)
+
+
+def _array(value: JsonValue, location: str) -> list[JsonValue]:
+    if not isinstance(value, list):
+        message = f"{location} must be an array"
+        raise SchemaSerializationError(message)
+    return value
+
+
+def _require_fields(value: JsonObject, fields: set[str], location: str) -> None:
+    actual = set(value)
+    if actual != fields:
+        message = f"{location} fields do not match the schema format"
+        raise SchemaSerializationError(message)
+
+
+def _string(value: JsonValue, location: str) -> str:
+    if not isinstance(value, str):
+        message = f"{location} must be a string"
+        raise SchemaSerializationError(message)
+    return value
+
+
+def _optional_string(value: JsonValue, location: str) -> str | None:
+    return None if value is None else _string(value, location)
+
+
+def _integer(value: JsonValue, location: str) -> int:
+    if type(value) is not int:
+        message = f"{location} must be an integer"
+        raise SchemaSerializationError(message)
+    return value
+
+
+def _optional_integer(value: JsonValue, location: str) -> int | None:
+    return None if value is None else _integer(value, location)
+
+
+def _boolean(value: JsonValue, location: str) -> bool:
+    if type(value) is not bool:
+        message = f"{location} must be a boolean"
+        raise SchemaSerializationError(message)
+    return value
+
+
+def _identifier(value: JsonValue, location: str) -> Identifier:
+    return Identifier(_string(value, location))
+
+
+def _optional_identifier(value: JsonValue, location: str) -> Identifier | None:
+    return None if value is None else _identifier(value, location)
+
+
+def _optional_expression(value: JsonValue, location: str) -> SqlExpression | None:
+    return None if value is None else SqlExpression(_string(value, location))
+
+
+def _enum(
+    enum_type: type[EnumValue],
+    value: JsonValue,
+    location: str,
+) -> EnumValue:
+    text = _string(value, location)
+    try:
+        return enum_type(text)
+    except ValueError as error:
+        message = f"{location} contains an unsupported value"
+        raise SchemaSerializationError(message) from error