(torchx/tracker) Allow AppRun.run_from_env() to be used without launching the app with torchx (#698)

Author: kiukchung

docs/source/app_best_practices.rst

@@ -105,7 +105,7 @@ model definition from a python file and then you'll load the weights and state
 dict from a ``.ckpt`` or ``.pt`` file.
 
 This is how Pytorch Lightning's
-`ModelCheckpoint <https://pytorch-lightning.readthedocs.io/en/latest/api/pytorch_lightning.callbacks.ModelCheckpoint.html>`__ hook works.
+`ModelCheckpoint <https://pytorch-lightning.readthedocs.io/en/stable/api/pytorch_lightning.callbacks.ModelCheckpoint.html>`__ hook works.
 
 This is the most common but makes it harder to make a reusable app since your
 trainer app needs to include the model definition code.

torchx/tracker/api.py

@@ -240,13 +240,39 @@ class AppRun:
     @staticmethod
     @lru_cache(maxsize=1)  # noqa: B019
     def run_from_env() -> AppRun:
-        """Factory method do build AppRun that uses environment variabes to build it.
+        """
+        Creates an :py:class:`AppRun` from environment variables. The environment variables are set by
+        the torchx runner. Hence if the application is launched via the torchx CLI as:
+
+        .. code-block:: shell-session
+
+            $ torchx run utils_python --script main.py
+
+
+        And the tracker settings are configured in ``.torchxconfig``, then this function returns an
+        ``AppRun`` with the configured tracker backends. This function returns a singleton ``AppRun``
+        hence the same instances of the tracker backend objects.
+
+        .. note::
+                When the application is NOT launched via torchx, this function
+                will return an "empty" ``AppRun`` with the ``job_id`` set to a constant
+                ``<UNDEFINED>`` since the app was not "launched" (e.g. submitted as a job)
+                and hence no canonical ``job_id`` exists.
+                No trackers are hooked up to the ``AppRun`` hence
+                calling ``add_*()`` (write) methods on the returned apprun will be a no-op.
+
+        Usage:
+
+        .. doctest::
+
+            >>> from torchx.tracker.api import AppRun
+            >>> apprun = AppRun.run_from_env()
+            >>> apprun.add_metadata(md_1 = "foo", md_2 = "bar")
+
 
-        Single instance of AppRun will be available for the duration of the application, thus expect that calling
-        this method will retorn same AppRun and hence same instances of the backend implementations.
         """
 
-        torchx_job_id = os.environ["TORCHX_JOB_ID"]
+        torchx_job_id = os.getenv("TORCHX_JOB_ID", default="<UNDEFINED>")
 
         trackers = trackers_from_environ()
         if TRACKER_PARENT_RUN_ENV_VAR_NAME in os.environ:

torchx/tracker/test/api_test.py

@@ -98,11 +98,14 @@ def run_ids(self, **kwargs: str) -> Iterable[str]:
 
 class AppRunApiTest(TestCase):
     def setUp(self) -> None:
-        os.environ["TORCHX_JOB_ID"] = "scheduler://sesison/app_id"
+        os.environ["TORCHX_JOB_ID"] = "scheduler://session/app_id"
         self.tracker = TestTrackerBackend()
         self.run_id = "run_id"
         self.model_run = AppRun(self.run_id, [self.tracker])
 
+    def tearDown(self) -> None:
+        del os.environ["TORCHX_JOB_ID"]
+
     @mock.patch.dict(
         os.environ,
         {
@@ -266,3 +269,16 @@ def test_build_trackers(self) -> None:
             self.assertEqual(1, len(trackers))
             tracker = trackers[0]
             self.assertEqual(tracker.config_path, "myconfig.txt")  # pyre-ignore[16]
+
+    @mock.patch.dict(os.environ, {}, clear=True)
+    def test_run_from_env_not_launched_with_torchx(self) -> None:
+        # asserts that an empty AppRun (with no trackers and job_id defaulted to program name)
+        # is created if not launched from torchx
+        # makes it possible to use `torchx.tracker.app_run_from_env()` without being tightly coupled with
+        # the torchx launcher
+
+        AppRun.run_from_env.cache_clear()
+        apprun = AppRun.run_from_env()
+        self.assertEqual("<UNDEFINED>", apprun.job_id())
+        # no backends configured if not launched via torchx
+        self.assertEqual([], list(apprun.backends))