tywrap 0.2.0 → 0.3.0

package/runtime/safe_codec.py

@@ -0,0 +1,344 @@
+"""
+Safe JSON codec with explicit edge case handling.
+
+Provides bidirectional validation and serialization for the JS<->Python bridge.
+This module handles special Python types and enforces payload size limits to
+ensure predictable behavior at the language boundary.
+"""
+
+import base64
+import json
+import math
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from pathlib import Path, PurePath
+from typing import Any, Optional, Union
+from uuid import UUID
+
+
+class CodecError(Exception):
+    """Raised when encoding/decoding fails."""
+
+    pass
+
+
+def _is_nan_or_inf(value: Any) -> bool:
+    """
+    Check if a numeric value is NaN or Infinity.
+
+    Args:
+        value: The value to check.
+
+    Returns:
+        True if the value is NaN, positive infinity, or negative infinity.
+    """
+    if not isinstance(value, (int, float)):
+        return False
+    try:
+        return math.isnan(value) or math.isinf(value)
+    except (TypeError, ValueError):
+        return False
+
+
+def _is_numpy_scalar(obj: Any) -> bool:
+    """
+    Detect numpy scalar types when NumPy is installed.
+
+    Why: numpy scalars have an `.item()` method to extract Python primitives,
+    which is needed for JSON serialization.
+    """
+    try:
+        import numpy as np
+    except ImportError:
+        return False
+    return isinstance(obj, (np.generic, np.ndarray)) and obj.ndim == 0
+
+
+def _is_pandas_scalar(obj: Any) -> bool:
+    """
+    Detect pandas scalar types (Timestamp, Timedelta, etc.).
+
+    Why: pandas wraps numpy scalars with additional metadata; extracting the
+    underlying value ensures clean JSON serialization.
+    """
+    try:
+        import pandas as pd
+    except ImportError:
+        return False
+    # Check for pandas Timestamp, Timedelta, NaT, etc.
+    return isinstance(
+        obj,
+        (
+            pd.Timestamp,
+            pd.Timedelta,
+            type(pd.NaT),
+        ),
+    )
+
+
+def _has_pydantic_model_dump(obj: Any) -> bool:
+    """
+    Check if object is a Pydantic v2 model with model_dump method.
+
+    Why: Pydantic models should be serialized via their built-in mechanism
+    to respect field aliases and serialization modes.
+    """
+    model_dump = getattr(obj, 'model_dump', None)
+    return callable(model_dump)
+
+
+class SafeCodec:
+    """
+    Safe JSON codec with explicit edge case handling.
+
+    This codec provides:
+    - Rejection of NaN/Infinity by default (configurable)
+    - Payload size limits to prevent memory exhaustion
+    - Automatic handling of common Python types (datetime, Decimal, UUID, etc.)
+    - Support for numpy/pandas scalars
+    - Pydantic model serialization
+
+    Args:
+        allow_nan: If False (default), reject NaN/Infinity values.
+        max_payload_bytes: Maximum payload size in bytes (default 10MB).
+
+    Example:
+        >>> codec = SafeCodec()
+        >>> codec.encode({"key": "value"})
+        '{"key": "value"}'
+        >>> codec.decode('{"key": "value"}')
+        {'key': 'value'}
+    """
+
+    def __init__(
+        self,
+        allow_nan: bool = False,
+        max_payload_bytes: int = 10 * 1024 * 1024,
+    ) -> None:
+        """
+        Initialize the codec with configuration.
+
+        Args:
+            allow_nan: If False (default), reject NaN/Infinity values.
+            max_payload_bytes: Maximum payload size in bytes (default 10MB).
+        """
+        self.allow_nan = allow_nan
+        self.max_payload_bytes = max_payload_bytes
+
+    def encode(self, value: Any) -> str:
+        """
+        Encode a Python value to a JSON string.
+
+        Args:
+            value: The Python value to encode.
+
+        Returns:
+            A JSON string representation of the value.
+
+        Raises:
+            CodecError: If encoding fails due to:
+                - NaN/Infinity values when allow_nan is False
+                - Payload exceeds max_payload_bytes
+                - Value contains non-serializable types
+        """
+        try:
+            result = json.dumps(
+                value,
+                default=self._default_encoder,
+                allow_nan=self.allow_nan,
+            )
+        except ValueError as exc:
+            # json.dumps raises ValueError for NaN/Infinity when allow_nan=False
+            error_msg = str(exc).lower()
+            if 'nan' in error_msg or 'infinity' in error_msg or 'inf' in error_msg:
+                raise CodecError(
+                    'Cannot serialize NaN - NaN/Infinity not allowed in JSON'
+                ) from exc
+            raise CodecError(f'JSON encoding failed: {exc}') from exc
+        except TypeError as exc:
+            raise CodecError(f'JSON encoding failed: {exc}') from exc
+
+        # Check payload size
+        payload_bytes = len(result.encode('utf-8'))
+        if payload_bytes > self.max_payload_bytes:
+            raise CodecError(f'Payload exceeds {self.max_payload_bytes} bytes')
+
+        return result
+
+    def decode(self, payload: str) -> Any:
+        """
+        Decode a JSON string to a Python value.
+
+        Args:
+            payload: The JSON string to decode.
+
+        Returns:
+            The decoded Python value.
+
+        Raises:
+            CodecError: If decoding fails due to:
+                - Payload exceeds max_payload_bytes
+                - Invalid JSON syntax
+        """
+        # Check payload size first
+        payload_bytes = len(payload.encode('utf-8'))
+        if payload_bytes > 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: Any) -> Any:
+        """
+        Handle special Python types during JSON encoding.
+
+        This method is called by json.dumps for objects that are not natively
+        JSON serializable.
+
+        Args:
+            obj: The object to encode.
+
+        Returns:
+            A JSON-serializable representation of the object.
+
+        Raises:
+            TypeError: If the object cannot be serialized.
+            CodecError: If the object contains NaN/Infinity when not allowed.
+        """
+        # Handle numpy/pandas scalars first (they need .item() extraction)
+        if _is_numpy_scalar(obj):
+            extracted = obj.item()
+            # Check for NaN/Infinity in extracted value
+            if not self.allow_nan and _is_nan_or_inf(extracted):
+                raise CodecError(
+                    'Cannot serialize NaN - NaN/Infinity not allowed in JSON'
+                )
+            return extracted
+
+        if _is_pandas_scalar(obj):
+            try:
+                import pandas as pd
+            except ImportError:
+                pass
+            else:
+                # Handle NaT (Not a Time)
+                if obj is pd.NaT or (hasattr(pd, 'isna') and pd.isna(obj)):
+                    return None
+                # Pandas Timestamp -> ISO string
+                if isinstance(obj, pd.Timestamp):
+                    return obj.isoformat()
+                # Pandas Timedelta -> total seconds
+                if isinstance(obj, pd.Timedelta):
+                    return obj.total_seconds()
+
+        # datetime types
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+
+        if isinstance(obj, date):
+            return obj.isoformat()
+
+        if isinstance(obj, time):
+            return obj.isoformat()
+
+        # timedelta -> total seconds (consistent with python_bridge.py)
+        if isinstance(obj, timedelta):
+            return obj.total_seconds()
+
+        # Decimal -> string (preserves precision)
+        if isinstance(obj, Decimal):
+            return str(obj)
+
+        # UUID -> string
+        if isinstance(obj, UUID):
+            return str(obj)
+
+        # Path -> string
+        if isinstance(obj, (Path, PurePath)):
+            return str(obj)
+
+        # bytes/bytearray -> base64 with type marker
+        if isinstance(obj, (bytes, bytearray)):
+            return {
+                '__type__': 'bytes',
+                'encoding': 'base64',
+                'data': base64.b64encode(obj).decode('ascii'),
+            }
+
+        # Pydantic models
+        if _has_pydantic_model_dump(obj):
+            try:
+                return obj.model_dump(by_alias=True, mode='json')
+            except TypeError:
+                # Older Pydantic versions may not support mode='json'
+                return obj.model_dump(by_alias=True)
+
+        # Sets -> lists (common conversion)
+        if isinstance(obj, (set, frozenset)):
+            return list(obj)
+
+        # Complex numbers (rejected by default as they contain floats)
+        if isinstance(obj, complex):
+            raise TypeError(
+                f'Object of type {type(obj).__name__} is not JSON serializable'
+            )
+
+        # Fallback: raise TypeError with clear message
+        raise TypeError(
+            f'Object of type {type(obj).__name__} is not JSON serializable'
+        )
+
+
+# Module-level convenience instance with default settings
+_default_codec: Optional[SafeCodec] = None
+
+
+def get_default_codec() -> SafeCodec:
+    """
+    Get or create the default SafeCodec instance.
+
+    Returns:
+        The default SafeCodec instance with standard settings.
+    """
+    global _default_codec
+    if _default_codec is None:
+        _default_codec = SafeCodec()
+    return _default_codec
+
+
+def encode(value: Any, *, allow_nan: bool = False) -> str:
+    """
+    Convenience function to encode a value using default settings.
+
+    Args:
+        value: The Python value to encode.
+        allow_nan: If True, allow NaN/Infinity values.
+
+    Returns:
+        A JSON string representation of the value.
+
+    Raises:
+        CodecError: If encoding fails.
+    """
+    if allow_nan:
+        codec = SafeCodec(allow_nan=True)
+        return codec.encode(value)
+    return get_default_codec().encode(value)
+
+
+def decode(payload: str) -> Any:
+    """
+    Convenience function to decode a JSON string using default settings.
+
+    Args:
+        payload: The JSON string to decode.
+
+    Returns:
+        The decoded Python value.
+
+    Raises:
+        CodecError: If decoding fails.
+    """
+    return get_default_codec().decode(payload)

package/src/cli.ts

@@ -192,6 +192,11 @@ async function main(): Promise<void> {
             type: 'boolean',
             describe: 'Enable debug logging',
           })
+          .option('verbose', {
+            alias: 'v',
+            type: 'boolean',
+            describe: 'Alias for --debug',
+          })
           .option('fail-on-warn', {
             type: 'boolean',
             default: false,
@@ -215,6 +220,7 @@ async function main(): Promise<void> {
           sourceMap?: boolean;
           useCache?: boolean;
           debug?: boolean;
+          verbose?: boolean;
           failOnWarn: boolean;
           check: boolean;
         }>
@@ -253,7 +259,9 @@ async function main(): Promise<void> {
           };
         }
 
-        if (typeof argv.debug === 'boolean') {
+        if (argv.verbose === true) {
+          overrides.debug = true;
+        } else if (typeof argv.debug === 'boolean') {
           overrides.debug = argv.debug;
         }
 
@@ -279,11 +287,27 @@ async function main(): Promise<void> {
           }
 
           const res = await generate(options, { check: argv.check });
+          const warnings = res.warnings ?? [];
+          const moduleCount = Object.keys(options.pythonModules ?? {}).length;
+
+          const emitWarnings = (): void => {
+            if (warnings.length === 0) {
+              return;
+            }
+            process.stderr.write(`Warnings (count ${warnings.length}):\n`);
+            for (const w of warnings) {
+              process.stderr.write(`- ${w}\n`);
+            }
+            process.stderr.write('\n');
+          };
+
           if (argv.check) {
             const outOfDate = res.outOfDate ?? [];
             if (outOfDate.length === 0) {
+              emitWarnings();
               process.stdout.write('Generated wrappers are up to date.\n');
             } else {
+              emitWarnings();
               process.stderr.write('Generated wrappers are out of date:\n');
               for (const file of outOfDate) {
                 process.stderr.write(`- ${file}\n`);
@@ -294,7 +318,42 @@ async function main(): Promise<void> {
               }
             }
           } else {
-            process.stdout.write(`Generated: ${res.written.join(', ')}\n`);
+            emitWarnings();
+
+            const written = res.written ?? [];
+            if (written.length === 0) {
+              process.stderr.write(
+                `No files were generated. This usually means Python failed to import one or more modules.\n`
+              );
+              const modulesConfigured = Object.keys(options.pythonModules ?? {});
+              if (modulesConfigured.length > 0) {
+                process.stderr.write(`Modules: ${modulesConfigured.join(', ')}\n`);
+              }
+
+              const pythonImportPath = options.pythonImportPath ?? [];
+              if (pythonImportPath.length > 0) {
+                process.stderr.write(`pythonImportPath: ${pythonImportPath.join(', ')}\n`);
+              } else {
+                process.stderr.write(
+                  `Tip: set "pythonImportPath" in your tywrap config to include your local module directories.\n`
+                );
+              }
+
+              const pyPath = process.env.PYTHONPATH;
+              if (typeof pyPath === 'string' && pyPath.trim().length > 0) {
+                process.stderr.write(`PYTHONPATH: ${pyPath}\n`);
+              }
+
+              process.stderr.write(`Tip: re-run with --debug for more context.\n`);
+              process.exit(1);
+            }
+
+            process.stdout.write(
+              `Generated: ${written.length} files from ${moduleCount} modules (warnings: ${warnings.length}).\n`
+            );
+            for (const file of written) {
+              process.stdout.write(`- ${file}\n`);
+            }
           }
           if (argv.failOnWarn && res.warnings.length > 0) {
             log.error(

package/src/config/index.ts

@@ -7,7 +7,8 @@
 
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { readFile, rm, writeFile, mkdtemp, symlink } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -20,11 +21,6 @@ import type {
 } from '../types/index.js';
 import { getDefaultPythonPath } from '../utils/python.js';
 
-/**
- * Public configuration type. Currently identical to {@link TywrapOptions}.
- */
-export type TywrapConfig = TywrapOptions;
-
 type DeepPartial<T> = {
   [K in keyof T]?: T[K] extends Array<infer U>
     ? Array<U>
@@ -33,11 +29,22 @@ type DeepPartial<T> = {
       : T[K];
 };
 
+/**
+ * User-authored configuration shape accepted by defineConfig() and config files.
+ */
+export type TywrapConfig = DeepPartial<TywrapOptions>;
+
+/**
+ * Fully resolved configuration shape returned by createConfig() and resolveConfig().
+ */
+export type ResolvedTywrapConfig = TywrapOptions;
+
 /**
  * Default configuration values used when options are not supplied.
  */
-const DEFAULT_CONFIG: TywrapConfig = {
+const DEFAULT_CONFIG: ResolvedTywrapConfig = {
   pythonModules: {},
+  pythonImportPath: [],
   output: { dir: './generated', format: 'esm', declaration: false, sourceMap: false },
   runtime: { node: { pythonPath: getDefaultPythonPath(), timeout: 30000 } },
   performance: { caching: false, batching: false, compression: 'none' },
@@ -85,9 +92,10 @@ function safeExists(path: string): boolean {
 /**
  * Validate configuration values and throw user-friendly errors when invalid.
  */
-function validateConfig(config: TywrapConfig): void {
+function validateConfig(config: ResolvedTywrapConfig): void {
   const allowedTopLevel = new Set([
     'pythonModules',
+    'pythonImportPath',
     'output',
     'runtime',
     'performance',
@@ -105,6 +113,15 @@ function validateConfig(config: TywrapConfig): void {
   if (typeof out.dir !== 'string') {
     throw new Error('output.dir must be a string');
   }
+
+  if (config.pythonImportPath !== undefined) {
+    if (
+      !Array.isArray(config.pythonImportPath) ||
+      config.pythonImportPath.some(p => typeof p !== 'string')
+    ) {
+      throw new Error('pythonImportPath must be an array of strings');
+    }
+  }
   if (!['esm', 'cjs', 'both'].includes(out.format)) {
     throw new Error('output.format must be one of "esm", "cjs" or "both"');
   }
@@ -183,7 +200,7 @@ function validateConfig(config: TywrapConfig): void {
  *
  * @param overrides CLI or programmatic overrides
  */
-export function createConfig(overrides: DeepPartial<TywrapOptions> = {}): TywrapConfig {
+export function createConfig(overrides: DeepPartial<TywrapOptions> = {}): ResolvedTywrapConfig {
   const merged = merge(DEFAULT_CONFIG, overrides);
   validateConfig(merged);
   return merged;
@@ -200,7 +217,9 @@ export interface ResolveConfigOptions {
  * Resolve configuration by loading a config file (JSON/JS/TS) and merging
  * defaults with any overrides.
  */
-export async function resolveConfig(options: ResolveConfigOptions = {}): Promise<TywrapConfig> {
+export async function resolveConfig(
+  options: ResolveConfigOptions = {}
+): Promise<ResolvedTywrapConfig> {
   const cwd = options.cwd ?? process.cwd();
   const overrides = options.overrides ?? {};
   const configFile = options.configFile ? resolve(cwd, options.configFile) : undefined;
@@ -272,6 +291,20 @@ export async function loadConfigFile(configFile: string): Promise<Partial<Tywrap
       fileName: resolved,
     });
 
+    let transpiledOutput = output.outputText;
+    if (!emitCommonJs) {
+      try {
+        // Preserve support for `import { defineConfig } from 'tywrap'` when ESM config
+        // is evaluated from an OS temp directory outside the package scope.
+        const tywrapEntryHref = await import.meta.resolve('tywrap');
+        transpiledOutput = transpiledOutput
+          .replaceAll("'tywrap'", `'${tywrapEntryHref}'`)
+          .replaceAll('\"tywrap\"', `\"${tywrapEntryHref}\"`);
+      } catch {
+        // Best-effort: leave source as-is when tywrap cannot be resolved.
+      }
+    }
+
     if (emitCommonJs) {
       // Why: `.cts` is explicitly CommonJS. We evaluate the transpiled output in-memory using
       // Node's Module internals (`Module._compile` / `_nodeModulePaths`) to avoid writing an extra
@@ -309,18 +342,31 @@ export async function loadConfigFile(configFile: string): Promise<Partial<Tywrap
       return ensureConfigObject(loaded ?? {}, resolved);
     }
 
-    // Why: Node can't import ESM from a string without a custom loader. We write the transpiled
-    // output to a temporary `.mjs` file next to the source config so relative imports and Node
-    // resolution behave naturally, then clean it up immediately after loading.
-    const tmpPath = resolve(dirname(resolved), `.tywrap.config.${randomUUID()}.mjs`);
+    // Why: Node can't import ESM from a string without a custom loader. We write transpiled
+    // output to a temporary `.mjs` file under the OS temp directory (not next to user config),
+    // then clean up both file and temporary directory after loading.
+    const tempDir = await mkdtemp(resolve(tmpdir(), 'tywrap-config-'));
+    const tmpPath = resolve(tempDir, `.tywrap.config.${randomUUID()}.mjs`);
     try {
-      // eslint-disable-next-line security/detect-non-literal-fs-filename -- temp path is derived from config location
-      await writeFile(tmpPath, output.outputText, 'utf-8');
+      const localNodeModules = resolve(process.cwd(), 'node_modules');
+      if (safeExists(localNodeModules)) {
+        const tempNodeModules = resolve(tempDir, 'node_modules');
+        try {
+          // eslint-disable-next-line security/detect-non-literal-fs-filename -- temp path is derived from OS temp directory
+          await symlink(localNodeModules, tempNodeModules, 'dir');
+        } catch {
+          // Best-effort only; regular resolution may still succeed without a symlink.
+        }
+      }
+
+      // eslint-disable-next-line security/detect-non-literal-fs-filename -- temp path is derived from OS temp directory
+      await writeFile(tmpPath, transpiledOutput, 'utf-8');
       const mod = (await import(pathToFileURL(tmpPath).href)) as Record<string, unknown>;
       const loaded = mod.default ?? mod;
       return ensureConfigObject(loaded ?? {}, resolved);
     } finally {
       await rm(tmpPath, { force: true });
+      await rm(tempDir, { recursive: true, force: true });
     }
   }
 
@@ -335,6 +381,6 @@ async function safeReadFileAsync(path: string): Promise<string> {
 /**
  * Type helper for authoring tywrap configs with full type inference.
  */
-export function defineConfig(config: TywrapConfig): TywrapConfig {
+export function defineConfig<T extends TywrapConfig>(config: T): T {
   return config;
 }