small-python 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ju Lin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# small-python
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run [Small Python](https://github.com/soasme/small-python), a small Python 3.15
+engine written in C, from JavaScript. The engine is compiled to WebAssembly
+and each runtime runs in a Worker thread of its own: code in it sees only the
+functions and modules you give it, cannot touch files, the network, or your
+objects, and can be stopped at any time.
+
+```sh
+npm install small-python
+```
+
+```js
+import { Runtime } from "small-python";
+
+const rt = await Runtime.create({ memoryLimit: 64 << 20, timeout: 5000 });
+await rt.define("fetchUser", async (id) => ({ id, name: "Ada" }));
+console.log(await rt.eval("fetchUser(7)['name'].upper()"));  // ADA
+rt.close();
+```
+
+## Values
+
+Plain data is copied in both directions: `null`, booleans, numbers, bigints,
+strings, `Uint8Array`, arrays, `Set`, `Map`, and plain objects. A Python
+`dict` comes back as a `Map`, an `int` beyond 2⁵³ as a bigint. Functions you
+pass in become Python functions; Python functions, instances, and other values
+come back as `PyObject` proxies whose methods (`get`, `call`, `getItem`, ...)
+return promises.
+
+Host functions are called with positional arguments. Wrap one with
+`keywords(fn)` to receive Python keyword arguments as a final object. They may
+be `async`; the engine waits.
+
+## Limits and safety
+
+| Option | Effect |
+|---|---|
+| `stepLimit` | `RuntimeError` in Python after that many steps per `eval`/`exec` |
+| `memoryLimit` | `MemoryError` in Python beyond that many bytes |
+| `timeout` | terminates the worker after that many milliseconds; rejects with `Timeout` |
+| `messageLimit` | largest value that may cross between JavaScript and Python |
+
+A crash or a trap in the engine ends only its Worker: the operation rejects
+with `WorkerError` and the runtime is closed.
+
+## Platforms
+
+Node.js 20 or later. In browsers the page must be cross-origin isolated
+(COOP and COEP headers), because the worker uses `SharedArrayBuffer`.
+
+The full specification is
+[docs/packaging/javascript.md](https://github.com/soasme/small-python/blob/main/docs/packaging/javascript.md).

package/index.d.ts

@@ -0,0 +1,81 @@
+/** A value that converts to an engine value. */
+export type PyValue =
+  | null | undefined | boolean | number | bigint | string | Uint8Array | Complex | PyObject
+  | PyValue[] | Set<PyValue> | Map<PyValue, PyValue> | { [key: string]: PyValue }
+  | ((...args: any[]) => unknown);
+
+export interface RuntimeOptions {
+  /** Register the standard modules (sys, gc, weakref). Default true. */
+  std?: boolean;
+  /** Evaluation steps per top-level eval or exec; 0 is unlimited. */
+  stepLimit?: number;
+  /** Bytes the engine may hold; 0 is unlimited. */
+  memoryLimit?: number;
+  /** Milliseconds one operation may run in the worker. */
+  timeout?: number;
+  /** Receives printed text; by default lines go to console.log. */
+  output?: (text: string) => void | Promise<void>;
+  /** Maps a module name to its source, or null. */
+  loader?: (name: string) => string | null | undefined | Promise<string | null | undefined>;
+  /** Largest message between the runtime and its worker, in bytes. */
+  messageLimit?: number;
+}
+
+export class Runtime {
+  static create(options?: RuntimeOptions): Promise<Runtime>;
+  private constructor();
+  readonly version: string;
+  readonly closed: boolean;
+  eval(source: string, filename?: string): Promise<any>;
+  exec(source: string, filename?: string): Promise<void>;
+  call(target: string | PyObject, args?: PyValue[], kwargs?: { [key: string]: PyValue } | Map<string, PyValue>): Promise<any>;
+  get(name: string): Promise<any>;
+  set(name: string, value: PyValue): Promise<void>;
+  delete(name: string): Promise<void>;
+  define<F extends (...args: any[]) => unknown>(name: string, fn: F): Promise<F>;
+  registerModule(name: string, members?: { [key: string]: PyValue } | Map<string, PyValue> | null, source?: string | null): Promise<void>;
+  collect(): Promise<number>;
+  close(): void;
+  [Symbol.dispose](): void;
+}
+
+export class PyObject {
+  private constructor();
+  get(name: string): Promise<any>;
+  set(name: string, value: PyValue): Promise<void>;
+  getItem(key: PyValue): Promise<any>;
+  setItem(key: PyValue, value: PyValue): Promise<void>;
+  len(): Promise<number>;
+  has(item: PyValue): Promise<boolean>;
+  call(args?: PyValue[], kwargs?: { [key: string]: PyValue } | Map<string, PyValue>): Promise<any>;
+  bool(): Promise<boolean>;
+  hash(): Promise<number | bigint>;
+  compare(op: "<" | "<=" | "==" | "!=" | ">" | ">=", other: PyValue): Promise<any>;
+  repr(): Promise<string>;
+  str(): Promise<string>;
+  dir(): Promise<string[]>;
+  [Symbol.asyncIterator](): AsyncIterator<any>;
+  release(): void;
+}
+
+export class Complex {
+  constructor(real: number, imag: number);
+  readonly real: number;
+  readonly imag: number;
+}
+
+/** Mark a host function as taking keyword arguments: fn(...args, kwargs). */
+export function keywords<F extends (...args: any[]) => unknown>(fn: F): F;
+
+export class PythonError extends Error {
+  readonly type: string;
+  readonly exception: PyObject | null;
+  readonly filename: string | null;
+  readonly lineno: number | null;
+}
+
+export class WorkerError extends Error {
+  readonly returncode: number | null;
+}
+
+export class Timeout extends WorkerError {}