Make example run from any directory (#377)

* Make it possible to run example scripts from anywhere.

* Add a docstring for the test case

* Add missing __init__.py

* Import abcdefg...

envisage/examples/_demo.py

@@ -0,0 +1,36 @@
+# (C) Copyright 2007-2020 Enthought, Inc., Austin, TX
+# All rights reserved.
+#
+# This software is provided without warranty under the terms of the BSD
+# license included in LICENSE.txt and may be redistributed only under
+# the conditions described in the aforementioned license. The license
+# is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+# Thanks for using Enthought open source!
+""" Utilities for supporting Envisage's demo examples.
+"""
+
+import contextlib
+import os
+import sys
+
+
+@contextlib.contextmanager
+def demo_path(path):
+    """ Context manager to temporarily insert the directory containing
+    the demo script to sys.path such that demo examples can be run using
+    local packages.
+
+    This function should only be used by Envisage example files.
+
+    Parameters
+    ----------
+    path : Path-like
+        Path to the demo script to be run.
+    """
+    path = os.path.dirname(os.fspath(path))
+    try:
+        sys.path.insert(0, path)
+        yield
+    finally:
+        sys.path.remove(path)

envisage/examples/tests/test__demo.py

@@ -0,0 +1,24 @@
+# (C) Copyright 2007-2020 Enthought, Inc., Austin, TX
+# All rights reserved.
+#
+# This software is provided without warranty under the terms of the BSD
+# license included in LICENSE.txt and may be redistributed only under
+# the conditions described in the aforementioned license. The license
+# is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+# Thanks for using Enthought open source!
+import os
+import sys
+import unittest
+
+from envisage.examples._demo import demo_path
+
+
+class TestDemoUtilities(unittest.TestCase):
+    """ Test utility functions in the _demo module."""
+
+    def test_sys_path_inserted(self):
+        path = os.path.join("dirname", "file.py")
+        with demo_path(path):
+            self.assertIn("dirname", sys.path)
+        self.assertNotIn("dirname", sys.path)

examples/MOTD/run.py

@@ -7,12 +7,6 @@
 # Enthought library imports.
 from envisage.api import Application, CorePlugin
 
-# Example plugins.
-from acme.motd.motd_plugin import MOTDPlugin
-from acme.motd.software_quotes.software_quotes_plugin import (
-    SoftwareQuotesPlugin,
-)
-
 
 # Do whatever you want to do with log messages! Here we create a log file.
 logger = logging.getLogger()
@@ -22,7 +16,12 @@
 
 def main():
     """ Run the application. """
-
+    # Import here so that this script can be run from anywhere without
+    # having to install the packages.
+    from acme.motd.motd_plugin import MOTDPlugin
+    from acme.motd.software_quotes.software_quotes_plugin import (
+        SoftwareQuotesPlugin,
+    )
     # Create an application containing the appropriate plugins.
     application = Application(
         id="acme.motd",
@@ -34,4 +33,9 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    # This context manager is added so that one can run this example from any
+    # directory without necessarily having installed the examples as packages.
+    from envisage.examples._demo import demo_path
+
+    with demo_path(__file__):
+        main()

examples/plugins/tasks/index.rst

@@ -2,9 +2,7 @@ Welcome to the attractors example.
 
 To run the application::
 
-  python -m attractors.run
-
-from this directory.
+  python run_attractor.py
 
 Note that this example application depends on the following additional
 packages::

examples/plugins/tasks/run_attractor.py

@@ -0,0 +1,32 @@
+# Standard library imports.
+import logging
+
+# Plugin imports.
+from envisage.api import CorePlugin
+from envisage.ui.tasks.api import TasksPlugin
+
+
+def main(argv):
+    """ Run the application.
+    """
+    # Import here so that this script can be run from anywhere without
+    # having to install the packages.
+    from attractors.attractors_plugin import AttractorsPlugin
+    from attractors.attractors_application import AttractorsApplication
+    logging.basicConfig(level=logging.WARNING)
+
+    plugins = [CorePlugin(), TasksPlugin(), AttractorsPlugin()]
+    app = AttractorsApplication(plugins=plugins)
+    app.run()
+
+    logging.shutdown()
+
+
+if __name__ == "__main__":
+    import sys
+    # This context manager is added so that one can run this example from any
+    # directory without necessarily having installed the examples as packages.
+    from envisage.examples._demo import demo_path
+
+    with demo_path(__file__):
+        main(sys.argv)