pytsast 0.1.6

Python TypeScript AST Generator - Create TypeScript code from Python

pytsast - Python TypeScript AST Generator

Generate TypeScript code from Python using TypeScript's AST factory API.

This library provides a Python interface to TypeScript's AST factory functions, allowing you to build TypeScript AST nodes programmatically and serialize them to JSON for consumption by TypeScript parsers like @pyts/tsparser.

Installation

pip install pytsast

Usage

Basic Example

from pytsast import factory as ts

# Create a simple identifier
identifier = ts.createIdentifier("myVariable")

# Serialize to JSON
json_output = identifier.serialize()
print(json_output.model_dump_json(indent=2))

Creating Complex Structures

from pytsast import factory as ts

# Create an import declaration
import_decl = ts.createImportDeclaration(
    None,
    ts.createImportClause(
        None,
        ts.createIdentifier("zod"),
        ts.createNamedImports([
            ts.createImportSpecifier(
                False, None, ts.createIdentifier("output")
            )
        ]),
    ),
    ts.createStringLiteral("zod"),
    None,
)

# Create a function declaration
func_decl = ts.createFunctionDeclaration(
    None,
    None,
    ts.createIdentifier("greet"),
    None,
    [
        ts.createParameterDeclaration(
            None, None, ts.createIdentifier("name"), None,
            ts.createTypeReferenceNode(ts.createIdentifier("string"), None), None
        )
    ],
    ts.createTypeReferenceNode(ts.createIdentifier("string"), None),
    ts.createBlock([
        ts.createReturnStatement(
            ts.createBinaryExpression(
                ts.createStringLiteral("Hello, "),
                ts.createToken(ts.SyntaxKind.PlusToken),
                ts.createIdentifier("name")
            )
        )
    ], True)
)

# Serialize both
print("Import:", import_decl.serialize().model_dump_json())
print("Function:", func_decl.serialize().model_dump_json())

Low-Level Node Creation

from pytsast.core import Node
from pytsast.nodes.misc import Parameter

# Create nodes directly
param = Parameter(
    decorators=None,
    modifiers=None,
    dot_dot_dot_token=None,
    name=ts.createIdentifier("arg"),
    question_token=None,
    type_annotation=ts.createTypeReferenceNode(ts.createIdentifier("number"), None),
    initializer=None
)

API

Factory Functions

The factory module mirrors TypeScript's ts.factory API:

• createIdentifier(text: str) - Create identifier node
• createStringLiteral(text: str) - Create string literal
• createNumericLiteral(value: str | int | float) - Create numeric literal
• createImportDeclaration(decorators, modifiers, import_clause, module_specifier, assert_clause) - Create import statement
• createFunctionDeclaration(decorators, modifiers, asterisk_token, name, type_parameters, parameters, type, body) - Create function declaration
• createClassDeclaration(decorators, modifiers, name, type_parameters, heritage_clauses, members) - Create class declaration
• createVariableStatement(modifiers, declaration_list) - Create variable statement
• createTypeAliasDeclaration(modifiers, name, type_parameters, type) - Create type alias
• And many more...

Core Classes

• Node - Base AST node class with serialization
• SyntaxKind - Enum of TypeScript syntax kinds
• NodeFlags - Node flags enum

Node Types

• Statement - Base for statements (function declarations, etc.)
• Expression - Base for expressions (identifiers, literals, etc.)
• Declaration - Base for declarations
• TypeNode - Base for type annotations

Serialization Format

Nodes serialize to JSON objects that can be consumed by TypeScript parsers:

{
  "type": "factory",
  "name": "createIdentifier",
  "args": [
    {
      "type": "literal",
      "value": "myVariable"
    }
  ]
}

Node Types

• literal: { "type": "literal", "value": null | boolean | string }
• number: { "type": "number", "value": number | string }
• undefined: { "type": "undefined" }
• factory: { "type": "factory", "name": string, "args": SerializedNode[] }

Integration with tsparser

pytsast is designed to work with @pyts/tsparser to generate actual TypeScript code:

# Python side (pytsast)
from pytsast import factory as ts
import json

node = ts.createIdentifier("hello")
json_str = json.dumps(node.serialize().model_dump())

# Send json_str to TypeScript side

// TypeScript side (@pyts/tsparser)
import { parseAndPrint } from '@pyts/tsparser';

const jsonFromPython = '...'; // JSON from Python
const tsCode = parseAndPrint(jsonFromPython);
console.log(tsCode); // hello

Complete Example

# Python: Generate a complete TypeScript interface
from pytsast import factory as ts
import json

interface = ts.createInterfaceDeclaration(
    None,  # decorators
    None,  # modifiers
    ts.createIdentifier("User"),
    None,  # type parameters
    None,  # heritage clauses
    [
        ts.createPropertySignature(
            None,  # modifiers
            ts.createIdentifier("id"),
            None,  # question token
            ts.createTypeReferenceNode(ts.createIdentifier("number"), None)
        ),
        ts.createPropertySignature(
            None,
            ts.createIdentifier("name"),
            None,
            ts.createTypeReferenceNode(ts.createIdentifier("string"), None)
        )
    ]
)

json_output = json.dumps(interface.serialize().model_dump(), indent=2)
print(json_output)

// TypeScript: Parse and generate code
import { parseAndPrint } from '@pyts/tsparser';

const jsonFromPython = `...`; // The JSON above
const tsCode = parseAndPrint(jsonFromPython);
console.log(tsCode);
// Output:
// interface User {
//     id: number;
//     name: string;
// }

Architecture

• pytsast/core/ - Base types, serialization, and syntax kinds
• pytsast/nodes/ - AST node definitions and implementations
• pytsast/factory.py - Factory functions (mirrors ts.factory)