repository·master·Indexed 19 days ago
https://github.com/phillipdupuis/pydantic-to-typescriptA CLI tool and Python API that converts Pydantic models (V1 and V2) into TypeScript interfaces. It utilizes the json-schema-to-typescript (json2ts) utility to generate type definitions, allowing for a single source of truth between Python and JavaScript applications.
Install the package via pip. Note that this tool requires the json2ts CLI utility (from the json-schema-to-typescript npm package) to be installed on your system to function correctly.
$ pip install pydantic-to-typescriptIf you are using Pydantic version 2 or higher and encounter issues, ensure you are using pydantic-to-typescript version 2 or later. You can upgrade using pip or update your project requirements.
$ pip install 'pydantic-to-typescript>2'Once the conversion is complete, the resulting TypeScript file contains exported interfaces that match your Pydantic models. You can import these directly into your TypeScript/JavaScript application to ensure type safety when interacting with your Python backend.
import { LoginCredentials, LoginResponseData } from "./apiTypes.ts";
async function login(
credentials: LoginCredentials,
resolve: (data: LoginResponseData) => void,
reject: (error: string) => void
) {
try {
const response: Response = await fetch("/login/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(credentials),
});
const data: LoginResponseData = await response.json();
resolve(data);
} catch (error) {
reject(error.message);
}
}You can convert models using either the Python module dot-notation or a direct file path to the .py file.
# Using module notation
$ pydantic2ts --module backend.api --output ./frontend/apiTypes.ts
# Using file path
$ pydantic2ts --module ./backend/api.py --output ./frontend/apiTypes.tsIf you need to trigger the conversion programmatically within your Python code, use the generate_typescript_defs function.
from pydantic2ts import generate_typescript_defs
generate_typescript_defs("backend.api", "./frontend/apiTypes.ts")The pydantic2ts command-line interface allows you to convert Pydantic models from a Python module into TypeScript interfaces. Use the following flags to configure the conversion:
| Prop | Description |
| :--- | :--- |
| `--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` |
| `--exclude` | name of a pydantic model which should be omitted from the resulting typescript definitions. This option can be defined multiple times, ex: `--exclude Foo --exclude Bar` to exclude both the Foo and Bar models from the output. |
| `--json2ts-cmd` | optional, the command used to invoke json2ts. The default is 'json2ts'. Specify this if you have it installed locally (ex: 'yarn json2ts') or if the exact path to the executable is required (ex: /myproject/node_modules/bin/json2ts) |The following flags are available for the pydantic2ts command:
| Flag | Required | Description |
|---|---|---|
--module | Yes | The name (dotted path) or valid filepath of the Python module containing your Pydantic models. Submodules will be searched recursively. |
--output | Yes | The filename where the generated TypeScript definitions will be written. |
--exclude | No | The name of a Pydantic model to omit from the output. This flag can be used multiple times to exclude multiple models. |
--json2ts-cmd | No | The command used to execute json2ts. Use this if the executable is not in your PATH or is installed locally (e.g., yarn json2ts). Defaults to json2ts. |
pydantic2ts --module my_project.schemas --output ./types/models.ts --exclude ModelA --exclude ModelB --json2ts-cmd "yarn json2ts"The pydantic2ts command-line tool converts Pydantic models (both V1 and V2) from a specified Python module into TypeScript interfaces. It works by generating a JSON schema from your models and then using the json-schema-to-typescript (json2ts) utility to produce the final TypeScript definitions.
Prerequisites
You must have the json-schema-to-typescript package installed and available in your path (e.g., via npm install -g json-schema-to-typescript).
pydantic2ts --module my_project.schemas --output ./types/models.ts