Add an env var to disable pkg_resources (#928)

* Add an env var to disable pkg_resources

- in some cases, pkg_resources can be slow to both import and use
- adds the OTIO_DISABLE_PKG_RESOURCE_PLUGINS environment variable to
  disable using this library for users that have those issues.
- Even for users not experiencing those issues, this speeds up the
  import time of OTIO slightly.

* add env variable doc page

* Update docs/tutorials/otio-env-variables.md

* Update docs/tutorials/otio-env-variables.md

* clarified comment

Co-authored-by: ssteinbach <[email protected]>

Author: ssteinbach

docs/index.rst

@@ -26,6 +26,7 @@ Quick Start
    :maxdepth: 2
 
    tutorials/quickstart
+   tutorials/otio-env-variables
 
 Tutorials
 ------------

docs/tutorials/otio-env-variables.md

@@ -0,0 +1,18 @@
+# Environment Variables
+
+This document describes the environment variables that can be used to configure
+various aspects of OTIO.
+
+## Plugin Configuration
+
+These variables must be set _before_ the OpenTimelineIO python library is imported.
+
+- `OTIO_PLUGIN_MANIFEST_PATH`: a ":" separated string with paths to .manifest.json files that contain OTIO plugin manifests.  See: <a href="write-an-adapter.html" target="_blank">Tutorial on how to write an adapter plugin</a>.
+- `OTIO_DEFAULT_MEDIA_LINKER`: the name of the default media linker to use after reading a file, if "" then no media linker is automatically invoked.
+- `OTIO_DISABLE_PKG_RESOURCE_PLUGINS`: By default, OTIO will use the pkg_resource entry_points mechanism to discover plugins that have been installed into the current python environment.  pkg_resources, however, can be slow in certain cases, so for users who wish to disable this behavior, this variable can be set to 1.
+
+## Unit tests
+
+These variables only impact unit tests.
+
+- `OTIO_DISABLE_SHELLOUT_TESTS`: When running the unit tests, skip the console tests that run the otiocat program and check output through the shell.  This is desirable in environments where running the commandline tests is not meaningful or problematic.  Does not disable the tests that run through python calling mechanisms.

src/py-opentimelineio/opentimelineio/plugins/manifest.py

@@ -28,11 +28,17 @@
 import logging
 import os
 
-# on some python interpreters, pkg_resources is not available
-try:
-    import pkg_resources
-except ImportError:
+# In some circumstances pkg_resources has bad performance characteristics.
+# Using the envirionment variable: $OTIO_DISABLE_PKG_RESOURCE_PLUGINS disables
+# OpenTimelineIO's import and of use of the pkg_resources module.
+if os.environ.get("OTIO_DISABLE_PKG_RESOURCE_PLUGINS", False):
     pkg_resources = None
+else:
+    try:
+        # on some python interpreters, pkg_resources is not available
+        import pkg_resources
+    except ImportError:
+        pkg_resources = None
 
 from .. import (
     core,

tests/test_plugin_detection.py

@@ -26,6 +26,7 @@
 import os
 import pkg_resources
 import sys
+import importlib
 
 try:
     # Python 3.3 forward includes the mock module
@@ -75,7 +76,8 @@ def setUp(self):
     def tearDown(self):
         self.sys_patch.stop()
         self.entry_patcher.stop()
-        del(sys.modules['otio_mockplugin'])
+        if 'otio_mockplugin' in sys.modules:
+            del(sys.modules['otio_mockplugin'])
 
     def test_detect_plugin(self):
         """This manifest uses the plugin_manifest function"""
@@ -98,6 +100,20 @@ def test_detect_plugin(self):
         for linker in man.media_linkers:
             self.assertIsInstance(linker, otio.media_linker.MediaLinker)
 
+    def test_pkg_resources_disabled(self):
+        os.environ["OTIO_DISABLE_PKG_RESOURCE_PLUGINS"] = "1"
+        importlib.reload(otio.plugins.manifest)
+
+        # detection of the environment variable happens on import, force a
+        # reload to ensure that it is triggered
+        with self.assertRaises(AssertionError):
+            self.test_detect_plugin()
+
+        # remove the environment variable and reload again for usage in the
+        # other tests
+        del os.environ["OTIO_DISABLE_PKG_RESOURCE_PLUGINS"]
+        importlib.reload(otio.plugins.manifest)
+
     def test_detect_plugin_json_manifest(self):
         # Test detecting a plugin that rather than exposing the plugin_manifest
         # function, just simply has a plugin_manifest.json provided at the