python2ts 1.3.0 → 1.3.2

package/README.md

@@ -1,77 +1,177 @@
 # python2ts
 
+<div align="center">
+
+**Transpile Python to TypeScript — Automatically**
+
 [![npm version](https://img.shields.io/npm/v/python2ts.svg)](https://www.npmjs.com/package/python2ts)
 [![npm downloads](https://img.shields.io/npm/dm/python2ts.svg)](https://www.npmjs.com/package/python2ts)
 [![CI](https://github.com/sebastian-software/python2ts/actions/workflows/ci.yml/badge.svg)](https://github.com/sebastian-software/python2ts/actions/workflows/ci.yml)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/npm/l/python2ts.svg)](https://github.com/sebastian-software/python2ts/blob/main/LICENSE)
 
-**AST-based Python to TypeScript transpiler** — Write Python, ship TypeScript.
+</div>
 
-> Convert Python code to clean, idiomatic TypeScript with full type preservation.
+---
 
-## Quick Start
+Stop rewriting Python code by hand. **python2ts** transforms your Python into clean, idiomatic
+TypeScript — with full type preservation.
+
+## Install
 
 ```bash
-npm install python2ts
+npm install -g python2ts
 ```
 
+## Usage
+
 ```bash
 # Transpile a file
-npx python2ts input.py -o output.ts
+python2ts algorithm.py -o algorithm.ts
+
+# Transpile to stdout
+python2ts script.py
 
 # Pipe from stdin
-cat script.py | npx python2ts > script.ts
+cat utils.py | python2ts > utils.ts
 ```
 
-## Example
+## What It Does
+
+<table>
+<tr>
+<td width="50%">
+
+**Your Python**
 
 ```python
-def fibonacci(n: int) -> list[int]:
-    a, b = 0, 1
-    result = []
-    for _ in range(n):
-        result.append(a)
-        a, b = b, a + b
-    return result
+from dataclasses import dataclass
+from collections import Counter
+
+@dataclass
+class WordStats:
+    text: str
+
+    def word_count(self) -> dict[str, int]:
+        words = self.text.lower().split()
+        return dict(Counter(words))
+
+    def most_common(self, n: int = 5):
+        counts = Counter(self.word_count())
+        return counts.most_common(n)
 ```
 
-Becomes:
+</td>
+<td width="50%">
+
+**Clean TypeScript**
 
 ```typescript
-import { range } from "pythonlib"
-
-function fibonacci(n: number): number[] {
-  let [a, b] = [0, 1]
-  let result: number[] = []
-  for (const _ of range(n)) {
-    result.push(a)
-    ;[a, b] = [b, a + b]
+import { Counter } from "pythonlib/collections"
+
+class WordStats {
+  constructor(public text: string) {}
+
+  wordCount(): Map<string, number> {
+    const words = this.text.toLowerCase().split(/\s+/)
+    return new Map(new Counter(words))
+  }
+
+  mostCommon(n: number = 5) {
+    const counts = new Counter(this.wordCount())
+    return counts.mostCommon(n)
   }
-  return result
 }
 ```
 
-## Documentation
+</td>
+</tr>
+</table>
+
+## Supported Python Features
+
+| Feature                  | Example                       | Output                                        |
+| ------------------------ | ----------------------------- | --------------------------------------------- |
+| **Type hints**           | `def foo(x: int) -> str:`     | `function foo(x: number): string`             |
+| **Dataclasses**          | `@dataclass class Point:`     | `class Point { constructor... }`              |
+| **List comprehensions**  | `[x*2 for x in items]`        | `items.map(x => x * 2)`                       |
+| **Dict comprehensions**  | `{k: v for k, v in pairs}`    | `new Map(pairs.map(...))`                     |
+| **Pattern matching**     | `match x: case 1: ...`        | `switch/if statements`                        |
+| **f-strings**            | `f"Hello {name}!"`            | `` `Hello ${name}!` ``                        |
+| **Async/await**          | `async def fetch():`          | `async function fetch()`                      |
+| **Decorators**           | `@lru_cache def fib(n):`      | Transformed decorators                        |
+| **Context managers**     | `with open(f) as file:`       | `try/finally` blocks                          |
+| **Generators**           | `yield from items`            | `yield* items`                                |
+| **Walrus operator**      | `if (n := len(x)) > 0:`       | `let n; if ((n = len(x)) > 0)`                |
+| **Multiple inheritance** | `class C(A, B):`              | Mixins                                        |
+| **Standard library**     | `from itertools import chain` | `import { chain } from "pythonlib/itertools"` |
+
+## CLI Options
 
-**[📚 View Full Documentation](https://sebastian-software.github.io/python2ts/)**
+```
+Usage: python2ts [options] [file]
+
+Arguments:
+  file                    Python file to transpile (reads from stdin if omitted)
+
+Options:
+  -o, --output <file>     Write output to file instead of stdout
+  -r, --runtime <path>    Custom runtime library path (default: "pythonlib")
+  --no-runtime            Don't add runtime imports
+  -v, --version           Show version number
+  -h, --help              Show help
+```
+
+## Programmatic API
+
+```typescript
+import { transpile } from "python2ts"
+
+const python = `
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+`
+
+const typescript = transpile(python)
+console.log(typescript)
+// function greet(name: string): string {
+//   return `Hello, ${name}!`
+// }
+```
 
-| Resource                                                                       | Description                                 |
-| ------------------------------------------------------------------------------ | ------------------------------------------- |
-| [Homepage](https://sebastian-software.github.io/python2ts/)                    | Project overview, features, and quick start |
-| [Getting Started](https://sebastian-software.github.io/python2ts/docs/)        | Installation and first steps                |
-| [Syntax Reference](https://sebastian-software.github.io/python2ts/docs/syntax) | Python → TypeScript transformation rules    |
-| [Runtime Library](https://sebastian-software.github.io/python2ts/docs/runtime) | Using pythonlib for Python standard library |
-| [API Reference](https://sebastian-software.github.io/python2ts/docs/api)       | Complete API documentation                  |
+## Runtime Library
+
+The transpiled code uses [**pythonlib**](https://www.npmjs.com/package/pythonlib) for Python
+standard library functions. Install it as a dependency in your project:
+
+```bash
+npm install pythonlib
+```
+
+## Documentation
+
+| Resource                                                                       | Description                    |
+| ------------------------------------------------------------------------------ | ------------------------------ |
+| [Homepage](https://sebastian-software.github.io/python2ts/)                    | Project overview and features  |
+| [Getting Started](https://sebastian-software.github.io/python2ts/docs/)        | Installation and first steps   |
+| [Syntax Reference](https://sebastian-software.github.io/python2ts/docs/syntax) | Complete transformation rules  |
+| [API Reference](https://sebastian-software.github.io/python2ts/docs/api)       | Programmatic API documentation |
 
 ## Runtime Support
 
-Tested on every commit: **Node.js** (v22, v24) · **Bun** · **Deno** · **Browsers**
+Transpiled code runs everywhere JavaScript runs:
+
+- **Node.js** (v22, v24)
+- **Bun**
+- **Deno**
+- **Browsers**
+- **Edge** (Cloudflare Workers, AWS Lambda, Vercel)
 
 ## Related
 
 - [**pythonlib**](https://www.npmjs.com/package/pythonlib) — Python standard library for TypeScript
-- [**GitHub**](https://github.com/sebastian-software/python2ts) — Source code and issue tracker
+- [**GitHub**](https://github.com/sebastian-software/python2ts) — Source code, issues, contributions
+  welcome
 
 ## License
 

package/dist/{chunk-LNOL3BMB.js → chunk-RNRRQS6K.js}

@@ -809,7 +809,22 @@ function transformNode(node, ctx) {
 }
 function transformScript(node, ctx) {
   const children = getChildren(node);
-  const statements = children.filter((child) => child.name !== "Comment" || getNodeText(child, ctx.source).trim() !== "").map((child) => {
+  let moduleDocstring = "";
+  let startIndex = 0;
+  const filteredChildren = children.filter(
+    (child) => child.name !== "Comment" || getNodeText(child, ctx.source).trim() !== ""
+  );
+  if (filteredChildren.length > 1) {
+    const firstChild = filteredChildren[0];
+    if (firstChild && isDocstringNode(firstChild, ctx)) {
+      const content = extractDocstringContent(firstChild, ctx);
+      const parsed = parseDocstring(content);
+      const jsdoc = toJSDoc(parsed, "");
+      moduleDocstring = jsdoc.replace(" */", " * @module\n */");
+      startIndex = 1;
+    }
+  }
+  const statements = filteredChildren.slice(startIndex).map((child) => {
     const transformed = transformNode(child, ctx);
     if (transformed === "") {
       return "";
@@ -819,6 +834,9 @@ function transformScript(node, ctx) {
     }
     return transformed;
   }).filter((s) => s.trim() !== "");
+  if (moduleDocstring) {
+    return moduleDocstring + "\n" + statements.join("\n");
+  }
   return statements.join("\n");
 }
 function transformExpressionStatement(node, ctx) {
@@ -1302,9 +1320,26 @@ function transformCallExpression(node, ctx) {
     case "reversed":
       ctx.usesRuntime.add("reversed");
       return `reversed(${args})`;
-    case "isinstance":
+    case "isinstance": {
       ctx.usesRuntime.add("isinstance");
+      if (argList) {
+        const argChildren = getChildren(argList).filter(
+          (c) => c.name !== "(" && c.name !== ")" && c.name !== ","
+        );
+        if (argChildren.length >= 2) {
+          const firstArg = argChildren[0];
+          const secondArg = argChildren[1];
+          if (firstArg && secondArg?.name === "TupleExpression") {
+            const tupleChildren = getChildren(secondArg).filter(
+              (c) => c.name !== "(" && c.name !== ")" && c.name !== ","
+            );
+            const typesCodes = tupleChildren.map((el) => transformNode(el, ctx));
+            return `isinstance(${transformNode(firstArg, ctx)}, [${typesCodes.join(", ")}])`;
+          }
+        }
+      }
       return `isinstance(${args})`;
+    }
     case "type":
       ctx.usesRuntime.add("type");
       return `type(${args})`;
@@ -3673,8 +3708,10 @@ function transformDecoratedStatement(node, ctx) {
     const returnTypeStr = returnType ? `: ${returnType === "null" ? "void" : returnType}` : "";
     return `function ${funcName}(${params})${returnTypeStr}`;
   }
+  const indent = "  ".repeat(ctx.indentLevel);
+  const { jsdoc, skipFirstStatement } = body ? extractDocstringFromBody(body, ctx, indent) : { jsdoc: null, skipFirstStatement: false };
   ctx.insideFunctionBody++;
-  const bodyCode = body ? transformBody(body, ctx, false, paramNames) : "";
+  const bodyCode = body ? transformBody(body, ctx, skipFirstStatement, paramNames) : "";
   ctx.insideFunctionBody--;
   let funcExpr = `function ${funcName}(${params}) {
 ${bodyCode}
@@ -3688,7 +3725,9 @@ ${bodyCode}
       funcExpr = `${dec.name}(${funcExpr})`;
     }
   }
-  return `const ${funcName} = ${funcExpr}`;
+  const declaration = `const ${funcName} = ${funcExpr}`;
+  return jsdoc ? `${jsdoc}
+${declaration}` : declaration;
 }
 function transformDecoratedClass(classDef, decorators, ctx) {
   const dataclassDecorator = decorators.find(

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   transpileAsync
-} from "../chunk-LNOL3BMB.js";
+} from "../chunk-RNRRQS6K.js";
 
 // src/cli/index.ts
 import { parseArgs } from "util";

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   transpile,
   transpileAsync,
   walkTree
-} from "./chunk-LNOL3BMB.js";
+} from "./chunk-RNRRQS6K.js";
 export {
   debugTree,
   formatCode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "python2ts",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "AST-based Python to TypeScript transpiler. Convert Python code to clean, idiomatic TypeScript with full type preservation.",
   "homepage": "https://sebastian-software.github.io/python2ts/",
   "repository": {
@@ -53,7 +53,7 @@
     "eslint": "^9.39.2",
     "prettier": "^3.8.0",
     "typescript-eslint": "^8.53.1",
-    "pythonlib": "2.0.0"
+    "pythonlib": "2.0.2"
   },
   "devDependencies": {
     "tsup": "^8.5.1",