From cc1ea30552f4c0e2dc60b539674e55f8c406041e Mon Sep 17 00:00:00 2001 From: Zach Lewis Date: Mon, 13 Jan 2025 15:41:56 -0500 Subject: [PATCH] fix: Use OPENIMAGEIO_ env var prefix and document DLL loading behavior OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH instead of OIIO_PYTHON_LOAD_DLLS_FROM_PATH. Signed-off-by: Zach Lewis --- .github/workflows/ci.yml | 2 +- INSTALL.md | 9 +++++++++ src/doc/imageioapi.rst | 14 ++++++++++++++ src/python/__init__.py | 4 ++-- 4 files changed, 26 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d24afcbe22..87a36a6311 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -594,4 +594,4 @@ jobs: vsver: 2022 generator: "Visual Studio 17 2022" python_ver: "3.9" - setenvs: export OIIO_PYTHON_LOAD_DLLS_FROM_PATH=1 + setenvs: export OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH=1 diff --git a/INSTALL.md b/INSTALL.md index f3c9033e43..0d5e38bb01 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -359,6 +359,15 @@ produce a dynamic-linked version. 3. Execute the PowerShell command from where vcpkg is located in directory. ``vcpkg install openimageio`` +**Note: Importing the OpenImageIO Python Module** + +As of OpenImageIO 3.0.3.0, the default DLL-loading behavior for Python 3.8+ has changed. + +If you've built OIIO from source and ``import OpenImageIO`` is throwing a ModuleNotFound exception, revert to the legacy DLL-loading behavior by setting environment variable +``OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH=1``. + + + Python-based Builds and Installs -------------------------------- diff --git a/src/doc/imageioapi.rst b/src/doc/imageioapi.rst index f294024d80..9bb7eaa142 100644 --- a/src/doc/imageioapi.rst +++ b/src/doc/imageioapi.rst @@ -384,3 +384,17 @@ inside the source code. name and version of the software and an indecipherable hash of the command line, but not the full human-readable command line. (This was added in OpenImageIO 2.5.11.) + +.. cpp:var:: OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH + + Windows only. Mimics the DLL-loading behavior of Python 3.7 and earlier. + If set to "1", all directories under ``PATH`` will be added to the DLL load + path before attempting to import the OpenImageIO module. (This was added in + OpenImageIO 3.0.3.0) + + Note: This "opt-in-style" behavior replaces and inverts the "opt-out-style" + Windows DLL-loading behavior governed by the now-defunct `OIIO_LOAD_DLLS_FROM_PATH` + environment variable (added in OpenImageIO 2.4.0/2.3.18). + + In other words, to reproduce the default Python-module-loading behavior of + earlier versions of OIIO, set ``OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH=1``. diff --git a/src/python/__init__.py b/src/python/__init__.py index 2eb0a9c3e0..6754b95cde 100644 --- a/src/python/__init__.py +++ b/src/python/__init__.py @@ -24,8 +24,8 @@ # We reproduce the old behavior by manually tokenizing PATH, checking that the # directories exist and are not ".", then add them to the DLL load path. # This behavior is disabled by default, but can be enabled by setting the environment - # variable "OIIO_PYTHON_LOAD_DLLS_FROM_PATH" to "1" - if os.getenv("OIIO_PYTHON_LOAD_DLLS_FROM_PATH", "0") == "1": + # variable "OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH" to "1" + if os.getenv("OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH", "0") == "1": for path in os.getenv("PATH", "").split(os.pathsep): if os.path.exists(path) and path != ".": os.add_dll_directory(path)