tywrap 0.8.0 → 0.9.0

package/runtime/tywrap_bridge_core.py

@@ -43,12 +43,11 @@ derived from TYWRAP_CODEC_FALLBACK=json so that "Node in json-fallback mode" and
 import base64
 import datetime as dt
 import decimal
-import functools
 import importlib
 import importlib.util
-import inspect
 import json
 import math
+import sys
 import traceback
 import uuid
 from pathlib import Path, PurePath
@@ -64,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."""
 
@@ -96,8 +91,8 @@ class AttributeNotAllowedError(PermissionError):
 # 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
@@ -204,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)."""
 
@@ -269,22 +248,24 @@ def _deserialize_bytes_envelope(value):
     return _NO_DESERIALIZE
 
 
-def deserialize(value):
+def deserialize(value, *, has_envelope_markers=True):
     """
     Recursively deserialize request values into Python-native types.
 
     Why: requests are JSON-only; we need a small set of explicit decoders
     (currently bytes) to restore Python semantics at the boundary.
     """
+    if not has_envelope_markers:
+        return value
     decoded = _deserialize_bytes_envelope(value)
     if decoded is not _NO_DESERIALIZE:
         return decoded
 
     if isinstance(value, list):
-        return [deserialize(item) for item in value]
+        return [deserialize(item, has_envelope_markers=True) for item in value]
     if isinstance(value, dict):
         # Preserve dict shape while decoding nested values.
-        return {k: deserialize(v) for k, v in value.items()}
+        return {k: deserialize(v, has_envelope_markers=True) for k, v in value.items()}
     return value
 
 
@@ -314,33 +295,33 @@ def module_available(module_name):
 
 
 def is_numpy_array(obj):
-    try:
-        import numpy as np  # noqa: F401
-    except Exception:
+    """Return whether obj is an ndarray without importing NumPy."""
+    np = sys.modules.get('numpy')
+    if np is None:
         return False
     return isinstance(obj, np.ndarray)
 
 
 def is_pandas_dataframe(obj):
-    try:
-        import pandas as pd  # noqa: F401
-    except Exception:
+    """Return whether obj is a DataFrame without importing pandas."""
+    pd = sys.modules.get('pandas')
+    if pd is None:
         return False
     return isinstance(obj, pd.DataFrame)
 
 
 def is_pandas_series(obj):
-    try:
-        import pandas as pd  # noqa: F401
-    except Exception:
+    """Return whether obj is a Series without importing pandas."""
+    pd = sys.modules.get('pandas')
+    if pd is None:
         return False
     return isinstance(obj, pd.Series)
 
 
 def is_scipy_sparse(obj):
-    try:
-        import scipy.sparse as sp  # noqa: F401
-    except Exception:
+    """Return whether obj is sparse without importing SciPy."""
+    sp = sys.modules.get('scipy.sparse')
+    if sp is None:
         return False
     try:
         return sp.issparse(obj)
@@ -349,9 +330,9 @@ def is_scipy_sparse(obj):
 
 
 def is_torch_tensor(obj):
-    try:
-        import torch  # noqa: F401
-    except Exception:
+    """Return whether obj is a Tensor without importing PyTorch."""
+    torch = sys.modules.get('torch')
+    if torch is None:
         return False
     try:
         return torch.is_tensor(obj)
@@ -360,11 +341,11 @@ def is_torch_tensor(obj):
 
 
 def is_sklearn_estimator(obj):
-    try:
-        from sklearn.base import BaseEstimator  # noqa: F401
-    except Exception:
+    """Return whether obj is an estimator without importing scikit-learn."""
+    sklearn_base = sys.modules.get('sklearn.base')
+    if sklearn_base is None:
         return False
-    return isinstance(obj, BaseEstimator)
+    return isinstance(obj, sklearn_base.BaseEstimator)
 
 
 # =============================================================================
@@ -748,26 +729,45 @@ def serialize_stdlib(obj):
 
 def serialize(obj, *, force_json_markers, torch_allow_copy=False):
     """
-    Top-level result serializer. Dispatch order is significant: numpy ndarray ->
-    dataframe -> series -> scipy.sparse -> torch -> sklearn -> Pydantic -> stdlib
-    -> passthrough. The remaining BridgeCodec value behaviors (numpy/pandas scalars,
-    bytes, sets, complex rejection, NaN/Infinity) are applied later during JSON
-    encoding by default_encoder.
+    Top-level result serializer.
+
+    Scientific codecs are type-first and only inspect packages that the value can
+    belong to. A value from an optional package implies that package is already in
+    sys.modules, so these checks never cold-import the scientific stack. The
+    package dispatch deliberately precedes the JSON-native fast path: e.g. a
+    package-defined subclass of dict still receives its relevant codec check.
+    The remaining BridgeCodec value behaviors (numpy/pandas scalars, bytes, sets,
+    complex rejection, NaN/Infinity) are applied later during JSON encoding by
+    default_encoder.
     """
-    if is_numpy_array(obj):
-        return serialize_ndarray(obj, force_json_markers=force_json_markers)
-    if is_pandas_dataframe(obj):
-        return serialize_dataframe(obj, force_json_markers=force_json_markers)
-    if is_pandas_series(obj):
-        return serialize_series(obj, force_json_markers=force_json_markers)
-    if is_scipy_sparse(obj):
-        return serialize_sparse_matrix(obj)
-    if is_torch_tensor(obj):
-        return serialize_torch_tensor(
-            obj, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy
-        )
-    if is_sklearn_estimator(obj):
+    package = type(obj).__module__.split('.', 1)[0]
+
+    if package == 'numpy' and 'numpy' in sys.modules:
+        if is_numpy_array(obj):
+            return serialize_ndarray(obj, force_json_markers=force_json_markers)
+    elif package == 'pandas' and 'pandas' in sys.modules:
+        if is_pandas_dataframe(obj):
+            return serialize_dataframe(obj, force_json_markers=force_json_markers)
+        if is_pandas_series(obj):
+            return serialize_series(obj, force_json_markers=force_json_markers)
+    elif package == 'scipy' and 'scipy.sparse' in sys.modules:
+        if is_scipy_sparse(obj):
+            return serialize_sparse_matrix(obj)
+    elif package == 'torch' and 'torch' in sys.modules:
+        if is_torch_tensor(obj):
+            return serialize_torch_tensor(
+                obj, force_json_markers=force_json_markers, torch_allow_copy=torch_allow_copy
+            )
+    elif 'sklearn.base' in sys.modules and is_sklearn_estimator(obj):
+        # No package gate here, unlike the branches above: subclassing
+        # BaseEstimator is sklearn's documented extension point, so user-defined
+        # estimators live outside the 'sklearn' package and must still get the
+        # estimator serializer (and its param-naming errors).
         return serialize_sklearn_estimator(obj)
+
+    if isinstance(obj, (type(None), bool, int, float, str, dict, list, tuple)):
+        return obj
+
     pydantic_value = serialize_pydantic(obj)
     if pydantic_value is not _NO_PYDANTIC:
         return pydantic_value
@@ -778,14 +778,12 @@ def serialize(obj, *, force_json_markers, torch_allow_copy=False):
 
 
 # =============================================================================
-# JSON ENCODE: BridgeCodec-equivalent value handling (NaN reject, scalars, bytes)
+# JSON CODEC: value handling and size-limited encode/decode
 # =============================================================================
 #
-# This mirrors BridgeCodec._default_encoder (runtime/safe_codec.py) for the VALUE
-# behaviors that are part of the wire contract. The subprocess server still uses
-# the real BridgeCodec for its final encode (it also enforces size limits); this
-# core encoder exists so the Pyodide server gets identical value handling without
-# depending on safe_codec.py. The conformance suite asserts these behaviors match.
+# This is the single Python implementation used by both the subprocess bridge and
+# the embedded Pyodide core. BridgeCodec adds payload-size enforcement around the
+# shared encoder; encode_value is the unbounded form used by the in-memory bridge.
 
 def _is_nan_or_inf(value):
     if not isinstance(value, (int, float)):
@@ -910,6 +908,56 @@ def encode_value(value, *, allow_nan):
         raise CodecError(f'JSON encoding failed: {exc}') from exc
 
 
+class BridgeCodec:
+    """Safe JSON codec with explicit value handling and payload-size limits."""
+
+    def __init__(self, allow_nan=False, max_payload_bytes=10 * 1024 * 1024):
+        self.allow_nan = allow_nan
+        self.max_payload_bytes = max_payload_bytes
+        self._encoder = make_default_encoder(allow_nan=allow_nan)
+
+    def encode(self, value):
+        result = encode_value(value, allow_nan=self.allow_nan)
+        if len(result.encode('utf-8')) > self.max_payload_bytes:
+            raise CodecError(f'Payload exceeds {self.max_payload_bytes} bytes')
+        return result
+
+    def decode(self, payload):
+        if len(payload.encode('utf-8')) > self.max_payload_bytes:
+            raise CodecError(f'Payload exceeds {self.max_payload_bytes} bytes')
+        try:
+            return json.loads(payload)
+        except json.JSONDecodeError as exc:
+            raise CodecError(f'JSON decoding failed: {exc}') from exc
+
+    def _default_encoder(self, obj):
+        """Compatibility hook for callers that used the codec's JSON encoder."""
+        return self._encoder(obj)
+
+
+_default_codec = None
+
+
+def get_default_codec():
+    """Return the lazily-created default BridgeCodec instance."""
+    global _default_codec
+    if _default_codec is None:
+        _default_codec = BridgeCodec()
+    return _default_codec
+
+
+def encode(value, *, allow_nan=False):
+    """Encode a value with the default codec settings."""
+    if allow_nan:
+        return BridgeCodec(allow_nan=True).encode(value)
+    return get_default_codec().encode(value)
+
+
+def decode(payload):
+    """Decode a JSON payload with the default codec settings."""
+    return get_default_codec().decode(payload)
+
+
 # =============================================================================
 # REQUEST VALIDATION + HANDLERS + DISPATCH
 # =============================================================================
@@ -949,11 +997,19 @@ def coerce_dict(value, key):
     return value
 
 
-def handle_call(params, *, force_json_markers, torch_allow_copy, allowed_modules, allow_private_attrs):
+def handle_call(
+    params,
+    *,
+    force_json_markers,
+    torch_allow_copy,
+    allowed_modules,
+    allow_private_attrs,
+    has_envelope_markers,
+):
     module_name = require_str(params, 'module')
     function_name = require_str(params, 'functionName')
-    args = deserialize(coerce_list(params.get('args'), 'args'))
-    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))
+    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)
     # function_name may be dotted ('Class.method') for @classmethod/@staticmethod
     # calls, which the generated wrapper routes through call() rather than an
@@ -963,61 +1019,13 @@ def handle_call(params, *, force_json_markers, torch_allow_copy, allowed_modules
     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):
-    module_name = require_str(params, 'module')
-    class_name = require_str(params, 'className')
-    args = deserialize(coerce_list(params.get('args'), 'args'))
-    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))
-    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):
-    handle_id = require_str(params, 'handle')
-    method_name = require_str(params, 'methodName')
-    args = deserialize(coerce_list(params.get('args'), 'args'))
-    kwargs = deserialize(coerce_dict(params.get('kwargs'), 'kwargs'))
-    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,
     python_version,
     codec_fallback,
     arrow_available_override=None,
-    transport_info=None,
 ):
     """
     Build the bridge metadata payload.
@@ -1031,13 +1039,6 @@ def build_meta(
     instead of probing pyarrow. The Pyodide server forces markers to JSON
     unconditionally, so it advertises arrowAvailable=False regardless of whether
     pyarrow happens to be importable in the WASM environment.
-
-    transport_info: optional chunked-transport negotiation block (BridgeInfo
-    .transport). Core stays oblivious to framing policy -- it only echoes what
-    the I/O layer tells it. The subprocess server passes a {'frameProtocol',
-    'supportsChunking', 'maxFrameBytes'} dict when chunking is negotiated; the
-    Pyodide server passes None (single-frame, in-memory). When None the block is
-    omitted entirely (backward compatible: old bridges never emit it).
     """
     arrow = arrow_available() if arrow_available_override is None else arrow_available_override
     meta = {
@@ -1051,16 +1052,13 @@ 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
     return meta
 
 
 def dispatch_request(
     msg,
-    instances,
     *,
     bridge,
     pid,
@@ -1071,7 +1069,7 @@ def dispatch_request(
     arrow_available_override=None,
     allowed_modules=None,
     allow_private_attrs=False,
-    transport_info=None,
+    has_envelope_markers=True,
 ):
     """
     Validate and route a request, returning the fully-serialized response dict
@@ -1083,7 +1081,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
@@ -1101,34 +1099,19 @@ def dispatch_request(
             torch_allow_copy=torch_allow_copy,
             allowed_modules=allowed_modules,
             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
-        )
-    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,
-        )
-    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,
             codec_fallback=codec_fallback,
             arrow_available_override=arrow_available_override,
-            transport_info=transport_info,
         )
     else:
         raise ProtocolError(f'Unknown method: {method}')

package/src/config/index.ts

@@ -118,6 +118,7 @@ function detectLegacyFields(config: TywrapConfig): void {
 const ALLOWED_TOP_LEVEL = new Set([
   'pythonModules',
   'pythonImportPath',
+  'contractInput',
   'output',
   'runtime',
   'performance',
@@ -129,6 +130,7 @@ const VALID_OUTPUT_FORMATS = ['esm', 'cjs', 'both'];
 const VALID_COMPRESSION = ['auto', 'gzip', 'brotli', 'none'];
 const VALID_TYPE_HINTS = ['strict', 'loose', 'ignore'];
 const VALID_TYPE_PRESETS = new Set([
+  // Accepted as an explicit no-op in 0.9; ndarray shape typing depends on #268.
   'numpy',
   'pandas',
   'pydantic',
@@ -276,6 +278,15 @@ function validateConfig(config: ResolvedTywrapConfig): void {
     throw new Error('pythonImportPath must be an array of strings');
   }
 
+  if (
+    config.contractInput !== undefined &&
+    typeof config.contractInput !== 'string' &&
+    (!isPlainObject(config.contractInput) ||
+      !Object.values(config.contractInput).every(value => typeof value === 'string'))
+  ) {
+    throw new Error('contractInput must be a path string or a record of module paths');
+  }
+
   validateOutput(config.output);
   validateRuntime(config.runtime);
   validatePerformance(config.performance);

package/src/core/annotation-parser.ts

@@ -1,6 +1,6 @@
 import type { PythonGenericParameter, PythonType } from '../types/index.js';
 
-export interface AnnotationParserOptions {
+interface AnnotationParserOptions {
   onUnknownTypeName?: (name: string) => void;
   knownTypeVarNames?: Iterable<string>;
   typeParameters?: readonly PythonGenericParameter[];
@@ -407,8 +407,7 @@ export function parseAnnotationToPythonType(
     const builtInClassMatch = raw.match(/^<class ['"][^'"]+['"]>$/);
     if (builtInClassMatch) {
       const inner = (raw.match(/^<class ['"]([^'"]+)['"]>$/) ?? [])[1] ?? '';
-      const name = (inner.split('.').pop() ?? '').toString();
-      return mapSimpleName(name);
+      return mapSimpleName(inner);
     }
 
     if (raw.includes('|')) {
@@ -506,7 +505,11 @@ export function parseAnnotationToPythonType(
       };
     }
 
-    return mapSimpleName(raw);
+    const qualified = splitQualifiedName(raw);
+    if (qualified.module) {
+      return { kind: 'custom', name: qualified.name, module: qualified.module };
+    }
+    return mapSimpleName(qualified.name);
   };
 
   return parse(annotation, 0);