nodepyx 1.0.0

package/dist/env/VenvManager.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * nodepyx — VenvManager
+ * Creates and manages Python virtualenvs for isolated package installation.
+ *
+ * Lifecycle:
+ *   1. Check if the venv directory exists and is valid.
+ *   2. If not, run `python3 -m venv <path>` to create it.
+ *   3. Upgrade pip to the latest version.
+ *   4. Install configured packages via pip.
+ *   5. Return the path to the Python executable inside the venv.
+ *
+ * State file (.nodepyx/venv-state.json) tracks installed packages
+ * to avoid re-running pip on every startup.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageInstallError = exports.VenvCreationError = exports.VenvManager = void 0;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('VenvManager');
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function isWindows() {
+    return process.platform === 'win32';
+}
+function venvBinDir(venvPath) {
+    return path.join(venvPath, isWindows() ? 'Scripts' : 'bin');
+}
+function venvPython(venvPath) {
+    return path.join(venvBinDir(venvPath), isWindows() ? 'python.exe' : 'python3');
+}
+function venvPip(venvPath) {
+    return path.join(venvBinDir(venvPath), isWindows() ? 'pip.exe' : 'pip3');
+}
+const STATE_FILENAME = '.nodepyx-venv-state.json';
+/**
+ * VenvManager — creates and manages Python virtualenvs.
+ *
+ * @example
+ * ```typescript
+ * const manager = new VenvManager({
+ *   virtualenv: {
+ *     path: './.venv',
+ *     packages: ['pandas', 'numpy', 'scikit-learn'],
+ *     autoInstall: true,
+ *   }
+ * });
+ *
+ * const result = await manager.setup();
+ * console.log(result.pythonExecutable);  // ./.venv/bin/python3
+ * ```
+ */
+class VenvManager {
+    _config;
+    _basePython;
+    _installTimeout;
+    _skipPipUpgrade;
+    _venvPath;
+    _statePath;
+    constructor(options) {
+        this._config = options.virtualenv;
+        this._basePython = options.basePython ?? 'python3';
+        this._installTimeout = options.installTimeout ?? 300_000;
+        this._skipPipUpgrade = options.skipPipUpgrade ?? false;
+        this._venvPath = path.resolve(this._config.path);
+        this._statePath = path.join(this._venvPath, STATE_FILENAME);
+    }
+    // ─── Public API ──────────────────────────────────────────────────────────
+    /**
+     * Set up the virtualenv and install packages if needed.
+     * Returns the path to the Python executable inside the venv.
+     */
+    async setup() {
+        let created = false;
+        let packagesInstalled = false;
+        // ── Create venv if it doesn't exist ──────────────────────────────────
+        if (!this._venvExists()) {
+            logger.info(`VenvManager: creating virtualenv at ${this._venvPath}`);
+            this._createVenv();
+            created = true;
+            if (!this._skipPipUpgrade) {
+                this._upgradePip();
+            }
+        }
+        const pythonExec = venvPython(this._venvPath);
+        const pipExec = venvPip(this._venvPath);
+        // ── Install packages ─────────────────────────────────────────────────
+        if (this._config.autoInstall && this._config.packages.length > 0) {
+            const missingPackages = this._findMissingPackages(pythonExec);
+            if (missingPackages.length > 0 || created) {
+                logger.info(`VenvManager: installing ${missingPackages.length > 0 ? missingPackages.join(', ') : this._config.packages.join(', ')}`);
+                this._installPackages(pipExec, missingPackages.length > 0 ? missingPackages : this._config.packages);
+                packagesInstalled = true;
+                this._updateState(pythonExec);
+            }
+        }
+        logger.info(`VenvManager: ready — ${pythonExec}`);
+        return {
+            pythonExecutable: pythonExec,
+            pipExecutable: pipExec,
+            created,
+            packagesInstalled,
+        };
+    }
+    /**
+     * Install additional packages into the venv.
+     */
+    async install(packages) {
+        if (!this._venvExists()) {
+            throw new Error(`VenvManager: venv does not exist at ${this._venvPath}`);
+        }
+        const pip = venvPip(this._venvPath);
+        this._installPackages(pip, packages);
+        this._updateState(venvPython(this._venvPath));
+    }
+    /**
+     * Check which of the configured packages are not installed in the venv.
+     */
+    getMissingPackages() {
+        if (!this._venvExists()) {
+            return this._config.packages;
+        }
+        return this._findMissingPackages(venvPython(this._venvPath));
+    }
+    /**
+     * Return the Python executable path inside the venv (without setup).
+     */
+    get pythonExecutable() {
+        return venvPython(this._venvPath);
+    }
+    /**
+     * Return true if the venv exists and appears valid.
+     */
+    isValid() {
+        return this._venvExists();
+    }
+    /**
+     * Destroy the venv directory.
+     */
+    destroy() {
+        if (fs.existsSync(this._venvPath)) {
+            fs.rmSync(this._venvPath, { recursive: true, force: true });
+            logger.info(`VenvManager: destroyed venv at ${this._venvPath}`);
+        }
+    }
+    /**
+     * Return the list of installed packages (pip freeze format).
+     */
+    listInstalled() {
+        const state = this._loadState();
+        return state?.installedPackages ?? [];
+    }
+    // ─── Private ─────────────────────────────────────────────────────────────
+    _venvExists() {
+        const pyExec = venvPython(this._venvPath);
+        return fs.existsSync(pyExec);
+    }
+    _createVenv() {
+        fs.mkdirSync(path.dirname(this._venvPath), { recursive: true });
+        // Try with pyvenv-cfg check
+        const result = (0, child_process_1.spawnSync)(this._basePython, ['-m', 'venv', '--clear', this._venvPath], {
+            encoding: 'utf8',
+            timeout: 60_000,
+            stdio: 'pipe',
+        });
+        if (result.status !== 0) {
+            const err = result.stderr?.trim() || result.error?.message || 'unknown error';
+            throw new VenvCreationError(`Failed to create virtualenv at ${this._venvPath}: ${err}`);
+        }
+        logger.info(`VenvManager: virtualenv created at ${this._venvPath}`);
+    }
+    _upgradePip() {
+        const pip = venvPip(this._venvPath);
+        try {
+            const result = (0, child_process_1.spawnSync)(pip, ['install', '--upgrade', 'pip', '--quiet'], { encoding: 'utf8', timeout: 60_000, stdio: 'pipe' });
+            if (result.status === 0) {
+                logger.debug('VenvManager: pip upgraded');
+            }
+        }
+        catch {
+            logger.warn('VenvManager: pip upgrade failed (continuing)');
+        }
+    }
+    _installPackages(pip, packages) {
+        if (packages.length === 0) {
+            return;
+        }
+        const args = ['install', '--quiet', ...packages];
+        if (this._config.pipIndexUrl) {
+            args.push('--index-url', this._config.pipIndexUrl);
+        }
+        if (this._config.pipArgs) {
+            args.push(...this._config.pipArgs);
+        }
+        logger.info(`VenvManager: running pip install ${packages.join(' ')}`);
+        const result = (0, child_process_1.spawnSync)(pip, args, {
+            encoding: 'utf8',
+            timeout: this._installTimeout,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.status !== 0) {
+            const err = result.stderr?.trim() || 'pip install failed';
+            throw new PackageInstallError(packages, err);
+        }
+    }
+    _findMissingPackages(pythonExec) {
+        const state = this._loadState();
+        if (!state) {
+            return this._config.packages;
+        }
+        // Quick check via import
+        const missing = [];
+        for (const pkg of this._config.packages) {
+            // Strip version specifiers for import test
+            const importName = this._packageToImportName(pkg);
+            const result = (0, child_process_1.spawnSync)(pythonExec, ['-c', `import ${importName}`], { encoding: 'utf8', timeout: 5000, stdio: 'pipe' });
+            if (result.status !== 0) {
+                missing.push(pkg);
+            }
+        }
+        return missing;
+    }
+    _packageToImportName(pkg) {
+        // Strip version specifiers: pandas>=2.0 → pandas
+        const stripped = pkg.replace(/[>=<!].*/g, '').trim();
+        // Normalize: scikit-learn → sklearn, Pillow → PIL
+        const importAliases = {
+            'scikit-learn': 'sklearn',
+            'scikit_learn': 'sklearn',
+            'Pillow': 'PIL',
+            'pillow': 'PIL',
+            'opencv-python': 'cv2',
+            'pyyaml': 'yaml',
+            'beautifulsoup4': 'bs4',
+        };
+        return importAliases[stripped] ?? stripped;
+    }
+    _updateState(pythonExec) {
+        try {
+            const result = (0, child_process_1.spawnSync)(pythonExec, ['-m', 'pip', 'freeze', '--quiet'], { encoding: 'utf8', timeout: 30_000, stdio: 'pipe' });
+            const installed = (result.stdout ?? '').trim().split('\n').filter(Boolean);
+            const state = {
+                createdAt: this._loadState()?.createdAt ?? Date.now(),
+                pythonVersion: this._getPythonVersion(pythonExec),
+                installedPackages: installed,
+                lastInstallAt: Date.now(),
+            };
+            fs.writeFileSync(this._statePath, JSON.stringify(state, null, 2), 'utf8');
+        }
+        catch (err) {
+            logger.warn('VenvManager: failed to update state file', err);
+        }
+    }
+    _loadState() {
+        try {
+            if (fs.existsSync(this._statePath)) {
+                return JSON.parse(fs.readFileSync(this._statePath, 'utf8'));
+            }
+        }
+        catch {
+            // ignore
+        }
+        return null;
+    }
+    _getPythonVersion(pythonExec) {
+        try {
+            const result = (0, child_process_1.spawnSync)(pythonExec, ['--version'], {
+                encoding: 'utf8',
+                timeout: 5000,
+                stdio: 'pipe',
+            });
+            return (result.stdout || result.stderr || '').trim().replace('Python ', '');
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+}
+exports.VenvManager = VenvManager;
+// ─── Error types ─────────────────────────────────────────────────────────────
+class VenvCreationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VenvCreationError';
+    }
+}
+exports.VenvCreationError = VenvCreationError;
+class PackageInstallError extends Error {
+    packages;
+    constructor(packages, detail) {
+        super(`Failed to install packages [${packages.join(', ')}]: ${detail}`);
+        this.name = 'PackageInstallError';
+        this.packages = packages;
+    }
+}
+exports.PackageInstallError = PackageInstallError;
+//# sourceMappingURL=VenvManager.js.map

package/dist/env/VenvManager.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+/**
+ * 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 type { nodepyxConfig } from './types/config';
+import type { PyProxyInterface } from './types/python';
+/**
+ * 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 declare const py: PyRuntime;
+/**
+ * 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 declare function init(config?: nodepyxConfig, options?: {
+    force?: boolean;
+}): Promise<void>;
+/**
+ * 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 declare function shutdown(): Promise<void>;
+/**
+ * Check if nodepyx is initialized and ready to use.
+ */
+export declare function isInitialized(): boolean;
+/**
+ * Get the current PyRuntime instance.
+ * @throws {nodepyxNotInitializedError} if not initialized
+ */
+export declare function getRuntime(): PyRuntime;
+/**
+ * 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 declare function importModule(moduleName: string): Promise<PyProxyInterface>;
+/**
+ * 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 declare function evalPython(expression: string): Promise<unknown>;
+/**
+ * Execute Python code (statements, not expressions).
+ * Shorthand for `py.exec(code)`.
+ *
+ * @example
+ * ```typescript
+ * await execPython(`
+ *   import sys
+ *   print(f"Python {sys.version}")
+ * `);
+ * ```
+ */
+export declare function execPython(code: string): Promise<void>;
+/**
+ * Run a Python script file.
+ */
+export declare function runFile(filePath: string): Promise<unknown>;
+/**
+ * Install Python packages into the configured virtualenv.
+ *
+ * @example
+ * ```typescript
+ * await installPackages(['pandas', 'numpy>=1.24.0', 'scikit-learn']);
+ * ```
+ */
+export declare function installPackages(packages: string[]): Promise<void>;
+/**
+ * Get memory statistics for the Python heap.
+ */
+export declare function getMemoryStats(): Promise<{
+    pythonHeapBytes: number;
+    pythonHeapPeakBytes: number;
+    trackedObjects: number;
+    pendingCallbacks: number;
+}>;
+/**
+ * Trigger Python garbage collection.
+ */
+export declare function collectGarbage(): Promise<void>;
+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';
+export { Serializer } from './serialization/Serializer';
+export { NumpyBridge } from './serialization/NumpyBridge';
+export { DataFrameBridge } from './serialization/DataFrameBridge';
+export { PythonError, PythonValueError, PythonTypeError, PythonKeyError, PythonIndexError, PythonAttributeError, PythonImportError, PythonModuleNotFoundError, PythonFileNotFoundError, PythonPermissionError, PythonRuntimeError, PythonMemoryError, PythonStopIteration, PythonTimeoutError, nodepyxNotInitializedError, nodepyxShutdownError, translatePythonError, isPythonError, isPythonErrorOfType, } from './utils/ErrorTranslator';
+export { TypeGenerator } from './types/TypeGenerator';
+export { PythonDetector } from './env/PythonDetector';
+export { VenvManager } from './env/VenvManager';
+export { CondaManager } from './env/CondaManager';
+export { PackageInstaller } from './env/PackageInstaller';
+export { PluginManager } from './plugins/PluginManager';
+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';
+declare const _default: {
+    init: typeof init;
+    shutdown: typeof shutdown;
+    isInitialized: typeof isInitialized;
+    getRuntime: typeof getRuntime;
+    py: PyRuntime;
+    import: typeof importModule;
+    eval: typeof evalPython;
+    exec: typeof execPython;
+    runFile: typeof runFile;
+    installPackages: typeof installPackages;
+    getMemoryStats: typeof getMemoryStats;
+    collectGarbage: typeof collectGarbage;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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