feat: Disable loading Python DLLs from PATH by default on Windows (#4590

)

Users can enable the legacy behavior by setting env var
`OIIO_PYTHON_LOAD_DLLS_FROM_PATH=1`.

This commit also changes the environment variable name from
`OIIO_LOAD_DLLS_FROM_PATH` to `OIIO_PYTHON_LOAD_DLLS_FROM_PATH` to match
the convention used by OCIO.

This PR addresses issue  #4519

---------

Signed-off-by: Zach Lewis <zachcanbereached@gmail.com>

.github/workflows/ci.yml

@@ -589,8 +589,10 @@ jobs:
             vsver: 2019
             generator: "Visual Studio 16 2019"
             python_ver: "3.9"
+            setenvs: export OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH=1
           - desc: Windows-2022 VS2022
             runner: windows-2022
             vsver: 2022
             generator: "Visual Studio 17 2022"
             python_ver: "3.9"
+            setenvs: export OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH=1

INSTALL.md

@@ -357,6 +357,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``. 
+
+
 Test Images
 -----------
 

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``.

src/python/__init__.py

@@ -7,8 +7,8 @@
 # This works around the python 3.8 change to stop loading DLLs from PATH on Windows.
 # We reproduce the old behaviour by manually tokenizing PATH, checking that the directories exist and are not ".",
 # then add them to the DLL load path.
-# This behviour can be disabled by setting the environment variable "OIIO_LOAD_DLLS_FROM_PATH" to "0"
-if sys.version_info >= (3, 8) and platform.system() == "Windows" and os.getenv("OIIO_LOAD_DLLS_FROM_PATH", "1") == "1":
+# This behviour can be enabled by setting the environment variable "OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH" to "1"
+if sys.version_info >= (3, 8) and platform.system() == "Windows" and 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)