pynect 0.0.0 → 0.2.1

package/dist/core/py-context.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * pynect - PyContext
+ * Manages an isolated Python execution context (namespace).
+ * Useful for running code in isolation without polluting the global namespace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyContext = void 0;
+const py_proxy_1 = require("./py-proxy");
+const error_translator_1 = require("../utils/error-translator");
+const logger_1 = require("../utils/logger");
+const logger = new logger_1.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');
+ * ```
+ */
+class PyContext {
+    _addon;
+    _namespacePyId;
+    _variables;
+    _destroyed = false;
+    constructor(addon, namespacePyId) {
+        this._addon = addon;
+        this._namespacePyId = namespacePyId;
+        this._variables = new Map();
+    }
+    /**
+     * Create a new isolated Python context.
+     */
+    static async create(addon) {
+        // Create a fresh namespace dict in Python
+        const result = await addon.evalPython('{}');
+        if (!result.success) {
+            if (result.error) {
+                throw (0, error_translator_1.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);
+    }
+    /**
+     * Execute Python code in this context.
+     */
+    async exec(code) {
+        this._ensureNotDestroyed();
+        const result = await this._addon.runPythonCode(code);
+        if (!result.success && result.error) {
+            throw (0, error_translator_1.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) {
+        this._ensureNotDestroyed();
+        const result = await this._addon.evalPython(expression);
+        if (!result.success) {
+            if (result.error) {
+                throw (0, error_translator_1.translatePythonError)({
+                    type: result.error.type,
+                    message: result.error.message,
+                    traceback: result.error.traceback || '',
+                });
+            }
+            throw new Error('Evaluation failed');
+        }
+        if (result.isObject && result.objectId) {
+            return py_proxy_1.PyProxy._createFromObjectId(result.objectId, [], 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) {
+        this._ensureNotDestroyed();
+        const result = await this._addon.importModule(moduleName);
+        if (!result.success) {
+            if (result.error) {
+                throw (0, error_translator_1.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 py_proxy_1.PyProxy._createFromObjectId(result.objectId, [], this._addon);
+    }
+    /**
+     * Get a variable from the context namespace.
+     */
+    async get(name) {
+        this._ensureNotDestroyed();
+        const pyId = this._variables.get(name);
+        if (pyId) {
+            return py_proxy_1.PyProxy._createFromObjectId(pyId, [], this._addon);
+        }
+        // Try to get from Python global namespace
+        const result = await this._addon.evalPython(name);
+        if (!result.success) {
+            if (result.error?.type === 'NameError') {
+                return undefined;
+            }
+            if (result.error) {
+                throw (0, error_translator_1.translatePythonError)({
+                    type: result.error.type,
+                    message: result.error.message,
+                    traceback: result.error.traceback || '',
+                });
+            }
+            return undefined;
+        }
+        if (result.isObject && result.objectId) {
+            return py_proxy_1.PyProxy._createFromObjectId(result.objectId, [], 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, value) {
+        this._ensureNotDestroyed();
+        assertPythonIdentifier(name);
+        if (value instanceof py_proxy_1.PyProxy) {
+            const internal = value[py_proxy_1.PYPROXY_INTERNAL];
+            this._variables.set(name, internal.objectId);
+            return;
+        }
+        // For primitives and serializable values: set via exec
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined) {
+            throw new TypeError(`Value for '${name}' is not JSON serializable`);
+        }
+        const encoded = Buffer.from(serialized, 'utf8').toString('base64');
+        await this.exec(`${name} = __import__('json').loads(__import__('base64').b64decode('${encoded}'))`);
+    }
+    /**
+     * Check if a name is defined in the context.
+     */
+    async has(name) {
+        this._ensureNotDestroyed();
+        try {
+            const val = await this.get(name);
+            return val !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Delete a variable from the context.
+     */
+    async delete(name) {
+        this._ensureNotDestroyed();
+        assertPythonIdentifier(name);
+        this._variables.delete(name);
+        await this.exec(`del ${name}`).catch(() => { }); // ignore if not defined
+    }
+    /**
+     * Clear all variables in the context.
+     */
+    async clear() {
+        this._ensureNotDestroyed();
+        this._variables.clear();
+    }
+    /**
+     * Destroy the context and free resources.
+     */
+    async destroy() {
+        if (this._destroyed) {
+            return;
+        }
+        this._destroyed = true;
+        this._variables.clear();
+        this._addon.decRef(this._namespacePyId);
+        logger.debug('PyContext destroyed');
+    }
+    _ensureNotDestroyed() {
+        if (this._destroyed) {
+            throw new Error('PyContext has been destroyed');
+        }
+    }
+    [Symbol.asyncDispose]() {
+        return this.destroy();
+    }
+}
+exports.PyContext = PyContext;
+function assertPythonIdentifier(name) {
+    if (!/^[A-Za-z_]\w*$/u.test(name)) {
+        throw new TypeError(`Invalid Python identifier: ${JSON.stringify(name)}`);
+    }
+}
+//# sourceMappingURL=py-context.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"py-context.js","sourceRoot":"","sources":["../../src/core/py-context.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIH,yCAAuD;AACvD,gEAAiE;AACjE,4CAAyC;AAEzC,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,WAAW,CAAC,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,SAAS;IACH,MAAM,CAAc;IACpB,cAAc,CAAa;IACpC,UAAU,CAA0B;IACpC,UAAU,GAAG,KAAK,CAAC;IAE3B,YAAoB,KAAkB,EAAE,aAAyB;QAC/D,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAkB;QACpC,0CAA0C;QAC1C,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,IAAI,CAKzC,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,MAAM,IAAA,uCAAoB,EAAC;oBACzB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;oBACvB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;oBAC7B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE;iBACxC,CAAC,CAAC;YACL,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QAED,OAAO,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,QAAsB,CAAC,CAAC;IAC7D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE3B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAGlD,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACpC,MAAM,IAAA,uCAAoB,EAAC;gBACzB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;gBACvB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;gBAC7B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE;aACxC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,UAAkB;QAC3B,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE3B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAMrD,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,MAAM,IAAA,uCAAoB,EAAC;oBACzB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;oBACvB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;oBAC7B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE;iBACxC,CAAC,CAAC;YACL,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACvC,CAAC;QAED,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvC,OAAO,kBAAO,CAAC,mBAAmB,CAChC,MAAM,CAAC,QAAsB,EAC7B,EAAE,EACF,IAAI,CAAC,MAAM,CACZ,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,MAAM,CAAC,UAAU,CAAC;YAC3B,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,UAAkB;QAC7B,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE3B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,UAAU,CAIvD,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,MAAM,IAAA,uCAAoB,EAAC;oBACzB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;oBACvB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;oBAC7B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE;iBACxC,CAAC,CAAC;YACL,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,GAAG,CAAC,CAAC;QAC7D,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QAED,OAAO,kBAAO,CAAC,mBAAmB,CAChC,MAAM,CAAC,QAAsB,EAC7B,EAAE,EACF,IAAI,CAAC,MAAM,CACZ,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,IAAY;QACpB,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAE3B,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEvC,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,kBAAO,CAAC,mBAAmB,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5D,CAAC;QAED,0CAA0C;QAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAM/C,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,KAAK,WAAW,EAAE,CAAC;gBACvC,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,MAAM,IAAA,uCAAoB,EAAC;oBACzB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;oBACvB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;oBAC7B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE;iBACxC,CAAC,CAAC;YACL,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvC,OAAO,kBAAO,CAAC,mBAAmB,CAChC,MAAM,CAAC,QAAsB,EAC7B,EAAE,EACF,IAAI,CAAC,MAAM,CACZ,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,MAAM,CAAC,UAAU,CAAC;YAC3B,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,KAAc;QACpC,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,sBAAsB,CAAC,IAAI,CAAC,CAAC;QAE7B,IAAI,KAAK,YAAY,kBAAO,EAAE,CAAC;YAC7B,MAAM,QAAQ,GAAG,KAAK,CAAC,2BAAgB,CAAC,CAAC;YACzC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC7C,OAAO;QACT,CAAC;QAED,uDAAuD;QACvD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,SAAS,CAAC,cAAc,IAAI,4BAA4B,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACnE,MAAM,IAAI,CAAC,IAAI,CACb,GAAG,IAAI,+DAA+D,OAAO,KAAK,CACnF,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,IAAY;QACpB,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,GAAG,KAAK,SAAS,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,sBAAsB,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,wBAAwB;IAC1E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC3B,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAAA,OAAO;QAAA,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,cAAwB,CAAC,CAAC;QAClD,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACtC,CAAC;IAEO,mBAAmB;QACzB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,CAAC,MAAM,CAAC,YAAY,CAAC;QACnB,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;CACF;AA7QD,8BA6QC;AAED,SAAS,sBAAsB,CAAC,IAAY;IAC1C,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CAAC,8BAA8B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,84 @@
+/**
+ * pynect - PyIterator
+ * Wraps a Python iterator for use with JavaScript's for await...of.
+ * Provides both async iteration and manual .next() calls.
+ */
+import type { NativeAddon } from '../types/addon';
+import type { PyObjectId } from '../types/python';
+import { PyProxy } from './py-proxy';
+export interface PyIteratorOptions {
+    /** Maximum number of items to yield (0 = no limit) */
+    limit?: number;
+    /** Whether to wrap Python objects in PyProxy */
+    wrapObjects?: boolean;
+    /** Timeout per .next() call (ms) */
+    timeout?: number;
+}
+/**
+ * PyIterator - manages a Python iterator lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const iterator = await PyIterator.create(pyList, addon);
+ *
+ * for await (const item of iterator) {
+ * console.log(item);
+ * }
+ *
+ * // Or manually:
+ * const { value, done } = await iterator.next();
+ * ```
+ */
+export declare class PyIterator<T = unknown> implements AsyncIterable<T>, AsyncIterator<T> {
+    private readonly _iteratorId;
+    private readonly _addon;
+    private readonly _objectId;
+    private readonly _options;
+    private _done;
+    private _position;
+    private _destroyed;
+    private constructor();
+    /**
+     * Create a PyIterator from a PyProxy.
+     */
+    static create(source: PyProxy, options?: PyIteratorOptions): Promise<PyIterator>;
+    /**
+     * Create a PyIterator from an object ID and iterator ID directly.
+     */
+    static fromIds(iteratorId: number, objectId: PyObjectId, addon: NativeAddon, options?: PyIteratorOptions): PyIterator;
+    /** Current position in iteration */
+    get position(): number;
+    /** Whether iteration is complete */
+    get isDone(): boolean;
+    next(): Promise<IteratorResult<T>>;
+    return(value?: T): Promise<IteratorResult<T>>;
+    throw(error?: unknown): Promise<IteratorResult<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Collect all items into an array.
+     * Use with care for large iterators!
+     */
+    toArray(maxItems?: number): Promise<T[]>;
+    /**
+     * Process items in batches.
+     */
+    batch(batchSize: number): AsyncGenerator<T[]>;
+    /**
+     * Map items through a transform function.
+     */
+    map<U>(fn: (item: T, index: number) => U | Promise<U>): AsyncGenerator<U>;
+    /**
+     * Filter items.
+     */
+    filter(fn: (item: T, index: number) => boolean | Promise<boolean>): AsyncGenerator<T>;
+    /**
+     * Take first N items.
+     */
+    take(n: number): Promise<T[]>;
+    /**
+     * Destroy the underlying Python iterator (frees resources).
+     * Called automatically when iteration completes.
+     */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=py-iterator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"py-iterator.d.ts","sourceRoot":"","sources":["../../src/core/py-iterator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAAE,OAAO,EAAoB,MAAM,YAAY,CAAC;AAKvD,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;IAChF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAS;IAE3B,OAAO;IAYP;;OAEG;WACU,MAAM,CACjB,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,UAAU,CAAC;IAgCtB;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,UAAU;IAIb,oCAAoC;IACpC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,oCAAoC;IACpC,IAAI,MAAM,IAAI,OAAO,CAEpB;IAIK,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IA4ElC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAK7C,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAOxD,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;IAM1C;;;OAGG;IACG,OAAO,CAAC,QAAQ,SAAS,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAS9C;;OAEG;IACI,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC;IAcpD;;OAEG;IACI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;IAOhF;;OAEG;IACI,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC;IAO5F;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAUnC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAU/B"}

package/dist/core/py-iterator.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * pynect - PyIterator
+ * Wraps a Python iterator for use with JavaScript's for await...of.
+ * Provides both async iteration and manual .next() calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PyIterator = void 0;
+const error_translator_1 = require("../utils/error-translator");
+const py_proxy_1 = require("./py-proxy");
+const logger_1 = require("../utils/logger");
+const logger = new logger_1.Logger('PyIterator');
+/**
+ * PyIterator - manages a Python iterator lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const iterator = await PyIterator.create(pyList, addon);
+ *
+ * for await (const item of iterator) {
+ * console.log(item);
+ * }
+ *
+ * // Or manually:
+ * const { value, done } = await iterator.next();
+ * ```
+ */
+class PyIterator {
+    _iteratorId;
+    _addon;
+    _objectId;
+    _options;
+    _done = false;
+    _position = 0;
+    _destroyed = false;
+    constructor(iteratorId, objectId, addon, options = {}) {
+        this._iteratorId = iteratorId;
+        this._objectId = objectId;
+        this._addon = addon;
+        this._options = options;
+    }
+    /**
+     * Create a PyIterator from a PyProxy.
+     */
+    static async create(source, options) {
+        const internal = source[py_proxy_1.PYPROXY_INTERNAL];
+        const addon = internal.addon;
+        const result = await addon.createIterator(internal.objectId, internal.path);
+        if (!result.success) {
+            if (result.error) {
+                throw (0, error_translator_1.translatePythonError)({
+                    type: result.error.type,
+                    message: result.error.message,
+                    traceback: result.error.traceback || '',
+                });
+            }
+            throw new Error('Failed to create Python iterator');
+        }
+        let iteratorId;
+        try {
+            const parsed = JSON.parse(result.resultJson || '{}');
+            if (!parsed.iteratorId) {
+                throw new Error('no iteratorId');
+            }
+            iteratorId = parsed.iteratorId;
+        }
+        catch {
+            throw new Error('Failed to parse iterator ID from: ' + result.resultJson);
+        }
+        return new PyIterator(iteratorId, internal.objectId, addon, options);
+    }
+    /**
+     * Create a PyIterator from an object ID and iterator ID directly.
+     */
+    static fromIds(iteratorId, objectId, addon, options) {
+        return new PyIterator(iteratorId, objectId, addon, options);
+    }
+    /** Current position in iteration */
+    get position() {
+        return this._position;
+    }
+    /** Whether iteration is complete */
+    get isDone() {
+        return this._done;
+    }
+    // AsyncIterator Protocol
+    async next() {
+        if (this._done || this._destroyed) {
+            return { value: undefined, done: true };
+        }
+        // Check limit
+        if (this._options.limit && this._position >= this._options.limit) {
+            await this.destroy();
+            return { value: undefined, done: true };
+        }
+        try {
+            const result = await this._addon.iteratorNext(this._iteratorId);
+            if (!result.success) {
+                if (result.error) {
+                    throw (0, error_translator_1.translatePythonError)({
+                        type: result.error.type,
+                        message: result.error.message,
+                        traceback: result.error.traceback || '',
+                    });
+                }
+                this._done = true;
+                return { value: undefined, done: true };
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(result.resultJson || '{"done":true}');
+            }
+            catch {
+                this._done = true;
+                return { value: undefined, done: true };
+            }
+            if (parsed.done) {
+                this._done = true;
+                return { value: undefined, done: true };
+            }
+            this._position++;
+            // Deserialize the value
+            const rawValue = parsed.value;
+            let value;
+            if (rawValue !== null &&
+                typeof rawValue === 'object' &&
+                '__pyref__' in rawValue) {
+                // It's a Python object reference
+                if (this._options.wrapObjects !== false) {
+                    const refId = rawValue.__pyref__;
+                    value = py_proxy_1.PyProxy._createFromObjectId(refId, [], this._addon);
+                }
+                else {
+                    value = rawValue;
+                }
+            }
+            else {
+                value = rawValue;
+            }
+            return { value, done: false };
+        }
+        catch (err) {
+            this._done = true;
+            throw err;
+        }
+    }
+    async return(value) {
+        await this.destroy();
+        return { value: value, done: true };
+    }
+    async throw(error) {
+        await this.destroy();
+        throw error;
+    }
+    // AsyncIterable Protocol
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    // Utilities
+    /**
+     * Collect all items into an array.
+     * Use with care for large iterators!
+     */
+    async toArray(maxItems = 100000) {
+        const items = [];
+        for await (const item of this) {
+            items.push(item);
+            if (items.length >= maxItems) {
+                break;
+            }
+        }
+        return items;
+    }
+    /**
+     * Process items in batches.
+     */
+    async *batch(batchSize) {
+        let current = [];
+        for await (const item of this) {
+            current.push(item);
+            if (current.length >= batchSize) {
+                yield current;
+                current = [];
+            }
+        }
+        if (current.length > 0) {
+            yield current;
+        }
+    }
+    /**
+     * Map items through a transform function.
+     */
+    async *map(fn) {
+        let i = 0;
+        for await (const item of this) {
+            yield await fn(item, i++);
+        }
+    }
+    /**
+     * Filter items.
+     */
+    async *filter(fn) {
+        let i = 0;
+        for await (const item of this) {
+            if (await fn(item, i++)) {
+                yield item;
+            }
+        }
+    }
+    /**
+     * Take first N items.
+     */
+    async take(n) {
+        const items = [];
+        for await (const item of this) {
+            items.push(item);
+            if (items.length >= n) {
+                break;
+            }
+        }
+        await this.destroy();
+        return items;
+    }
+    /**
+     * Destroy the underlying Python iterator (frees resources).
+     * Called automatically when iteration completes.
+     */
+    async destroy() {
+        if (this._destroyed) {
+            return;
+        }
+        this._destroyed = true;
+        this._done = true;
+        try {
+            await this._addon.destroyIterator(this._iteratorId);
+        }
+        catch (err) {
+            logger.debug('Error destroying iterator', err);
+        }
+    }
+}
+exports.PyIterator = PyIterator;
+//# sourceMappingURL=py-iterator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"py-iterator.js","sourceRoot":"","sources":["../../src/core/py-iterator.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIH,gEAAiE;AACjE,yCAAuD;AACvD,4CAAyC;AAEzC,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,YAAY,CAAC,CAAC;AAWxC;;;;;;;;;;;;;;GAcG;AACH,MAAa,UAAU;IACJ,WAAW,CAAS;IACpB,MAAM,CAAc;IACpB,SAAS,CAAa;IACtB,QAAQ,CAAoB;IACrC,KAAK,GAAG,KAAK,CAAC;IACd,SAAS,GAAG,CAAC,CAAC;IACd,UAAU,GAAG,KAAK,CAAC;IAE3B,YACE,UAAkB,EAClB,QAAoB,EACpB,KAAkB,EAClB,UAA6B,EAAE;QAE/B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,CACjB,MAAe,EACf,OAA2B;QAE3B,MAAM,QAAQ,GAAG,MAAM,CAAC,2BAAgB,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QAE7B,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,cAAc,CACvC,QAAQ,CAAC,QAAkB,EAC3B,QAAQ,CAAC,IAAI,CAC8F,CAAC;QAE9G,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,MAAM,IAAA,uCAAoB,EAAC;oBACzB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;oBACvB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;oBAC7B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE;iBACxC,CAAC,CAAC;YACL,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,UAAkB,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,IAAI,IAAI,CAA4B,CAAC;YAChF,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;gBAAA,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;YAAA,CAAC;YAC3D,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;QAC5E,CAAC;QAED,OAAO,IAAI,UAAU,CAAC,UAAU,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACvE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,UAAkB,EAClB,QAAoB,EACpB,KAAkB,EAClB,OAA2B;QAE3B,OAAO,IAAI,UAAU,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED,oCAAoC;IACpC,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,oCAAoC;IACpC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,yBAAyB;IAEzB,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAClC,OAAO,EAAE,KAAK,EAAE,SAAyB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC1D,CAAC;QAED,cAAc;QACd,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjE,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACrB,OAAO,EAAE,KAAK,EAAE,SAAyB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC1D,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAI7D,CAAC;YAEF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;oBACjB,MAAM,IAAA,uCAAoB,EAAC;wBACzB,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;wBACvB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;wBAC7B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE;qBACxC,CAAC,CAAC;gBACL,CAAC;gBACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;gBAClB,OAAO,EAAE,KAAK,EAAE,SAAyB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC1D,CAAC;YAED,IAAI,MAA2C,CAAC;YAChD,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,IAAI,eAAe,CAAwC,CAAC;YACnG,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;gBAClB,OAAO,EAAE,KAAK,EAAE,SAAyB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC1D,CAAC;YAED,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;gBAChB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;gBAClB,OAAO,EAAE,KAAK,EAAE,SAAyB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC1D,CAAC;YAED,IAAI,CAAC,SAAS,EAAE,CAAC;YAEjB,wBAAwB;YACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC;YAC9B,IAAI,KAAQ,CAAC;YAEb,IACE,QAAQ,KAAK,IAAI;gBACjB,OAAO,QAAQ,KAAK,QAAQ;gBAC5B,WAAW,IAAK,QAAoC,EACpD,CAAC;gBACD,iCAAiC;gBACjC,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;oBACxC,MAAM,KAAK,GAAI,QAAkC,CAAC,SAAS,CAAC;oBAC5D,KAAK,GAAG,kBAAO,CAAC,mBAAmB,CACjC,KAAmB,EACnB,EAAE,EACF,IAAI,CAAC,MAAM,CACI,CAAC;gBACpB,CAAC;qBAAM,CAAC;oBACN,KAAK,GAAG,QAAa,CAAC;gBACxB,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,KAAK,GAAG,QAAa,CAAC;YACxB,CAAC;YAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAS;QACpB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,EAAE,KAAK,EAAE,KAAU,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,KAAe;QACzB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,KAAK,CAAC;IACd,CAAC;IAED,yBAAyB;IAEzB,CAAC,MAAM,CAAC,aAAa,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY;IAEZ;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,QAAQ,GAAG,MAAM;QAC7B,MAAM,KAAK,GAAQ,EAAE,CAAC;QACtB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAAA,MAAM;YAAA,CAAC;QACxC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,CAAC,KAAK,CAAC,SAAiB;QAC5B,IAAI,OAAO,GAAQ,EAAE,CAAC;QACtB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,IAAI,OAAO,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;gBAChC,MAAM,OAAO,CAAC;gBACd,OAAO,GAAG,EAAE,CAAC;YACf,CAAC;QACH,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,OAAO,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,CAAC,GAAG,CAAI,EAA8C;QAC1D,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YAC9B,MAAM,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,CAAC,MAAM,CAAC,EAA0D;QACtE,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YAC9B,IAAI,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;gBAAA,MAAM,IAAI,CAAC;YAAA,CAAC;QACxC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,CAAS;QAClB,MAAM,KAAK,GAAQ,EAAE,CAAC;QACtB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;gBAAA,MAAM;YAAA,CAAC;QACjC,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAAA,OAAO;QAAA,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE,GAAG,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;CACF;AA9PD,gCA8PC"}

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

@@ -0,0 +1,53 @@
+/**
+ * pynect - PyModule
+ * Represents a Python module with its full namespace.
+ * Inherits from PyProxy but adds module-specific introspection.
+ */
+import { PyProxy } from './py-proxy';
+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.__pynect_inspect__();  // get module metadata
+ * ```
+ */
+export declare class PyModule extends PyProxy {
+    private readonly _moduleName;
+    constructor(objectId: PyObjectId, moduleName: string, addon: NativeAddon, callTimeout?: number, executionTimeout?: number);
+    /** The Python module name */
+    get moduleName(): string;
+    /** Object ID in Python heap */
+    get objectId(): PyObjectId;
+    /**
+     * Inspect the module and return detailed type information.
+     */
+    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, executionTimeout?: number): PyModule;
+    toString(): string;
+}
+//# sourceMappingURL=py-module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"py-module.d.ts","sourceRoot":"","sources":["../../src/core/py-module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAoB,MAAM,YAAY,CAAC;AACvD,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;gBAGnC,QAAQ,EAAE,UAAU,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,gBAAgB,CAAC,EAAE,MAAM;IAY3B,6BAA6B;IAC7B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,+BAA+B;IAC/B,IAAI,QAAQ,IAAI,UAAU,CAEzB;IAED;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAqE5C;;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;IAM7B;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,QAAQ,EAAE,UAAU,EACpB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,gBAAgB,CAAC,EAAE,MAAM,GACxB,QAAQ;IAIF,QAAQ,IAAI,MAAM;CAG5B"}