typesync 0.0.1a1__py3-none-any.whl

typesync/__init__.py

@@ -0,0 +1,13 @@
+__all__ = [
+    "cli",
+    "extractor",
+    "ts_types",
+    "type_translators",
+    "utils",
+]
+
+from .codegen import extractor
+from . import type_translators
+from . import utils
+from . import ts_types
+from .cli import cli

typesync/cli.py

@@ -0,0 +1,126 @@
+import os
+
+import click
+from flask import current_app
+from flask.cli import AppGroup
+from werkzeug.routing.rules import Rule
+
+from .codegen import CodeWriter, FlaskRouteTypeExtractor
+
+
+cli = AppGroup("typesync")
+
+
+@cli.command(help="Generate Typescript types based on Flask routes.")
+@click.argument("out_dir", type=click.Path(file_okay=False, resolve_path=True))
+@click.option("--endpoint", "-E", help="The base endpoint.", default="")
+@click.option("--samefile", "-S", help="Write types and apis to the same file")
+@click.option(
+    "--inference",
+    "-i",
+    is_flag=True,
+    help="Whether to use inference when type annotations cannot be resolved",
+)
+@click.option(
+    "--inference-can-eval",
+    is_flag=True,
+    help=(
+        "Whether eval() can be called during inference. WARNING: this will"
+        " execute arbitrary code."
+    ),
+)
+@click.option(
+    "--types-file",
+    help="Name of output file containing type definitions (defaults to 'types.ts')",
+    default="types.ts",
+)
+@click.option(
+    "--apis-file",
+    help="Name of output file containing API functions (defaults to 'apis.ts')",
+    default="apis.ts",
+)
+@click.option(
+    "--return-type-format",
+    default="{pc}ReturnType",
+    help=(
+        "Format string used to generate return type names from the route name. "
+        "Available placeholders are: "
+        "{d} (default route name), "
+        "{cc} (camelCase), "
+        "{pc} (PascalCase), "
+        "{uc} (UPPERCASE), "
+        "{lc} (lowercase), "
+        "{sc} (snake_case). "
+        "Defaults to: '{pc}ReturnType'"
+    ),
+)
+@click.option(
+    "--args-type-format",
+    default="{pc}ArgsType",
+    help=(
+        "Format string used to generate argument type names from the route name. "
+        "Available placeholders are: "
+        "{d} (default route name), "
+        "{cc} (camelCase), "
+        "{pc} (PascalCase), "
+        "{uc} (UPPERCASE), "
+        "{lc} (lowercase), "
+        "{sc} (snake_case). "
+        "Defaults to: '{pc}ArgsType'"
+    ),
+)
+@click.option(
+    "--function-name-format",
+    default="{m_lc}{r_pc}",
+    help=(
+        "Format string used to generate function names from the route and HTTP method. "
+        "Available placeholders are: "
+        "{r_d} or {m_d} (default route name or HTTP method), "
+        "{r_cc} or {m_cc} (camelCase), "
+        "{r_pc} or {m_pc} (PascalCase), "
+        "{r_uc} or {m_uc} (UPPERCASE), "
+        "{r_lc} or {m_lc} (lowercase), "
+        "{r_sc} or {m_sc} (snake_case). "
+        "Defaults to: '{m_lc}{r_pc}'"
+    ),
+)
+def generate(
+    out_dir: str,
+    endpoint: str,
+    inference: bool,
+    inference_can_eval: bool,
+    types_file: str,
+    apis_file: str,
+    return_type_format: str,
+    args_type_format: str,
+    function_name_format: str,
+    samefile: str | None = None,
+):
+    rules: list[Rule] = list(current_app.url_map.iter_rules())
+
+    os.makedirs(out_dir, exist_ok=True)
+
+    with (
+        open(os.path.join(out_dir, types_file), "w") as types_f,
+        open(os.path.join(out_dir, apis_file), "w") as api_f,
+    ):
+        code_writer = CodeWriter(
+            types_f,
+            api_f,
+            types_file,
+            return_type_format,
+            args_type_format,
+            function_name_format,
+            endpoint,
+        )
+        result = code_writer.write(
+            FlaskRouteTypeExtractor(
+                current_app,
+                rule,
+                inference_enabled=inference,
+                inference_can_eval=inference_can_eval,
+            )
+            for rule in rules
+        )
+        if not result:
+            click.secho("Errors occurred during file generation", fg="red")

typesync/codegen/__init__.py

@@ -0,0 +1,7 @@
+__all__ = [
+    "CodeWriter",
+    "FlaskRouteTypeExtractor",
+]
+
+from .extractor import FlaskRouteTypeExtractor
+from .writer import CodeWriter

typesync/codegen/extractor.py

@@ -0,0 +1,232 @@
+import typing
+
+import click
+from flask import Flask
+from werkzeug.routing import (
+    FloatConverter,
+    BaseConverter,
+    IntegerConverter,
+    UUIDConverter,
+    PathConverter,
+    UnicodeConverter,
+)
+from werkzeug.routing.rules import Rule
+
+from .inference import infer_return_type
+from typesync.ts_types import TSType, TSSimpleType, TSObject
+from typesync.type_translators import TypeNode, to_type_node
+
+if typing.TYPE_CHECKING:
+    from typesync.type_translators import Translator
+
+
+type Type = typing.Any
+type TypeTreeTuple = tuple[TypeTree, ...]
+type TypeTreeDict = dict[str, TypeTree]
+type TypeTree = Type | tuple[Type, TypeTreeTuple | TypeTreeDict]
+type GenericParamValues = dict[typing.TypeVar, TypeTree]
+
+
+class Logger(typing.Protocol):
+    def info(self, text: str) -> None: ...
+    def warning(self, text: str) -> None: ...
+    def error(self, text: str) -> None: ...
+
+
+class ClickLogger:
+    @staticmethod
+    def info(text: str) -> None:
+        click.echo(f"Info: {text}")
+
+    @staticmethod
+    def warning(text: str) -> None:
+        click.secho(f"Warning: {text}", fg="yellow")
+
+    @staticmethod
+    def error(text: str) -> None:
+        click.secho(f"Error: {text}", fg="red")
+
+
+def get_type_hints(tp: typing.Any) -> dict[str, typing.Any]:
+    return getattr(tp, "__annotations__", {})
+
+
+class FlaskRouteTypeExtractor:
+    def __init__(
+        self,
+        app: Flask,
+        rule: Rule,
+        translators: tuple[type["Translator"]] | None = None,
+        inference_enabled: bool = False,
+        inference_can_eval: bool = False,
+        logger: Logger | None = None,
+    ) -> None:
+        self.app = app
+        self.rule = rule
+        self.inference_enabled = inference_enabled
+        self.inference_can_eval = inference_can_eval
+        self.logger = ClickLogger() if logger is None else logger
+        self.translators = (
+            self._load_default_translators() if translators is None else translators
+        )
+
+    @staticmethod
+    def _load_default_translators() -> tuple[type["Translator"], ...]:
+        from typesync.type_translators import BaseTranslator, FlaskTranslator  # noqa: PLC0415
+
+        return (BaseTranslator, FlaskTranslator)
+
+    @property
+    def rule_name(self) -> str:
+        return self.rule.endpoint.replace(".", "_")
+
+    @property
+    def rule_url(self) -> str:
+        return "".join(
+            [(f"<{content}>" if arg else content) for arg, content in self.rule._trace][
+                1:
+            ]
+        )
+
+    def parse_args_type(self) -> TSType | None:
+        try:
+            used_converters: dict[str, BaseConverter] = {
+                arg: converter
+                for arg, converter in (
+                    (arg, self.rule._converters.get(arg, None))
+                    for arg in self.rule.arguments
+                )
+                if converter is not None
+            }
+            types: list[tuple[str, TSType]] = [
+                (arg, self._get_converter_type(arg, converter))
+                for arg, converter in used_converters.items()
+            ]
+
+            return (
+                TSObject([t[0] for t in types], [t[1] for t in types])
+                if len(types) > 0
+                else TSSimpleType("undefined")
+            )
+
+        except Exception as e:
+            self.logger.error(f"couldn't parse argument types ({e})")
+            return None
+
+    def translate_type(self, type_: Type) -> tuple[TSType, str | None]:
+        warning = None
+
+        def translate(
+            node: TypeNode, generics: dict[typing.TypeVar, TSType] | None
+        ) -> TSType:
+            nonlocal warning
+            for translator in translators:
+                r = translator.translate(node, generics)
+                if r is not None:
+                    return r
+
+            warning = (
+                f"can't translate '{getattr(node.origin, '__name__', node.origin)}'"
+                " to a TypeScript equivalent, defaulting to 'any'"
+            )
+            return TSSimpleType("any")
+
+        translators = [Translator(translate) for Translator in self.translators]
+        node = to_type_node(type_)
+        return translate(node, {}), warning
+
+    def parse_return_type(self) -> TSType | None:
+        try:
+            function = self.app.view_functions[self.rule.endpoint]
+            annotations = get_type_hints(function)
+            if annotations is not None and "return" in annotations:
+                return_annotations = annotations["return"]
+                route_return_annotations = self._get_route_annotations(
+                    return_annotations
+                )
+                return_type, warning = self.translate_type(route_return_annotations)
+            else:
+                return_type = warning = None
+
+            if self.inference_enabled and (return_type is None or warning is not None):
+                route_return_type = infer_return_type(
+                    function, self.logger, self.inference_can_eval
+                )
+                if route_return_type is not None:
+                    return_type, warning = self.translate_type(
+                        self._get_route_annotations(route_return_type)
+                    )
+
+            if warning is not None:
+                self.logger.warning(warning)
+
+            return return_type or TSSimpleType("any")
+
+        except Exception as e:
+            self.logger.error(
+                f"couldn't parse return type of '{self.rule.endpoint}' ({e})"
+            )
+            return None
+
+        else:
+            return TSSimpleType("any") if return_type is None else return_type
+
+    def parse_json_body(self) -> TSType | None:
+        try:
+            function = self.app.view_functions[self.rule.endpoint]
+            json_key = getattr(function, "_typesync", None)
+            if json_key is None:
+                return None
+
+            annotations = get_type_hints(function)
+            if json_key not in annotations:
+                self.logger.error(
+                    f"'{self.rule.endpoint}' expected to receive JSON body as keyword "
+                    f"argument '{json_key}'"
+                )
+                return None
+
+            json_body_annotations = annotations[json_key]
+            json_body_type, warning = self.translate_type(json_body_annotations)
+            if warning is not None:
+                self.logger.warning(warning)
+
+        except Exception as e:
+            self.logger.error(
+                f"couldn't parse JSON body type of '{self.rule.endpoint}' ({e})"
+            )
+            return None
+
+        else:
+            return json_body_type
+
+    def _get_route_annotations_from_tuple(self, tp: typing.Any) -> Type:
+        args = typing.get_args(tp)
+        return args[0]
+
+    def _get_route_annotations(self, tp: typing.Any) -> Type:
+        origin = typing.get_origin(tp) or tp
+        if origin is tuple:
+            return self._get_route_annotations_from_tuple(tp)
+        return tp
+
+    def _get_converter_type(self, arg: str, converter: BaseConverter) -> TSType:
+        if isinstance(converter, (FloatConverter, IntegerConverter)):
+            return TSSimpleType("number")
+        if isinstance(converter, (UUIDConverter, PathConverter, UnicodeConverter)):
+            return TSSimpleType("string")
+
+        # Custom converter, check to_python() annotations
+        annotations = get_type_hints(converter.to_python)
+        if annotations is None or "return" not in annotations:
+            self.logger.warning(
+                f"route '{self.rule.endpoint}', argument '{arg}': using non-standard"
+                "converter without type annotations, defaulting to 'string'",
+            )
+            return TSSimpleType("string")
+
+        return_annotations = annotations["return"]
+        return_type, warning = self.translate_type(return_annotations)
+        if warning is not None:
+            self.logger.warning(warning)
+        return return_type

typesync/codegen/inference.py

@@ -0,0 +1,239 @@
+import ast
+import builtins
+import inspect
+import itertools
+import textwrap
+import types
+import typing
+
+if typing.TYPE_CHECKING:
+    from .extractor import Logger
+
+
+class ASTVisitor(ast.NodeVisitor):
+    def __init__(
+        self, function: typing.Callable, logger: "Logger", can_eval: bool = False
+    ) -> None:
+        self.function = function
+        self.logger = logger
+        self.can_eval = can_eval
+        self.locals: dict[str, typing.Any] = {}
+        self.returns: list = []
+
+    def get_variable(self, name: ast.Name) -> typing.Any:
+        local_var = self.locals.get(name.id, None)
+        if local_var is not None:
+            return local_var
+        global_var = self.function.__globals__.get(name.id, None)
+        if global_var is not None:
+            return global_var
+        builtin = getattr(builtins, name.id, None)
+        if isinstance(builtin, type):
+            return builtin
+        return None
+
+    def get_constant(self, constant: ast.Constant) -> typing.Any:
+        try:
+            constant_value = ast.literal_eval(constant)
+            return type(constant_value)
+        except Exception:
+            return None
+
+    def get_type_if_all_equal(self, expressions: list[ast.expr]) -> typing.Any:
+        if len(expressions) == 0:
+            return None
+        if len(expressions) == 1:
+            return self.get_value(expressions[0])
+
+        el_types: dict[ast.expr, typing.Any] = {}
+        for el1, el2 in itertools.pairwise(expressions):
+            el1_type = el_types[el1] if el1 in el_types else self.get_value(el1)
+            el_types.setdefault(el1, el1_type)
+
+            el2_type = el_types[el2] if el2 in el_types else self.get_value(el2)
+            el_types.setdefault(el2, el2_type)
+            if el1_type != el2_type:
+                return None
+
+        return el_types[el1]
+
+    def get_list(self, list_: ast.List) -> typing.Any:
+        list_type = self.get_type_if_all_equal(list_.elts)
+        return list if list_type is None else list[list_type]
+
+    def get_tuple(self, tuple_: ast.Tuple) -> typing.Any:
+        types = tuple(self.get_value(el) for el in tuple_.elts)
+        if len([t for t in types if t is None]) != 0:
+            return tuple
+        return tuple[types]
+
+    def get_dict(self, dict_: ast.Dict) -> typing.Any:
+        keys_type = self.get_type_if_all_equal(dict_.keys)
+        values_type = self.get_type_if_all_equal(dict_.values)
+
+        if keys_type is None and values_type is None:
+            return dict
+
+        return dict[
+            typing.Any if keys_type is None else keys_type,
+            typing.Any if values_type is None else values_type,
+        ]
+
+    def get_value(self, expr: ast.expr) -> typing.Any:
+        match expr:
+            case ast.Name():
+                return self.get_variable(expr)
+            case ast.Constant():
+                return self.get_constant(expr)
+            case ast.List():
+                return self.get_list(expr)
+            case ast.Tuple():
+                return self.get_tuple(expr)
+            case ast.Dict():
+                return self.get_dict(expr)
+            case ast.Call():
+                return self.infer_call_type(expr)
+            case _:
+                return None
+
+    def from_func_call(self, func: ast.Name) -> typing.Any:
+        called_function = self.get_variable(func)
+        if called_function is None:
+            return None
+
+        if isinstance(called_function, type):
+            # This is a class
+            return called_function
+
+        origin = typing.get_origin(called_function) or called_function
+        if isinstance(origin, type):
+            # This is of the form type[T], so we should return T
+            args = typing.get_args(called_function)
+            if len(args) != 1:
+                return None
+            return args[0]
+
+        annotations = getattr(called_function, "__annotations__", {})
+        if "return" not in annotations:
+            return infer_return_type(called_function, self.logger, self.can_eval)
+
+        return annotations["return"]
+
+    def from_method_call(self, method: ast.Attribute) -> typing.Any:
+        value = self.get_value(method.value)
+        if value is None:
+            return None
+
+        func = getattr(value, method.attr, None)
+        if func is None or not callable(func):
+            return None
+        annotations = getattr(func, "__annotations__", {})
+        if "return" not in annotations:
+            return infer_return_type(func, self.logger, self.can_eval)
+        return annotations["return"]
+
+    def infer_call_type(self, call: ast.Call) -> typing.Any:
+        callable_ = call.func
+
+        match callable_:
+            case ast.Name():
+                return self.from_func_call(callable_)
+            case ast.Attribute():
+                return self.from_method_call(callable_)
+            case _:
+                return None
+
+    def visit_Return(self, node: ast.Return) -> None:
+        if node.value is not None:
+            self.returns.append(self.get_value(node.value))
+        self.generic_visit(node)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        annotation = self.get_value(node.annotation)
+        if annotation is None and self.can_eval:
+            annotation_string = ast.unparse(node.annotation)
+            annotation_code = compile(
+                annotation_string,
+                "<annotation>",
+                "eval",
+                0,
+            )
+            try:
+                annotation = eval(annotation_code, self.function.__globals__, {})  # noqa: S307
+            except Exception as e:
+                self.logger.warning(
+                    f"failed to parse annotation {annotation_string!r}: {e!s}"
+                )
+                annotation = None
+        if annotation is not None:
+            self.locals[node.target.id] = annotation
+        self.generic_visit(node)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        for target in node.targets:
+            if not isinstance(target, ast.Name):
+                continue
+            self.locals[target.id] = self.get_value(node.value)
+        self.generic_visit(node)
+
+
+def smart_type(type_: typing.Any) -> typing.Any:
+    if isinstance(type_, type):
+        return type[type_]
+    return type_
+
+
+def define_types_from_closure(function: typing.Callable, visitor: ASTVisitor) -> None:
+    closure: tuple[types.CellType, ...] | None = getattr(function, "__closure__", None)
+    code: types.CodeType | None = getattr(function, "__code__", None)
+    if code is None or closure is None:
+        return
+
+    visitor.locals.update(
+        zip(
+            code.co_freevars,
+            (smart_type(cell.cell_contents) for cell in closure),
+            strict=True,
+        )
+    )
+
+
+def define_types_from_signature(function: typing.Callable, visitor: ASTVisitor) -> None:
+    try:
+        signature = inspect.signature(function)
+        visitor.locals.update(
+            {param: value.annotation for param, value in signature.parameters.items()}
+        )
+    except ValueError:
+        pass
+
+
+def infer_return_type(
+    function: typing.Callable, logger: "Logger", can_eval: bool
+) -> typing.Any:
+    try:
+        source = inspect.getsource(function)
+    except (TypeError, OSError):
+        return None
+    source = textwrap.dedent(source)
+    statements = ast.parse(source).body
+    if len(statements) != 1:
+        # TODO: Handle this case
+        return None
+
+    body = statements[0]
+    if not isinstance(body, ast.FunctionDef):
+        return None
+
+    visitor = ASTVisitor(function, logger, can_eval=can_eval)
+    define_types_from_closure(function, visitor)
+    define_types_from_signature(function, visitor)
+    visitor.visit(body)
+    if len(visitor.returns) == 0:
+        return type(None)
+
+    for rt1, rt2 in itertools.pairwise(visitor.returns):
+        if rt1 != rt2:
+            return typing.Any
+
+    return visitor.returns[0]