pynect 0.0.0 → 0.2.1

package/dist/core/py-module.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * pynect - 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 py_proxy_1 = require("./py-proxy");
+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.__pynect_inspect__();  // get module metadata
+ * ```
+ */
+class PyModule extends py_proxy_1.PyProxy {
+    _moduleName;
+    constructor(objectId, moduleName, addon, callTimeout, executionTimeout) {
+        super({
+            objectId,
+            path: [],
+            addon,
+            callTimeout,
+            executionTimeout,
+        });
+        this._moduleName = moduleName;
+    }
+    /** The Python module name */
+    get moduleName() {
+        return this._moduleName;
+    }
+    /** Object ID in Python heap */
+    get objectId() {
+        return this[py_proxy_1.PYPROXY_INTERNAL].objectId;
+    }
+    /**
+     * Inspect the module and return detailed type information.
+     */
+    async inspect() {
+        const addon = this[py_proxy_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, '"'));
+                return parsed;
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to inspect module ${this._moduleName}`, err);
+        }
+        // Return minimal inspection
+        return {
+            name: this._moduleName,
+            docstring: '',
+            functions: [],
+            classes: [],
+            constants: [],
+            submodules: [],
+        };
+    }
+    /**
+     * Get list of public names in the module (dir() equivalent).
+     */
+    async getNames() {
+        const addon = this[py_proxy_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[py_proxy_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[py_proxy_1.PYPROXY_INTERNAL].addon;
+        await addon.reloadModule(this.objectId);
+        logger.debug(`Module ${this._moduleName} reloaded`);
+    }
+    /**
+     * Create a PyModule from an existing addon import result.
+     */
+    static fromRef(objectId, moduleName, addon, callTimeout, executionTimeout) {
+        return new PyModule(objectId, moduleName, addon, callTimeout, executionTimeout);
+    }
+    toString() {
+        return `[PyModule '${this._moduleName}' id=${this.objectId}]`;
+    }
+}
+exports.PyModule = PyModule;
+//# sourceMappingURL=py-module.js.map

package/dist/core/py-module.js.map

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

package/dist/core/py-proxy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * pynect - PyProxy
+ *
+ * The heart of pynect'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, PyCallOptions } 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;
+export declare const PYNECT_WITH_OPTIONS: unique symbol;
+export type PynectFunction<FunctionType extends (...args: never[]) => Promise<unknown>> = FunctionType & {
+    withOptions(options: PyCallOptions, ...args: Parameters<FunctionType>): ReturnType<FunctionType>;
+    [PYNECT_WITH_OPTIONS](options: PyCallOptions, ...args: Parameters<FunctionType>): ReturnType<FunctionType>;
+};
+/**
+ * Internal state of a PyProxy.
+ */
+export interface PyProxyInternal {
+    objectId: PyObjectId;
+    path: AttributePath;
+    addon: NativeAddon;
+    callTimeout?: number;
+    executionTimeout?: number;
+}
+/**
+ * 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;
+    callWithOptions(args: unknown[], options?: PyCallOptions, kwargs?: Record<string, unknown>): Promise<unknown>;
+    /** Call this Python function with cancellation or timeout overrides. */
+    withOptions(options: PyCallOptions, ...args: unknown[]): Promise<unknown>;
+    /** Collision-free form of withOptions(). */
+    [PYNECT_WITH_OPTIONS](options: PyCallOptions, ...args: unknown[]): Promise<unknown>;
+    private _call;
+    private _makeAsyncIterator;
+    private _setAttr;
+    static _createFromObjectId(objectId: PyObjectId, path: AttributePath, addon: NativeAddon, callTimeout?: number, executionTimeout?: number): PyProxy;
+    static _deserializeAddonResult(result: unknown, internal: PyProxyInternal): unknown;
+    private static _abortError;
+    private static _withAbort;
+    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=py-proxy.d.ts.map

package/dist/core/py-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"py-proxy.d.ts","sourceRoot":"","sources":["../../src/core/py-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAoB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAQzB,eAAO,MAAM,gBAAgB,eAA4B,CAAC;AAC1D,eAAO,MAAM,gBAAgB,eAA4B,CAAC;AAC1D,eAAO,MAAM,YAAY,eAAwB,CAAC;AAClD,eAAO,MAAM,mBAAmB,eAAmC,CAAC;AAEpE,MAAM,MAAM,cAAc,CACxB,YAAY,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,IACzD,YAAY,GAAG;IACjB,WAAW,CACT,OAAO,EAAE,aAAa,EACtB,GAAG,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,GAChC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC5B,CAAC,mBAAmB,CAAC,CACnB,OAAO,EAAE,aAAa,EACtB,GAAG,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,GAChC,UAAU,CAAC,YAAY,CAAC,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,UAAU,CAAC;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,eAAe,CAAC;gBAEjC,QAAQ,EAAE,eAAe;IAkBrC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,CAiK5C;YAIY,QAAQ;IA8BhB,eAAe,CACnB,IAAI,EAAE,OAAO,EAAE,EACf,OAAO,GAAE,aAAkB,EAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,OAAO,CAAC;IAKnB,wEAAwE;IAClE,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/E,4CAA4C;IACtC,CAAC,mBAAmB,CAAC,CACzB,OAAO,EAAE,aAAa,EACtB,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,OAAO,CAAC;YAIL,KAAK;YAwEJ,kBAAkB;YAyEnB,QAAQ;IAetB,MAAM,CAAC,mBAAmB,CACxB,QAAQ,EAAE,UAAU,EACpB,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO;IAUV,MAAM,CAAC,uBAAuB,CAC5B,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,eAAe,GACxB,OAAO;IAqDV,OAAO,CAAC,MAAM,CAAC,WAAW;IAM1B,OAAO,CAAC,MAAM,CAAC,UAAU;WAoCZ,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"}