nodepyx 1.0.0

package/src/index.ts

@@ -0,0 +1,425 @@
+/**
+ * nodepyx — Main Entry Point
+ *
+ * Run Python libraries from Node.js as if they were Native.
+ * Embeds CPython in-process via N-API addon with full TypeScript types,
+ * Proxy-based API, async/await support, and Next.js integration.
+ *
+ * @example
+ * ```typescript
+ * import { init, py } from 'nodepyx';
+ *
+ * await init({
+ *   virtualenv: {
+ *     path: './.venv',
+ *     packages: ['pandas', 'numpy'],
+ *     autoInstall: true,
+ *   },
+ * });
+ *
+ * const pd = await py.import('pandas');
+ * const df = await pd.read_csv('data.csv');
+ * const result = await df.describe().to_dict('records');
+ * ```
+ */
+
+import { PyRuntime } from './core/PyRuntime';
+import { Logger } from './utils/Logger';
+import { nodepyxNotInitializedError } from './utils/ErrorTranslator';
+import type { nodepyxConfig } from './types/config';
+import type { PyProxyInterface } from './types/python';
+
+// ─── Singleton Runtime Management ──────────────────────────────────────────
+
+let _runtime: PyRuntime | null = null;
+let _initializing = false;
+let _initPromise: Promise<void> | null = null;
+
+const _logger = new Logger('nodepyx');
+
+// ─── Main py Object (Proxy over PyRuntime) ─────────────────────────────────
+
+/**
+ * The main `py` object — a proxy over the PyRuntime singleton.
+ * Provides access to all PyRuntime methods after initialization.
+ *
+ * @throws {nodepyxNotInitializedError} if accessed before calling `init()`
+ */
+export const py: PyRuntime = new Proxy({} as PyRuntime, {
+  get(_target, prop: string | symbol): unknown {
+    if (!_runtime) {
+      // Provide helpful error for common misuse
+      if (prop === 'then') {
+        // Prevent silent "awaiting py" mistakes
+        return undefined;
+      }
+      throw new nodepyxNotInitializedError(
+        `Cannot access py.${String(prop)} — nodepyx is not initialized. ` +
+        `Call 'await nodepyx.init()' before using 'py'.`
+      );
+    }
+    const value = (_runtime as unknown as Record<string | symbol, unknown>)[prop];
+    if (typeof value === 'function') {
+      return value.bind(_runtime);
+    }
+    return value;
+  },
+
+  set(_target, prop: string | symbol, value: unknown): boolean {
+    if (!_runtime) {
+      throw new nodepyxNotInitializedError('nodepyx is not initialized.');
+    }
+    (_runtime as unknown as Record<string | symbol, unknown>)[prop] = value;
+    return true;
+  },
+
+  has(_target, prop: string | symbol): boolean {
+    if (!_runtime) {return false;}
+    return prop in _runtime;
+  },
+});
+
+// ─── Lifecycle Functions ────────────────────────────────────────────────────
+
+/**
+ * Initialize the nodepyx runtime.
+ * Must be called before using `py` or any other nodepyx API.
+ *
+ * Calling `init()` multiple times is safe — subsequent calls are no-ops
+ * unless `shutdown()` was called first, or `force: true` is passed.
+ *
+ * @param config - nodepyx configuration options
+ * @param options - Additional initialization options
+ * @returns Promise that resolves when Python is ready
+ *
+ * @example
+ * ```typescript
+ * await init({
+ *   virtualenv: { path: '.venv', packages: ['pandas'], autoInstall: true },
+ *   logLevel: 'info',
+ * });
+ * ```
+ */
+export async function init(
+  config?: nodepyxConfig,
+  options?: { force?: boolean }
+): Promise<void> {
+  // Already initialized
+  if (_runtime && !options?.force) {
+    _logger.debug('nodepyx already initialized, skipping');
+    return;
+  }
+
+  // Initialization in progress — wait for it
+  if (_initializing && _initPromise) {
+    return _initPromise;
+  }
+
+  // Force re-init: shut down first
+  if (_runtime && options?.force) {
+    await shutdown();
+  }
+
+  _initializing = true;
+  _initPromise = _doInit(config);
+
+  try {
+    await _initPromise;
+  } finally {
+    _initializing = false;
+    _initPromise = null;
+  }
+}
+
+async function _doInit(config?: nodepyxConfig): Promise<void> {
+  _logger.info('Initializing nodepyx runtime...');
+  const startTime = performance.now();
+
+  try {
+    _runtime = await PyRuntime.create(config);
+    const elapsed = (performance.now() - startTime).toFixed(0);
+    _logger.success(`nodepyx runtime ready in ${elapsed}ms`);
+  } catch (err) {
+    _runtime = null;
+    _logger.error('Failed to initialize nodepyx runtime', err);
+    throw err;
+  }
+}
+
+/**
+ * Shut down the nodepyx runtime and release all Python resources.
+ * After calling this, `py` is no longer accessible until `init()` is called again.
+ *
+ * @example
+ * ```typescript
+ * await shutdown();
+ * ```
+ */
+export async function shutdown(): Promise<void> {
+  if (!_runtime) {
+    _logger.debug('nodepyx not initialized, nothing to shut down');
+    return;
+  }
+
+  _logger.info('Shutting down nodepyx runtime...');
+  const runtime = _runtime;
+  _runtime = null;
+
+  try {
+    await runtime.shutdown();
+    _logger.success('nodepyx runtime shut down');
+  } catch (err) {
+    _logger.error('Error during nodepyx shutdown', err);
+    throw err;
+  }
+}
+
+/**
+ * Check if nodepyx is initialized and ready to use.
+ */
+export function isInitialized(): boolean {
+  return _runtime !== null && _runtime.isRunning();
+}
+
+/**
+ * Get the current PyRuntime instance.
+ * @throws {nodepyxNotInitializedError} if not initialized
+ */
+export function getRuntime(): PyRuntime {
+  if (!_runtime) {
+    throw new nodepyxNotInitializedError();
+  }
+  return _runtime;
+}
+
+// ─── Convenience API ────────────────────────────────────────────────────────
+
+/**
+ * Import a Python module and return a Proxy.
+ * Shorthand for `py.import(moduleName)`.
+ *
+ * @example
+ * ```typescript
+ * const np = await importModule('numpy');
+ * const arr = await np.array([1, 2, 3]);
+ * ```
+ */
+export async function importModule(moduleName: string): Promise<PyProxyInterface> {
+  if (!_runtime) {throw new nodepyxNotInitializedError();}
+  return _runtime.import(moduleName);
+}
+
+/**
+ * Evaluate a Python expression and return the result.
+ * Shorthand for `py.eval(expression)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await evalPython('1 + 2 + 3');
+ * // result === 6
+ * ```
+ */
+export async function evalPython(expression: string): Promise<unknown> {
+  if (!_runtime) {throw new nodepyxNotInitializedError();}
+  return _runtime.eval(expression);
+}
+
+/**
+ * Execute Python code (statements, not expressions).
+ * Shorthand for `py.exec(code)`.
+ *
+ * @example
+ * ```typescript
+ * await execPython(`
+ *   import sys
+ *   print(f"Python {sys.version}")
+ * `);
+ * ```
+ */
+export async function execPython(code: string): Promise<void> {
+  if (!_runtime) {throw new nodepyxNotInitializedError();}
+  return _runtime.exec(code);
+}
+
+/**
+ * Run a Python script file.
+ */
+export async function runFile(filePath: string): Promise<unknown> {
+  if (!_runtime) {throw new nodepyxNotInitializedError();}
+  return _runtime.runFile(filePath);
+}
+
+/**
+ * Install Python packages into the configured virtualenv.
+ *
+ * @example
+ * ```typescript
+ * await installPackages(['pandas', 'numpy>=1.24.0', 'scikit-learn']);
+ * ```
+ */
+export async function installPackages(packages: string[]): Promise<void> {
+  if (!_runtime) {throw new nodepyxNotInitializedError();}
+  return _runtime.installPackages(packages);
+}
+
+/**
+ * Get memory statistics for the Python heap.
+ */
+export async function getMemoryStats(): Promise<{
+  pythonHeapBytes: number;
+  pythonHeapPeakBytes: number;
+  trackedObjects: number;
+  pendingCallbacks: number;
+}> {
+  if (!_runtime) {throw new nodepyxNotInitializedError();}
+  return _runtime.getMemoryStats();
+}
+
+/**
+ * Trigger Python garbage collection.
+ */
+export async function collectGarbage(): Promise<void> {
+  if (!_runtime) {throw new nodepyxNotInitializedError();}
+  return _runtime.collectGarbage();
+}
+
+// ─── Auto-cleanup on process exit ──────────────────────────────────────────
+
+let _cleanupRegistered = false;
+
+function _registerCleanup(): void {
+  if (_cleanupRegistered) {return;}
+  _cleanupRegistered = true;
+
+  const cleanup = async () => {
+    if (_runtime) {
+      try {
+        await shutdown();
+      } catch {
+        // Ignore errors during cleanup
+      }
+    }
+  };
+
+  process.on('exit', () => {
+    // Synchronous cleanup on exit (best-effort)
+    if (_runtime) {
+      try {
+        _runtime.shutdownSync();
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  process.on('SIGINT', async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', async () => {
+    await cleanup();
+    process.exit(0);
+  });
+
+  process.on('uncaughtException', async (err) => {
+    _logger.error('Uncaught exception, shutting down nodepyx', err);
+    await cleanup();
+    throw err;
+  });
+}
+
+// Register cleanup automatically
+_registerCleanup();
+
+// ─── Exports ───────────────────────────────────────────────────────────────
+
+// Core
+export { PyRuntime } from './core/PyRuntime';
+export { PyProxy } from './core/PyProxy';
+export { PyModule } from './core/PyModule';
+export { PyCallable } from './core/PyCallable';
+export { PyIterator } from './core/PyIterator';
+export { PyContext } from './core/PyContext';
+
+// Serialization
+export { Serializer } from './serialization/Serializer';
+export { NumpyBridge } from './serialization/NumpyBridge';
+export { DataFrameBridge } from './serialization/DataFrameBridge';
+
+// Error types
+export {
+  PythonError,
+  PythonValueError,
+  PythonTypeError,
+  PythonKeyError,
+  PythonIndexError,
+  PythonAttributeError,
+  PythonImportError,
+  PythonModuleNotFoundError,
+  PythonFileNotFoundError,
+  PythonPermissionError,
+  PythonRuntimeError,
+  PythonMemoryError,
+  PythonStopIteration,
+  PythonTimeoutError,
+  nodepyxNotInitializedError,
+  nodepyxShutdownError,
+  translatePythonError,
+  isPythonError,
+  isPythonErrorOfType,
+} from './utils/ErrorTranslator';
+
+// Type generation
+export { TypeGenerator } from './types/TypeGenerator';
+
+// Environment management
+export { PythonDetector } from './env/PythonDetector';
+export { VenvManager } from './env/VenvManager';
+export { CondaManager } from './env/CondaManager';
+export { PackageInstaller } from './env/PackageInstaller';
+
+// Plugins
+export { PluginManager } from './plugins/PluginManager';
+
+// Types
+export type {
+  nodepyxConfig,
+  ResolvednodepyxConfig,
+  VirtualenvConfig,
+  CondaConfig,
+  LogLevel,
+  PyObjectId,
+  PyTypeInfo,
+  PyParamInfo,
+  PyCallableInfo,
+  PyClassInfo,
+  PyModuleInspection,
+  SerializedFormat,
+  SerializedValue,
+  PyCallResult,
+  PyErrorInfo,
+  DataFrameResult,
+  SeriesResult,
+  NumPyArrayResult,
+  PyProxyInterface,
+  AttributePath,
+  NativeAddon,
+} from './types/index';
+
+// Default export
+export default {
+  init,
+  shutdown,
+  isInitialized,
+  getRuntime,
+  py,
+  import: importModule,
+  eval: evalPython,
+  exec: execPython,
+  runFile,
+  installPackages,
+  getMemoryStats,
+  collectGarbage,
+};
+

package/src/native/gil_guard.cpp

@@ -0,0 +1,26 @@
+/**
+ * nodepyx — GIL Guard Implementation
+ * The GIL guard is header-only; this file provides explicit template
+ * instantiations and any platform-specific workarounds.
+ */
+
+#include "gil_guard.h"
+
+// All implementation is in the header file (RAII classes are trivial inline).
+// This .cpp exists to satisfy the build system and future non-inline additions.
+
+namespace nodepyx {
+
+// Verify at compile time that our RAII types are not accidentally copied
+static_assert(!std::is_copy_constructible<GILAcquire>::value,
+              "GILAcquire must not be copy-constructible");
+static_assert(!std::is_copy_constructible<GILRelease>::value,
+              "GILRelease must not be copy-constructible");
+static_assert(!std::is_copy_constructible<PyRef>::value,
+              "PyRef must not be copy-constructible");
+
+static_assert(std::is_move_constructible<PyRef>::value,
+              "PyRef must be move-constructible");
+
+} // namespace nodepyx
+

package/src/native/gil_guard.h

@@ -0,0 +1,175 @@
+/**
+ * nodepyx — GIL Guard Header
+ * RAII wrappers for the Python Global Interpreter Lock (GIL).
+ *
+ * The GIL ensures only one thread executes Python bytecode at a time.
+ * These guards make GIL management safe via RAII idiom.
+ */
+
+#pragma once
+
+#include <Python.h>
+#include <stdexcept>
+
+namespace nodepyx {
+
+/**
+ * GILAcquire — RAII guard that acquires the GIL on construction
+ * and releases it on destruction.
+ *
+ * Use when Python code needs to run in a non-Python thread (e.g. a worker thread).
+ * The calling thread must NOT already hold the GIL.
+ *
+ * @example
+ * ```cpp
+ * void worker_thread_func() {
+ *   GILAcquire gil;  // GIL acquired
+ *   PyObject* result = PyEval_EvalCode(...);
+ *   // GIL released when gil goes out of scope
+ * }
+ * ```
+ */
+class GILAcquire {
+public:
+  GILAcquire() noexcept : _state(PyGILState_Ensure()) {}
+  ~GILAcquire() noexcept { PyGILState_Release(_state); }
+
+  // Non-copyable, non-movable
+  GILAcquire(const GILAcquire&) = delete;
+  GILAcquire& operator=(const GILAcquire&) = delete;
+  GILAcquire(GILAcquire&&) = delete;
+  GILAcquire& operator=(GILAcquire&&) = delete;
+
+private:
+  PyGILState_STATE _state;
+};
+
+/**
+ * GILRelease — RAII guard that releases the GIL on construction
+ * and re-acquires it on destruction.
+ *
+ * Use to temporarily release the GIL while performing blocking I/O or
+ * other operations that don't need Python, allowing other Python threads to run.
+ * The calling thread MUST already hold the GIL.
+ *
+ * @example
+ * ```cpp
+ * // Inside Python-holding code:
+ * {
+ *   GILRelease release;  // GIL released — other Python threads can run
+ *   perform_blocking_io();
+ * }  // GIL re-acquired here
+ * ```
+ */
+class GILRelease {
+public:
+  GILRelease() noexcept : _state(PyEval_SaveThread()) {}
+  ~GILRelease() noexcept { PyEval_RestoreThread(_state); }
+
+  // Non-copyable, non-movable
+  GILRelease(const GILRelease&) = delete;
+  GILRelease& operator=(const GILRelease&) = delete;
+  GILRelease(GILRelease&&) = delete;
+  GILRelease& operator=(GILRelease&&) = delete;
+
+private:
+  PyThreadState* _state;
+};
+
+/**
+ * PyRef — RAII wrapper for PyObject* reference counting.
+ *
+ * Automatically calls Py_XDECREF on destruction.
+ * Use steal() for objects returned from Python C API with new references.
+ * Use borrow() for borrowed references (won't decref).
+ */
+class PyRef {
+public:
+  PyRef() noexcept : _obj(nullptr), _owned(false) {}
+
+  ~PyRef() noexcept {
+    reset();
+  }
+
+  /** Take ownership of an object (new reference from Python API) */
+  static PyRef steal(PyObject* obj) noexcept {
+    PyRef ref;
+    ref._obj = obj;
+    ref._owned = true;
+    return ref;
+  }
+
+  /** Borrow a reference (will Py_INCREF and Py_DECREF) */
+  static PyRef borrow(PyObject* obj) noexcept {
+    PyRef ref;
+    ref._obj = obj;
+    ref._owned = false;
+    if (obj) {
+      Py_INCREF(obj);
+      ref._owned = true;
+    }
+    return ref;
+  }
+
+  /** Increment reference count and get raw pointer */
+  PyObject* incref() const noexcept {
+    Py_XINCREF(_obj);
+    return _obj;
+  }
+
+  /** Get raw pointer without changing reference count */
+  PyObject* get() const noexcept { return _obj; }
+
+  /** Release ownership without decrementing ref count */
+  PyObject* release() noexcept {
+    PyObject* obj = _obj;
+    _obj = nullptr;
+    _owned = false;
+    return obj;
+  }
+
+  /** Reset — decrements ref count if owned */
+  void reset() noexcept {
+    if (_owned && _obj) {
+      Py_DECREF(_obj);
+    }
+    _obj = nullptr;
+    _owned = false;
+  }
+
+  /** Check if the object is valid (non-null) */
+  explicit operator bool() const noexcept { return _obj != nullptr; }
+
+  /** Check for Python exception state */
+  bool hasException() const noexcept {
+    return _obj == nullptr && PyErr_Occurred() != nullptr;
+  }
+
+  // Non-copyable
+  PyRef(const PyRef&) = delete;
+  PyRef& operator=(const PyRef&) = delete;
+
+  // Movable
+  PyRef(PyRef&& other) noexcept : _obj(other._obj), _owned(other._owned) {
+    other._obj = nullptr;
+    other._owned = false;
+  }
+
+  PyRef& operator=(PyRef&& other) noexcept {
+    if (this != &other) {
+      reset();
+      _obj = other._obj;
+      _owned = other._owned;
+      other._obj = nullptr;
+      other._owned = false;
+    }
+    return *this;
+  }
+
+private:
+  PyObject* _obj;
+  bool _owned;
+};
+
+} // namespace nodepyx
+