tywrap 0.7.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)
 
 
 # =============================================================================
@@ -536,7 +517,10 @@ def serialize_sparse_matrix(obj):
         raise RuntimeError('Failed to inspect scipy sparse matrix format') from exc
 
     if fmt not in ('csr', 'csc', 'coo'):
-        raise RuntimeError(f'Unsupported scipy sparse format: {fmt}')
+        raise RuntimeError(
+            f'Unsupported scipy sparse format: {fmt}; only csr/csc/coo are supported. '
+            'Convert explicitly (e.g. matrix.tocsr()) before returning'
+        )
 
     dtype = None
     try:
@@ -544,7 +528,10 @@ def serialize_sparse_matrix(obj):
     except Exception:
         dtype = None
     if getattr(obj.dtype, 'kind', None) == 'c':
-        raise RuntimeError('Complex sparse matrices are not supported by JSON codec')
+        raise RuntimeError(
+            'Complex scipy sparse matrices are not supported by the JSON codec; '
+            'split into real/imag components explicitly before returning'
+        )
 
     if fmt in ('csr', 'csc'):
         data = obj.data.tolist()
@@ -584,8 +571,58 @@ def serialize_torch_tensor(obj, *, force_json_markers, torch_allow_copy=False):
     Serialize torch.Tensor values via the nested ndarray envelope. CPU-only by
     default; device/copy behavior is explicit. force_json_markers is threaded
     into the nested ndarray serialization so Pyodide gets a JSON ndarray value.
+
+    Rejection order is significant: the categorical rejections (sparse / quantized
+    / meta / complex) are checked BEFORE the device/contiguous opt-in branch so
+    they fail with a clear, specific message and are NOT bypassable by
+    TYWRAP_TORCH_ALLOW_COPY. The opt-in only governs the lossy-but-lossless device
+    transfer and contiguous copy, never an unrepresentable layout/dtype.
     """
+    import torch  # already importable: is_torch_tensor() gated the dispatch
+
     tensor = obj.detach()
+
+    # Sparse tensors (COO/CSR/CSC/BSR/BSC -> any non-strided layout) have no dense
+    # numpy representation without a densify step, which is not the round-trip this
+    # envelope promises. Reject explicitly rather than emitting a misleading
+    # "not contiguous" error or silently densifying.
+    layout = getattr(tensor, 'layout', None)
+    if getattr(tensor, 'is_sparse', False) or (
+        layout is not None and layout != torch.strided
+    ):
+        raise RuntimeError(
+            f'Torch sparse tensors are not supported (layout={layout}); '
+            'convert to a dense CPU tensor explicitly (e.g. tensor.to_dense()) before returning'
+        )
+
+    # Quantized tensors carry a qscheme/scale/zero_point that numpy() cannot
+    # represent; .numpy() raises an opaque "unsupported ScalarType" deep in torch.
+    # Reject up front with an actionable message.
+    if getattr(tensor, 'is_quantized', False):
+        raise RuntimeError(
+            'Torch quantized tensors are not supported; dequantize explicitly '
+            '(e.g. tensor.dequantize()) before returning'
+        )
+
+    # Meta tensors have shape/dtype but NO storage; copying to CPU yields garbage,
+    # so this is never a lossy-but-honest transfer the opt-in could authorize.
+    if getattr(tensor, 'is_meta', False) or (
+        getattr(tensor, 'device', None) is not None and tensor.device.type == 'meta'
+    ):
+        raise RuntimeError(
+            'Torch meta tensors carry no data and cannot be serialized; '
+            'materialize the tensor on a real device before returning'
+        )
+
+    # Complex tensors round-trip to numpy complex arrays, which are not
+    # JSON-serializable and have no codec envelope. Reject explicitly instead of
+    # emitting Python complex tuples that the JS decoder cannot parse.
+    if torch.is_complex(tensor):
+        raise RuntimeError(
+            f'Torch complex tensors are not supported (dtype={tensor.dtype}); '
+            'split into real/imag components explicitly before returning'
+        )
+
     if getattr(tensor, 'device', None) is not None and tensor.device.type != 'cpu':
         if not torch_allow_copy:
             raise RuntimeError(
@@ -622,12 +659,22 @@ def serialize_sklearn_estimator(obj):
         raise RuntimeError('scikit-learn is not available') from exc
 
     params = obj.get_params(deep=False)
-    try:
-        json.dumps(params)
-    except Exception as exc:
-        raise RuntimeError(
-            'scikit-learn estimator params are not JSON-serializable; avoid returning estimators or sanitize params'
-        ) from exc
+
+    # Metadata-only: NEVER pickle/joblib. Every param value must be plain JSON
+    # (no callables, nested estimators, numpy arrays, or other objects). Probe
+    # each value individually so the error names the offending param instead of
+    # failing opaquely on the whole dict. allow_nan=False also rejects NaN/Inf
+    # params here for parity with the response codec.
+    for key, value in params.items():
+        try:
+            json.dumps(value, allow_nan=False)
+        except (TypeError, ValueError) as exc:
+            raise RuntimeError(
+                f'scikit-learn estimator param {key!r} is not JSON-serializable '
+                f'(got {type(value).__name__}); estimators are serialized as metadata only '
+                '(no pickle/joblib), so every param must be a plain JSON value. '
+                'Sanitize or drop the param before returning'
+            ) from exc
 
     return {
         '__tywrap__': 'sklearn.estimator',
@@ -682,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
@@ -712,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)):
@@ -844,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
 # =============================================================================
@@ -883,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
@@ -897,53 +1019,14 @@ 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):
+def build_meta(
+    *,
+    bridge,
+    pid,
+    python_version,
+    codec_fallback,
+    arrow_available_override=None,
+):
     """
     Build the bridge metadata payload.
 
@@ -958,7 +1041,7 @@ def build_meta(instances, *, bridge, pid, python_version, codec_fallback, arrow_
     pyarrow happens to be importable in the WASM environment.
     """
     arrow = arrow_available() if arrow_available_override is None else arrow_available_override
-    return {
+    meta = {
         'protocol': PROTOCOL,
         'protocolVersion': PROTOCOL_VERSION,
         'bridge': bridge,
@@ -969,13 +1052,13 @@ def build_meta(instances, *, bridge, pid, python_version, codec_fallback, arrow_
         'scipyAvailable': module_available('scipy'),
         'torchAvailable': module_available('torch'),
         'sklearnAvailable': module_available('sklearn'),
-        'instances': len(instances),
+        'instances': 0,
     }
+    return meta
 
 
 def dispatch_request(
     msg,
-    instances,
     *,
     bridge,
     pid,
@@ -986,6 +1069,7 @@ def dispatch_request(
     arrow_available_override=None,
     allowed_modules=None,
     allow_private_attrs=False,
+    has_envelope_markers=True,
 ):
     """
     Validate and route a request, returning the fully-serialized response dict
@@ -997,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
@@ -1015,28 +1099,14 @@ 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,

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[];
@@ -253,7 +253,8 @@ export function parseAnnotationToPythonType(
   // Returns the content between the first `[` and the last `]` of a special-form
   // annotation (e.g. the `int, str` of `Union[int, str]`). Callers gate this on a
   // prefix check, so the brackets are known to be present.
-  const bracketInner = (raw: string): string => raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
+  const bracketInner = (raw: string): string =>
+    raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
 
   // True when `raw` opens with one of the supported module prefixes followed by
   // `name[`. Mirrors the inlined `raw.startsWith('typing.Name[') || ...` checks so
@@ -406,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('|')) {
@@ -505,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);

package/src/core/emit-call.ts

@@ -132,13 +132,7 @@ export function emitCallPrelude(desc: CallDescriptor, helpers: CallEmitHelpers):
  * keywords and enforce required keyword-only arguments.
  */
 export function emitArgGuards(desc: CallDescriptor): string[] {
-  const {
-    hasKwArgs,
-    positionalOnlyNames,
-    requiredKwOnlyNames,
-    indent: i,
-    errorLabel,
-  } = desc;
+  const { hasKwArgs, positionalOnlyNames, requiredKwOnlyNames, indent: i, errorLabel } = desc;
   const i2 = `${i}  `;
   const i3 = `${i2}  `;