TypeScript2Python

2.2.0 verified Fri May 01 auth: no javascript

TypeScript2Python is a transpiler that converts TypeScript type declarations into Python type annotations compatible with Pyright and TypedDict. The current stable version is 2.2.0. It is actively maintained with regular releases. Key differentiators include support for nested objects, optional properties, docstrings, and strict null checks. It is designed for serializable data (JSON) and does not support generics or function signatures.

Common errors

error Error: Cannot find module 'typescript2python' when using require() ↓

cause The package is ESM-only since v2.0, not compatible with CommonJS require.

fix

Use dynamic import: const { transform } = await import('typescript2python');

error TypeError: transform is not a function ↓

cause Using default import instead of named import.

fix

Use import { transform } from 'typescript2python';

error TranspilationError: Unsupported syntax: Generic type 'Foo<T>' ↓

cause Generics are not supported by the transpiler.

fix

Remove generics or replace with concrete types before transpilation.

Warnings

breaking In v2.0, the package switched from CommonJS to ESM. require() calls will throw an error. ↓

fix Use import statements or dynamic import() for CJS codebases.

deprecated The CLI option '--nullable-optionals' is deprecated in favor of '--nullable-optionals' (typo fixed in v2.2.0). ↓

fix Use '--nullable-optionals' (correct spelling) in v2.2.0+.

gotcha The transform function does not handle generics, function signatures, or complex conditional types. Use only for serializable data. ↓

fix Pre-process your TypeScript types to remove unsupported constructs before passing to the transformer.

gotcha Empty string keys in objects are silently transformed into functional typed dict definitions before v2.1.1, which may cause runtime errors in Python. ↓

fix Update to v2.1.1+ where empty string keys are no longer transpiled.

Install

npm install typescript2python

yarn add typescript2python

pnpm add typescript2python

Imports

TransformConfig

wrong

const TransformConfig = require('typescript2python').TransformConfig

correct

import { TransformConfig } from 'typescript2python'

ESM-only since v2.0; CJS require will fail. Use dynamic import() if needed.

TransformResult
wrong
```
import TransformResult from 'typescript2python'
```
correct
```
import { TransformResult } from 'typescript2python'
```
Named export, not default. TypeScript users may also import type TransformResult.

transform

wrong

import * as t2p from 'typescript2python'; t2p.transform()

correct

import { transform } from 'typescript2python'

Direct named export. The default export does not exist.

TransformerError
```
import { TransformerError } from 'typescript2python'
```
Used for error handling. No common mistake.

Quickstart

How to use the transform function to convert TypeScript type declarations to Python TypedDict classes.

import { transform } from 'typescript2python';

const tsCode = `
export type Person = {
  name: string;
  age?: number;
}`;

const result = transform(tsCode, { filename: 'types.ts' });
console.log(result.code);
// Output:
// from typing_extensions import NotRequired, TypedDict
// class Person(TypedDict):
//   name: str
//   age: NotRequired[float]