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 <[email protected]>

.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

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

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

@@ -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)