Merge pull request #295 from bbopen/feat/0.9-remove-instance-api

feat!: remove the stateful instance API — server, client/protocol, generator

Author: bbopen

docs/examples/index.md

@@ -57,16 +57,15 @@ import { sin, pi } from './generated/math.generated.js';
 console.log(await sin(pi / 4));
 ```
 
-## Generated Classes
+## Value-returning APIs
 
-Generated classes have an async `create(...)` constructor and an explicit `disposeHandle()`:
+v0.9 generated wrappers do not keep live Python class instances. Expose an
+operation as a value-returning module function instead:
 
 ```ts
-import { Counter } from './generated/collections.generated.js';
+import { median } from './generated/statistics.generated.js';
 
-const counter = await Counter.create([1, 2, 2]);
-console.log(await counter.mostCommon(1));
-await counter.disposeHandle();
+console.log(await median([1, 2, 2])); // 2
 ```
 
 ## More Docs

docs/guide/getting-started.md

@@ -138,19 +138,13 @@ def calculate_area(width: float, height: float) -> float:
     """Calculate rectangular area."""
     return width * height
 
-class Calculator:
-    """Simple calculator class."""
+def add(a: float, b: float, precision: int = 2) -> float:
+    """Add two numbers."""
+    return round(a + b, precision)
 
-    def __init__(self, precision: int = 2):
-        self.precision = precision
-
-    def add(self, a: float, b: float) -> float:
-        """Add two numbers."""
-        return round(a + b, self.precision)
-
-    def multiply(self, a: float, b: float) -> float:
-        """Multiply two numbers."""
-        return round(a * b, self.precision)
+def multiply(a: float, b: float, precision: int = 2) -> float:
+    """Multiply two numbers."""
+    return round(a * b, precision)
 ```
 
 ### Configuration
@@ -199,7 +193,8 @@ import { setRuntimeBridge } from 'tywrap/runtime';
 import {
   greet,
   calculate_area,
-  Calculator,
+  add,
+  multiply,
 } from './generated/my_utils.generated.js';
 
 const bridge = new NodeBridge({ pythonPath: 'python3' });
@@ -213,14 +208,12 @@ async function demo() {
   const area = await calculate_area(10.5, 8.2);
   console.log(`Area: ${area}`); // Area: 86.1
 
-  // Class instantiation and methods
-  const calc = await Calculator.create(3);
-  const sum = await calc.add(3.14159, 2.71828);
-  const product = await calc.multiply(sum, 2);
-  await calc.disposeHandle();
+  // Use value-returning module functions instead of live class handles.
+  const sum = await add(3.14159, 2.71828, 3);
+  const product = await multiply(sum, 2, 3);
 
-  console.log(`Sum: ${sum}`); // Sum: 5.860
-  console.log(`Product: ${product}`); // Product: 11.720
+  console.log(`Sum: ${sum}`); // Sum: 5.86
+  console.log(`Product: ${product}`); // Product: 11.72
 }
 ```
 

docs/public/llms-full.txt

@@ -197,19 +197,13 @@ def calculate_area(width: float, height: float) -> float:
     """Calculate rectangular area."""
     return width * height
 
-class Calculator:
-    """Simple calculator class."""
+def add(a: float, b: float, precision: int = 2) -> float:
+    """Add two numbers."""
+    return round(a + b, precision)
 
-    def __init__(self, precision: int = 2):
-        self.precision = precision
-
-    def add(self, a: float, b: float) -> float:
-        """Add two numbers."""
-        return round(a + b, self.precision)
-
-    def multiply(self, a: float, b: float) -> float:
-        """Multiply two numbers."""
-        return round(a * b, self.precision)
+def multiply(a: float, b: float, precision: int = 2) -> float:
+    """Multiply two numbers."""
+    return round(a * b, precision)
 ```
 
 ### Configuration
@@ -258,7 +252,8 @@ import { setRuntimeBridge } from 'tywrap/runtime';
 import {
   greet,
   calculate_area,
-  Calculator,
+  add,
+  multiply,
 } from './generated/my_utils.generated.js';
 
 const bridge = new NodeBridge({ pythonPath: 'python3' });
@@ -272,14 +267,12 @@ async function demo() {
   const area = await calculate_area(10.5, 8.2);
   console.log(`Area: ${area}`); // Area: 86.1
 
-  // Class instantiation and methods
-  const calc = await Calculator.create(3);
-  const sum = await calc.add(3.14159, 2.71828);
-  const product = await calc.multiply(sum, 2);
-  await calc.disposeHandle();
+  // Use value-returning module functions instead of live class handles.
+  const sum = await add(3.14159, 2.71828, 3);
+  const product = await multiply(sum, 2, 3);
 
-  console.log(`Sum: ${sum}`); // Sum: 5.860
-  console.log(`Product: ${product}`); // Product: 11.720
+  console.log(`Sum: ${sum}`); // Sum: 5.86
+  console.log(`Product: ${product}`); // Product: 11.72
 }
 ```
 
@@ -2671,7 +2664,7 @@ Generates TypeScript shaped like:
 export type Pair<T> = [T, T];
 export type Transform<P extends unknown[], T> = (...args: P) => T;
 export class Container<T> {
-  get(): Promise<T>;
+  // NOTE: Instance members are not generated in v0.9; migrate this API to value-returning module functions.
 }
 ```
 
@@ -3464,16 +3457,15 @@ import { sin, pi } from './generated/math.generated.js';
 console.log(await sin(pi / 4));
 ```
 
-## Generated Classes
+## Value-returning APIs
 
-Generated classes have an async `create(...)` constructor and an explicit `disposeHandle()`:
+v0.9 generated wrappers do not keep live Python class instances. Expose an operation as a
+value-returning module function instead:
 
 ```ts
-import { Counter } from './generated/collections.generated.js';
+import { median } from './generated/statistics.generated.js';
 
-const counter = await Counter.create([1, 2, 2]);
-console.log(await counter.mostCommon(1));
-await counter.disposeHandle();
+console.log(await median([1, 2, 2])); // 2
 ```
 
 ## More Docs

docs/reference/type-mapping.md

@@ -183,7 +183,7 @@ Generates TypeScript shaped like:
 export type Pair<T> = [T, T];
 export type Transform<P extends unknown[], T> = (...args: P) => T;
 export class Container<T> {
-  get(): Promise<T>;
+  // NOTE: Instance members are not generated in v0.9; migrate this API to value-returning module functions.
 }
 ```
 

runtime/python_bridge.py

@@ -19,7 +19,7 @@
     the explicit byte-size limit error message)
 
 SECURITY / TRUST MODEL: the bridge imports the requested module and getattrs the
-requested function/class/method, so call/instantiate/call_method are an arbitrary
+requested function/class method, so call is an arbitrary
 import+getattr+call surface. Two guards (implemented in tywrap_bridge_core) bound
 that surface:
   * TYWRAP_ALLOWED_MODULES (comma/space separated): when set, only those modules
@@ -54,7 +54,6 @@
     PROTOCOL_VERSION,
     CODEC_VERSION,
     ProtocolError,
-    InstanceHandleError,
     ImportNotAllowedError,
     AttributeNotAllowedError,
     import_allowed_module,
@@ -95,8 +94,6 @@
     except (OSError, ValueError):
         pass
 
-instances = {}
-
 FALLBACK_JSON = os.environ.get('TYWRAP_CODEC_FALLBACK', '').lower() == 'json'
 TORCH_ALLOW_COPY = os.environ.get('TYWRAP_TORCH_ALLOW_COPY', '').lower() in ('1', 'true', 'yes')
 BRIDGE_NAME = 'python-subprocess'
@@ -334,7 +331,6 @@ def handle_meta():
     real pid and bridge='python-subprocess'.
     """
     return core.build_meta(
-        instances,
         bridge=BRIDGE_NAME,
         pid=os.getpid(),
         python_version=sys.version.split()[0],
@@ -353,7 +349,6 @@ def dispatch_request(msg, *, has_envelope_markers=True):
     """
     out = core.dispatch_request(
         msg,
-        instances,
         bridge=BRIDGE_NAME,
         pid=os.getpid(),
         force_json_markers=FALLBACK_JSON,

runtime/tywrap_bridge_core.py

@@ -43,10 +43,8 @@
 import base64
 import datetime as dt
 import decimal
-import functools
 import importlib
 import importlib.util
-import inspect
 import json
 import math
 import sys
@@ -65,10 +63,6 @@ class ProtocolError(Exception):
     """Raised for malformed requests (bad protocol/id/method/params)."""
 
 
-class InstanceHandleError(ValueError):
-    """Raised when an instance handle is unknown or no longer valid."""
-
-
 class ImportNotAllowedError(PermissionError):
     """Raised when a requested module import is not on the active allowlist."""
 
@@ -97,8 +91,8 @@ def __init__(self, attr_name):
 # IMPORT / ATTRIBUTE ALLOWLIST (trust boundary enforcement)
 # =============================================================================
 #
-# The bridge dispatches call/instantiate/call_method by importing the requested
-# module and getattr-ing the requested function/class/method. That is an
+# The bridge dispatches call requests by importing the requested module and
+# getattr-ing the requested function/class method. That is an
 # arbitrary import+getattr+call surface, so two complementary guards live here.
 # Both are PURE (no env reads) so the rules behave identically under the
 # subprocess server and the in-WASM Pyodide server; the subprocess server derives
@@ -205,22 +199,6 @@ def resolve_allowed_attr_path(root, dotted_name, *, allow_private_attrs):
     return obj
 
 
-def is_accessor_attr(obj, attr_name):
-    """
-    True when attr_name resolves to a @property or functools.cached_property on
-    obj's type — i.e. it is read by attribute access, not called.
-
-    Inspects type(obj)'s MRO via getattr_static (which never triggers the
-    descriptor protocol), NOT the instance dict. That matters for
-    cached_property: after the first read it stores its value in the instance
-    __dict__, so an instance-level static lookup would return the cached value
-    rather than the descriptor and misclassify it as a method on the next read.
-    Reading from the type keeps the classification stable across repeated reads.
-    """
-    descriptor = inspect.getattr_static(type(obj), attr_name, None)
-    return isinstance(descriptor, (property, functools.cached_property))
-
-
 class CodecError(Exception):
     """Raised when value encoding fails (e.g. NaN/Infinity not allowed)."""
 
@@ -990,64 +968,7 @@ def handle_call(
     return serialize(res, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy)
 
 
-def handle_instantiate(
-    params, instances, *, allowed_modules, allow_private_attrs, has_envelope_markers
-):
-    module_name = require_str(params, 'module')
-    class_name = require_str(params, 'className')
-    args = deserialize(coerce_list(params.get('args'), 'args'), has_envelope_markers=has_envelope_markers)
-    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'), has_envelope_markers=has_envelope_markers)
-    mod = import_allowed_module(module_name, allowed_modules)
-    cls = get_allowed_attr(mod, class_name, allow_private_attrs=allow_private_attrs)
-    obj = cls(*args, **kwargs)
-    handle_id = str(id(obj))
-    instances[handle_id] = obj
-    return handle_id
-
-
-def handle_call_method(
-    params,
-    instances,
-    *,
-    force_json_markers,
-    torch_allow_copy,
-    allow_private_attrs,
-    has_envelope_markers,
-):
-    handle_id = require_str(params, 'handle')
-    method_name = require_str(params, 'methodName')
-    args = deserialize(coerce_list(params.get('args'), 'args'), has_envelope_markers=has_envelope_markers)
-    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'), has_envelope_markers=has_envelope_markers)
-    if handle_id not in instances:
-        raise InstanceHandleError(f'Unknown instance handle: {handle_id}')
-    obj = instances[handle_id]
-    # A @property / functools.cached_property is read, not called: the generated
-    # `get prop()` accessor emits callMethod(handle, name, []). Classify before
-    # touching the value (so cached_property is detected on its first read) and
-    # return the attribute directly; everything else is a bound method to call.
-    if is_accessor_attr(obj, method_name):
-        # An accessor is read, never called: a generated `get prop()` always
-        # sends empty args. Reject a malformed request that supplies any so it
-        # fails loudly instead of silently dropping the arguments.
-        if args or kwargs:
-            raise ProtocolError(f'Accessor {method_name!r} does not accept arguments')
-        res = get_allowed_attr(obj, method_name, allow_private_attrs=allow_private_attrs)
-    else:
-        func = get_allowed_attr(obj, method_name, allow_private_attrs=allow_private_attrs)
-        res = func(*args, **kwargs)
-    return serialize(res, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy)
-
-
-def handle_dispose_instance(params, instances):
-    handle_id = require_str(params, 'handle')
-    if handle_id not in instances:
-        return False
-    del instances[handle_id]
-    return True
-
-
 def build_meta(
-    instances,
     *,
     bridge,
     pid,
@@ -1088,7 +1009,7 @@ def build_meta(
         'scipyAvailable': module_available('scipy'),
         'torchAvailable': module_available('torch'),
         'sklearnAvailable': module_available('sklearn'),
-        'instances': len(instances),
+        'instances': 0,
     }
     if transport_info is not None:
         meta['transport'] = transport_info
@@ -1097,7 +1018,6 @@ def build_meta(
 
 def dispatch_request(
     msg,
-    instances,
     *,
     bridge,
     pid,
@@ -1121,7 +1041,7 @@ def dispatch_request(
     the final encode_value() call, which the caller performs.
 
     allowed_modules: None (default) disables the import allowlist so existing
-    behavior is preserved. Supplying a set restricts call/instantiate imports to
+    behavior is preserved. Supplying a set restricts call imports to
     those modules (plus the stdlib the bridge itself needs) and raises
     ImportNotAllowedError otherwise. allow_private_attrs=False (default) blocks
     getattr of underscore-prefixed names; True restores unrestricted access. See
@@ -1141,32 +1061,12 @@ def dispatch_request(
             allow_private_attrs=allow_private_attrs,
             has_envelope_markers=has_envelope_markers,
         )
-    elif method == 'instantiate':
-        result = handle_instantiate(
-            params,
-            instances,
-            allowed_modules=allowed_modules,
-            allow_private_attrs=allow_private_attrs,
-            has_envelope_markers=has_envelope_markers,
-        )
-    elif method == 'call_method':
-        result = handle_call_method(
-            params,
-            instances,
-            force_json_markers=force_json_markers,
-            torch_allow_copy=torch_allow_copy,
-            allow_private_attrs=allow_private_attrs,
-            has_envelope_markers=has_envelope_markers,
-        )
-    elif method == 'dispose_instance':
-        result = handle_dispose_instance(params, instances)
     elif method == 'meta':
         if python_version is None:
             import sys
             python_version = sys.version.split()[0]
         codec_fallback = 'json' if force_json_markers else 'none'
         result = build_meta(
-            instances,
             bridge=bridge,
             pid=pid,
             python_version=python_version,