typesync 0.0.1a1__tar.gz → 0.0.1a2__tar.gz

{typesync-0.0.1a1 → typesync-0.0.1a2}/PKG-INFO

@@ -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.1a1 → typesync-0.0.1a2}/README.md

@@ -21,9 +21,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
@@ -37,9 +37,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.1a1 → typesync-0.0.1a2}/pyproject.toml

@@ -1,5 +1,5 @@
 [project]
-version = "0.0.1a1"
+version = "0.0.1a2"
 name = "typesync"
 description = "Auto-generate TypeScript client code from Flask routes and Python type annotations."
 readme = "README.md"
@@ -8,6 +8,7 @@ dependencies = [
   "click",
   "flask",
   "inflection>=0.5.1",
+  "prettytable>=3.17.0",
 ]
 requires-python = ">= 3.12"
 authors = [
@@ -36,6 +37,12 @@ dev = [
     "ruff>=0.14.13",
 ]
 
+[tool.ty.rules]
+invalid-type-form = "ignore"
+
+[tool.ty.src]
+exclude = ["tests"]
+
 [tool.ruff.lint]
 extend-select = [
   "E",      # pycodestyle (errors)

{typesync-0.0.1a1 → typesync-0.0.1a2}/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-0.0.1a2/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-0.0.1a2/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-0.0.1a1 → typesync-0.0.1a2}/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-0.0.1a2/typesync/codegen/__init__.py

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