instructure-pysqlsync 0.8.5.dev0__py3-none-any.whl

pysqlsync/formation/sql_to_py.py

@@ -0,0 +1,194 @@
+import dataclasses
+import datetime
+import decimal
+import keyword
+import sys
+import types
+import typing
+from dataclasses import dataclass
+from io import StringIO
+from typing import Annotated, Any, Optional, Union
+from uuid import UUID
+
+from strong_typing.auxiliary import Length, MaxLength, Precision, TimePrecision, float32, float64, int16, int32, int64
+from strong_typing.core import JsonType
+from strong_typing.inspection import DataclassInstance, TypeLike
+
+from ..model.data_types import (
+    SqlArrayType,
+    SqlBooleanType,
+    SqlDataType,
+    SqlDateType,
+    SqlDecimalType,
+    SqlDoubleType,
+    SqlFixedCharacterType,
+    SqlFloatType,
+    SqlIntegerType,
+    SqlJsonType,
+    SqlRealType,
+    SqlTimestampType,
+    SqlTimeType,
+    SqlUserDefinedType,
+    SqlUuidType,
+    SqlVariableCharacterType,
+)
+from ..model.id_types import SupportsQualifiedId
+from ..model.key_types import PrimaryKey
+from .object_types import Column, DiscriminatedConstraint, ForeignConstraint, ReferenceConstraint, Table
+
+
+def sql_type_to_python(sql_type: SqlDataType) -> TypeLike:
+    if isinstance(sql_type, SqlBooleanType):
+        return bool
+    elif isinstance(sql_type, SqlIntegerType):
+        if sql_type.width == 2:
+            return int16
+        elif sql_type.width == 4:
+            return int32
+        elif sql_type.width == 8:
+            return int64
+        return int
+    elif isinstance(sql_type, SqlRealType):
+        return float32
+    elif isinstance(sql_type, SqlDoubleType):
+        return float64
+    elif isinstance(sql_type, SqlFloatType):
+        if sql_type.precision is not None:
+            return Annotated[float, Precision(sql_type.precision)]
+        return float
+    elif isinstance(sql_type, SqlDecimalType):
+        return decimal.Decimal
+    elif isinstance(sql_type, SqlTimestampType):
+        if sql_type.precision is not None:
+            return Annotated[datetime.datetime, TimePrecision(sql_type.precision)]
+        return datetime.datetime
+    elif isinstance(sql_type, SqlDateType):
+        return datetime.date
+    elif isinstance(sql_type, SqlTimeType):
+        if sql_type.precision is not None:
+            return Annotated[datetime.time, TimePrecision(sql_type.precision)]
+        return datetime.time
+    elif isinstance(sql_type, SqlFixedCharacterType):
+        if sql_type.limit is not None:
+            return Annotated[str, Length(sql_type.limit)]
+        return str
+    elif isinstance(sql_type, SqlVariableCharacterType):
+        if sql_type.limit is not None:
+            return Annotated[str, MaxLength(sql_type.limit)]
+        return str
+    elif isinstance(sql_type, SqlUuidType):
+        return UUID
+    elif isinstance(sql_type, SqlJsonType):
+        return JsonType
+    elif isinstance(sql_type, SqlUserDefinedType):
+        return sql_type.ref.compact_id
+    elif isinstance(sql_type, SqlArrayType):
+        item_type = (sql_type_to_python(sql_type.element_type),)
+        return list[item_type]  # type: ignore
+
+    raise TypeError(f"unrecognized SQL type: {sql_type}")
+
+
+def safe_id(id: str) -> str:
+    "Apply PEP 8: single trailing underscore to avoid conflicts with Python keyword"
+
+    return f"{id}_" if keyword.iskeyword(id) else id
+
+
+@dataclass
+class SqlConverterOptions:
+    namespaces: dict[Optional[str], types.ModuleType]
+
+
+class SqlConverter:
+    options: SqlConverterOptions
+
+    def __init__(self, options: SqlConverterOptions) -> None:
+        self.options = options
+
+    def qual_to_module(self, id: SupportsQualifiedId) -> str:
+        return f"{self.options.namespaces[id.scope_id].__name__}.{safe_id(id.local_id)}"
+
+    def column_to_field(self, table: Table, column: Column) -> tuple[str, type, dataclasses.Field[Any]]:
+        """
+        Generates a dataclass field corresponding to a table column.
+
+        :param column: The database column from which to produce a dataclass field.
+        """
+
+        field_name = safe_id(column.name.local_id)
+
+        default: Any = dataclasses.MISSING
+        if column.default is not None:
+            default = column.default
+
+        field_type = sql_type_to_python(column.data_type)
+        if (column.name,) == table.primary_key:
+            field_type = PrimaryKey[(field_type,)]  # type: ignore
+        elif column.nullable:
+            field_type = Optional[field_type]
+
+        for c in table.constraints.values():
+            if not isinstance(c, ReferenceConstraint):
+                continue
+
+            if column.name not in c.foreign_columns:
+                continue
+
+            if isinstance(c, ForeignConstraint):
+                field_type = self.qual_to_module(c.reference.table)
+            elif isinstance(c, DiscriminatedConstraint):
+                union_types = tuple(self.qual_to_module(r.table) for r in c.references)
+                field_type = Union[union_types]
+
+        # use cast to ensure compatibility with signature of `make_dataclass`
+        data_type = typing.cast(type, field_type)
+
+        return (field_name, data_type, dataclasses.field(default=default))
+
+    def table_to_dataclass(self, table: Table) -> type[DataclassInstance]:
+        """
+        Generates a dataclass type corresponding to a table schema.
+
+        :param table: The database table from which to produce a dataclass.
+        """
+
+        fields = [self.column_to_field(table, column) for column in table.columns.values()]
+        class_name = safe_id(table.name.local_id)
+
+        # default arguments must follow non-default arguments
+        fields.sort(key=lambda f: f[2].default is not dataclasses.MISSING)
+
+        # look up target module
+        module = self.options.namespaces[table.name.scope_id]
+
+        # produce class definition with docstring
+        if sys.version_info >= (3, 12):
+            typ = dataclasses.make_dataclass(class_name, fields, module=module.__name__)
+        else:
+            typ = dataclasses.make_dataclass(class_name, fields, namespace={"__module__": module.__name__})
+        with StringIO() as out:
+            for field in dataclasses.fields(typ):
+                description = field.metadata.get("description")
+                if description is not None:
+                    print(f":param {field.name}: {description}", file=out)
+            paramstring = out.getvalue()
+        with StringIO() as out:
+            if table.description:
+                out.write(table.description)
+            if table.description and paramstring:
+                out.write("\n\n")
+            if paramstring:
+                out.write(paramstring)
+            docstring = out.getvalue()
+        typ.__doc__ = docstring
+
+        # assign the newly created type to the target module
+        setattr(sys.modules[module.__name__], class_name, typ)
+
+        return typ
+
+
+def table_to_dataclass(table: Table, options: SqlConverterOptions) -> type[DataclassInstance]:
+    converter = SqlConverter(options)
+    return converter.table_to_dataclass(table)

pysqlsync/model/data_types.py

@@ -0,0 +1,397 @@
+import datetime
+import decimal
+from dataclasses import dataclass
+from functools import reduce
+from typing import Any, Optional
+
+from strong_typing.auxiliary import IntegerRange, MaxLength, Precision, Signed, Storage, TimePrecision
+from strong_typing.inspection import dataclass_fields, is_dataclass_instance
+
+from .id_types import LocalId, SupportsQualifiedId
+
+
+def quote(s: str) -> str:
+    "Quotes a string to be embedded in an SQL statement."
+
+    return "'" + s.replace("'", "''") + "'"
+
+
+def constant(v: Any) -> str:
+    "Outputs a constant value."
+
+    if isinstance(v, str):
+        return quote(v)
+    elif isinstance(v, bool):
+        return "TRUE" if v else "FALSE"
+    elif isinstance(v, (int, float)):
+        return str(v)
+    elif isinstance(v, decimal.Decimal):
+        return str(v)
+    elif isinstance(v, datetime.datetime):
+        if v.tzinfo is not None:
+            timestamp = v.astimezone(tz=datetime.timezone.utc).replace(tzinfo=None)
+        else:
+            timestamp = v
+        return quote(timestamp.isoformat(sep=" "))
+    elif isinstance(v, tuple):
+        values = ", ".join(constant(value) for value in v)  # pyright: ignore[reportUnknownVariableType]
+        return f"({values})"
+    elif is_dataclass_instance(v):
+        values = ", ".join(constant(getattr(v, field.name)) for field in dataclass_fields(type(v)))
+        return f"({values})"
+    else:
+        raise NotImplementedError(f"unknown constant representation for value (of type): {v} ({type(v)})")
+
+
+def escape_like(value: str, escape_char: str) -> str:
+    "Escapes a string to be embedded in an SQL LIKE '...' ESCAPE '...' expression."
+
+    return (
+        value.replace("'", "''")
+        .replace(escape_char, f"{escape_char}{escape_char}")
+        .replace("_", f"{escape_char}_")
+        .replace("%", f"{escape_char}%")
+    )
+
+
+@dataclass
+class SqlDataType:
+    def parse_meta(self, meta: Any) -> None:
+        raise TypeError(f"unrecognized Python type annotation for {type(self).__name__}: {meta}")
+
+    def value_to_sql_literal(self, value: Any) -> str:
+        return constant(value)
+
+
+@dataclass
+class SqlArrayType(SqlDataType):
+    element_type: SqlDataType
+
+    def __str__(self) -> str:
+        return f"{self.element_type} ARRAY"
+
+
+@dataclass
+class SqlUuidType(SqlDataType):
+    def __str__(self) -> str:
+        return "uuid"
+
+
+@dataclass
+class SqlBooleanType(SqlDataType):
+    def __str__(self) -> str:
+        return "boolean"
+
+
+@dataclass
+class SqlIntegerType(SqlDataType):
+    width: int
+    signed: bool = True
+    minimum: Optional[int] = None
+    maximum: Optional[int] = None
+
+    def __str__(self) -> str:
+        if self.width == 1:
+            return "tinyint"
+        elif self.width == 2:
+            return "smallint"
+        elif self.width == 4:
+            return "integer"
+        elif self.width == 8:
+            return "bigint"
+
+        raise TypeError(f"invalid integer width: {self.width}")
+
+    def parse_meta(self, meta: Any) -> None:
+        if isinstance(meta, IntegerRange):
+            self.minimum = meta.minimum
+            self.maximum = meta.maximum
+        elif isinstance(meta, Signed):
+            self.signed = meta.is_signed
+        elif isinstance(meta, Storage):
+            self.width = meta.bytes
+        else:
+            super().parse_meta(meta)
+
+
+@dataclass
+class SqlFloatType(SqlDataType):
+    """
+    Floating-point numeric type.
+
+    :param precision: Numeric precision in base 2.
+    """
+
+    precision: Optional[int] = None
+
+    def __str__(self) -> str:
+        if self.precision is not None:
+            precision = self.precision
+        else:
+            precision = 53
+
+        return f"float({precision})"
+
+    def parse_meta(self, meta: Any) -> None:
+        if isinstance(meta, Precision):
+            self.precision = meta.significant_digits
+        else:
+            super().parse_meta(meta)
+
+
+@dataclass
+class SqlRealType(SqlDataType):
+    def __str__(self) -> str:
+        return "real"
+
+
+@dataclass
+class SqlDoubleType(SqlDataType):
+    def __str__(self) -> str:
+        return "double precision"
+
+
+@dataclass
+class SqlDecimalType(SqlDataType):
+    """
+    Fixed-point numeric type.
+
+    :param precision: Numeric precision in base 10.
+    :param scale: Scale in base 10.
+    """
+
+    precision: Optional[int] = None
+    scale: Optional[int] = None
+
+    def __str__(self) -> str:
+        if self.precision is not None and self.scale is not None:
+            return f"decimal({self.precision}, {self.scale})"
+        elif self.precision is not None:
+            return f"decimal({self.precision})"
+        else:
+            return "decimal"
+
+    def parse_meta(self, meta: Any) -> None:
+        if isinstance(meta, Precision):
+            self.precision = meta.significant_digits
+            self.scale = meta.decimal_digits
+        else:
+            super().parse_meta(meta)
+
+
+@dataclass
+class SqlFixedBinaryType(SqlDataType):
+    storage: Optional[int] = None
+
+    def __str__(self) -> str:
+        storage = f"({self.storage})" if self.storage is not None else ""
+        return f"binary{storage}"
+
+
+@dataclass
+class SqlVariableBinaryType(SqlDataType):
+    storage: Optional[int] = None
+
+    def __str__(self) -> str:
+        if self.storage is not None:
+            return f"varbinary({self.storage})"
+        else:
+            return "blob"
+
+    def parse_meta(self, meta: Any) -> None:
+        if isinstance(meta, Storage):
+            self.storage = meta.bytes
+        else:
+            super().parse_meta(meta)
+
+
+@dataclass
+class SqlFixedCharacterType(SqlDataType):
+    limit: Optional[int] = None
+
+    def __str__(self) -> str:
+        limit = f"({self.limit})" if self.limit is not None else ""
+        return f"char{limit}"
+
+
+@dataclass
+class SqlVariableCharacterType(SqlDataType):
+    limit: Optional[int] = None
+
+    def __str__(self) -> str:
+        if self.limit is not None:
+            return f"varchar({self.limit})"
+        else:
+            return "text"
+
+    def parse_meta(self, meta: Any) -> None:
+        if isinstance(meta, MaxLength):
+            self.limit = meta.value
+        else:
+            super().parse_meta(meta)
+
+
+@dataclass
+class SqlTimestampType(SqlDataType):
+    precision: Optional[int] = None
+    with_time_zone: bool = False
+
+    def __str__(self) -> str:
+        if self.precision is not None:
+            precision = f"({self.precision})"
+        else:
+            precision = ""
+        if self.with_time_zone:
+            time_zone = " with time zone"
+        else:
+            time_zone = ""  # PostgreSQL: " without time zone"
+        return f"timestamp{precision}{time_zone}"
+
+    def parse_meta(self, meta: Any) -> None:
+        if isinstance(meta, TimePrecision):
+            self.precision = meta.decimal_digits
+        else:
+            super().parse_meta(meta)
+
+
+@dataclass
+class SqlDateType(SqlDataType):
+    def __str__(self) -> str:
+        return "date"
+
+
+@dataclass
+class SqlTimeType(SqlDataType):
+    precision: Optional[int] = None
+    with_time_zone: bool = False
+
+    def __str__(self) -> str:
+        if self.precision is not None:
+            precision = f"({self.precision})"
+        else:
+            precision = ""
+        if self.with_time_zone:
+            time_zone = " with time zone"
+        else:
+            time_zone = ""  # PostgreSQL: " without time zone"
+        return f"time{precision}{time_zone}"
+
+    def parse_meta(self, meta: Any) -> None:
+        if isinstance(meta, TimePrecision):
+            self.precision = meta.decimal_digits
+        else:
+            super().parse_meta(meta)
+
+
+@dataclass
+class SqlIntervalType(SqlDataType):
+    def __str__(self) -> str:
+        return "interval"
+
+
+@dataclass
+class SqlJsonType(SqlDataType):
+    def __str__(self) -> str:
+        return "json"
+
+
+@dataclass
+class SqlEnumType(SqlDataType):
+    values: list[str]
+
+    def __str__(self) -> str:
+        values = ", ".join(quote(val) for val in self.values)
+        return f"ENUM ({values})"
+
+
+@dataclass
+class SqlStructMember:
+    name: LocalId
+    data_type: SqlDataType
+    nullable: bool
+
+    def __str__(self) -> str:
+        nullable = " NOT NULL" if not self.nullable else ""
+        return f"{self.name} {self.data_type}{nullable}"
+
+
+@dataclass
+class SqlStructType(SqlDataType):
+    fields: list[SqlStructMember]
+
+    def __str__(self) -> str:
+        field_list = ", ".join(str(f) for f in self.fields)
+        return f"STRUCT <{field_list}>"
+
+
+@dataclass
+class SqlUserDefinedType(SqlDataType):
+    ref: SupportsQualifiedId
+
+    def __str__(self) -> str:
+        return self.ref.quoted_id
+
+
+class CompatibilityError(TypeError):
+    "Raised when a list of types cannot be reduced into a single common type."
+
+
+def compatible_type(data_types: list[SqlDataType]) -> SqlDataType:
+    "Returns a single common type that all elements in a list of types can be converted into without data loss."
+
+    return reduce(_compatible_type, data_types)
+
+
+def max_or_none(left: Optional[int], right: Optional[int]) -> Optional[int]:
+    if left is None or right is None:
+        return None
+    else:
+        return max(left, right)
+
+
+def _compatible_type(left: SqlDataType, right: SqlDataType) -> SqlDataType:
+    """
+    Returns a common type that can represent instances of both source types without data loss.
+
+    The implementation makes use of `type(...)` to ensure the most specific class is instantiated when
+    database-specific data types are created with inheritance.
+    """
+
+    if left == right:
+        return left
+
+    # integer types
+    if isinstance(left, SqlIntegerType) and isinstance(right, SqlIntegerType):
+        return type(left)(width=max(left.width, right.width))
+
+    # floating-point types
+    if isinstance(left, SqlRealType):
+        if isinstance(right, SqlRealType):
+            return type(left)()
+        elif isinstance(right, SqlDoubleType):
+            return type(right)()
+    elif isinstance(left, SqlDoubleType):
+        if isinstance(right, (SqlRealType, SqlDoubleType)):
+            return type(left)()
+
+    # character types
+    if isinstance(left, SqlFixedCharacterType):
+        if isinstance(right, SqlFixedCharacterType):
+            return type(left)(limit=max_or_none(left.limit, right.limit))
+        elif isinstance(right, SqlVariableCharacterType):
+            return type(right)(limit=max_or_none(left.limit, right.limit))
+    elif isinstance(left, SqlVariableCharacterType):
+        if isinstance(right, (SqlFixedCharacterType, SqlVariableCharacterType)):
+            return type(left)(limit=max_or_none(left.limit, right.limit))
+
+    # binary types
+    if isinstance(left, SqlFixedBinaryType):
+        if isinstance(right, SqlFixedBinaryType):
+            return type(left)(storage=max_or_none(left.storage, right.storage))
+        elif isinstance(right, SqlVariableBinaryType):
+            return type(right)(storage=max_or_none(left.storage, right.storage))
+    elif isinstance(left, SqlVariableBinaryType):
+        if isinstance(right, (SqlFixedBinaryType, SqlVariableBinaryType)):
+            return type(left)(storage=max_or_none(left.storage, right.storage))
+
+    raise CompatibilityError()

pysqlsync/model/entity_types.py

@@ -0,0 +1,68 @@
+import dataclasses
+import sys
+from typing import Any, Optional
+
+from strong_typing.inspection import DataclassField, DataclassInstance, dataclass_fields
+
+from .key_types import PrimaryKey
+
+
+def key_value_fields(cls: type[DataclassInstance], key: str) -> tuple[DataclassField, list[DataclassField]]:
+    """
+    Separates the key and the value fields in a data-class definition.
+
+    :param cls: The data-class type to transform.
+    :param key: The field to be come the primary key.
+    """
+
+    source_fields = dataclass_fields(cls)
+    key_field: Optional[DataclassField] = None
+    value_fields: list[DataclassField] = []
+    for source_field in source_fields:
+        if source_field.name == key:
+            key_field = source_field
+        else:
+            value_fields.append(source_field)
+
+    if key_field is None:
+        raise ValueError(f"key field not found: {key}")
+
+    return key_field, value_fields
+
+
+def make_entity(cls: type[DataclassInstance], key: str) -> type[DataclassInstance]:
+    """
+    Transforms a regular data-class type into an entity type.
+
+    :param cls: The data-class type to transform.
+    :param key: The field to become the primary key.
+    """
+
+    key_field, value_fields = key_value_fields(cls, key)
+    key_type = key_field.type
+
+    primary_key_type = PrimaryKey[key_type]  # type: ignore
+    target_fields: list[tuple[str, Any, dataclasses.Field[Any]]] = [
+        (key_field.name, primary_key_type, dataclasses.field(default=key_field.default))
+    ]
+    for value_field in value_fields:
+        target_fields.append(
+            (
+                value_field.name,
+                value_field.type,
+                dataclasses.field(default=value_field.default),
+            )
+        )
+
+    class_name = cls.__name__
+    class_module = cls.__module__
+    class_doc = cls.__doc__
+
+    if sys.version_info >= (3, 12):
+        class_type = dataclasses.make_dataclass(class_name, target_fields, module=class_module)
+    else:
+        class_type = dataclasses.make_dataclass(class_name, target_fields, namespace={"__module__": class_module})
+
+    class_type.__doc__ = class_doc
+    setattr(sys.modules[class_module], class_name, class_type)
+    return class_type