Bugfixes, black formatting, updated the --module argument to accept a filepath as well as a module path, and added comprehensive tests

Author: phillipdupuis

README.md

@@ -1,5 +1,7 @@
 # pydantic-to-typescript
 
+[![PyPI version](https://badge.fury.io/py/pydantic-to-typescript.svg)](https://badge.fury.io/py/pydantic-to-typescript)
+
 A simple CLI tool for converting pydantic models into typescript interfaces. Useful for any scenario in which python and javascript applications are interacting, since it allows you to have a single source of truth for type definitions.
 
 This tool requires that you have the lovely json2ts CLI utility installed. Instructions can be found here: https://www.npmjs.com/package/json-schema-to-typescript
@@ -13,7 +15,7 @@ $ pip install pydantic-to-typescript
 
 |Prop|Description|
 |:----------|:-----------|
-|‑‑module|name of the python module you would like to convert. All the pydantic models within it will be converted to typescript interfaces. Discoverable submodules will also be checked. Ex: 'pydantic2ts.examples.pydantic_models'|
+|‑‑module|name or filepath of the python module you would like to convert. All the pydantic models within it will be converted to typescript interfaces. Discoverable submodules will also be checked.|
 |‑‑output|name of the file the typescript definitions should be written to. Ex: './frontend/apiTypes.ts'|
 |‑‑json2ts‑cmd|optional, the command used to invoke json2ts. The default is 'json2ts'. Specify this if you have it installed in a strange location and need to provide the exact path (ex: /myproject/node_modules/bin/json2ts)|
 ---
@@ -44,10 +46,21 @@ def login(body: LoginCredentials):
     profile = Profile(**body.dict(), age=72, hobbies=['cats'])
     return LoginResponseData(token='very-secure', profile=profile)
 ```
-Execute the command for converting these models into typescript definitions:
+Execute the command for converting these models into typescript definitions, via:
 ```bash
 $ pydantic2ts --module backend.api --output ./frontend/apiTypes.ts
 ```
+or:
+```bash
+$ pydantic2ts --module ./backend/api.py --output ./frontend/apiTypes.ts
+```
+or:
+```python
+from pydantic2ts import generate_typescript_defs
+
+generate_typescript_defs("backend.api", "./frontend/apiTypes.ts")
+```
+
 The models are now defined in typescript...
 ```ts
 /* tslint:disable */
@@ -91,4 +104,4 @@ async function login(
     reject(error.message);
   }
 }
-```
+```

pydantic2ts/__init__.py

@@ -0,0 +1 @@
+from pydantic2ts.cli.script import generate_typescript_defs

pydantic2ts/cli/script.py

@@ -1,44 +1,76 @@
-import click
-import inspect
 import importlib
+import inspect
+import json
+import logging
 import os
 import shutil
-from pydantic import BaseModel, Extra, create_model
+import sys
+from importlib.util import spec_from_file_location, module_from_spec
 from tempfile import mkdtemp
-from typing import Type, Dict, Any, List
 from types import ModuleType
+from typing import Type, Dict, Any, List
+from uuid import uuid4
 
+import click
+from pydantic import BaseModel, Extra, create_model
 
-def clean_schema(schema: Dict[str, Any], model: Type[BaseModel]) -> None:
-    """
-    Monkey-patched method for cleaning up resulting JSON schemas by:
+try:
+    from pydantic.generics import GenericModel
+except ImportError:
+    GenericModel = None
 
-    1) Removing titles from JSON schema properties.
-       If we don't do this, each property will have its own interface in the
-       resulting typescript file (which is a LOT of unnecessary noise).
-    2) Setting 'additionalProperties' to False UNLESS Config.extra is explicitly
-       set to "allow". This keeps the typescript interfaces clean (ie useful).
-    """
-    for prop in schema.get('properties', {}).values():
-        prop.pop('title', None)
+logging.basicConfig(level=logging.DEBUG, format="%(asctime)s %(message)s")
 
-    if model.Config.extra != Extra.allow:
-        schema['additionalProperties'] = False
+logger = logging.getLogger("pydantic2ts")
 
 
-def not_private(obj) -> bool:
-    """Return true if an object does not seem to be private"""
-    return not getattr(obj, '__name__', '').startswith('_')
+def import_module(path: str) -> ModuleType:
+    """
+    Helper which allows modules to be specified by either dotted path notation or by filepath.
+
+    If we import by filepath, we must also assign a name to it and add it to sys.modules BEFORE
+    calling 'spec.loader.exec_module' because there is code in pydantic which requires that the
+    definition exist in sys.modules under that name.
+    """
+    try:
+        if os.path.exists(path):
+            name = uuid4().hex
+            spec = spec_from_file_location(name, path, submodule_search_locations=[])
+            module = module_from_spec(spec)
+            sys.modules[name] = module
+            spec.loader.exec_module(module)
+            return module
+        else:
+            return importlib.import_module(path)
+    except BaseException as e:
+        logger.error(
+            "The --module argument must be a module path separated by dots or a valid filepath"
+        )
+        raise e
 
 
 def is_submodule(obj, module_name: str) -> bool:
-    """Return true if an object is a submodule"""
-    return not_private(obj) and inspect.ismodule(obj) and getattr(obj, '__name__', '').startswith(f'{module_name}.')
+    """
+    Return true if an object is a submodule
+    """
+    return inspect.ismodule(obj) and getattr(obj, "__name__", "").startswith(
+        f"{module_name}."
+    )
 
 
-def is_pydantic_model(obj) -> bool:
-    """Return true if an object is a subclass of pydantic's BaseModel"""
-    return not_private(obj) and inspect.isclass(obj) and issubclass(obj, BaseModel) and obj != BaseModel
+def is_concrete_pydantic_model(obj) -> bool:
+    """
+    Return true if an object is a concrete subclass of pydantic's BaseModel.
+    'concrete' meaning that it's not a GenericModel.
+    """
+    if not inspect.isclass(obj):
+        return False
+    elif obj is BaseModel:
+        return False
+    elif GenericModel and issubclass(obj, GenericModel):
+        return bool(obj.__concrete__)
+    else:
+        return issubclass(obj, BaseModel)
 
 
 def extract_pydantic_models(module: ModuleType) -> List[Type[BaseModel]]:
@@ -48,10 +80,12 @@ def extract_pydantic_models(module: ModuleType) -> List[Type[BaseModel]]:
     models = []
     module_name = module.__name__
 
-    for _, model in inspect.getmembers(module, is_pydantic_model):
+    for _, model in inspect.getmembers(module, is_concrete_pydantic_model):
         models.append(model)
 
-    for _, submodule in inspect.getmembers(module, lambda obj: is_submodule(obj, module_name)):
+    for _, submodule in inspect.getmembers(
+        module, lambda obj: is_submodule(obj, module_name)
+    ):
         models.extend(extract_pydantic_models(submodule))
 
     return models
@@ -63,30 +97,73 @@ def remove_master_model_from_output(output: str) -> None:
     clean typescript definitions without any duplicates, but we don't actually want it in the
     output. This function handles removing it from the generated typescript file.
     """
-    with open(output, 'r') as f:
+    with open(output, "r") as f:
         lines = f.readlines()
 
     start, end = None, None
     for i, line in enumerate(lines):
-        if line.rstrip('\r\n') == 'export interface _Master_ {':
+        if line.rstrip("\r\n") == "export interface _Master_ {":
             start = i
-        elif (start is not None) and line.rstrip('\r\n') == '}':
+        elif (start is not None) and line.rstrip("\r\n") == "}":
             end = i
             break
 
-    new_lines = lines[:start] + lines[(end + 1):]
-    with open(output, 'w') as f:
+    new_lines = lines[:start] + lines[(end + 1) :]
+    with open(output, "w") as f:
         f.writelines(new_lines)
 
 
-@click.command()
-@click.option('--module')
-@click.option('--output')
-@click.option('--json2ts-cmd', default='json2ts')
-def main(
-    module: str,
-    output: str,
-    json2ts_cmd: str = 'json2ts',
+def clean_schema(schema: Dict[str, Any]) -> None:
+    """
+    Clean up the resulting JSON schemas by:
+
+    1) Removing titles from JSON schema properties.
+       If we don't do this, each property will have its own interface in the
+       resulting typescript file (which is a LOT of unnecessary noise).
+    2) Getting rid of the useless "An enumeration." description applied to Enums
+       which don't have a docstring.
+    """
+    for prop in schema.get("properties", {}).values():
+        prop.pop("title", None)
+
+    if "enum" in schema and schema.get("description") == "An enumeration.":
+        del schema["description"]
+
+
+def generate_json_schema(models: List[Type[BaseModel]]) -> str:
+    """
+    Create a top-level '_Master_' model with references to each of the actual models.
+    Generate the schema for this model, which will include the schemas for all the
+    nested models. Then clean up the schema.
+
+    One weird thing we do is we temporarily override the 'extra' setting in models,
+    changing it to 'forbid' UNLESS it was explicitly set to 'allow'. This prevents
+    '[k: string]: any' from being added to every interface. This change is reverted
+    once the schema has been generated.
+    """
+    model_extras = [m.Config.extra for m in models]
+
+    for m in models:
+        if m.Config.extra != Extra.allow:
+            m.Config.extra = Extra.forbid
+
+    master_model = create_model("_Master_", **{m.__name__: (m, ...) for m in models})
+    master_model.Config.extra = Extra.forbid
+    master_model.Config.schema_extra = staticmethod(clean_schema)
+
+    schema = json.loads(master_model.schema_json())
+
+    for d in schema.get("definitions", {}).values():
+        clean_schema(d)
+
+    for m, x in zip(models, model_extras):
+        m.Config.extra = x
+
+    return json.dumps(schema, indent=2)
+
+
+def generate_typescript_defs(
+    module: str, output: str, json2ts_cmd: str = "json2ts"
 ) -> None:
     """
     Convert the pydantic models in a python module into typescript interfaces.
@@ -96,35 +173,54 @@ def main(
     :param json2ts_cmd: optional, the command that will execute json2ts. Use this if it's installed in a strange spot.
     """
     if not shutil.which(json2ts_cmd):
-        raise Exception('json2ts must be installed. Instructions can be found here: '
-                        'https://www.npmjs.com/package/json-schema-to-typescript')
+        raise Exception(
+            "json2ts must be installed. Instructions can be found here: "
+            "https://www.npmjs.com/package/json-schema-to-typescript"
+        )
 
-    models = extract_pydantic_models(importlib.import_module(module))
+    logger.info("Finding pydantic models...")
 
-    for m in models:
-        m.Config.schema_extra = staticmethod(clean_schema)
+    models = extract_pydantic_models(import_module(module))
 
-    master_model = create_model('_Master_', **{m.__name__: (m, ...) for m in models})
-    master_model.Config.schema_extra = staticmethod(clean_schema)
+    logger.info("Generating JSON schema from pydantic models...")
 
+    schema = generate_json_schema(models)
     schema_dir = mkdtemp()
-    schema_file_path = os.path.join(schema_dir, 'schema.json')
+    schema_file_path = os.path.join(schema_dir, "schema.json")
+
+    with open(schema_file_path, "w") as f:
+        f.write(schema)
+
+    logger.info("Converting JSON schema to typescript definitions...")
+
+    banner_comment = "\n".join(
+        [
+            "/* tslint:disable */",
+            "/**",
+            "/* This file was automatically generated from pydantic models by running pydantic2ts.",
+            "/* Do not modify it by hand - just update the pydantic models and then re-run the script",
+            "*/",
+        ]
+    )
+    os.system(
+        f'{json2ts_cmd} -i {schema_file_path} -o {output} --bannerComment "{banner_comment}"'
+    )
+    shutil.rmtree(schema_dir)
+    remove_master_model_from_output(output)
 
-    with open(schema_file_path, 'w') as f:
-        f.write(master_model.schema_json(indent=2))
+    logger.info(f"Saved typescript definitions to {output}.")
 
-    banner_comment = '\n'.join([
-        '/* tslint:disable */',
-        '/**',
-        '/* This file was automatically generated from pydantic models by running pydantic2ts.',
-        '/* Do not modify it by hand - just update the pydantic models and then re-run the script',
-        '*/',
-    ])
 
-    os.system(f'{json2ts_cmd} -i {schema_file_path} -o {output} --bannerComment "{banner_comment}"')
-    shutil.rmtree(schema_dir)
-    remove_master_model_from_output(output)
+@click.command()
+@click.option("--module")
+@click.option("--output")
+@click.option("--json2ts-cmd", default="json2ts")
+def main(module: str, output: str, json2ts_cmd: str = "json2ts") -> None:
+    """
+    CLI entrypoint to run :func:`generate_typescript_defs`
+    """
+    return generate_typescript_defs(module, output, json2ts_cmd)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()