nodepyx 1.0.0

package/scripts/install.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * nodepyx — Post-install Script
+ * Tries to load pre-built binaries, falls back to building from source.
+ * Runs automatically via `postinstall` npm hook.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { execSync, spawnSync } = require('child_process');
+const os = require('os');
+
+const ROOT = path.resolve(__dirname, '..');
+const SKIP_BUILD = process.env.nodepyx_SKIP_BUILD === '1' || process.env.CI_SKIP_NATIVE === '1';
+const FORCE_BUILD = process.env.nodepyx_FORCE_BUILD === '1';
+const VERBOSE = process.env.nodepyx_VERBOSE === '1' || process.env.npm_config_loglevel === 'verbose';
+
+function log(msg) {
+  console.log(`[nodepyx install] ${msg}`);
+}
+
+function logVerbose(msg) {
+  if (VERBOSE) log(msg);
+}
+
+function warn(msg) {
+  console.warn(`[nodepyx install] WARNING: ${msg}`);
+}
+
+function error(msg) {
+  console.error(`[nodepyx install] ERROR: ${msg}`);
+}
+
+/** Get platform string matching prebuilds directory naming */
+function getPlatformDir() {
+  const platform = process.platform;
+  const arch = process.arch;
+  return `${platform}-${arch}`;
+}
+
+/** Try to load the addon to verify it works */
+function tryLoad(addonPath) {
+  try {
+    require(addonPath);
+    return true;
+  } catch (e) {
+    logVerbose(`Failed to load ${addonPath}: ${e.message}`);
+    return false;
+  }
+}
+
+/** Try to find and load a pre-built binary */
+function tryPrebuilt() {
+  const platformDir = getPlatformDir();
+  const prebuildsDir = path.join(ROOT, 'prebuilds', platformDir);
+
+  if (!fs.existsSync(prebuildsDir)) {
+    logVerbose(`No prebuilds directory for ${platformDir}`);
+    return false;
+  }
+
+  // Look for .node files in the prebuilds directory
+  const files = fs.readdirSync(prebuildsDir).filter(f => f.endsWith('.node'));
+
+  if (files.length === 0) {
+    logVerbose(`No .node files in ${prebuildsDir}`);
+    return false;
+  }
+
+  for (const file of files) {
+    const addonPath = path.join(prebuildsDir, file);
+    if (tryLoad(addonPath)) {
+      log(`Loaded pre-built binary: ${path.relative(ROOT, addonPath)}`);
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/** Try to load from build/Release */
+function tryBuildRelease() {
+  const releasePath = path.join(ROOT, 'build', 'Release', 'nodepyx_addon.node');
+  if (fs.existsSync(releasePath) && tryLoad(releasePath)) {
+    log('Loaded from build/Release');
+    return true;
+  }
+  return false;
+}
+
+/** Check if build tools are available */
+function hasBuildTools() {
+  try {
+    execSync('node-gyp --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    try {
+      // Try via npx
+      execSync('npx node-gyp --version', { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** Check if Python development headers are available */
+function hasPythonDev() {
+  const pythons = ['python3', 'python'];
+  for (const py of pythons) {
+    try {
+      const result = execSync(`${py}-config --includes 2>/dev/null || ${py} -c "import sysconfig; print(sysconfig.get_path('include'))"`, {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 5000,
+      });
+      const includes = result.toString().trim();
+      if (includes) {
+        logVerbose(`Python dev headers found via: ${py}`);
+        return true;
+      }
+    } catch {
+      // continue
+    }
+  }
+  return false;
+}
+
+/** Build the native addon from source */
+function buildFromSource() {
+  log('Building native addon from source...');
+  log('This may take a few minutes...');
+
+  const nodeGyp = 'node-gyp';
+  const buildArgs = ['rebuild', '--release'];
+
+  if (VERBOSE) {
+    buildArgs.push('--verbose');
+  }
+
+  const result = spawnSync(nodeGyp, buildArgs, {
+    cwd: ROOT,
+    stdio: 'inherit',
+    env: { ...process.env },
+  });
+
+  if (result.status !== 0) {
+    // Try via npx
+    const result2 = spawnSync('npx', [nodeGyp, ...buildArgs], {
+      cwd: ROOT,
+      stdio: 'inherit',
+      env: { ...process.env },
+    });
+
+    if (result2.status !== 0) {
+      return false;
+    }
+  }
+
+  return tryBuildRelease();
+}
+
+/** Print helpful error message with install instructions */
+function printInstallHelp() {
+  const platform = process.platform;
+
+  console.log('');
+  console.log('┌─────────────────────────────────────────────────────────────────┐');
+  console.log('│                     nodepyx install failed                       │');
+  console.log('└─────────────────────────────────────────────────────────────────┘');
+  console.log('');
+  console.log('nodepyx requires:');
+  console.log('  • Python 3.8+ with development headers');
+  console.log('  • C++ compiler (GCC/Clang/MSVC)');
+  console.log('  • node-gyp build tools');
+  console.log('');
+
+  if (platform === 'linux') {
+    console.log('Ubuntu/Debian install:');
+    console.log('  sudo apt-get install python3-dev build-essential');
+    console.log('');
+    console.log('RHEL/CentOS/Fedora install:');
+    console.log('  sudo dnf install python3-devel gcc-c++ make');
+  } else if (platform === 'darwin') {
+    console.log('macOS install:');
+    console.log('  brew install python3');
+    console.log('  xcode-select --install');
+  } else if (platform === 'win32') {
+    console.log('Windows install:');
+    console.log('  npm install --global windows-build-tools');
+    console.log('  or install Visual Studio Build Tools');
+  }
+
+  console.log('');
+  console.log('To skip native build (limited functionality):');
+  console.log('  nodepyx_SKIP_BUILD=1 npm install nodepyx');
+  console.log('');
+  console.log('See https://nodepyx.dev/install for detailed instructions.');
+  console.log('');
+}
+
+async function main() {
+  log(`Installing nodepyx native addon for ${process.platform}-${process.arch} / Node.js ${process.version}`);
+
+  if (SKIP_BUILD) {
+    warn('nodepyx_SKIP_BUILD=1 — skipping native addon build. Functionality will be limited.');
+    return;
+  }
+
+  // 1. Try pre-built binary (fastest)
+  if (!FORCE_BUILD && tryPrebuilt()) {
+    log('✓ Pre-built binary loaded successfully');
+    return;
+  }
+
+  // 2. Try existing build
+  if (!FORCE_BUILD && tryBuildRelease()) {
+    log('✓ Existing build loaded successfully');
+    return;
+  }
+
+  // 3. Try to build from source
+  if (!hasBuildTools()) {
+    warn('node-gyp not found. Cannot build from source.');
+    printInstallHelp();
+
+    if (process.env.nodepyx_REQUIRE_NATIVE === '1') {
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (!hasPythonDev()) {
+    warn('Python development headers not found. Cannot build native addon.');
+    printInstallHelp();
+
+    if (process.env.nodepyx_REQUIRE_NATIVE === '1') {
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (buildFromSource()) {
+    log('✓ Native addon built and loaded successfully');
+  } else {
+    error('Failed to build native addon.');
+    printInstallHelp();
+
+    if (process.env.nodepyx_REQUIRE_NATIVE === '1') {
+      process.exit(1);
+    }
+  }
+}
+
+main().catch(err => {
+  error(`Unexpected error: ${err.message}`);
+  process.exit(0); // Don't fail npm install
+});
+

package/src/core/PyCallable.ts

@@ -0,0 +1,137 @@
+/**
+ * nodepyx — PyCallable
+ * Represents a Python callable (function, method, class constructor).
+ * Extends PyProxy with call metadata and convenience methods.
+ */
+
+import { PyProxy, PYPROXY_INTERNAL } from './PyProxy';
+import type { NativeAddon } from '../types/addon';
+import type { PyObjectId, AttributePath, PyCallableInfo } from '../types/python';
+
+/**
+ * PyCallable — wraps a Python function or method.
+ *
+ * @example
+ * ```typescript
+ * const np = await py.import('numpy');
+ * const zeros = await np.zeros;  // PyCallable
+ * const arr = await zeros([3, 3], { dtype: 'float64' });
+ *
+ * // Or more concisely:
+ * const arr2 = await np.zeros([3, 3]);
+ * ```
+ */
+export class PyCallable extends PyProxy {
+  private readonly _callableName: string;
+  private _info: PyCallableInfo | null = null;
+
+  constructor(
+    objectId: PyObjectId,
+    path: AttributePath,
+    callableName: string,
+    addon: NativeAddon,
+    callTimeout?: number
+  ) {
+    super({
+      objectId,
+      path,
+      addon,
+      isResolved: false,
+      callTimeout,
+      childCache: new Map(),
+    });
+    this._callableName = callableName;
+  }
+
+  /** Callable name */
+  get callableName(): string {
+    return this._callableName;
+  }
+
+  /**
+   * Call the callable with given arguments.
+   * Same as using the callable directly (proxy syntax).
+   *
+   * @example
+   * ```typescript
+   * const result = await callable.invoke([1, 2, 3], { axis: 0 });
+   * // equivalent to: await callable([1, 2, 3], { axis: 0 })
+   * ```
+   */
+  async invoke(...args: unknown[]): Promise<unknown> {
+    return (this as unknown as (...a: unknown[]) => unknown)(...args);
+  }
+
+  /**
+   * Call with explicit positional args and keyword args.
+   *
+   * @example
+   * ```typescript
+   * const result = await callable.call([1, 2, 3], { axis: 0, keepdims: true });
+   * ```
+   */
+  async call(args: unknown[], kwargs?: Record<string, unknown>): Promise<unknown> {
+    if (kwargs) {
+      return (this as unknown as (...a: unknown[]) => unknown)(...args, kwargs);
+    }
+    return (this as unknown as (...a: unknown[]) => unknown)(...args);
+  }
+
+  /**
+   * Partially apply arguments (like functools.partial in Python).
+   *
+   * @example
+   * ```typescript
+   * const readCsvUtf8 = await pd.read_csv.partial({ encoding: 'utf-8' });
+   * const df = await readCsvUtf8('data.csv');
+   * ```
+   */
+  partial(...partialArgs: unknown[]): PyCallable {
+    const internal = this[PYPROXY_INTERNAL];
+    const callableName = `${this._callableName}(partial)`;
+    const wrapper = new PyCallable(
+      internal.objectId,
+      internal.path,
+      callableName,
+      internal.addon,
+      internal.callTimeout
+    );
+
+    // Override: always prepend partialArgs (use arrow to capture outer `this` lexically)
+    const callSelf = (...a: unknown[]) =>
+      (this as unknown as (...x: unknown[]) => unknown)(...a);
+    const overrideProxy = new Proxy(wrapper, {
+      apply(_target, _thisArg, args: unknown[]) {
+        return callSelf(...partialArgs, ...args);
+      },
+    });
+
+    return overrideProxy as PyCallable;
+  }
+
+  /**
+   * Get introspection information about this callable.
+   */
+  async getInfo(): Promise<PyCallableInfo | null> {
+    if (this._info) {return this._info;}
+
+    // Not yet implemented — would require Python introspection
+    return null;
+  }
+
+  static fromProxy(proxy: PyProxy, name: string): PyCallable {
+    const internal = proxy[PYPROXY_INTERNAL];
+    return new PyCallable(
+      internal.objectId,
+      internal.path,
+      name,
+      internal.addon,
+      internal.callTimeout
+    );
+  }
+
+  override toString(): string {
+    return `[PyCallable '${this._callableName}' id=${this[PYPROXY_INTERNAL].objectId}]`;
+  }
+}
+

package/src/core/PyContext.ts

@@ -0,0 +1,296 @@
+/**
+ * nodepyx — PyContext
+ * Manages an isolated Python execution context (namespace).
+ * Useful for running code in isolation without polluting the global namespace.
+ */
+
+import type { NativeAddon } from '../types/addon';
+import type { PyObjectId } from '../types/python';
+import { PyProxy, PYPROXY_INTERNAL } from './PyProxy';
+import { translatePythonError } from '../utils/ErrorTranslator';
+import { Logger } from '../utils/Logger';
+
+const logger = new Logger('PyContext');
+
+/**
+ * PyContext — an isolated Python execution environment.
+ *
+ * @example
+ * ```typescript
+ * const ctx = await PyContext.create(addon);
+ *
+ * // Run code in isolation
+ * await ctx.exec('x = 42');
+ * await ctx.exec('y = x * 2');
+ * const result = await ctx.eval('x + y');
+ * console.log(result);  // 126
+ *
+ * // Import into context
+ * const pd = await ctx.import('pandas');
+ * await ctx.exec("df = pd.DataFrame({'a': [1,2,3]})");
+ * const df = await ctx.get('df');
+ * ```
+ */
+export class PyContext {
+  private readonly _addon: NativeAddon;
+  private readonly _namespacePyId: PyObjectId;
+  private _variables: Map<string, PyObjectId>;
+  private _destroyed = false;
+
+  private constructor(addon: NativeAddon, namespacePyId: PyObjectId) {
+    this._addon = addon;
+    this._namespacePyId = namespacePyId;
+    this._variables = new Map();
+  }
+
+  /**
+   * Create a new isolated Python context.
+   */
+  static async create(addon: NativeAddon): Promise<PyContext> {
+    // Create a fresh namespace dict in Python
+    const result = await addon.evalPython('{}') as {
+      success?: boolean;
+      objectId?: number;
+      isObject?: boolean;
+      error?: { type: string; message: string; traceback: string };
+    };
+
+    if (!result.success) {
+      if (result.error) {
+        throw translatePythonError({
+          type: result.error.type,
+          message: result.error.message,
+          traceback: result.error.traceback || '',
+        });
+      }
+      throw new Error('Failed to create Python context');
+    }
+
+    if (!result.objectId) {
+      throw new Error('Context namespace object ID not returned');
+    }
+
+    return new PyContext(addon, result.objectId as PyObjectId);
+  }
+
+  /**
+   * Execute Python code in this context.
+   */
+  async exec(code: string): Promise<void> {
+    this._ensureNotDestroyed();
+
+    const result = await this._addon.runPythonCode(code) as {
+      success?: boolean;
+      error?: { type: string; message: string; traceback: string };
+    };
+
+    if (!result.success && result.error) {
+      throw translatePythonError({
+        type: result.error.type,
+        message: result.error.message,
+        traceback: result.error.traceback || '',
+      });
+    }
+  }
+
+  /**
+   * Evaluate a Python expression in this context and return the result.
+   */
+  async eval(expression: string): Promise<unknown> {
+    this._ensureNotDestroyed();
+
+    const result = await this._addon.evalPython(expression) as {
+      success?: boolean;
+      resultJson?: string;
+      objectId?: number;
+      isObject?: boolean;
+      error?: { type: string; message: string; traceback: string };
+    };
+
+    if (!result.success) {
+      if (result.error) {
+        throw translatePythonError({
+          type: result.error.type,
+          message: result.error.message,
+          traceback: result.error.traceback || '',
+        });
+      }
+      throw new Error('Evaluation failed');
+    }
+
+    if (result.isObject && result.objectId) {
+      return PyProxy._createFromObjectId(
+        result.objectId as PyObjectId,
+        [],
+        this._addon
+      );
+    }
+
+    if (result.resultJson !== undefined) {
+      try {
+        return JSON.parse(result.resultJson);
+      } catch {
+        return result.resultJson;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Import a module into this context.
+   */
+  async import(moduleName: string): Promise<PyProxy> {
+    this._ensureNotDestroyed();
+
+    const result = await this._addon.importModule(moduleName) as {
+      success?: boolean;
+      objectId?: number;
+      error?: { type: string; message: string; traceback: string };
+    };
+
+    if (!result.success) {
+      if (result.error) {
+        throw translatePythonError({
+          type: result.error.type,
+          message: result.error.message,
+          traceback: result.error.traceback || '',
+        });
+      }
+      throw new Error(`Failed to import module '${moduleName}'`);
+    }
+
+    if (!result.objectId) {
+      throw new Error('Module object ID not returned');
+    }
+
+    return PyProxy._createFromObjectId(
+      result.objectId as PyObjectId,
+      [],
+      this._addon
+    );
+  }
+
+  /**
+   * Get a variable from the context namespace.
+   */
+  async get(name: string): Promise<unknown> {
+    this._ensureNotDestroyed();
+
+    const pyId = this._variables.get(name);
+
+    if (pyId) {
+      return PyProxy._createFromObjectId(pyId, [], this._addon);
+    }
+
+    // Try to get from Python global namespace
+    const result = await this._addon.evalPython(name) as {
+      success?: boolean;
+      resultJson?: string;
+      objectId?: number;
+      isObject?: boolean;
+      error?: { type: string; message: string; traceback: string };
+    };
+
+    if (!result.success) {
+      if (result.error?.type === 'NameError') {
+        return undefined;
+      }
+      if (result.error) {
+        throw translatePythonError({
+          type: result.error.type,
+          message: result.error.message,
+          traceback: result.error.traceback || '',
+        });
+      }
+      return undefined;
+    }
+
+    if (result.isObject && result.objectId) {
+      return PyProxy._createFromObjectId(
+        result.objectId as PyObjectId,
+        [],
+        this._addon
+      );
+    }
+
+    if (result.resultJson !== undefined) {
+      try {
+        return JSON.parse(result.resultJson);
+      } catch {
+        return result.resultJson;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Set a variable in the context namespace.
+   */
+  async set(name: string, value: unknown): Promise<void> {
+    this._ensureNotDestroyed();
+
+    if (value instanceof PyProxy) {
+      const internal = value[PYPROXY_INTERNAL];
+      this._variables.set(name, internal.objectId);
+      return;
+    }
+
+    // For primitives and serializable values: set via exec
+    const serialized = JSON.stringify(value);
+    await this.exec(`${name} = __import__('json').loads('${serialized.replace(/'/g, "\\'")}')`);
+  }
+
+  /**
+   * Check if a name is defined in the context.
+   */
+  async has(name: string): Promise<boolean> {
+    this._ensureNotDestroyed();
+    try {
+      const val = await this.get(name);
+      return val !== undefined;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Delete a variable from the context.
+   */
+  async delete(name: string): Promise<void> {
+    this._ensureNotDestroyed();
+    this._variables.delete(name);
+    await this.exec(`del ${name}`).catch(() => {}); // ignore if not defined
+  }
+
+  /**
+   * Clear all variables in the context.
+   */
+  async clear(): Promise<void> {
+    this._ensureNotDestroyed();
+    this._variables.clear();
+  }
+
+  /**
+   * Destroy the context and free resources.
+   */
+  async destroy(): Promise<void> {
+    if (this._destroyed) {return;}
+    this._destroyed = true;
+    this._variables.clear();
+    this._addon.decRef(this._namespacePyId as number);
+    logger.debug('PyContext destroyed');
+  }
+
+  private _ensureNotDestroyed(): void {
+    if (this._destroyed) {
+      throw new Error('PyContext has been destroyed');
+    }
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.destroy();
+  }
+}
+