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

pysqlsync/model/id_types.py

@@ -0,0 +1,193 @@
+import abc
+from dataclasses import dataclass
+from typing import Optional, Protocol, runtime_checkable
+
+ID_QUOTE_CHAR = '"'
+
+
+def quote_id(name: str) -> str:
+    return name.replace(ID_QUOTE_CHAR, 2 * ID_QUOTE_CHAR)
+
+
+@runtime_checkable
+class SupportsQuotedId(Protocol):
+    __slots__ = ()
+
+    @property
+    @abc.abstractmethod
+    def quoted_id(self) -> str:
+        "A fully-quoted identifier."
+        ...
+
+
+@runtime_checkable
+class SupportsLocalId(Protocol):
+    __slots__ = ()
+
+    @property
+    @abc.abstractmethod
+    def local_id(self) -> str:
+        "Unquoted component of an identifier to be used in a local context, e.g. columns of a table."
+        ...
+
+    @property
+    @abc.abstractmethod
+    def quoted_id(self) -> str:
+        "A fully-quoted identifier."
+        ...
+
+
+@runtime_checkable
+class SupportsQualifiedId(Protocol):
+    __slots__ = ()
+
+    @property
+    @abc.abstractmethod
+    def scope_id(self) -> Optional[str]:
+        "Unquoted scope identifier."
+        ...
+
+    @property
+    @abc.abstractmethod
+    def local_id(self) -> str:
+        "Unquoted component of an identifier to be used in a local context, e.g. columns of a table."
+        ...
+
+    @property
+    @abc.abstractmethod
+    def compact_id(self) -> str:
+        "An unquoted composite identifier."
+        ...
+
+    @property
+    @abc.abstractmethod
+    def quoted_id(self) -> str:
+        "A fully-quoted identifier."
+        ...
+
+    def rename(self, id: str) -> "SupportsQualifiedId": ...
+
+
+@runtime_checkable
+class SupportsName(Protocol):
+    __slots__ = ()
+
+    @property
+    @abc.abstractmethod
+    def name(self) -> SupportsLocalId: ...
+
+
+@dataclass(frozen=True)
+class LocalId:
+    id: str
+
+    @property
+    def local_id(self) -> str:
+        "Unquoted identifier."
+
+        return self.id
+
+    @property
+    def quoted_id(self) -> str:
+        return ID_QUOTE_CHAR + quote_id(self.id) + ID_QUOTE_CHAR
+
+    def __str__(self) -> str:
+        "Quotes an identifier to be embedded in a SQL statement."
+
+        return self.quoted_id
+
+
+@dataclass(frozen=True)
+class PrefixedId:
+    namespace: Optional[str]
+    id: str
+
+    @property
+    def scope_id(self) -> Optional[str]:
+        return None
+
+    @property
+    def local_id(self) -> str:
+        return f"{self.namespace}__{self.id}" if self.namespace is not None else self.id
+
+    @property
+    def compact_id(self) -> str:
+        return self.local_id
+
+    @property
+    def quoted_id(self) -> str:
+        if self.namespace is not None:
+            return ID_QUOTE_CHAR + quote_id(self.namespace) + "__" + quote_id(self.id) + ID_QUOTE_CHAR
+        else:
+            return ID_QUOTE_CHAR + quote_id(self.id) + ID_QUOTE_CHAR
+
+    def rename(self, id: str) -> "SupportsQualifiedId":
+        return PrefixedId(self.namespace, id)
+
+    def __str__(self) -> str:
+        "Quotes a qualified identifier to be embedded in a SQL statement."
+
+        return self.quoted_id
+
+
+@dataclass(frozen=True)
+class QualifiedId:
+    namespace: Optional[str]
+    id: str
+
+    @property
+    def scope_id(self) -> Optional[str]:
+        return self.namespace
+
+    @property
+    def local_id(self) -> str:
+        return self.id
+
+    @property
+    def compact_id(self) -> str:
+        if self.namespace is not None:
+            return f"{self.namespace}.{self.id}"
+        else:
+            return self.id
+
+    @property
+    def quoted_id(self) -> str:
+        if self.namespace is not None:
+            return ID_QUOTE_CHAR + quote_id(self.namespace) + ID_QUOTE_CHAR + "." + ID_QUOTE_CHAR + quote_id(self.id) + ID_QUOTE_CHAR
+        else:
+            return ID_QUOTE_CHAR + quote_id(self.id) + ID_QUOTE_CHAR
+
+    def rename(self, id: str) -> "SupportsQualifiedId":
+        return QualifiedId(self.namespace, id)
+
+    def __str__(self) -> str:
+        "Quotes a qualified identifier to be embedded in a SQL statement."
+
+        return self.quoted_id
+
+
+@dataclass(frozen=True)
+class GlobalId:
+    id: str
+
+    @property
+    def scope_id(self) -> Optional[str]:
+        return None
+
+    @property
+    def local_id(self) -> str:
+        return self.id
+
+    @property
+    def compact_id(self) -> str:
+        return self.id
+
+    @property
+    def quoted_id(self) -> str:
+        return self.id
+
+    def rename(self, id: str) -> "SupportsQualifiedId":
+        return GlobalId(id)
+
+    def __str__(self) -> str:
+        return self.id

pysqlsync/model/key_types.py

@@ -0,0 +1,38 @@
+from typing import Annotated, TypeVar, Union
+
+T = TypeVar("T")
+
+
+class PrimaryKeyTag:
+    "Marks a field as the primary key of a table."
+
+    def __repr__(self) -> str:
+        return "PrimaryKey"
+
+
+class IdentityTag:
+    "Marks a field as an identity column in a table."
+
+    def __repr__(self) -> str:
+        return "Identity"
+
+
+class UniqueTag:
+    "Marks a field as a column with a unique constraint."
+
+    def __repr__(self) -> str:
+        return "Unique"
+
+
+class DefaultTag:
+    "The placeholder value DEFAULT."
+
+    def __repr__(self) -> str:
+        return "DEFAULT"
+
+
+DEFAULT = DefaultTag()
+
+PrimaryKey = Annotated[T, PrimaryKeyTag()]
+Identity = Annotated[Union[T, DefaultTag], IdentityTag()]
+Unique = Annotated[T, UniqueTag()]

pysqlsync/model/properties.py

@@ -0,0 +1,234 @@
+import dataclasses
+import datetime
+import decimal
+import ipaddress
+import typing
+import uuid
+from dataclasses import dataclass
+from typing import Annotated, Any, Union
+
+from strong_typing.inspection import (
+    DataclassInstance,
+    TypeLike,
+    dataclass_fields,
+    get_annotation,
+    is_dataclass_type,
+    is_type_enum,
+    is_type_literal,
+    is_type_optional,
+    is_type_union,
+    unwrap_annotated_type,
+    unwrap_literal_types,
+    unwrap_optional_type,
+    unwrap_union_types,
+)
+
+from .key_types import DefaultTag, IdentityTag, PrimaryKeyTag, UniqueTag
+
+
+def is_primary_key_type(field_type: TypeLike) -> bool:
+    "Checks if the field type is marked as the primary key of a table."
+
+    return get_annotation(field_type, PrimaryKeyTag) is not None
+
+
+def is_identity_type(field_type: TypeLike) -> bool:
+    "Checks if the field type is marked as an identity column in a table."
+
+    return get_annotation(field_type, IdentityTag) is not None
+
+
+def is_unique_type(field_type: TypeLike) -> bool:
+    "Checks if the field type is marked as a unique column in a table."
+
+    return get_annotation(field_type, UniqueTag) is not None
+
+
+def get_primary_key_name(class_type: type[DataclassInstance]) -> str:
+    "Fetches the primary key of the table."
+
+    for field in dataclass_fields(class_type):
+        if is_primary_key_type(field.type):
+            return field.name
+
+    raise TypeError(f"table type has no primary key: {class_type.__name__}")
+
+
+def get_primary_key_name_type(class_type: type[DataclassInstance]) -> tuple[str, type]:
+    "Returns the primary key of the table and its plain representation type."
+
+    for field in dataclass_fields(class_type):
+        props = get_field_properties(field.type)
+        if props.is_primary:
+            return field.name, props.tsv_type
+
+    raise TypeError(f"table type has no primary key: {class_type.__name__}")
+
+
+def is_constraint(item: Any) -> bool:
+    return isinstance(item, (PrimaryKeyTag, IdentityTag, UniqueTag))
+
+
+def tsv_type(plain_type: TypeLike) -> type:
+    "Python type that represents the TSV storage type for this data."
+
+    plain_type = unwrap_annotated_type(plain_type)
+
+    if is_type_enum(plain_type):
+        return str
+    elif is_type_literal(plain_type):
+        literal_types = set(tsv_type(t) for t in unwrap_literal_types(plain_type))
+        if len(literal_types) != 1:
+            raise TypeError(f"inconsistent literal value types: {literal_types}")
+        return literal_types.pop()
+    elif is_type_union(plain_type):
+        union_types = set(tsv_type(t) for t in unwrap_union_types(plain_type))
+        if len(union_types) != 1:
+            if len(union_types) == 2 and ipaddress.IPv4Address in union_types and ipaddress.IPv6Address in union_types:
+                return typing.cast(type, plain_type)
+            raise TypeError(f"inconsistent union types: {union_types}")
+        return union_types.pop()
+    elif is_dataclass_type(plain_type):
+        return dict
+    elif plain_type is bool:
+        return bool
+    elif plain_type is bytes:
+        return bytes
+    elif plain_type is int:
+        return int
+    elif plain_type is float:
+        return float
+    elif plain_type is str:
+        return str
+    elif plain_type is uuid.UUID:
+        return uuid.UUID
+    elif plain_type is datetime.datetime:
+        return datetime.datetime
+    elif plain_type is datetime.date:
+        return datetime.date
+    elif plain_type is datetime.time:
+        return datetime.time
+    elif plain_type is decimal.Decimal:
+        return decimal.Decimal
+    elif plain_type is ipaddress.IPv4Address:
+        return ipaddress.IPv4Address
+    elif plain_type is ipaddress.IPv6Address:
+        return ipaddress.IPv6Address
+
+    origin_type = typing.get_origin(plain_type)
+    if origin_type is list:  # JSON
+        return list
+    elif origin_type is set:  # JSON
+        return set
+    elif origin_type is dict:  # JSON
+        return dict
+
+    raise TypeError(f"unsupported TSV value type: {plain_type}")
+
+
+@dataclass
+class FieldProperties:
+    """
+    Captures type information associated with a field type.
+
+    :param plain_type: Unadorned type without any metadata.
+    :param nullable: True if the field is optional.
+    :param metadata: Any metadata that is not a constraint such as identity, primary key or unique.
+    :param is_primary: True if the field is a primary key.
+    :param is_identity: True if the field is generated as identity.
+    :param is_unique: True if values of this type must be unique.
+    """
+
+    plain_type: TypeLike
+    nullable: bool
+    metadata: tuple[Any, ...]
+    is_primary: bool
+    is_identity: bool
+    is_unique: bool
+
+    @property
+    def field_type(self) -> TypeLike:
+        "Type without constraint annotations such as identity, primary key, or unique."
+
+        if self.metadata:
+            # type becomes Annotated[T, ...]
+            return Annotated[(self.plain_type, *self.metadata)]
+        else:
+            # type becomes a regular type
+            return self.plain_type
+
+    @property
+    def tsv_type(self) -> type:
+        "Python type that represents the TSV storage type for this data."
+
+        return tsv_type(self.plain_type)
+
+
+def _get_field_metadata(field_type: TypeLike) -> list[Any]:
+    # field has a type of Annotated[T, ...]
+    return list(getattr(field_type, "__metadata__", ()))
+
+
+def get_field_properties(field_type: TypeLike) -> FieldProperties:
+    "Extracts column properties such as primary key, identity or unique constraints."
+
+    metadata = _get_field_metadata(field_type)
+    plain_type = unwrap_annotated_type(field_type)
+
+    # check if field has DEFAULT as a union type member
+    if is_type_union(plain_type):
+        union_types = list(unwrap_union_types(plain_type))
+        if DefaultTag in union_types:
+            union_types.remove(DefaultTag)
+            plain_type = Union[tuple(union_types)]  # may cease to become a union type
+
+    # check if field is nullable
+    if is_type_optional(plain_type):
+        nullable = True
+        plain_type = unwrap_optional_type(plain_type)
+    else:
+        nullable = False
+
+    metadata.extend(_get_field_metadata(plain_type))
+    plain_type = unwrap_annotated_type(plain_type)
+
+    if not metadata:
+        # field has a type without annotations or constraints
+        return FieldProperties(
+            plain_type=plain_type,
+            nullable=nullable,
+            metadata=(),
+            is_primary=False,
+            is_identity=False,
+            is_unique=False,
+        )
+
+    # check for constraints
+    is_primary = any(isinstance(m, PrimaryKeyTag) for m in metadata)
+    is_identity = any(isinstance(m, IdentityTag) for m in metadata)
+    is_unique = any(isinstance(m, UniqueTag) for m in metadata)
+
+    # filter annotations that represent constraints
+    metadata = [item for item in metadata if not is_constraint(item)]
+
+    return FieldProperties(
+        plain_type=plain_type,
+        nullable=nullable,
+        metadata=tuple(metadata),
+        is_primary=is_primary,
+        is_identity=is_identity,
+        is_unique=is_unique,
+    )
+
+
+@dataclass
+class ClassProperties:
+    fields: tuple[FieldProperties, ...]
+
+    @property
+    def tsv_types(self) -> tuple[type, ...]:
+        return tuple(prop.tsv_type for prop in self.fields)
+
+
+def get_class_properties(class_type: type[DataclassInstance]) -> ClassProperties:
+    return ClassProperties(tuple(get_field_properties(field.type) for field in dataclasses.fields(class_type)))

pysqlsync/python_types.py

@@ -0,0 +1,192 @@
+import dataclasses
+import enum
+import inspect
+import io
+import re
+import sys
+import textwrap
+import typing
+from types import ModuleType
+from typing import TextIO
+
+from strong_typing.docstring import has_docstring, parse_type
+from strong_typing.inspection import (
+    DataclassInstance,
+    get_module_classes,
+    is_dataclass_type,
+    is_type_enum,
+)
+from strong_typing.name import TypeFormatter
+
+
+def module_to_stream(module: ModuleType, target: TextIO) -> None:
+    "Generates Python code of all declared types in a module."
+
+    print("from __future__ import annotations", file=target)
+    print("import dataclasses", file=target)
+    print("import enum", file=target)
+    print("from datetime import datetime, date, time", file=target)
+    print("from decimal import Decimal", file=target)
+    print("from uuid import UUID", file=target)
+    print(
+        "from typing import Annotated, Dict, List, Literal, Optional, Union",
+        file=target,
+    )
+    print(
+        "from strong_typing.auxiliary import int16, int32, int64, float32, float64, MaxLength, Precision, TimePrecision",
+        file=target,
+    )
+    print(file=target)
+
+    for cls in get_module_classes(module):
+        if is_type_enum(cls):
+            enum_class_to_stream(cls, target)
+        elif is_dataclass_type(cls):
+            dataclass_to_stream(cls, target)
+        else:
+            raise NotImplementedError("classes in module must be of enumeration or data-class type")
+        print(file=target)
+
+
+def module_to_code(module: ModuleType) -> str:
+    "Generates Python code of all declared types in a module."
+
+    with io.StringIO() as out:
+        module_to_stream(module, out)
+        return out.getvalue()
+
+
+def dataclass_to_stream(typ: type[DataclassInstance], target: TextIO) -> None:
+    "Generates Python code corresponding to a dataclass type."
+
+    print("@dataclasses.dataclass", file=target)
+    print(f"class {typ.__name__}:", file=target)
+
+    # check if class has a doc-string other than the auto-generated string assigned by @dataclass
+    if has_docstring(typ):
+        if "\n" in typing.cast(str, typ.__doc__):
+            ds = parse_type(typ)
+            print('    """', file=target)
+
+            if ds.short_description:
+                _wrap_print(ds.short_description, file=target)
+                if ds.long_description:
+                    print(file=target)
+                    _wrap_print(ds.long_description, file=target)
+
+            if ds.short_description and (ds.params or ds.returns):
+                print(file=target)
+
+            for name, param in ds.params.items():
+                _wrap_print(f":param {name}: {param.description}", file=target)
+            if ds.returns:
+                _wrap_print(f":returns: {ds.returns.description}", file=target)
+
+            print('    """', file=target)
+        else:
+            print(f"    {repr(typ.__doc__)}", file=target)
+        print(file=target)
+
+    # class variables (e.g. "primary_key")
+    field_names = [field.name for field in dataclasses.fields(typ)]
+    variables = {
+        name: value
+        for name, value in inspect.getmembers(typ, lambda m: not inspect.isroutine(m))
+        if not re.match(r"^__.+__$", name) and name not in field_names
+    }
+    if variables:
+        for name, value in variables.items():
+            print(f"    {name} = {repr(value)}", file=target)
+        print(file=target)
+
+    # member variables
+    fmt = TypeFormatter(context=sys.modules[typ.__module__])
+    for field in dataclasses.fields(typ):
+        type_name = fmt.python_type_to_str(field.type)
+        metadata = dict(field.metadata)
+
+        field_initializer: dict[str, str] = {}
+        if field.default is not dataclasses.MISSING:
+            field_initializer["default"] = repr(field.default)
+        if field.default_factory is not dataclasses.MISSING:
+            field_initializer["default_factory"] = fmt.python_type_to_str(field.default_factory)
+        if metadata:
+            field_initializer["metadata"] = repr(metadata)
+
+        if not field_initializer:
+            initializer = ""
+        elif field.default is not dataclasses.MISSING and len(field_initializer) == 1:
+            initializer = f" = {repr(field.default)}"
+        else:
+            initializer_list = ", ".join(f"{key} = {value}" for key, value in field_initializer.items())
+            initializer = f" = field({initializer_list})"
+
+        print(f"    {field.name}: {type_name}{initializer}", file=target)
+
+
+def dataclasses_to_stream(types: list[type[DataclassInstance]], target: TextIO) -> None:
+    "Generates Python code corresponding to a set of dataclass types."
+
+    for typ in types:
+        dataclass_to_stream(typ, target)
+
+
+def dataclass_to_code(data_type: type[DataclassInstance]) -> str:
+    "Generates Python code corresponding to a dataclass type."
+
+    return dataclasses_to_code([data_type])
+
+
+def dataclasses_to_code(types: list[type[DataclassInstance]]) -> str:
+    "Generates Python code corresponding to a set of dataclass types."
+
+    f = io.StringIO()
+    dataclasses_to_stream(types, f)
+    return f.getvalue()
+
+
+def enum_class_to_stream(enum_class: type[enum.Enum], target: TextIO) -> None:
+    "Writes an enumeration class as a class definition."
+
+    print("@enum.unique", file=target)
+    print(f"class {enum_class.__name__}(enum.Enum):", file=target)
+    if enum_class.__doc__:
+        print(f"    {repr(enum_class.__doc__)}", file=target)
+        print(file=target)
+
+    for e in enum_class:
+        value = repr(e.value)
+        print(f"    {e.name} = {value}", file=target)
+
+    for e in enum_class:
+        if not e.__doc__ or e.__doc__ == enum_class.__doc__:
+            continue
+
+        print(
+            f"{enum_class.__name__}.{e.name}.__doc__ = {repr(e.__doc__)}",
+            file=target,
+        )
+
+
+def enum_class_to_code(enum_class: type[enum.Enum]) -> str:
+    "Returns an enumeration class as a class definition string."
+
+    with io.StringIO() as out:
+        enum_class_to_stream(enum_class, out)
+        return out.getvalue()
+
+
+def _wrap_print(text: str, file: TextIO) -> None:
+    if not text:
+        return
+
+    # wrap long lines
+    for line in textwrap.wrap(
+        text,
+        width=139,
+        initial_indent="    ",
+        subsequent_indent="    ",
+        break_long_words=False,
+        break_on_hyphens=False,
+    ):
+        print(line, file=file)