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

pysqlsync/resultset.py

@@ -0,0 +1,106 @@
+"""
+pysqlsync: Synchronize schema and large volumes of data.
+
+This module helps convert between data-class, dictionary and tuple representation of result-sets.
+
+:see: https://github.com/instructure-internal/pysqlsync
+"""
+
+import typing
+from collections.abc import Sequence
+from typing import Any, Iterable, TypeVar
+
+from strong_typing.inspection import DataclassInstance, is_dataclass_type
+
+D = TypeVar("D", bound=DataclassInstance)
+T = TypeVar("T")
+
+
+def resultset_unwrap_dict(signature: type[D], records: Iterable[dict[str, Any]]) -> list[D]:
+    """
+    Converts a result-set into a list of data-class instances.
+
+    :param signature: A data-class type.
+    :param records: The result-set whose rows to convert.
+    """
+
+    if not is_dataclass_type(signature):
+        raise TypeError(f"expected: data-class type as result-set signature; got: {signature}")
+
+    return [signature(**{name: value for name, value in record.items()}) for record in records]
+
+
+def resultset_unwrap_object(signature: type[D], records: Iterable[Any]) -> list[D]:
+    """
+    Converts a result-set into a list of data-class instances.
+
+    :param signature: A data-class type.
+    :param records: The result-set whose rows to convert.
+    """
+
+    if not is_dataclass_type(signature):
+        raise TypeError(f"expected: data-class type as result-set signature; got: {signature}")
+
+    names = [name for name in signature.__dataclass_fields__.keys()]  # pyright: ignore[reportUnknownMemberType]
+    return [signature(**{name: record.__getattribute__(name) for name in names}) for record in records]
+
+
+def resultset_unwrap_tuple(signature: type[T], records: Iterable[Sequence[Any]]) -> list[T]:
+    """
+    Converts a result-set into a list of tuples, or a list of simple types (as appropriate).
+
+    :param signature: A tuple type, or a simple type (e.g. `bool` or `str`).
+    :param records: The result-set whose rows to convert.
+    """
+
+    if signature in [bool, int, float, str]:
+        scalar_results: list[T] = []
+
+        # check result shape
+        it = iter(records)
+        try:
+            item = next(it)
+        except StopIteration:
+            return []
+        if len(item) != 1:
+            raise ValueError(f"invalid number of columns, expected: 1; got: {len(item)}")
+        scalar_results.append(item[0])
+        while True:
+            try:
+                item = next(it)
+            except StopIteration:
+                return scalar_results
+            scalar_results.append(item[0])
+
+    origin_type = typing.get_origin(signature)
+    if origin_type is tuple:
+        origin_args = typing.get_args(signature)
+        results: list[T] = []
+
+        # check result shape
+        it = iter(records)
+        try:
+            item = next(it)
+        except StopIteration:
+            return []
+        if len(item) != len(origin_args):
+            raise ValueError(f"invalid number of columns, expected: {len(origin_args)}; got: {len(item)}")
+
+        if isinstance(item, tuple):
+            results.append(item)  # type: ignore
+            while True:
+                try:
+                    item = next(it)
+                except StopIteration:
+                    return results
+                results.append(item)  # type: ignore
+        else:
+            results.append(tuple(item))  # type: ignore
+            while True:
+                try:
+                    item = next(it)
+                except StopIteration:
+                    return results
+                results.append(tuple(item))  # type: ignore
+
+    raise TypeError(f"expected: tuple or simple type as result-set signature; got: {signature}")

pysqlsync/util/dataclasses.py

@@ -0,0 +1,80 @@
+import dataclasses
+import sys
+import types
+from typing import Optional
+
+from strong_typing.docstring import Docstring, DocstringParam, parse_type
+from strong_typing.inspection import DataclassField, DataclassInstance, dataclass_fields
+
+from ..formation.inspection import is_struct_type
+from ..model.properties import get_field_properties
+
+
+def make_dataclass(
+    name: str,
+    fields: list[DataclassField],
+    *,
+    module: Optional[types.ModuleType] = None,
+    docstring: Optional[Docstring] = None,
+) -> type[DataclassInstance]:
+    """
+    Dynamically creates a new data class type.
+
+    :param name: Name of the newly created type.
+    :param fields: Fields of the new data class type to create.
+    :param module: The module to assign the new type to.
+    :param docstring: The doc-string to set on the newly created type.
+    """
+
+    field_names = set(field.name for field in fields)
+
+    if docstring is not None:
+        docstring.params = {name: param for name, param in docstring.params.items() if name in field_names}
+
+    dataclass_fields = [(field.name, field.type, field.default) for field in fields]
+    module_name = module.__name__ if module is not None else None
+    if sys.version_info >= (3, 12):
+        data_type = dataclasses.make_dataclass(name, dataclass_fields, module=module_name)
+    else:
+        namespace = {"__module__": module_name} if module is not None else None
+        data_type = dataclasses.make_dataclass(name, dataclass_fields, namespace=namespace)
+    if module is not None:
+        setattr(module, data_type.__name__, data_type)
+
+    if docstring is not None:
+        data_type.__doc__ = str(docstring)
+
+    return data_type
+
+
+def flatten_dataclass(
+    cls: type[DataclassInstance],
+) -> tuple[list[DataclassField], Docstring]:
+    """
+    Extracts nested structures into a flat list of data-class fields.
+    """
+
+    fields: list[DataclassField] = []
+    docstring = parse_type(cls)
+
+    for field in dataclass_fields(cls):
+        props = get_field_properties(field.type)
+        plain_type = props.plain_type
+        if is_struct_type(plain_type):
+            nested_docstring = parse_type(plain_type)
+            for subfield in dataclass_fields(plain_type):
+                name = f"{field.name}__{subfield.name}"
+                fields.append(
+                    DataclassField(
+                        name,
+                        subfield.type,
+                        subfield.default,
+                    )
+                )
+                param = nested_docstring.params.get(subfield.name)
+                if param is not None:
+                    docstring.params[name] = DocstringParam(name, param.description, param.param_type)
+        else:
+            fields.append(field)
+
+    return fields, docstring

pysqlsync/util/dispatch.py

@@ -0,0 +1,28 @@
+import asyncio
+import functools
+import inspect
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable, Coroutine, TypeVar
+
+from .typing import ParamSpec
+
+R = TypeVar("R")
+P = ParamSpec("P")
+
+
+def thread_dispatch(fn: Callable[P, R]) -> Callable[P, Coroutine[None, None, R]]:
+    "A decorator to transform a synchronous function into an asynchronous function dispatched to a thread pool."
+
+    if not callable(fn):
+        raise TypeError("expected: a callable")
+
+    if inspect.iscoroutinefunction(fn):
+        raise TypeError("expected: a regular function; got: an async function")
+
+    @functools.wraps(fn)
+    async def invoke(*args: P.args, **kwargs: P.kwargs) -> R:
+        loop = asyncio.get_running_loop()
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            return await loop.run_in_executor(pool, functools.partial(fn, *args, **kwargs))
+
+    return invoke

pysqlsync/util/typing.py

@@ -0,0 +1,13 @@
+import sys
+
+if sys.version_info >= (3, 10):
+    from typing import ParamSpec as ParamSpec  # noqa: F401
+    from typing import TypeGuard as TypeGuard  # noqa: F401
+else:
+    from typing_extensions import ParamSpec as ParamSpec  # noqa: F401
+    from typing_extensions import TypeGuard as TypeGuard  # noqa: F401
+
+if sys.version_info >= (3, 12):
+    from typing import override as override  # noqa: F401
+else:
+    from typing_extensions import override as override  # noqa: F401