pynect 0.2.5 → 0.2.7

package/prebuilds/linux-arm64/pynect-prebuild.json

@@ -1,10 +1,11 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "platform": "linux",
   "architecture": "arm64",
-  "pythonMajorMinor": "3.12",
-  "pythonLibraryName": "libpython3.12.so",
+  "pythonMinimumVersion": "3.10",
+  "pythonAbi": "cp310-abi3",
+  "pythonLibraryName": "libpython3.so",
   "napi": 8,
-  "nativeFingerprint": "sha256:b3e6e170e36500af003354a4012bed2c2d2c65a8f105a355bda0d329e0c82075",
+  "nativeFingerprint": "sha256:e375cc859a1ef9a6e8e72f182886c847c2489e9ed5a6017f08d43dd01425bd52",
   "glibc": "2.39"
 }

package/prebuilds/linux-x64/pynect-prebuild.json

@@ -1,10 +1,11 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "platform": "linux",
   "architecture": "x64",
-  "pythonMajorMinor": "3.12",
-  "pythonLibraryName": "libpython3.12.so",
+  "pythonMinimumVersion": "3.10",
+  "pythonAbi": "cp310-abi3",
+  "pythonLibraryName": "libpython3.so",
   "napi": 8,
-  "nativeFingerprint": "sha256:b3e6e170e36500af003354a4012bed2c2d2c65a8f105a355bda0d329e0c82075",
+  "nativeFingerprint": "sha256:e375cc859a1ef9a6e8e72f182886c847c2489e9ed5a6017f08d43dd01425bd52",
   "glibc": "2.35"
 }

package/prebuilds/win32-arm64/pynect-prebuild.json

@@ -1,9 +1,10 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "platform": "win32",
   "architecture": "arm64",
-  "pythonMajorMinor": "3.12",
-  "pythonLibraryName": "python312.lib",
+  "pythonMinimumVersion": "3.10",
+  "pythonAbi": "cp310-abi3",
+  "pythonLibraryName": "python3.dll",
   "napi": 8,
-  "nativeFingerprint": "sha256:b3e6e170e36500af003354a4012bed2c2d2c65a8f105a355bda0d329e0c82075"
+  "nativeFingerprint": "sha256:e375cc859a1ef9a6e8e72f182886c847c2489e9ed5a6017f08d43dd01425bd52"
 }

package/prebuilds/win32-x64/pynect-prebuild.json

@@ -1,9 +1,10 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "platform": "win32",
   "architecture": "x64",
-  "pythonMajorMinor": "3.12",
-  "pythonLibraryName": "python312.lib",
+  "pythonMinimumVersion": "3.10",
+  "pythonAbi": "cp310-abi3",
+  "pythonLibraryName": "python3.dll",
   "napi": 8,
-  "nativeFingerprint": "sha256:b3e6e170e36500af003354a4012bed2c2d2c65a8f105a355bda0d329e0c82075"
+  "nativeFingerprint": "sha256:e375cc859a1ef9a6e8e72f182886c847c2489e9ed5a6017f08d43dd01425bd52"
 }

package/scripts/build-native.js

@@ -14,6 +14,12 @@ async function main() {
     pythonPath: process.env.PYNECT_PYTHON,
   });
   const embedding = python.embedding;
+  const stableAbiLibrary = process.platform === 'win32'
+    ? embedding.stableAbiLibraryPath || path.join(embedding.libraryDirectory, 'python3.lib')
+    : '';
+  const linkLibrary = stableAbiLibrary && fs.existsSync(stableAbiLibrary)
+    ? stableAbiLibrary
+    : embedding.libraryPath;
   const nodeGyp = require.resolve('node-gyp/bin/node-gyp.js');
   const mode = process.argv.includes('--debug') ? '--debug' : '--release';
   const args = [nodeGyp, 'rebuild', mode];
@@ -24,8 +30,8 @@ async function main() {
     npm_config_python: python.executable,
     PYTHON: python.executable,
     PYNECT_PYTHON_INCLUDE_DIR: embedding.includeDirectory,
-    PYNECT_PYTHON_LIBRARY: embedding.libraryPath,
-    PYNECT_PYTHON_LIBRARY_DIR: embedding.libraryDirectory,
+    PYNECT_PYTHON_LIBRARY: linkLibrary,
+    PYNECT_PYTHON_LIBRARY_DIR: path.dirname(linkLibrary),
     PATH: [embedding.libraryDirectory, path.dirname(python.executable), process.env.PATH || '']
       .filter(Boolean)
       .join(path.delimiter),
@@ -40,7 +46,7 @@ async function main() {
       schemaVersion: 1,
       pythonExecutable: path.resolve(python.executable),
       pythonVersion: python.version,
-      pythonLibrary: path.resolve(embedding.libraryPath),
+      pythonLibrary: path.resolve(linkLibrary),
       buildType: mode === '--debug' ? 'Debug' : 'Release',
     }, null, 2)}\n`,
   );

package/scripts/ensure-native.js

@@ -7,6 +7,7 @@ const { spawnSync } = require('child_process');
 const ROOT = path.resolve(__dirname, '..');
 const BUILD_DIRECTORY = path.join(ROOT, 'build');
 const METADATA = path.join(BUILD_DIRECTORY, 'pynect-python.json');
+let lastLoadError;
 
 function normalize(value) {
   const resolved = path.resolve(value);
@@ -33,12 +34,14 @@ function matchingAddonPath() {
 }
 
 function loads() {
+  lastLoadError = undefined;
   const addon = matchingAddonPath();
   if (!addon || !fs.existsSync(addon)) return false;
   try {
     require(addon);
     return true;
-  } catch {
+  } catch (error) {
+    lastLoadError = error;
     return false;
   }
 }
@@ -55,7 +58,10 @@ function build() {
   if (result.status !== 0) {
     throw new Error(`Native addon build failed with exit code ${result.status}.`);
   }
-  if (!loads()) throw new Error('Native addon did not load after it was built.');
+  if (!loads()) {
+    const detail = lastLoadError instanceof Error ? ` ${lastLoadError.message}` : '';
+    throw new Error(`Native addon did not load after it was built.${detail}`);
+  }
 }
 
 async function main() {

package/scripts/smoke-python-boundary.js

@@ -77,7 +77,7 @@ async function main() {
     await pynect.shutdown();
   }
 
-  console.log(`Python boundary verified: ${python.executable}`);
+  console.log(`Python ${python.version} boundary verified: ${python.executable}`);
 }
 
 function assertSuccess(result, label) {

package/src/native/native-addon-loader.ts

@@ -72,10 +72,11 @@ interface NativeBuildMetadata {
 }
 
 interface NativePrebuildMetadata {
-  schemaVersion: 1;
+  schemaVersion: 2;
   platform: NodeJS.Platform;
   architecture: string;
-  pythonMajorMinor: string;
+  pythonMinimumVersion: string;
+  pythonAbi: string;
   napi: number;
   glibc?: string;
   pythonLibraryName: string;
@@ -91,17 +92,22 @@ function loadMatchingPrebuild(options: NativeAddonBuildOptions): NativeAddon {
   } catch (error) {
     throw new Error(`Native prebuild metadata is unavailable at ${metadataPath}.`, { cause: error });
   }
-  const pythonMajorMinor = options.pythonVersion.split('.').slice(0, 2).join('.');
+  const pythonVersion = majorMinor(options.pythonVersion);
+  const minimumVersion = typeof metadata.pythonMinimumVersion === 'string'
+    ? majorMinor(metadata.pythonMinimumVersion)
+    : [Number.POSITIVE_INFINITY, 0] as const;
   if (
-    metadata.schemaVersion !== 1 ||
+    metadata.schemaVersion !== 2 ||
     metadata.platform !== process.platform ||
     metadata.architecture !== process.arch ||
-    metadata.pythonMajorMinor !== pythonMajorMinor ||
+    metadata.pythonAbi !== 'cp310-abi3' ||
+    pythonVersion[0] !== 3 ||
+    compareMajorMinor(pythonVersion, minimumVersion) < 0 ||
     metadata.napi > Number(process.versions.napi ?? 0)
   ) {
     throw new Error(
       `Native prebuild does not match ${process.platform}-${process.arch}, ` +
-      `Python ${pythonMajorMinor}, N-API ${process.versions.napi ?? 'unknown'}.`,
+      `Python ${options.pythonVersion}, N-API ${process.versions.napi ?? 'unknown'}.`,
     );
   }
   if (process.platform === 'linux' && metadata.glibc) {
@@ -137,7 +143,7 @@ function materializePortablePrebuild(
     'node_modules',
     '.pynect',
     'native',
-    `${process.platform}-${process.arch}-python${metadata.pythonMajorMinor}-${identity}`,
+    `${process.platform}-${process.arch}-${metadata.pythonAbi}-${identity}`,
   );
   const addon = path.join(directory, 'pynect_addon.node');
   const library = path.join(directory, metadata.pythonLibraryName);
@@ -216,3 +222,16 @@ function compareVersions(left: string, right: string): number {
   }
   return 0;
 }
+
+function majorMinor(version: string): readonly [number, number] {
+  const match = version.match(/^(\d+)\.(\d+)/u);
+  if (!match) throw new Error(`Invalid Python version: ${version}`);
+  return [Number(match[1]), Number(match[2])];
+}
+
+function compareMajorMinor(
+  left: readonly [number, number],
+  right: readonly [number, number],
+): number {
+  return left[0] - right[0] || left[1] - right[1];
+}

package/src/native/pynect_addon.cpp

@@ -141,6 +141,12 @@ static Napi::Value InitializePython(const Napi::CallbackInfo& info) {
   std::string pythonExecutable = opts.Has("pythonExecutable") ?
     opts.Get("pythonExecutable").As<Napi::String>().Utf8Value() : "python3";
 
+  std::string pythonBaseExecutable = opts.Has("pythonBaseExecutable") ?
+    opts.Get("pythonBaseExecutable").As<Napi::String>().Utf8Value() : pythonExecutable;
+
+  std::string pythonPrefix = opts.Has("pythonPrefix") ?
+    opts.Get("pythonPrefix").As<Napi::String>().Utf8Value() : "";
+
   std::string pythonLibrary = opts.Has("pythonLibrary") ?
     opts.Get("pythonLibrary").As<Napi::String>().Utf8Value() : "";
 
@@ -180,6 +186,8 @@ static Napi::Value InitializePython(const Napi::CallbackInfo& info) {
     PythonBridge::getInstance().initializePython(
       pythonHome,
       pythonExecutable,
+      pythonBaseExecutable,
+      pythonPrefix,
       pythonLibrary,
       pythonPathExtra,
       envVars

package/src/native/python_bridge.cpp

@@ -12,6 +12,7 @@
 #include <stdexcept>
 #include <iostream>
 #include <algorithm>
+#include <fstream>
 
 #if defined(__linux__) || defined(__APPLE__)
 #include <dlfcn.h>
@@ -21,6 +22,40 @@ namespace pynect {
 
 namespace {
 
+void setEnvironmentVariable(const std::string& key, const std::string& value) {
+#ifdef _WIN32
+  _putenv_s(key.c_str(), value.c_str());
+#else
+  setenv(key.c_str(), value.c_str(), 1);
+#endif
+}
+
+PyObject* evaluateSource(
+  const std::string& source,
+  const std::string& filename,
+  const char* mode,
+  PyObject* globals
+) {
+  PyObject* builtins = PyImport_ImportModule("builtins");
+  if (!builtins) return nullptr;
+  PyRef builtinsRef = PyRef::steal(builtins);
+
+  PyObject* compile = PyObject_GetAttrString(builtins, "compile");
+  if (!compile) return nullptr;
+  PyRef compileRef = PyRef::steal(compile);
+
+  PyObject* code = PyObject_CallFunction(
+    compile,
+    "sss",
+    source.c_str(),
+    filename.c_str(),
+    mode
+  );
+  if (!code) return nullptr;
+  PyRef codeRef = PyRef::steal(code);
+  return PyEval_EvalCode(code, globals, globals);
+}
+
 #if defined(__linux__) || defined(__APPLE__)
 void promotePythonLibrary(const std::string& libraryPath) {
   if (libraryPath.empty()) {
@@ -60,6 +95,8 @@ PythonBridge& PythonBridge::getInstance() {
 void PythonBridge::initializePython(
   const std::string& pythonHome,
   const std::string& pythonExecutable,
+  const std::string& pythonBaseExecutable,
+  const std::string& pythonPrefix,
   const std::string& pythonLibrary,
   const std::vector<std::string>& extraSysPaths,
   const std::vector<std::pair<std::string, std::string>>& envVars
@@ -74,52 +111,57 @@ void PythonBridge::initializePython(
 
   // Set environment variables before initialization
   for (const auto& [key, val] : envVars) {
-#ifdef _WIN32
-    _putenv_s(key.c_str(), val.c_str());
-#else
-    setenv(key.c_str(), val.c_str(), 1);
-#endif
+    setEnvironmentVariable(key, val);
   }
 
-  // Configure the interpreter with the detected executable so CPython can
-  // resolve its standard library consistently across platforms.
-  PyConfig config;
-  PyConfig_InitPythonConfig(&config);
-  PyStatus status = PyConfig_SetBytesString(
-    &config,
-    &config.program_name,
-    pythonExecutable.c_str()
-  );
-  if (!PyStatus_Exception(status) && !pythonHome.empty()) {
-    status = PyConfig_SetBytesString(&config, &config.home, pythonHome.c_str());
-  }
-  if (!PyStatus_Exception(status)) {
-    status = Py_InitializeFromConfig(&config);
+  // These process-wide setters are in Python's Stable ABI. Keep their decoded
+  // storage alive until finalization, as required by CPython.
+  _programName = Py_DecodeLocale(pythonExecutable.c_str(), nullptr);
+  if (!_programName) {
+    throw std::runtime_error("Failed to decode the Python executable path");
   }
-  std::string configError = PyStatus_Exception(status) && status.err_msg
-    ? status.err_msg
-    : "";
-  PyConfig_Clear(&config);
-  if (PyStatus_Exception(status)) {
-    throw std::runtime_error("Failed to configure Python: " + configError);
+  Py_SetProgramName(_programName);
+  if (!pythonHome.empty()) {
+    _pythonHome = Py_DecodeLocale(pythonHome.c_str(), nullptr);
+    if (!_pythonHome) {
+      throw std::runtime_error("Failed to decode the Python home path");
+    }
+    Py_SetPythonHome(_pythonHome);
   }
+  Py_Initialize();
 
   if (!Py_IsInitialized()) {
     throw std::runtime_error("Failed to initialize Python interpreter");
   }
 
-  // Enable thread support
-  PyEval_InitThreads();
-
   // Save main thread state and release GIL so threads can run
   _mainThreadState = PyEval_SaveThread();
 
-  // Add extra sys.path entries (done with GIL held)
-  if (!extraSysPaths.empty()) {
+  // Restore the selected environment identity and add its import paths after
+  // Stable ABI initialization used the base installation for the stdlib.
+  {
     GILAcquire gil;
     PyObject* sysModule = PyImport_ImportModule("sys");
     if (sysModule) {
       PyRef sysRef = PyRef::steal(sysModule);
+      PyObject* executable = PyUnicode_FromString(pythonExecutable.c_str());
+      if (executable) {
+        PyRef executableRef = PyRef::steal(executable);
+        PyObject_SetAttrString(sysModule, "executable", executable);
+      }
+      PyObject* baseExecutable = PyUnicode_FromString(pythonBaseExecutable.c_str());
+      if (baseExecutable) {
+        PyRef baseExecutableRef = PyRef::steal(baseExecutable);
+        PyObject_SetAttrString(sysModule, "_base_executable", baseExecutable);
+      }
+      if (!pythonPrefix.empty()) {
+        PyObject* prefix = PyUnicode_FromString(pythonPrefix.c_str());
+        if (prefix) {
+          PyRef prefixRef = PyRef::steal(prefix);
+          PyObject_SetAttrString(sysModule, "prefix", prefix);
+          PyObject_SetAttrString(sysModule, "exec_prefix", prefix);
+        }
+      }
       PyObject* sysPath = PyObject_GetAttrString(sysModule, "path");
       if (sysPath) {
         PyRef pathRef = PyRef::steal(sysPath);
@@ -131,6 +173,23 @@ void PythonBridge::initializePython(
           }
         }
       }
+      PyObject* siteModule = PyImport_ImportModule("site");
+      if (siteModule) {
+        PyRef siteRef = PyRef::steal(siteModule);
+        PyObject* addSiteDirectory = PyObject_GetAttrString(siteModule, "addsitedir");
+        if (addSiteDirectory) {
+          PyRef addSiteDirectoryRef = PyRef::steal(addSiteDirectory);
+          for (const auto& p : extraSysPaths) {
+            PyObject* added = PyObject_CallFunction(addSiteDirectory, "s", p.c_str());
+            if (added) Py_DECREF(added);
+            else PyErr_Clear();
+          }
+        } else {
+          PyErr_Clear();
+        }
+      } else {
+        PyErr_Clear();
+      }
     }
   }
 
@@ -203,8 +262,7 @@ TaskResult PythonBridge::_makeSuccessResult(PyObject* obj) {
   }
 
   // For callable objects
-  if (PyCallable_Check(obj) && !PyFunction_Check(obj) &&
-      !PyModule_Check(obj) && !PyType_Check(obj)) {
+  if (PyCallable_Check(obj) && !PyModule_Check(obj) && !PyType_Check(obj)) {
     // Instance of a class with __call__ - usually want as reference
     result.objectId = TypeConverter::registerObject(obj);
     result.isObject = true;
@@ -563,7 +621,11 @@ bool PythonBridge::_buildCallArgs(
       argsOut = nullptr;
       return false;
     }
-    PyTuple_SET_ITEM(argsOut, static_cast<Py_ssize_t>(i), arg);  // steals reference
+    if (PyTuple_SetItem(argsOut, static_cast<Py_ssize_t>(i), arg) != 0) {
+      Py_DECREF(argsOut);
+      argsOut = nullptr;
+      return false;
+    }
   }
 
   // Build kwargs dict
@@ -643,7 +705,7 @@ TaskResult PythonBridge::runCodeSync(const std::string& code) {
 
   PyObject* globalDict = PyModule_GetDict(mainModule);  // borrowed
 
-  PyObject* result = PyRun_String(code.c_str(), Py_file_input, globalDict, globalDict);
+  PyObject* result = evaluateSource(code, "<pynect>", "exec", globalDict);
   if (!result) {
     return _makeErrorResult();
   }
@@ -661,7 +723,7 @@ TaskResult PythonBridge::evalExpressionSync(const std::string& expression) {
 
   PyObject* globalDict = PyModule_GetDict(mainModule);  // borrowed
 
-  PyObject* result = PyRun_String(expression.c_str(), Py_eval_input, globalDict, globalDict);
+  PyObject* result = evaluateSource(expression, "<pynect>", "eval", globalDict);
   if (!result) {
     return _makeErrorResult();
   }
@@ -671,8 +733,8 @@ TaskResult PythonBridge::evalExpressionSync(const std::string& expression) {
 }
 
 TaskResult PythonBridge::runFileSync(const std::string& filePath) {
-  FILE* fp = fopen(filePath.c_str(), "r");
-  if (!fp) {
+  std::ifstream input(filePath, std::ios::binary);
+  if (!input) {
     TaskResult r;
     r.success = false;
     r.errorType = "FileNotFoundError";
@@ -680,11 +742,14 @@ TaskResult PythonBridge::runFileSync(const std::string& filePath) {
     return r;
   }
 
+  std::ostringstream source;
+  source << input.rdbuf();
+
   PyObject* mainModule = PyImport_AddModule("__main__");
+  if (!mainModule) return _makeErrorResult();
   PyObject* globalDict = PyModule_GetDict(mainModule);
 
-  PyObject* result = PyRun_File(fp, filePath.c_str(), Py_file_input, globalDict, globalDict);
-  fclose(fp);
+  PyObject* result = evaluateSource(source.str(), filePath, "exec", globalDict);
 
   if (!result) {
     return _makeErrorResult();
@@ -763,7 +828,7 @@ TaskResult PythonBridge::getObjectKeysSync(uint32_t objectId) {
     PyObject* name = PyList_GetItem(dirList, i);
     if (!name || !PyUnicode_Check(name)) continue;
 
-    const char* nameStr = PyUnicode_AsUTF8(name);
+    const char* nameStr = PyUnicode_AsUTF8AndSize(name, nullptr);
     if (!nameStr) continue;
 
     // Filter out private names

package/src/native/python_bridge.h

@@ -67,6 +67,8 @@ public:
   void initializePython(
     const std::string& pythonHome,
     const std::string& pythonExecutable,
+    const std::string& pythonBaseExecutable,
+    const std::string& pythonPrefix,
     const std::string& pythonLibrary,
     const std::vector<std::string>& extraSysPaths,
     const std::vector<std::pair<std::string, std::string>>& envVars
@@ -253,6 +255,10 @@ private:
 
   bool _initialized = false;
   PyThreadState* _mainThreadState = nullptr;
+  // CPython requires these buffers to remain unchanged for the process
+  // lifetime, so the singleton intentionally retains them after finalization.
+  wchar_t* _programName = nullptr;
+  wchar_t* _pythonHome = nullptr;
 
   // Iterator registry: iteratorId -> Python iterator object
   std::map<uint32_t, PyObject*> _iterators;