nodepyx 1.0.0

package/dist/core/PyProxy.js

@@ -0,0 +1,483 @@
+"use strict";
+/**
+ * nodepyx — PyProxy
+ *
+ * The heart of nodepyx's JavaScript API.
+ * Every Python object is represented as a PyProxy — a JavaScript Proxy that:
+ *
+ * 1. Intercepts property access → creates lazy child PyProxy
+ * 2. Intercepts function call → sends to Python worker thread
+ * 3. Intercepts `then` → resolves the proxy chain into a value (makes it awaitable)
+ * 4. Intercepts Symbol.iterator → enables for...of loops
+ * 5. Intercepts Symbol.asyncIterator → enables for await...of loops
+ * 6. Intercepts property assignment → sets Python attribute
+ *
+ * The key insight: attributes are NOT resolved eagerly. The chain
+ * `df.groupby('country').agg({'sales': 'sum'}).reset_index()`
+ * creates a chain of PyProxy objects, each recording the operation,
+ * and only executes when you `await` the final result.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyProxy = exports.PYPROXY_PATH = exports.PYPROXY_OBJECTID = exports.PYPROXY_INTERNAL = void 0;
+exports.isPyProxy = isPyProxy;
+const ErrorTranslator_1 = require("../utils/ErrorTranslator");
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('PyProxy');
+// Internal symbols used to brand PyProxy and access internals
+exports.PYPROXY_INTERNAL = Symbol('nodepyx.internal');
+exports.PYPROXY_OBJECTID = Symbol('nodepyx.objectId');
+exports.PYPROXY_PATH = Symbol('nodepyx.path');
+/**
+ * PyProxy — wraps any Python object in JavaScript.
+ *
+ * Usage:
+ * ```typescript
+ * const pd = await py.import('pandas');
+ * const df = await pd.read_csv('data.csv');  // df is a PyProxy
+ * const rows = await df.describe().to_dict('records');  // chained calls
+ * ```
+ */
+class PyProxy {
+    /** Internal state — do not access directly from outside */
+    [exports.PYPROXY_INTERNAL];
+    constructor(internal) {
+        this[exports.PYPROXY_INTERNAL] = internal;
+        return new Proxy(this, PyProxy.handler);
+    }
+    // ─── Proxy Handler ─────────────────────────────────────────────────────────
+    static handler = {
+        get(target, prop, receiver) {
+            const internal = target[exports.PYPROXY_INTERNAL];
+            // ── Internal Symbol Access ──────────────────────────────────────────
+            if (prop === exports.PYPROXY_INTERNAL || prop === exports.PYPROXY_OBJECTID || prop === exports.PYPROXY_PATH) {
+                return Reflect.get(target, prop, receiver);
+            }
+            // ── JavaScript built-in symbols ──────────────────────────────────────
+            if (typeof prop === 'symbol') {
+                // Make for...of work (synchronous iteration via async iterator)
+                if (prop === Symbol.asyncIterator) {
+                    return () => target._makeAsyncIterator(internal);
+                }
+                // Symbol.iterator — not directly supported for Python objects
+                if (prop === Symbol.iterator) {
+                    return () => {
+                        throw new Error('Python objects are not synchronously iterable from JavaScript. ' +
+                            'Use "for await...of" instead.');
+                    };
+                }
+                // Symbol.toPrimitive — for coercion
+                if (prop === Symbol.toPrimitive) {
+                    return (hint) => {
+                        if (hint === 'string') {
+                            return `[PyProxy id=${internal.objectId}]`;
+                        }
+                        return NaN;
+                    };
+                }
+                // Symbol.toStringTag
+                if (prop === Symbol.toStringTag) {
+                    return 'PyProxy';
+                }
+                return Reflect.get(target, prop, receiver);
+            }
+            // ── toString / valueOf ────────────────────────────────────────────────
+            if (prop === 'toString') {
+                return () => `[PyProxy id=${internal.objectId} path=${internal.path.join('.')}]`;
+            }
+            if (prop === 'valueOf') {
+                return () => target;
+            }
+            // ── then (Thenable — makes it work with await) ─────────────────────────
+            if (prop === 'then') {
+                return (onfulfilled, onrejected) => {
+                    return target._resolve(internal).then(onfulfilled, onrejected);
+                };
+            }
+            // ── catch / finally (Promise chain support) ───────────────────────────
+            if (prop === 'catch') {
+                return (onrejected) => target._resolve(internal).catch(onrejected);
+            }
+            if (prop === 'finally') {
+                return (onfinally) => target._resolve(internal).finally(onfinally);
+            }
+            // ── Internal nodepyx methods ───────────────────────────────────────────
+            if (prop.startsWith('__nodepyx_')) {
+                return Reflect.get(target, prop, receiver);
+            }
+            // ── Check child cache (optimization) ──────────────────────────────────
+            if (internal.childCache.has(prop)) {
+                return internal.childCache.get(prop);
+            }
+            // ── Create lazy child PyProxy ──────────────────────────────────────────
+            const childInternal = {
+                objectId: internal.objectId,
+                path: [...internal.path, prop],
+                addon: internal.addon,
+                isResolved: false,
+                callTimeout: internal.callTimeout,
+                childCache: new Map(),
+            };
+            const child = new PyProxy(childInternal);
+            // Cache it for repeated access
+            if (internal.addon) {
+                internal.childCache.set(prop, child);
+            }
+            return child;
+        },
+        // ── Function call (proxy() or proxy.method()) ──────────────────────────
+        apply(target, _thisArg, args) {
+            const internal = target[exports.PYPROXY_INTERNAL];
+            return target._call(internal, args);
+        },
+        // ── Property assignment ────────────────────────────────────────────────
+        set(target, prop, value) {
+            const internal = target[exports.PYPROXY_INTERNAL];
+            if (typeof prop === 'symbol' || prop.startsWith('__nodepyx_')) {
+                return Reflect.set(target, prop, value);
+            }
+            // Schedule async setAttribute (best-effort, no await)
+            target._setAttr(internal, String(prop), value).catch(err => {
+                logger.error(`Failed to set Python attribute '${String(prop)}'`, err);
+            });
+            return true;
+        },
+        // ── has() — needed for 'in' operator ──────────────────────────────────
+        has(_target, _prop) {
+            // We can't know without checking Python; return true for everything
+            return true;
+        },
+        // ── deleteProperty ────────────────────────────────────────────────────
+        deleteProperty(target, prop) {
+            if (typeof prop === 'string') {
+                const internal = target[exports.PYPROXY_INTERNAL];
+                internal.addon.deleteAttribute(internal.objectId, prop).catch(err => {
+                    logger.error(`Failed to delete Python attribute '${prop}'`, err);
+                });
+                internal.childCache.delete(prop);
+            }
+            return true;
+        },
+        // ── ownKeys — for Object.keys() ───────────────────────────────────────
+        ownKeys(_target) {
+            // Can't synchronously get Python keys; return empty
+            return [];
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (typeof prop === 'symbol') {
+                return undefined;
+            }
+            return {
+                enumerable: false,
+                configurable: true,
+                writable: false,
+                value: undefined,
+            };
+        },
+    };
+    // ─── Resolution (await) ────────────────────────────────────────────────────
+    async _resolve(internal) {
+        try {
+            const addon = internal.addon;
+            if (internal.path.length === 0) {
+                // Resolve the object itself
+                const result = await addon.getObjectValue(internal.objectId);
+                return PyProxy._deserializeAddonResult(result, internal);
+            }
+            // Resolve attribute path
+            const result = await addon.getAttributePath(internal.objectId, internal.path);
+            return PyProxy._deserializeAddonResult(result, internal);
+        }
+        catch (err) {
+            if (err && typeof err === 'object' && 'pythonType' in err) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: err.pythonType,
+                    message: err.message,
+                    traceback: err.pythonTraceback || '',
+                });
+            }
+            throw err;
+        }
+    }
+    // ─── Function Call ─────────────────────────────────────────────────────────
+    async _call(internal, args) {
+        try {
+            const addon = internal.addon;
+            // Serialize arguments
+            const serializedArgs = await Promise.all(args.map(arg => PyProxy._serializeArg(arg)));
+            const callOptions = {
+                args: serializedArgs,
+                kwargs: {},
+                timeout: internal.callTimeout,
+            };
+            // If last arg is a plain object (not PyProxy/Array), treat as kwargs
+            if (args.length > 0) {
+                const lastArg = args[args.length - 1];
+                if (lastArg !== null &&
+                    typeof lastArg === 'object' &&
+                    !Array.isArray(lastArg) &&
+                    !(lastArg instanceof PyProxy) &&
+                    !(lastArg instanceof ArrayBuffer) &&
+                    !ArrayBuffer.isView(lastArg) &&
+                    !('__pyref__' in lastArg) &&
+                    PyProxy._isPlainObject(lastArg)) {
+                    // Treat as kwargs
+                    callOptions.args = serializedArgs.slice(0, -1);
+                    const kwargsEntries = await Promise.all(Object.entries(lastArg).map(async ([k, v]) => [k, await PyProxy._serializeArg(v)]));
+                    callOptions.kwargs = Object.fromEntries(kwargsEntries);
+                }
+            }
+            const result = await addon.callFunction(internal.objectId, internal.path, callOptions);
+            return PyProxy._deserializeAddonResult(result, internal);
+        }
+        catch (err) {
+            if (err && typeof err === 'object' && 'pythonType' in err) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: err.pythonType,
+                    message: err.message,
+                    traceback: err.pythonTraceback || '',
+                });
+            }
+            throw err;
+        }
+    }
+    // ─── Async Iterator (for await...of) ──────────────────────────────────────
+    async *_makeAsyncIterator(internal) {
+        const addon = internal.addon;
+        // Create Python iterator
+        const iterResult = await addon.createIterator(internal.objectId, internal.path);
+        const iteratorResult = iterResult;
+        if (!iteratorResult.success) {
+            const err = iteratorResult.error;
+            if (err) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: err.type,
+                    message: err.message,
+                    traceback: err.traceback || '',
+                });
+            }
+            throw new Error('Failed to create Python iterator');
+        }
+        // Parse iteratorId from resultJson
+        let iteratorId;
+        try {
+            const parsed = JSON.parse(iterResult.resultJson || '{}');
+            iteratorId = parsed.iteratorId;
+        }
+        catch {
+            throw new Error('Failed to parse iterator ID');
+        }
+        if (!iteratorId) {
+            throw new Error('Iterator ID not returned from Python');
+        }
+        try {
+            while (true) {
+                const next = await addon.iteratorNext(iteratorId);
+                const nextResult = next;
+                if (!nextResult.success) {
+                    break;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(nextResult.resultJson || '{"done":true}');
+                }
+                catch {
+                    break;
+                }
+                if (parsed.done) {
+                    break;
+                }
+                // Deserialize the value
+                const value = parsed.value;
+                if (value && typeof value === 'object' && '__pyref__' in value) {
+                    const refId = value.__pyref__;
+                    yield PyProxy._createFromObjectId(refId, [], addon, internal.callTimeout);
+                }
+                else {
+                    yield value;
+                }
+            }
+        }
+        finally {
+            // Always destroy the iterator
+            await addon.destroyIterator(iteratorId).catch(() => { });
+        }
+    }
+    // ─── Set Attribute ────────────────────────────────────────────────────────
+    async _setAttr(internal, propName, value) {
+        const serialized = await PyProxy._serializeArg(value);
+        await internal.addon.setAttribute(internal.objectId, propName, serialized);
+        // Invalidate cache
+        internal.childCache.delete(propName);
+    }
+    // ─── Static Helpers ────────────────────────────────────────────────────────
+    static _createFromObjectId(objectId, path, addon, callTimeout) {
+        return new PyProxy({
+            objectId,
+            path,
+            addon,
+            isResolved: false,
+            callTimeout,
+            childCache: new Map(),
+        });
+    }
+    static _deserializeAddonResult(result, internal) {
+        const r = result;
+        if (!r.success) {
+            if (r.error) {
+                throw (0, ErrorTranslator_1.translatePythonError)({
+                    type: r.error.type,
+                    message: r.error.message,
+                    traceback: r.error.traceback || '',
+                });
+            }
+            throw new Error('Python call failed without error details');
+        }
+        if (r.isObject && r.objectId) {
+            // Result is a Python object — wrap in PyProxy
+            return PyProxy._createFromObjectId(r.objectId, [], internal.addon, internal.callTimeout);
+        }
+        // Deserialize JSON result
+        if (r.resultJson !== undefined && r.resultJson !== null) {
+            try {
+                const parsed = JSON.parse(r.resultJson);
+                if (parsed && typeof parsed === 'object' && '__pyref__' in parsed) {
+                    return PyProxy._createFromObjectId(parsed.__pyref__, [], internal.addon, internal.callTimeout);
+                }
+                return parsed;
+            }
+            catch {
+                return r.resultJson;
+            }
+        }
+        return null;
+    }
+    static async _serializeArg(value) {
+        // Already a SerializedValue
+        if (value !== null &&
+            typeof value === 'object' &&
+            'format' in value) {
+            return value;
+        }
+        // PyProxy → pass as Python reference
+        if (value instanceof PyProxy) {
+            const internal = value[exports.PYPROXY_INTERNAL];
+            // If proxy has a path, resolve it first to get the objectId
+            if (internal.path.length > 0) {
+                // We need to resolve it — for now, keep as reference
+                // Production: could pre-resolve path to objectId
+            }
+            return {
+                format: 6, // PYTHON_REF
+                data: null,
+                metadata: { objectId: internal.objectId },
+            };
+        }
+        // null / undefined
+        if (value === null || value === undefined) {
+            return { format: 0, data: 'null', metadata: {} };
+        }
+        // TypedArrays → numpy-compatible binary
+        if (value instanceof Float32Array ||
+            value instanceof Float64Array ||
+            value instanceof Int8Array ||
+            value instanceof Int16Array ||
+            value instanceof Int32Array ||
+            value instanceof Uint8Array ||
+            value instanceof Uint16Array ||
+            value instanceof Uint32Array ||
+            value instanceof BigInt64Array ||
+            value instanceof BigUint64Array) {
+            const ta = value;
+            const dtype = PyProxy._getTypedArrayDtype(ta);
+            return {
+                format: 2, // NUMPY_ARRAY
+                data: new Uint8Array(ta.buffer, ta.byteOffset, ta.byteLength),
+                metadata: {
+                    dtype,
+                    shape: [ta.length],
+                },
+            };
+        }
+        // ArrayBuffer
+        if (value instanceof ArrayBuffer) {
+            return {
+                format: 7, // BYTES
+                data: new Uint8Array(value),
+                metadata: {},
+            };
+        }
+        // Primitive types
+        if (typeof value === 'number' ||
+            typeof value === 'string' ||
+            typeof value === 'boolean') {
+            return {
+                format: 0, // JSON
+                data: JSON.stringify(value),
+                metadata: {},
+            };
+        }
+        // Array or object — use JSON
+        try {
+            return {
+                format: 0, // JSON
+                data: JSON.stringify(value),
+                metadata: {},
+            };
+        }
+        catch {
+            // Can't serialize — this shouldn't happen for plain objects
+            return { format: 8, data: null, metadata: {} }; // NONE
+        }
+    }
+    static _getTypedArrayDtype(arr) {
+        if (arr instanceof Float32Array) {
+            return 'float32';
+        }
+        if (arr instanceof Float64Array) {
+            return 'float64';
+        }
+        if (arr instanceof Int8Array) {
+            return 'int8';
+        }
+        if (arr instanceof Int16Array) {
+            return 'int16';
+        }
+        if (arr instanceof Int32Array) {
+            return 'int32';
+        }
+        if (arr instanceof BigInt64Array) {
+            return 'int64';
+        }
+        if (arr instanceof Uint8Array) {
+            return 'uint8';
+        }
+        if (arr instanceof Uint16Array) {
+            return 'uint16';
+        }
+        if (arr instanceof Uint32Array) {
+            return 'uint32';
+        }
+        if (arr instanceof BigUint64Array) {
+            return 'uint64';
+        }
+        return 'uint8';
+    }
+    static _isPlainObject(obj) {
+        if (!obj || typeof obj !== 'object') {
+            return false;
+        }
+        const proto = Object.getPrototypeOf(obj);
+        return proto === null || proto === Object.prototype;
+    }
+}
+exports.PyProxy = PyProxy;
+/**
+ * Check if a value is a PyProxy.
+ */
+function isPyProxy(value) {
+    return (value instanceof PyProxy ||
+        (value !== null &&
+            typeof value === 'object' &&
+            exports.PYPROXY_INTERNAL in value));
+}
+//# sourceMappingURL=PyProxy.js.map

package/dist/core/PyProxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PyProxy.js","sourceRoot":"","sources":["../../src/core/PyProxy.ts"],"names":[],"mappings":"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"}

package/dist/core/PyRuntime.d.ts

@@ -0,0 +1,105 @@
+/**
+ * nodepyx — PyRuntime
+ * The central manager for the Python interpreter lifecycle.
+ * Creates, configures, and shuts down the embedded CPython instance.
+ */
+import type { NativeAddon } from '../types/addon';
+import type { nodepyxConfig, ResolvednodepyxConfig } from '../types/config';
+import { PyModule } from './PyModule';
+import { PyContext } from './PyContext';
+/**
+ * PyRuntime — manages the lifecycle of the embedded Python interpreter.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await PyRuntime.create({
+ *   virtualenv: { path: '.venv', packages: ['pandas'], autoInstall: true },
+ * });
+ *
+ * const pd = await runtime.import('pandas');
+ * const df = await pd.read_csv('data.csv');
+ * const result = await df.to_dict('records');
+ *
+ * await runtime.shutdown();
+ * ```
+ */
+export declare class PyRuntime {
+    private readonly _config;
+    private readonly _addon;
+    private readonly _serializer;
+    private readonly _typeGenerator;
+    private readonly _pluginManager;
+    private readonly _memoryMonitor;
+    private readonly _moduleCache;
+    private _running;
+    private constructor();
+    /**
+     * Create and initialize a PyRuntime instance.
+     */
+    static create(config?: nodepyxConfig): Promise<PyRuntime>;
+    private _initialize;
+    private _setupPythonEnvironment;
+    private _bootstrapPythonRuntime;
+    /**
+     * Import a Python module and return a PyProxy.
+     *
+     * @example
+     * ```typescript
+     * const pd = await runtime.import('pandas');
+     * const df = await pd.read_csv('data.csv');
+     * ```
+     */
+    import(moduleName: string): Promise<PyModule>;
+    /**
+     * Import multiple modules at once (concurrent).
+     */
+    importAll(moduleNames: string[]): Promise<Record<string, PyModule>>;
+    /**
+     * Evaluate a Python expression.
+     */
+    eval(expression: string): Promise<unknown>;
+    /**
+     * Execute Python statements.
+     */
+    exec(code: string): Promise<void>;
+    /**
+     * Run a Python script file.
+     */
+    runFile(filePath: string): Promise<unknown>;
+    /**
+     * Create an isolated Python execution context.
+     */
+    createContext(): Promise<PyContext>;
+    /**
+     * Install Python packages into the active environment.
+     */
+    installPackages(packages: string[]): Promise<void>;
+    /**
+     * Get current memory statistics.
+     */
+    getMemoryStats(): ReturnType<NativeAddon['getMemoryStats']>;
+    /**
+     * Trigger Python garbage collection.
+     */
+    collectGarbage(): Promise<void>;
+    /**
+     * Get the underlying native addon.
+     * Advanced use only.
+     */
+    getAddon(): NativeAddon;
+    isRunning(): boolean;
+    getConfig(): ResolvednodepyxConfig;
+    /**
+     * Gracefully shut down the Python runtime.
+     * Releases all Python objects and finalizes the interpreter.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Synchronous shutdown (for process.on('exit') handler).
+     * Best-effort only — may not complete all cleanup.
+     */
+    shutdownSync(): void;
+    private _ensureRunning;
+    private _parseBytes;
+}
+//# sourceMappingURL=PyRuntime.d.ts.map

package/dist/core/PyRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PyRuntime.d.ts","sourceRoot":"","sources":["../../src/core/PyRuntime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG5E,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAkBxC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+B;IAC5D,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO;IAYP;;OAEG;WACU,MAAM,CAAC,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,SAAS,CAAC;YA4BrD,WAAW;YAyCX,uBAAuB;YAkCvB,uBAAuB;IA8BrC;;;;;;;;OAQG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IA0DnD;;OAEG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IASzE;;OAEG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0ChD;;OAEG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBvC;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2BjD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,SAAS,CAAC;IAOzC;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxD;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAK3D;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrC;;;OAGG;IACH,QAAQ,IAAI,WAAW;IAMvB,SAAS,IAAI,OAAO;IAIpB,SAAS,IAAI,qBAAqB;IAMlC;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB/B;;;OAGG;IACH,YAAY,IAAI,IAAI;IAWpB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,WAAW;CAUpB"}