TypeScript2Python

This project implements a transpiler for creating pyright compatible type declarations automatically from TypeScript code! This is useful in a number of scenarios. For example:

• Automatic generation of type-safe APIs between Node.js and Python services
• Safely use JSON objects created by TypeScript projects in Python
• A nice way to write complex Python types using TypeScript

export type Foo = {
    type: "foo"
    foo: number[]
    optional?: string
}

/** DocStrings are supported! */
export type Bar = {
    type: "bar"
    bar: string
    /** nested objects need extra declarations in Python */
    nested: { 
        foo: Foo
    }
}

export type FooBarMap = { 
    [key: string]: Foo | Bar
}

export type TupleType = [string, Foo | Bar, any[]]

from typing_extensions import Any, Dict, List, Literal, NotRequired, Optional, Tuple, TypedDict, Union

class Foo(TypedDict):
  type: Literal["foo"]
  foo: List[float]
  optional: NotRequired[Optional[str]]

class Ts2PyHelperType1(TypedDict):
  foo: Foo

class Bar(TypedDict):
  """
  DocStrings are supported!
  """
  type: Literal["bar"]
  bar: str
  nested: Ts2PyHelperType1
  """
  nested objects need extra declarations in Python
  """

FooBarMap = Dict[str,Union[Foo,Bar]]

TupleType = Tuple[str,Union[Foo,Bar],List[Any]]

The easiest way to use TypeScript2Python, is to invoke it directly using npx and pointing it to one (or multiple) source files that export type declarations.

npx typescript2python <path to typescript source>

It will then output the transpiled code to the terminal. To save the output as a python file, simply pipe the result to the desired destination. For example npx typescript2python types.ts > types.py.

TypeScript2Python supports many of TypeScripts type constructs, including:

• Basic types, like boolean, number, string, undefined
• Literal types, e.g. type X = 42, type Y = 'test'
• Object types, { foo: string }
• Unions, string | number
• Arrays, boolean[]
• Nested objects { bar: { foo: string } }, that will get transpiled into helper dictionaries
• Optional properties { optional?: number }, that get transpiled to NotRequired[Optional[...]] attributes
• Docstrings /** this is very useful */

We currently do not support the following features:

• Generics, as they cannot be fully supported by Python
• Function signatures, as we restrict ourselves top serializable data
• Values, as this is an extremely difficult problem and we currently only attempt to transpile types