typesync 0.0.1a1__py3-none-any.whl → 0.0.1a2__py3-none-any.whl

typesync/__init__.py

@@ -1,4 +1,5 @@
 __all__ = [
+    "annotations",
     "cli",
     "extractor",
     "ts_types",
@@ -6,8 +7,9 @@ __all__ = [
     "utils",
 ]
 
-from .codegen import extractor
+from . import annotations
 from . import type_translators
 from . import utils
 from . import ts_types
 from .cli import cli
+from .codegen import extractor

typesync/annotations.py

@@ -0,0 +1,27 @@
+import typing
+
+from typesync.misc import HTTPMethod
+
+
+class TypesyncAnnotation: ...
+
+
+class TypesyncSkipGenerationAnnotation(TypesyncAnnotation): ...
+
+
+class TypesyncHTTPMethodAnnotation(TypesyncAnnotation):
+    def __init__(self, methods: set[HTTPMethod]) -> None:
+        self.methods = methods
+
+
+type SkipGeneration[T] = typing.Annotated[T, TypesyncSkipGenerationAnnotation()]
+
+type ForHTTPGet[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"GET"})]
+type ForHTTPHead[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"HEAD"})]
+type ForHTTPPost[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"POST"})]
+type ForHTTPPut[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"PUT"})]
+type ForHTTPDelete[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"DELETE"})]
+type ForHTTPConnect[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"CONNECT"})]
+type ForHTTPOptions[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"OPTIONS"})]
+type ForHTTPTrace[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"TRACE"})]
+type ForHTTPPatch[T] = typing.Annotated[T, TypesyncHTTPMethodAnnotation({"PATCH"})]

typesync/argument_types.py

@@ -0,0 +1,116 @@
+import hashlib
+import importlib.util
+import pathlib
+import sys
+import types
+
+from click import ParamType
+
+from .type_translators import Translator
+
+
+class PythonModuleParamType(ParamType):
+    name = "python_module"
+
+    def convert(self, value, param, ctx) -> types.ModuleType:
+        if isinstance(value, types.ModuleType):
+            return value
+
+        if not isinstance(value, str):
+            return self.fail(f"{value!r} is not a valid value", param, ctx)
+
+        path = pathlib.Path(value).resolve()
+
+        if not path.exists:
+            return self.fail(f"file {value!r} does not exist", param, ctx)
+
+        if not path.is_file():
+            return self.fail(f"{value!r} is not a file", param, ctx)
+
+        mod_name = f"module_{hashlib.sha256(str(path).encode()).hexdigest()[:16]}"
+        spec = importlib.util.spec_from_file_location(mod_name, str(path))
+        if spec is None or spec.loader is None:
+            return self.fail(f"{value!r} is not a valid python module", param, ctx)
+
+        try:
+            module = importlib.util.module_from_spec(spec)
+        except ModuleNotFoundError:
+            return self.fail(f"{value!r} is not a valid python module", param, ctx)
+
+        sys.modules[mod_name] = module
+        try:
+            spec.loader.exec_module(module)
+        except Exception as e:
+            del sys.modules[mod_name]
+            return self.fail(f"could not load module at {value!r} ({e})", param, ctx)
+
+        return module
+
+
+class TranslatorPluginParamType(ParamType):
+    name = "translator_plugin"
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.python_module_plugin_param_type = PythonModuleParamType()
+
+    def convert(self, value, param, ctx) -> type[Translator]:
+        module = self.python_module_plugin_param_type.convert(value, param, ctx)
+
+        translator_func = getattr(module, "translator", None)
+        if translator_func is None:
+            return self.fail(
+                f"{value!r} must define a function 'translator() -> type[Translator]'",
+                param,
+                ctx,
+            )
+        try:
+            translator = translator_func()
+        except Exception as e:
+            return self.fail(
+                f"failed to run the 'translator()' function defined by {value!r} ({e})",
+                param,
+                ctx,
+            )
+
+        if not issubclass(translator, Translator):
+            return self.fail(
+                f"'translator()' function defined by {value!r} must return a class "
+                "that inherits from typesync.type_translators.Translator",
+                param,
+                ctx,
+            )
+
+        return translator
+
+
+class TranslatorPriorityParamType(ParamType):
+    name = "translator_priority"
+
+    def convert(self, value, param, ctx) -> tuple[str, int]:
+        if isinstance(value, tuple):
+            return value
+
+        if not isinstance(value, str):
+            return self.fail(f"{value!r} is not a valid value", param, ctx)
+
+        id_and_priority = value.rsplit(":", 1)
+        if len(id_and_priority) != 2:
+            return self.fail(
+                f"must be of the form ID:PRIORITY (was {value!r})", param, ctx
+            )
+
+        id_, priority_str = id_and_priority
+        try:
+            priority = int(priority_str)
+        except ValueError:
+            return self.fail(
+                f"priority {priority_str!r} cannot be converted to an int", param, ctx
+            )
+
+        return id_, priority
+
+
+PYTHON_MODULE = PythonModuleParamType()
+TRANSLATOR_PLUGIN = TranslatorPluginParamType()
+TRANSLATOR_PRIORITY = TranslatorPriorityParamType()

typesync/cli.py

@@ -1,11 +1,17 @@
 import os
+import typing
 
 import click
 from flask import current_app
 from flask.cli import AppGroup
+from prettytable import PrettyTable
 from werkzeug.routing.rules import Rule
 
-from .codegen import CodeWriter, FlaskRouteTypeExtractor
+from . import argument_types
+from .codegen import CodeWriter, RouteTypeExtractor
+
+if typing.TYPE_CHECKING:
+    from .type_translators import Translator
 
 
 cli = AppGroup("typesync")
@@ -14,12 +20,37 @@ 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("--samefile", "-S", help="Write types and apis to the same file.")
+@click.option(
+    "--translator",
+    "-t",
+    help=(
+        "Path to a python script containing a additional type translators. "
+        "May be used multiple times."
+    ),
+    type=argument_types.TRANSLATOR_PLUGIN,
+    multiple=True,
+)
+@click.option(
+    "--translator-priority",
+    help=("Set the priority of a translator.May be used multiple times."),
+    type=argument_types.TRANSLATOR_PRIORITY,
+    multiple=True,
+)
+@click.option(
+    "--skip-unannotated",
+    type=bool,
+    default=True,
+    help=(
+        "Whether to skip code generation for routes whose annotations are not specified"
+        " and could not be inferred. Defaults to True."
+    ),
+)
 @click.option(
     "--inference",
     "-i",
     is_flag=True,
-    help="Whether to use inference when type annotations cannot be resolved",
+    help="Whether to use inference when type annotations cannot be resolved.",
 )
 @click.option(
     "--inference-can-eval",
@@ -31,42 +62,42 @@ cli = AppGroup("typesync")
 )
 @click.option(
     "--types-file",
-    help="Name of output file containing type definitions (defaults to 'types.ts')",
+    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')",
+    help="Name of output file containing API functions (defaults to 'apis.ts').",
     default="apis.ts",
 )
 @click.option(
     "--return-type-format",
-    default="{pc}ReturnType",
+    default="{r_pc}{m_uc}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'"
+        "{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: '{r_pc}{m_uc}ReturnType'."
     ),
 )
 @click.option(
     "--args-type-format",
-    default="{pc}ArgsType",
+    default="{r_pc}{m_uc}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'"
+        "{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: '{r_pc}{m_uc}ArgsType'."
     ),
 )
 @click.option(
@@ -81,14 +112,17 @@ cli = AppGroup("typesync")
         "{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}'"
+        "Defaults to: '{m_lc}{r_pc}'."
     ),
 )
 def generate(
     out_dir: str,
     endpoint: str,
+    translator: tuple[type["Translator"], ...],
+    translator_priority: tuple[tuple[str, int], ...],
     inference: bool,
     inference_can_eval: bool,
+    skip_unannotated: bool,
     types_file: str,
     apis_file: str,
     return_type_format: str,
@@ -114,13 +148,31 @@ def generate(
             endpoint,
         )
         result = code_writer.write(
-            FlaskRouteTypeExtractor(
+            RouteTypeExtractor(
                 current_app,
                 rule,
+                translators=translator,
+                translator_priorities=dict(translator_priority),
                 inference_enabled=inference,
                 inference_can_eval=inference_can_eval,
+                skip_unannotated=skip_unannotated,
             )
             for rule in rules
         )
         if not result:
             click.secho("Errors occurred during file generation", fg="red")
+
+
+@cli.command(help="Show available translators and their default priorities.")
+def list_translators():
+    translators = RouteTypeExtractor.sort_translators(
+        RouteTypeExtractor.default_translators(), {}
+    )
+    table = PrettyTable()
+    table.field_names = ["ID", "Priority"]
+    table.add_rows(
+        [[translator.ID, translator.DEFAULT_PRIORITY] for translator in translators]
+    )
+    table.align["ID"] = "l"
+    table.align["Priority"] = "r"
+    print(table)

typesync/codegen/__init__.py

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

typesync/codegen/extractor.py

@@ -12,9 +12,11 @@ from werkzeug.routing import (
 )
 from werkzeug.routing.rules import Rule
 
+
 from .inference import infer_return_type
+from typesync.misc import HTTPMethod
 from typesync.ts_types import TSType, TSSimpleType, TSObject
-from typesync.type_translators import TypeNode, to_type_node
+from typesync.type_translators import TranslationContext, TypeNode, to_type_node
 
 if typing.TYPE_CHECKING:
     from typesync.type_translators import Translator
@@ -51,30 +53,50 @@ def get_type_hints(tp: typing.Any) -> dict[str, typing.Any]:
     return getattr(tp, "__annotations__", {})
 
 
-class FlaskRouteTypeExtractor:
+class RouteTypeExtractor:
     def __init__(
         self,
         app: Flask,
         rule: Rule,
-        translators: tuple[type["Translator"]] | None = None,
+        translators: tuple[type["Translator"], ...] | None = None,
+        translator_priorities: dict[str, int] | None = None,
         inference_enabled: bool = False,
         inference_can_eval: bool = False,
+        skip_unannotated: bool = True,
         logger: Logger | None = None,
     ) -> None:
         self.app = app
         self.rule = rule
         self.inference_enabled = inference_enabled
         self.inference_can_eval = inference_can_eval
+        self.skip_unannotated = skip_unannotated
         self.logger = ClickLogger() if logger is None else logger
-        self.translators = (
-            self._load_default_translators() if translators is None else translators
+        self.translator_priorities = (
+            {} if translator_priorities is None else translator_priorities
+        )
+        self.translators = self.sort_translators(
+            (*self.default_translators(), *(translators or ())),
+            self.translator_priorities,
         )
 
     @staticmethod
-    def _load_default_translators() -> tuple[type["Translator"], ...]:
-        from typesync.type_translators import BaseTranslator, FlaskTranslator  # noqa: PLC0415
+    def sort_translators[T: type["Translator"] | "Translator"](
+        translators: typing.Iterable[T],
+        priorities: dict[str, int],
+    ) -> tuple[T, ...]:
+        return tuple(
+            sorted(translators, key=lambda t: -priorities.get(t.ID, t.DEFAULT_PRIORITY))
+        )
 
-        return (BaseTranslator, FlaskTranslator)
+    @staticmethod
+    def default_translators() -> tuple[type["Translator"], ...]:
+        from typesync.type_translators import (  # noqa: PLC0415
+            AnnotationsTranslator,
+            BaseTranslator,
+            FlaskTranslator,
+        )
+
+        return (AnnotationsTranslator, BaseTranslator, FlaskTranslator)
 
     @property
     def rule_name(self) -> str:
@@ -88,7 +110,7 @@ class FlaskRouteTypeExtractor:
             ]
         )
 
-    def parse_args_type(self) -> TSType | None:
+    def parse_args_types(self) -> dict[HTTPMethod, TSType]:
         try:
             used_converters: dict[str, BaseConverter] = {
                 arg: converter
@@ -98,22 +120,30 @@ class FlaskRouteTypeExtractor:
                 )
                 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")
-            )
+            results: dict[HTTPMethod, TSType] = {}
+            for method in self.rule.methods or set():
+                types: list[tuple[str, TSType]] = [
+                    (arg, self._get_converter_type(arg, converter, method))
+                    for arg, converter in used_converters.items()
+                ]
+
+                results[method] = (
+                    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
+            return {}
+
+        else:
+            return results
 
-    def translate_type(self, type_: Type) -> tuple[TSType, str | None]:
+    def translate_type(
+        self, type_: Type, ctx: TranslationContext
+    ) -> tuple[TSType, str | None]:
         warning = None
 
         def translate(
@@ -131,52 +161,68 @@ class FlaskRouteTypeExtractor:
             )
             return TSSimpleType("any")
 
-        translators = [Translator(translate) for Translator in self.translators]
+        translators = [Translator(translate, ctx) for Translator in self.translators]
         node = to_type_node(type_)
         return translate(node, {}), warning
 
-    def parse_return_type(self) -> TSType | None:
+    def parse_return_types(self, force_inference=False) -> dict[HTTPMethod, TSType]:
         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(
+            ctx = TranslationContext(
+                rule=self.rule,
+                view_function=function,
+                method="GET",
+                mode="RETURN",
+                inferred=False,
+            )
+
+            return_annotations = None
+            if (
+                not force_inference
+                and annotations is not None
+                and "return" in annotations
+            ):
+                return_annotations = annotations["return"]
+            elif self.inference_enabled:
+                return_annotations = 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)
-                    )
+                ctx.inferred = True
+
+            if return_annotations is None and self.skip_unannotated:
+                return {}
 
-            if warning is not None:
-                self.logger.warning(warning)
+            route_annotations = self._get_route_annotations(return_annotations)
 
-            return return_type or TSSimpleType("any")
+            results: dict[HTTPMethod, TSType] = {}
+            for method in self.rule.methods or set():
+                ctx.method = method
+                result, warning = self.translate_type(route_annotations, ctx)
+
+                if warning is not None and not ctx.inferred and self.inference_enabled:
+                    return self.parse_return_types(force_inference=True)
+
+                results[method] = result or TSSimpleType("any")
+                if warning is not None:
+                    self.logger.warning(warning)
 
         except Exception as e:
             self.logger.error(
                 f"couldn't parse return type of '{self.rule.endpoint}' ({e})"
             )
-            return None
+            return {}
 
         else:
-            return TSSimpleType("any") if return_type is None else return_type
+            return results
 
-    def parse_json_body(self) -> TSType | None:
+    def parse_json_body(self) -> dict[HTTPMethod, TSType]:
         try:
             function = self.app.view_functions[self.rule.endpoint]
             json_key = getattr(function, "_typesync", None)
             if json_key is None:
-                return None
+                return {}
 
             annotations = get_type_hints(function)
             if json_key not in annotations:
@@ -184,21 +230,36 @@ class FlaskRouteTypeExtractor:
                     f"'{self.rule.endpoint}' expected to receive JSON body as keyword "
                     f"argument '{json_key}'"
                 )
-                return None
+                return {}
 
             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)
+
+            ctx = TranslationContext(
+                rule=self.rule,
+                view_function=function,
+                method="GET",
+                mode="JSON",
+                inferred=False,
+            )
+            results: dict[HTTPMethod, TSType] = {}
+
+            for method in self.rule.methods or set():
+                json_body_type, warning = self.translate_type(
+                    json_body_annotations, ctx
+                )
+                if warning is not None:
+                    self.logger.warning(warning)
+
+                results[method] = json_body_type
 
         except Exception as e:
             self.logger.error(
                 f"couldn't parse JSON body type of '{self.rule.endpoint}' ({e})"
             )
-            return None
+            return {}
 
         else:
-            return json_body_type
+            return results
 
     def _get_route_annotations_from_tuple(self, tp: typing.Any) -> Type:
         args = typing.get_args(tp)
@@ -210,7 +271,9 @@ class FlaskRouteTypeExtractor:
             return self._get_route_annotations_from_tuple(tp)
         return tp
 
-    def _get_converter_type(self, arg: str, converter: BaseConverter) -> TSType:
+    def _get_converter_type(
+        self, arg: str, converter: BaseConverter, method: HTTPMethod
+    ) -> TSType:
         if isinstance(converter, (FloatConverter, IntegerConverter)):
             return TSSimpleType("number")
         if isinstance(converter, (UUIDConverter, PathConverter, UnicodeConverter)):
@@ -225,8 +288,16 @@ class FlaskRouteTypeExtractor:
             )
             return TSSimpleType("string")
 
+        ctx = TranslationContext(
+            rule=self.rule,
+            view_function=self.app.view_functions[self.rule.endpoint],
+            method=method,
+            mode="ARGS",
+            inferred=False,
+        )
+
         return_annotations = annotations["return"]
-        return_type, warning = self.translate_type(return_annotations)
+        return_type, warning = self.translate_type(return_annotations, ctx)
         if warning is not None:
             self.logger.warning(warning)
         return return_type

typesync/codegen/inference.py

@@ -14,7 +14,7 @@ class ASTVisitor(ast.NodeVisitor):
     def __init__(
         self, function: typing.Callable, logger: "Logger", can_eval: bool = False
     ) -> None:
-        self.function = function
+        self.function: typing.Callable = function
         self.logger = logger
         self.can_eval = can_eval
         self.locals: dict[str, typing.Any] = {}
@@ -24,7 +24,8 @@ class ASTVisitor(ast.NodeVisitor):
         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)
+        globals_dict = getattr(self.function, "__globals__", {})
+        global_var = globals_dict.get(name.id, None)
         if global_var is not None:
             return global_var
         builtin = getattr(builtins, name.id, None)
@@ -68,7 +69,11 @@ class ASTVisitor(ast.NodeVisitor):
         return tuple[types]
 
     def get_dict(self, dict_: ast.Dict) -> typing.Any:
-        keys_type = self.get_type_if_all_equal(dict_.keys)
+        if None in dict_.keys:
+            # TODO: support unpacking
+            return dict
+        keys = typing.cast(list[ast.expr], dict_.keys)
+        keys_type = self.get_type_if_all_equal(keys)
         values_type = self.get_type_if_all_equal(dict_.values)
 
         if keys_type is None and values_type is None:
@@ -149,6 +154,10 @@ class ASTVisitor(ast.NodeVisitor):
         self.generic_visit(node)
 
     def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        target = node.target
+        if not isinstance(target, ast.Name):
+            # TODO
+            return
         annotation = self.get_value(node.annotation)
         if annotation is None and self.can_eval:
             annotation_string = ast.unparse(node.annotation)
@@ -159,14 +168,15 @@ class ASTVisitor(ast.NodeVisitor):
                 0,
             )
             try:
-                annotation = eval(annotation_code, self.function.__globals__, {})  # noqa: S307
+                function_globals = getattr(self.function, "__globals__", {})
+                annotation = eval(annotation_code, 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.locals[target.id] = annotation
         self.generic_visit(node)
 
     def visit_Assign(self, node: ast.Assign) -> None:

typesync/codegen/writer.py

@@ -2,10 +2,12 @@ import typing
 
 import inflection
 
+from typesync.ts_types import TSType, TSSimpleType
+
 if typing.TYPE_CHECKING:
     from io import TextIOBase
-    from typesync.ts_types import TSType
-    from .extractor import FlaskRouteTypeExtractor
+    from typesync.misc import HTTPMethod
+    from .extractor import RouteTypeExtractor
 
 
 def make_rule_name_map(rule_name: str, prefix: str = "") -> dict[str, str]:
@@ -19,6 +21,12 @@ def make_rule_name_map(rule_name: str, prefix: str = "") -> dict[str, str]:
     }
 
 
+class TypesDict(typing.TypedDict):
+    return_type: TSType
+    args_type: TSType
+    json_body_type: TSType
+
+
 class CodeWriter:
     def __init__(
         self,
@@ -45,41 +53,64 @@ class CodeWriter:
             {**make_rule_name_map(rule_name, "r_"), **make_rule_name_map(method, "m_")}
         )
 
-    def _return_type_name(self, rule_name: str) -> str:
-        return self.return_type_format.format_map(make_rule_name_map(rule_name))
+    def _return_type_name(self, rule_name: str, method: str) -> str:
+        return self.return_type_format.format_map(
+            {**make_rule_name_map(rule_name, "r_"), **make_rule_name_map(method, "m_")}
+        )
+
+    def _params_type_name(self, rule_name: str, method: str) -> str:
+        return self.params_type_format.format_map(
+            {**make_rule_name_map(rule_name, "r_"), **make_rule_name_map(method, "m_")}
+        )
 
-    def _params_type_name(self, rule_name: str) -> str:
-        return self.params_type_format.format_map(make_rule_name_map(rule_name))
+    def _bundle_types_per_method(
+        self,
+        return_types: dict["HTTPMethod", TSType],
+        args_types: dict["HTTPMethod", TSType],
+        json_body_types: dict["HTTPMethod", TSType],
+    ) -> dict["HTTPMethod", TypesDict]:
+        methods = {*return_types.keys(), *args_types.keys(), *json_body_types.keys()}
+        return {
+            method: TypesDict(
+                return_type=return_types.get(method, TSSimpleType("undefined")),
+                args_type=args_types.get(method, TSSimpleType("undefined")),
+                json_body_type=json_body_types.get(method, TSSimpleType("undefined")),
+            )
+            for method in methods
+        }
 
-    def write(self, parsers: typing.Iterable["FlaskRouteTypeExtractor"]) -> bool:
+    def write(self, parsers: typing.Iterable["RouteTypeExtractor"]) -> bool:
         error = False
         self._write_types_header()
         self._write_api_header()
         names: list[str] = []
         for parser in parsers:
-            return_type = parser.parse_return_type()
-            args_type = parser.parse_args_type()
-            json_body_type = parser.parse_json_body()
-            if return_type is None or args_type is None:
-                error = True
-                if self.stop_on_error:
-                    return False
-                continue
-            return_type_name, params_type_name, has_args, has_json = self._write_types(
-                parser.rule_name, return_type, args_type, json_body_type
+            return_types = parser.parse_return_types()
+            args_types = parser.parse_args_types()
+            json_body_types = parser.parse_json_body()
+
+            types_per_method = self._bundle_types_per_method(
+                return_types, args_types, json_body_types
             )
-            names.extend(
-                self._write_api_function(
-                    parser.rule_name,
-                    parser.rule_url,
-                    method,
-                    return_type_name,
-                    params_type_name,
-                    has_args,
-                    has_json,
+
+            for (
+                method,
+                return_type_name,
+                params_type_name,
+                has_args,
+                has_json,
+            ) in self._write_types(parser.rule_name, types_per_method):
+                names.append(
+                    self._write_api_function(
+                        parser.rule_name,
+                        parser.rule_url,
+                        method,
+                        return_type_name,
+                        params_type_name,
+                        has_args,
+                        has_json,
+                    )
                 )
-                for method in (parser.rule.methods or {})
-            )
         self._write_api_footer(names)
         return not error
 
@@ -153,43 +184,48 @@ class CodeWriter:
     def _write_types(
         self,
         rule_name: str,
-        return_type: "TSType",
-        args_type: "TSType",
-        json_body_type: "TSType | None",
-    ) -> tuple[str, str, bool, bool]:
-        return_type_name = self._return_type_name(rule_name)
-        self.types_file.write(
-            f"export type {return_type_name} = {return_type.generate(return_type_name)}"
-            ";\n"
-        )
-        params_type_name = self._params_type_name(rule_name)
-        optional_args = "?" if args_type == "undefined" else ""
-        optional_body = (
-            "?" if json_body_type is None or json_body_type == "undefined" else ""
-        )
+        types_per_method: dict["HTTPMethod", TypesDict],
+    ) -> typing.Generator[tuple[str, str, str, bool, bool], None, None]:
+        for method, types in types_per_method.items():
+            return_type_name = self._return_type_name(rule_name, method)
+            generated_return_type = types["return_type"].generate(return_type_name)
+            self.types_file.write(
+                f"export type {return_type_name} = {generated_return_type};\n"
+            )
+            params_type_name = self._params_type_name(rule_name, method)
+            optional_args = "?" if types["args_type"] == "undefined" else ""
+            json_body_type = types["json_body_type"]
+            optional_body = (
+                "?" if json_body_type is None or json_body_type == "undefined" else ""
+            )
 
-        internal_args_name = f"_{rule_name}Args"
-        self.types_file.write(
-            f"type {internal_args_name} = {args_type.generate(internal_args_name)};\n"
-        )
+            internal_args_name = f"_{rule_name}{method}Args"
+            generated_args_type = types["args_type"].generate(internal_args_name)
+            self.types_file.write(
+                f"type {internal_args_name} = {generated_args_type};\n"
+            )
 
-        internal_body_name = f"_{rule_name}Body"
-        string_json_body_type = (
-            "undefined"
-            if json_body_type is None
-            else json_body_type.generate(internal_body_name)
-        )
-        self.types_file.write(f"type {internal_body_name} = {string_json_body_type};\n")
+            internal_body_name = f"_{rule_name}{method}Body"
+            string_json_body_type = (
+                "undefined"
+                if types["json_body_type"] is None
+                else types["json_body_type"].generate(internal_body_name)
+            )
+            self.types_file.write(
+                f"type {internal_body_name} = {string_json_body_type};\n"
+            )
 
-        self.types_file.write(
-            f"export interface {params_type_name} extends RequestArgs" + " {\n"
-            f"    args{optional_args}: {internal_args_name};\n"
-            f"    body{optional_body}: {internal_body_name};\n"
-            "}\n\n"
-        )
-        return (
-            return_type_name,
-            params_type_name,
-            optional_args == "",
-            optional_body == "",
-        )
+            self.types_file.write(
+                f"export interface {params_type_name} extends RequestArgs" + " {\n"
+                f"    args{optional_args}: {internal_args_name};\n"
+                f"    body{optional_body}: {internal_body_name};\n"
+                "}\n\n"
+            )
+
+            yield (
+                method,
+                return_type_name,
+                params_type_name,
+                optional_args == "",
+                optional_body == "",
+            )

typesync/misc.py

@@ -0,0 +1,7 @@
+import typing
+
+type HTTPMethodStrict = typing.Literal[
+    "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH"
+]
+
+type HTTPMethod = HTTPMethodStrict | str

typesync/type_translators/__init__.py

@@ -1,12 +1,16 @@
 __all__ = [
+    "AnnotationsTranslator",
     "BaseTranslator",
     "FlaskTranslator",
+    "TranslationContext",
     "Translator",
     "TypeNode",
     "to_type_node",
 ]
 
+from .annotations_translator import AnnotationsTranslator
 from .base_translator import BaseTranslator
 from .flask_translator import FlaskTranslator
+from .context import TranslationContext
 from .abstract import Translator
 from .type_node import TypeNode, to_type_node

typesync/type_translators/abstract.py

@@ -1,19 +1,26 @@
 import abc
 import typing
 
+
 if typing.TYPE_CHECKING:
     from . import TypeNode
+    from .context import TranslationContext
     from typesync.ts_types import TSType
 
 
 class Translator(abc.ABC):
-    @abc.abstractmethod
+    DEFAULT_PRIORITY: int = 0
+    ID: str
+
     def __init__(
         self,
-        convert: typing.Callable[
+        translate: typing.Callable[
             ["TypeNode", dict[typing.TypeVar, "TSType"] | None], "TSType"
         ],
-    ) -> None: ...
+        ctx: "TranslationContext",
+    ) -> None:
+        self._translate = translate
+        self.ctx = ctx
 
     @abc.abstractmethod
     def translate(

typesync/type_translators/annotations_translator.py

@@ -0,0 +1,47 @@
+import typing
+
+
+from .abstract import Translator
+from .type_node import TypeNode
+from typesync import annotations
+from typesync.ts_types import TSSimpleType, TSType
+
+
+class AnnotationsTranslator(Translator):
+    DEFAULT_PRIORITY = -100
+    ID = "typesync.AnnotationsTranslator"
+
+    def _translate_http_method_annotation(
+        self,
+        node: TypeNode,
+        annotation: annotations.TypesyncHTTPMethodAnnotation,
+        generics: dict[typing.TypeVar, TSType] | None,
+    ) -> TSType | None:
+        if self.ctx.method in annotation.methods:
+            return self._translate(node, generics)
+        return TSSimpleType("never")
+
+    def _translate_annotation(
+        self,
+        node: TypeNode,
+        annotation: typing.Any,
+        generics: dict[typing.TypeVar, TSType] | None,
+    ) -> TSType | None:
+        match annotation:
+            case annotations.TypesyncHTTPMethodAnnotation():
+                return self._translate_http_method_annotation(
+                    node, annotation, generics
+                )
+
+        return self._translate(node, generics)
+
+    def translate(
+        self, node: TypeNode, generics: dict[typing.TypeVar, TSType] | None
+    ) -> TSType | None:
+        if node.origin is not typing.Annotated:
+            return None
+
+        if len(node.args) != 1:
+            return None
+
+        return self._translate_annotation(node.args[0], node.annotation, generics)

typesync/type_translators/base_translator.py

@@ -17,13 +17,8 @@ from typesync.ts_types import (
 
 
 class BaseTranslator(Translator):
-    def __init__(
-        self,
-        translate: typing.Callable[
-            [TypeNode, dict[typing.TypeVar, TSType] | None], TSType
-        ],
-    ):
-        self._translate = translate
+    DEFAULT_PRIORITY = 0
+    ID = "typesync.BaseTranslator"
 
     def _unwrap_generic(
         self, node: TypeNode, generics: dict[typing.TypeVar, TSType]
@@ -71,6 +66,15 @@ class BaseTranslator(Translator):
     def _translate_complex_type(
         self, node: TypeNode, generics: dict[typing.TypeVar, TSType]
     ) -> TSType | None:
+        if node.origin not in {
+            dict,
+            list,
+            tuple,
+            types.UnionType,
+            typing.Union,
+        }:
+            return None
+
         translated_args = self._translate_args(node.args, generics)
 
         if node.origin is dict:
@@ -132,6 +136,9 @@ class BaseTranslator(Translator):
         if node.origin is RecursiveCall:
             return self._translate_recursive_call(node, generics)
 
+        if isinstance(node.origin, typing.TypeVar):
+            return generics.get(node.origin)
+
         if isinstance(node.origin, typing.TypeAliasType):
             return self._translate_type_alias(node, generics)
 

typesync/type_translators/context.py

@@ -0,0 +1,16 @@
+import dataclasses
+import typing
+
+from flask.typing import RouteCallable
+from werkzeug.routing.rules import Rule
+
+from typesync.misc import HTTPMethod
+
+
+@dataclasses.dataclass
+class TranslationContext:
+    rule: Rule
+    view_function: RouteCallable
+    method: HTTPMethod
+    mode: typing.Literal["JSON", "RETURN", "ARGS"]
+    inferred: bool

typesync/type_translators/flask_translator.py

@@ -7,13 +7,8 @@ from typesync.utils import Response
 
 
 class FlaskTranslator(Translator):
-    def __init__(
-        self,
-        translate: typing.Callable[
-            [TypeNode, dict[typing.TypeVar, TSType] | None], TSType
-        ],
-    ) -> None:
-        self._translate = translate
+    DEFAULT_PRIORITY = -10
+    ID = "typesync.FlaskTranslator"
 
     def translate(
         self, node: TypeNode, generics: dict[typing.TypeVar, TSType] | None

typesync/type_translators/type_node.py

@@ -17,6 +17,7 @@ class TypeNode:
     args: tuple["TypeNode", ...]
     hints: dict[str, "TypeNode"]
     value: "TypeNode | None"
+    annotation: typing.Any
 
     def __repr__(self) -> str:
         s = f"<TypeNode {getattr(self.origin, '__name__', self.origin)}"
@@ -28,6 +29,8 @@ class TypeNode:
             s += f" hints={self.hints}"
         if self.value is not None:
             s += f" value={self.value}"
+        if self.annotation is not None:
+            s += f" annotation={self.annotation}"
         return s + ">"
 
 
@@ -37,9 +40,17 @@ def to_type_node(
     mapping = {} if mapping is None else mapping
     origin = typing.get_origin(type_) or type_
     params: tuple[typing.TypeVar, ...] = getattr(origin, "__type_params__", ())
-    args = tuple(
-        to_type_node(arg, original_type, mapping) for arg in typing.get_args(type_)
-    )
+    args = ()
+    annotations = ()
+    if origin is not typing.Annotated:
+        args = tuple(
+            to_type_node(arg, original_type, mapping) for arg in typing.get_args(type_)
+        )
+    else:
+        base_args = typing.get_args(type_)
+        if len(base_args) > 0:
+            args = (to_type_node(base_args[0], original_type, mapping),)
+            annotations = base_args[1:]
     hints = {
         key: to_type_node(hint, original_type, mapping)
         for key, hint in getattr(origin, "__annotations__", {}).items()
@@ -61,11 +72,12 @@ def to_type_node(
         ):
             origin = RecursiveCall
 
-    return TypeNode(
+    node = TypeNode(
         origin=origin,
         params=params,
         args=args,
         hints=hints,
+        annotation=annotations[0] if len(annotations) else None,
         value=(
             to_type_node(
                 origin.__value__,
@@ -75,6 +87,7 @@ def to_type_node(
                     args=patched_args,
                     hints=hints,
                     value=None,
+                    annotation=(),
                 ),
                 mapping=mapping,
             )
@@ -82,3 +95,14 @@ def to_type_node(
             else None
         ),
     )
+    for annotation in annotations[1:]:
+        new_node = TypeNode(
+            origin=typing.Annotated,
+            params=params,
+            args=(node,),
+            hints={},
+            annotation=annotation,
+            value=None,
+        )
+        node = new_node
+    return node

{typesync-0.0.1a1.dist-info → typesync-0.0.1a2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typesync
-Version: 0.0.1a1
+Version: 0.0.1a2
 Summary: Auto-generate TypeScript client code from Flask routes and Python type annotations.
 Author-email: Francisco Rodrigues <francisco.rodrigues0908@gmail.com>
 Project-URL: Homepage, https://github.com/ArmindoFlores/typesync
@@ -11,6 +11,7 @@ License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: flask
 Requires-Dist: inflection>=0.5.1
+Requires-Dist: prettytable>=3.17.0
 Dynamic: license-file
 
 # Typesync
@@ -36,9 +37,9 @@ Some features are already implemented, others are planned.
 - [x] Support for multiple HTTP methods (GET, POST, PUT, DELETE, etc.)
 - [x] Support for JSON request bodies with typed parameters
     - [ ] Support validators such as pydantic
-- [ ] Support for `typing.Annotated` to:
+- [x] Support for `typing.Annotated` to:
     - [ ] Ignore specific routes
-    - [ ] Customize generation behavior (naming, visibility, etc.)
+    - [x] Customize generation behavior (naming, visibility, etc.)
 - [ ] Improved error reporting for unsupported or ambiguous annotations
 - [ ] Optional generation modes (types only, requests only)
 - [ ] Configuration file support
@@ -52,9 +53,7 @@ Some features are already implemented, others are planned.
 
 ## Installation
 
-The project is not yet published on PyPI. Installation is currently done directly from source, preferably using `uv`.
-
-Clone the repository and install dependencies:
+You can install typesync using `pip install typesync`. Alternatively, you can do it directly from source, preferably using `uv`, by cloning the repository and installing dependencies:
 
 ```bash
 git clone https://github.com/ArmindoFlores/typesync

typesync-0.0.1a2.dist-info/RECORD

@@ -0,0 +1,23 @@
+typesync/__init__.py,sha256=cxlYkEhU2kEV8AB0elVJoS45IZkQ7FF-8el_NuY7c6o,267
+typesync/annotations.py,sha256=ZGy_kcuXZMYV-Zv9CKcMJNH4y6fDpMS3BsnVvEedaAk,1135
+typesync/argument_types.py,sha256=x_2kYlMq2fH7B_8wwmpWa_tcduU76fJmKlMH1s9txKQ,3687
+typesync/cli.py,sha256=GdNDQYHBZ6lAbtYwMLFAZDdWIr73hbUmEA4TDY0beo8,5435
+typesync/misc.py,sha256=ye2FQJC7cBU6RtEgGjMkZUXRAHGPOrQIYXwcuDVoNo0,182
+typesync/ts_types.py,sha256=A5mJElZg7RyM58x9HGO9_XzXb9pznEPMDfO1yRUUzE8,3448
+typesync/utils.py,sha256=0Mp8D9eLz12MJb5a3u2x0hqUffiLK-OUBpUhP4LuXv0,2131
+typesync/codegen/__init__.py,sha256=mS7UpHXh6pQdRyXN3-KvRL0DgAulTE9hRDnqIvl6zQ8,132
+typesync/codegen/extractor.py,sha256=Ho9hk2FnegNccXw3TN0-qmTdPNxMjg5blXXwwmyYsCA,10056
+typesync/codegen/inference.py,sha256=U7t3a6LJldQPvpChOAtFffL0Tu2jB0063G3E4C81rbE,8320
+typesync/codegen/writer.py,sha256=T_eliJ3d0Iu9B9bw3PmnsPajTN1sDOTag_t9-LKkuio,8500
+typesync/type_translators/__init__.py,sha256=ugOt2XsDXc0B-Sp5HjbApZyyCmbAW4SKHKb2B6nCfz4,436
+typesync/type_translators/abstract.py,sha256=WvMNcIMnzwy12eObck00GFklsMbr6bkPv1odQzkLCA4,652
+typesync/type_translators/annotations_translator.py,sha256=LOFFBCK1-bIgscrtM7vVIaLFyM30fKC8CgUBf6_3AJE,1416
+typesync/type_translators/base_translator.py,sha256=FSEt2mshN6QdUude65PvNfKgueRH6v2npLxNTlGSajk,5122
+typesync/type_translators/context.py,sha256=qbffuT5UAmCbkN7KFzUPkYijQiuFl4PCCcv3uv1XpMc,343
+typesync/type_translators/flask_translator.py,sha256=8CSg1VdszkfSksSDHEnXARHugExaov52hopqLhOzhEE,552
+typesync/type_translators/type_node.py,sha256=ef02XyeHFn5EXJ59DYaQ8zA_MAfpoI1_1mF-CFHm1iM,3217
+typesync-0.0.1a2.dist-info/licenses/LICENSE,sha256=7MsKRg4kFMMFoz-h2zVg6sZ1rxQU6HuvrECEz1evDAY,1059
+typesync-0.0.1a2.dist-info/METADATA,sha256=jFoeoDYgxLMEAKN7quyj9TjDj9TPIHjEV6ScS844IL0,4376
+typesync-0.0.1a2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+typesync-0.0.1a2.dist-info/top_level.txt,sha256=clLTcTcqWa7iQrgM1b_v3GHC1Z7W1uqiLUzXeGInWRs,9
+typesync-0.0.1a2.dist-info/RECORD,,

typesync-0.0.1a1.dist-info/RECORD

@@ -1,18 +0,0 @@
-typesync/__init__.py,sha256=KhtqS2tUcczOFAMQIkuQdRi7bBY21IuwcMeR5V45g6g,222
-typesync/cli.py,sha256=ATa0O1Gr2q9j1MxfmcBrIWij6-6iiAkIW1OC5mQLKM0,3655
-typesync/ts_types.py,sha256=A5mJElZg7RyM58x9HGO9_XzXb9pznEPMDfO1yRUUzE8,3448
-typesync/utils.py,sha256=0Mp8D9eLz12MJb5a3u2x0hqUffiLK-OUBpUhP4LuXv0,2131
-typesync/codegen/__init__.py,sha256=TD41Nti-hXO7xJi9HHr4QTFKIY4Wv_3QJtLSl718lpw,142
-typesync/codegen/extractor.py,sha256=HK8-FbmO-memDtZEbNsV3ukuBo2oC7GD9lspFZgYL3M,7938
-typesync/codegen/inference.py,sha256=JZcictBq_jDGW6bJycQi53oQtJkkNBdk5cDp2WYXj60,7934
-typesync/codegen/writer.py,sha256=a8mE3cdKmpBmXLnqM0IkpXwZlRc713E_AzQtTHnaEmY,7051
-typesync/type_translators/__init__.py,sha256=mNpgJLMZW_p_7bp3l23gZ6BUrqSt_mrjXJixhOKZzeI,283
-typesync/type_translators/abstract.py,sha256=nTg6sjJCxXGJD5hW9FAtgel8ZUWJPNgD6y7q7xUy54o,496
-typesync/type_translators/base_translator.py,sha256=wD9PUkBLJP8gz5l5WoelP2m3evJyXgQrdUocUgT628Q,4976
-typesync/type_translators/flask_translator.py,sha256=PezojREhL9GShJn4cXHrmoxs3Rrsgpk0miopqUB3nzQ,687
-typesync/type_translators/type_node.py,sha256=wF60KWXuXtNExq_ZlcxHj99rEnIw0VyxtNGhSW6Vhrk,2428
-typesync-0.0.1a1.dist-info/licenses/LICENSE,sha256=7MsKRg4kFMMFoz-h2zVg6sZ1rxQU6HuvrECEz1evDAY,1059
-typesync-0.0.1a1.dist-info/METADATA,sha256=MPEuQMs0m8NUKDUATdI9IlNOHzLvxCNAV0sR8MQHcaw,4323
-typesync-0.0.1a1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-typesync-0.0.1a1.dist-info/top_level.txt,sha256=clLTcTcqWa7iQrgM1b_v3GHC1Z7W1uqiLUzXeGInWRs,9
-typesync-0.0.1a1.dist-info/RECORD,,