nodepyx 1.0.0

package/dist/core/PyModule.d.ts

@@ -0,0 +1,55 @@
+/**
+ * nodepyx — PyModule
+ * Represents a Python module with its full namespace.
+ * Inherits from PyProxy but adds module-specific introspection.
+ */
+import { PyProxy } from './PyProxy';
+import type { NativeAddon } from '../types/addon';
+import type { PyObjectId, PyModuleInspection } from '../types/python';
+/**
+ * PyModule extends PyProxy with module-specific utilities.
+ *
+ * @example
+ * ```typescript
+ * const pd = await py.import('pandas');
+ * // pd is a PyModule
+ * const df = await pd.read_csv('data.csv');  // access module attribute
+ * const info = await pd.__nodepyx_inspect__();  // get module metadata
+ * ```
+ */
+export declare class PyModule extends PyProxy {
+    private readonly _moduleName;
+    private _inspection;
+    constructor(objectId: PyObjectId, moduleName: string, addon: NativeAddon, callTimeout?: number);
+    /** The Python module name */
+    get moduleName(): string;
+    /** Object ID in Python heap */
+    get objectId(): PyObjectId;
+    /**
+     * Inspect the module — returns detailed type information.
+     * Cached after first call.
+     */
+    inspect(): Promise<PyModuleInspection>;
+    /**
+     * Get list of public names in the module (dir() equivalent).
+     */
+    getNames(): Promise<string[]>;
+    /**
+     * Check if the module has a specific attribute.
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Get module version string.
+     */
+    getVersion(): Promise<string | null>;
+    /**
+     * Reload the module (re-imports from Python).
+     */
+    reload(): Promise<void>;
+    /**
+     * Create a PyModule from an existing addon import result.
+     */
+    static fromRef(objectId: PyObjectId, moduleName: string, addon: NativeAddon, callTimeout?: number): PyModule;
+    toString(): string;
+}
+//# sourceMappingURL=PyModule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PyModule.d.ts","sourceRoot":"","sources":["../../src/core/PyModule.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKtE;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,OAAO;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,WAAW,CAAmC;gBAGpD,QAAQ,EAAE,UAAU,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM;IAatB,6BAA6B;IAC7B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,+BAA+B;IAC/B,IAAI,QAAQ,IAAI,UAAU,CAEzB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC;IA0E5C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAcnC;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKzC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAK1C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,QAAQ,EAAE,UAAU,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM,GACnB,QAAQ;IAIF,QAAQ,IAAI,MAAM;CAG5B"}

package/dist/core/PyModule.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * nodepyx — PyModule
+ * Represents a Python module with its full namespace.
+ * Inherits from PyProxy but adds module-specific introspection.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyModule = void 0;
+const PyProxy_1 = require("./PyProxy");
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('PyModule');
+/**
+ * PyModule extends PyProxy with module-specific utilities.
+ *
+ * @example
+ * ```typescript
+ * const pd = await py.import('pandas');
+ * // pd is a PyModule
+ * const df = await pd.read_csv('data.csv');  // access module attribute
+ * const info = await pd.__nodepyx_inspect__();  // get module metadata
+ * ```
+ */
+class PyModule extends PyProxy_1.PyProxy {
+    _moduleName;
+    _inspection = null;
+    constructor(objectId, moduleName, addon, callTimeout) {
+        super({
+            objectId,
+            path: [],
+            addon,
+            isResolved: false,
+            callTimeout,
+            childCache: new Map(),
+        });
+        this._moduleName = moduleName;
+    }
+    /** The Python module name */
+    get moduleName() {
+        return this._moduleName;
+    }
+    /** Object ID in Python heap */
+    get objectId() {
+        return this[PyProxy_1.PYPROXY_INTERNAL].objectId;
+    }
+    /**
+     * Inspect the module — returns detailed type information.
+     * Cached after first call.
+     */
+    async inspect() {
+        if (this._inspection) {
+            return this._inspection;
+        }
+        const addon = this[PyProxy_1.PYPROXY_INTERNAL].addon;
+        try {
+            // Run Python introspection
+            const result = await addon.runPythonCode(`
+import json
+import sys
+
+def _inspect_module_${this._moduleName.replace(/\./g, '_')}():
+    try:
+        import ${this._moduleName} as _mod
+        import inspect
+        
+        result = {
+            'name': '${this._moduleName}',
+            'file': getattr(_mod, '__file__', None),
+            'docstring': (getattr(_mod, '__doc__', '') or '')[:500],
+            'version': getattr(_mod, '__version__', None),
+            'functions': [],
+            'classes': [],
+            'constants': [],
+            'submodules': [],
+        }
+        
+        for name in dir(_mod):
+            if name.startswith('_'):
+                continue
+            try:
+                obj = getattr(_mod, name)
+                if inspect.ismodule(obj):
+                    result['submodules'].append(name)
+                elif inspect.isclass(obj):
+                    result['classes'].append({'name': name, 'type': 'class'})
+                elif callable(obj):
+                    result['functions'].append({'name': name, 'type': 'function'})
+                else:
+                    result['constants'].append({'name': name, 'type': type(obj).__name__})
+            except Exception:
+                pass
+        
+        return result
+    except Exception as e:
+        return {'name': '${this._moduleName}', 'error': str(e), 'functions': [], 'classes': [], 'constants': [], 'submodules': []}
+
+_result = _inspect_module_${this._moduleName.replace(/\./g, '_')}()
+json.dumps(_result)
+`);
+            const r = result;
+            if (r.success && r.resultJson) {
+                const parsed = JSON.parse(r.resultJson.replace(/^"|"$/g, '').replace(/\\"/g, '"'));
+                this._inspection = parsed;
+                return this._inspection;
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to inspect module ${this._moduleName}`, err);
+        }
+        // Return minimal inspection
+        this._inspection = {
+            name: this._moduleName,
+            docstring: '',
+            functions: [],
+            classes: [],
+            constants: [],
+            submodules: [],
+        };
+        return this._inspection;
+    }
+    /**
+     * Get list of public names in the module (dir() equivalent).
+     */
+    async getNames() {
+        const addon = this[PyProxy_1.PYPROXY_INTERNAL].addon;
+        const result = await addon.getObjectKeys(this.objectId);
+        const r = result;
+        if (r.success && r.resultJson) {
+            try {
+                return JSON.parse(r.resultJson);
+            }
+            catch {
+                return [];
+            }
+        }
+        return [];
+    }
+    /**
+     * Check if the module has a specific attribute.
+     */
+    async has(name) {
+        const addon = this[PyProxy_1.PYPROXY_INTERNAL].addon;
+        return addon.hasAttribute(this.objectId, name);
+    }
+    /**
+     * Get module version string.
+     */
+    async getVersion() {
+        const inspection = await this.inspect();
+        return inspection.version ?? null;
+    }
+    /**
+     * Reload the module (re-imports from Python).
+     */
+    async reload() {
+        const addon = this[PyProxy_1.PYPROXY_INTERNAL].addon;
+        await addon.reloadModule(this.objectId);
+        this._inspection = null; // Clear inspection cache
+        this[PyProxy_1.PYPROXY_INTERNAL].childCache.clear(); // Clear attribute cache
+        logger.debug(`Module ${this._moduleName} reloaded`);
+    }
+    /**
+     * Create a PyModule from an existing addon import result.
+     */
+    static fromRef(objectId, moduleName, addon, callTimeout) {
+        return new PyModule(objectId, moduleName, addon, callTimeout);
+    }
+    toString() {
+        return `[PyModule '${this._moduleName}' id=${this.objectId}]`;
+    }
+}
+exports.PyModule = PyModule;
+//# sourceMappingURL=PyModule.js.map

package/dist/core/PyModule.js.map

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

package/dist/core/PyProxy.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+import type { NativeAddon } from '../types/addon';
+import type { PyObjectId, AttributePath, SerializedValue } from '../types/python';
+export declare const PYPROXY_INTERNAL: unique symbol;
+export declare const PYPROXY_OBJECTID: unique symbol;
+export declare const PYPROXY_PATH: unique symbol;
+/**
+ * Internal state of a PyProxy.
+ */
+export interface PyProxyInternal {
+    objectId: PyObjectId;
+    path: AttributePath;
+    addon: NativeAddon;
+    isResolved: boolean;
+    callTimeout?: number;
+    /** Cache of child proxies keyed by attribute name */
+    childCache: Map<string, PyProxy>;
+}
+/**
+ * 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
+ * ```
+ */
+export declare class PyProxy {
+    /** Internal state — do not access directly from outside */
+    readonly [PYPROXY_INTERNAL]: PyProxyInternal;
+    constructor(internal: PyProxyInternal);
+    static readonly handler: ProxyHandler<PyProxy>;
+    private _resolve;
+    private _call;
+    private _makeAsyncIterator;
+    private _setAttr;
+    static _createFromObjectId(objectId: PyObjectId, path: AttributePath, addon: NativeAddon, callTimeout?: number): PyProxy;
+    static _deserializeAddonResult(result: unknown, internal: PyProxyInternal): unknown;
+    static _serializeArg(value: unknown): Promise<SerializedValue>;
+    static _getTypedArrayDtype(arr: ArrayBufferView): string;
+    static _isPlainObject(obj: unknown): boolean;
+}
+/**
+ * Check if a value is a PyProxy.
+ */
+export declare function isPyProxy(value: unknown): value is PyProxy;
+//# sourceMappingURL=PyProxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PyProxy.d.ts","sourceRoot":"","sources":["../../src/core/PyProxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAOzB,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAC3D,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAC3D,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,UAAU,CAAC;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,eAAe,CAAC;gBAEjC,QAAQ,EAAE,eAAe;IAOrC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,CA6J5C;YAIY,QAAQ;YA8BR,KAAK;YA4DJ,kBAAkB;YAyEnB,QAAQ;IAiBtB,MAAM,CAAC,mBAAmB,CACxB,QAAQ,EAAE,UAAU,EACpB,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO;IAWV,MAAM,CAAC,uBAAuB,CAC5B,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,eAAe,GACxB,OAAO;WAmDG,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IA0FpE,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM;IAcxD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;CAK7C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAS1D"}