local_scheduler: add local_cwd scheduler + improve default handling (#203)

Summary:
* `local_cwd`: This adds a new scheduler/image provider that overrides the image with the current working directory. This is intended to be a better approach for local launching since it doesn't require interacting with the images.
* This removes `local_dir` scheduler in favor of `local_cwd`.
* Changes how the default scheduler is specified since it's unclear what `default` even means without looking at the code and instead the CLI specifies the default via argparse default.
* Updates the documentation to use local_cwd and local_docker instead.

Pull Request resolved: #203

Test Plan:
```
$ pytest
$ pyre
$ env O="--port 4444" make clean livehtml
```

Go to quickstart page and ensure command run without any changes.

CI

Reviewed By: aivanou

Differential Revision: D31178356

Pulled By: d4l3k

fbshipit-source-id: e1fff784184b1b3a41a01cbed2d96dec2345f774

Author: d4l3k

docs/source/quickstart.rst

@@ -26,7 +26,7 @@ Echo looks familiar and simple. Lets understand how to run ``utils.echo``.
 
 .. code-block:: shell-session
 
- $ torchx run --scheduler local utils.echo --help
+ $ torchx run --scheduler local_cwd utils.echo --help
  usage: torchx run echo [-h] [--msg MSG]
 
  Echos a message
@@ -39,7 +39,7 @@ We can see that it takes a ``--msg`` argument. Lets try running it locally
 
 .. code-block:: shell-session
 
- $ torchx run --scheduler local utils.echo --msg "hello world"
+ $ torchx run --scheduler local_cwd utils.echo --msg "hello world"
 
 .. note:: ``echo`` in this context is just an app spec. It is not the application
           logic itself but rather just the "job definition" for running `/bin/echo`.
@@ -83,7 +83,7 @@ Now copy paste the following into ``test.py``
              specs.Role(
                  name="echo",
                  entrypoint="/bin/echo",
-                 image="/tmp",
+                 image="ubuntu:latest",
                  args=[f"replica #{specs.macros.replica_id}: {msg}"],
                  num_replicas=num_replicas,
              )
@@ -94,17 +94,15 @@ Notice that
 
 1. Unlike ``--msg``, ``--num_replicas`` does not have a default value
    indicating that it is a required argument.
-2. We use a local dir (``/tmp``) as the ``image``. In practice this will be
-   the identifier of the package (e.g. Docker image) that the scheduler supports.
-3. ``test.py`` does **not** contain the logic of the app and is
+2. ``test.py`` does **not** contain the logic of the app and is
    simply a job definition.
 
 
 Now lets try running our custom ``echo``
 
 .. code-block:: shell-session
 
- $ torchx run --scheduler local ~/test.py:echo --num_replicas 4 --msg "foobar"
+ $ torchx run --scheduler local_cwd ~/test.py:echo --num_replicas 4 --msg "foobar"
 
  replica #0: foobar
  replica #1: foobar
@@ -113,13 +111,14 @@ Now lets try running our custom ``echo``
 
 Running on Other Images
 -----------------------------
-So far we've run ``utils.echo`` with ``image=/tmp``. This means that the
-``entrypoint`` we specified is relative to ``/tmp``. That did not matter for us
+So far we've run ``utils.echo`` with the ``local_cwd`` scheduler. This means that the
+``entrypoint`` we specified is relative to the current working directory and
+ignores the specified image. That did not matter for us
 since we specified an absolute path as the entrypoint (``entrypoint=/bin/echo``).
-Had we specified ``entrypoint=echo`` the local scheduler would have tried to invoke
-``/tmp/echo``.
+Had we specified ``entrypoint=echo`` the local_cwd scheduler would have tried to invoke
+``echo`` relative to the current directory and the specified PATH.
 
-If you have a pre-built application binary, setting the image to a local directory is a
+If you have a pre-built application binary, using local_cwd is a
 quick way to validate the application and the ``specs.AppDef``. But its not all
 that useful if you want to run the application on a remote scheduler
 (see :ref:`quickstart:Running On Other Schedulers`).
@@ -128,18 +127,8 @@ that useful if you want to run the application on a remote scheduler
           supported by the scheduler. Refer to the scheduler documentation to find out
           what container image is supported by the scheduler you want to use.
 
-For ``local`` scheduler we can see that it supports both a local directory
-and docker as the image:
-
-.. code-block:: shell-session
-
- $ torchx runopts local
-
- { 'image_type': { 'default': 'dir',
-                  'help': 'image type. One of [dir, docker]',
-                  'type': 'str'},
- ... <omitted for brevity> ...
-
+To match remote image behavior we can use the ``local_docker`` scheduler which
+will launch the image via docker and run the same application.
 
 .. note:: Before proceeding, you will need docker installed. If you have not done so already
           follow the install instructions on: https://docs.docker.com/get-docker/
@@ -178,8 +167,7 @@ Try running the echo app
 
 .. code-block:: shell-session
 
- $ torchx run --scheduler local \
-              --scheduler_args image_type=docker \
+ $ torchx run --scheduler local_docker \
               ~/test.py:echo \
               --num_replicas 4 \
               --msg "foobar from docker!"
@@ -209,15 +197,15 @@ required by the scheduler you are planning to use
 .. code-block:: shell-session
 
  $ torchx runopts <sched_name>
- $ torchx runopts local
+ $ torchx runopts local_docker
 
 Now that you've figured out what scheduler args are required, launch your app
 
 .. code-block:: shell-session
 
  $ torchx run --scheduler <sched_name> --scheduler_args <k1=v1,k2=v2,...> \
      utils.sh ~/my_app.py <app_args...>
- $ torchx run --scheduler local --scheduler_args image_type=dir,log_dir=/tmp \
+ $ torchx run --scheduler local_cwd --scheduler_args log_dir=/tmp \
      utils.sh ~/my_app.py --foo=bar
 
 .. note:: If your app args overlap with the ``run`` subcommand's args, you
@@ -227,7 +215,7 @@ Now that you've figured out what scheduler args are required, launch your app
 
 .. code-block:: shell-session
 
- $ torchx run --scheduler local ~/my_app.py -- --scheduler foobar
+ $ torchx run --scheduler local_docker ~/my_app.py -- --scheduler foobar
 
 
 Next Steps

docs/source/schedulers.rst

@@ -5,6 +5,11 @@ torchx.schedulers
 .. currentmodule:: torchx.schedulers
 
 .. autofunction:: get_schedulers
+.. autofunction:: get_scheduler_factories
+.. autofunction:: get_default_scheduler_name
 
 .. autoclass:: Scheduler
-   :members:
+   :members:
+
+.. autoclass:: SchedulerFactory
+   :members:

docs/source/schedulers/local.rst

@@ -13,8 +13,8 @@ Image Providers
 .. autoclass:: ImageProvider
    :members:
 
-.. autoclass:: LocalDirectoryImageProvider
+.. autoclass:: DockerImageProvider
    :members:
 
-.. autoclass::DockerImageProvider
+.. autoclass:: CWDImageProvider
    :members:

torchx/cli/__init__.py

@@ -31,13 +31,23 @@
   3. touch
   ... <omitted for brevity>
 
-Listing the supported schedulers
-----------------------------------
+Listing the supported schedulers and arguments
+-------------------------------------------------
 To get a list of supported schedulers that you can launch your job into run:
 
 .. code-block:: shell-session
 
- $ torchx schedulers
+ $ torchx runopts
+ local_docker:
+ { 'log_dir': { 'default': 'None',
+                'help': 'dir to write stdout/stderr log files of replicas',
+                'type': 'str'}}
+ local_cwd:
+ ...
+ slurm:
+ ...
+ kubernetes:
+ ...
 
 Running a component as a job
 ---------------------------------
@@ -80,27 +90,24 @@ def my_trainer(foo: int, bar: str) -> specs.AppDef:
 
 2. arguments to the scheduler (``--scheduler_args``, also known as ``run_options`` or ``run_configs``),
    each scheduler takes different args, to find out the args for a specific scheduler run (command for
-   ``local`` scheduler shown below:
+   ``local_cwd`` scheduler shown below:
 
    .. code-block:: shell-session
 
-    $ torchx runopts local
-    { 'image_fetcher': { 'default': 'dir',
-                     'help': 'image fetcher type',
-                     'type': 'str'},
-    'log_dir': { 'default': 'None',
+    $ torchx runopts local_cwd
+    { 'log_dir': { 'default': 'None',
                'help': 'dir to write stdout/stderr log files of replicas',
                'type': 'str'}}
 
     # pass run options as comma-delimited k=v pairs
-    $ torchx run --scheduler local --scheduler_args image_fetcher=dir,log_dir=/tmp ...
+    $ torchx run --scheduler local_cwd --scheduler_args log_dir=/tmp ...
 
 3. arguments to the component (the app args are included here), this also depends on the
    component and can be seen with the ``--help`` string on the component
 
    .. code-block:: shell-session
 
-    $ torchx run --scheduler local utils.echo --help
+    $ torchx run --scheduler local_cwd utils.echo --help
     usage: torchx run echo.torchx [-h] [--msg MSG]
 
     Echos a message
@@ -109,11 +116,11 @@ def my_trainer(foo: int, bar: str) -> specs.AppDef:
     -h, --help  show this help message and exit
     --msg MSG   Message to echo
 
-Putting everything together, running ``echo`` with the ``local`` scheduler:
+Putting everything together, running ``echo`` with the ``local_cwd`` scheduler:
 
 .. code-block:: shell-session
 
- $ torchx run --scheduler local --scheduler_args image_fetcher=dir,log_dir=/tmp utils.echo --msg "hello $USER"
+ $ torchx run --scheduler local_cwd --scheduler_args log_dir=/tmp utils.echo --msg "hello $USER"
  === RUN RESULT ===
  Launched app: local://torchx_kiuk/echo_ecd30f74
 
@@ -137,7 +144,7 @@ def my_trainer(foo: int, bar: str) -> specs.AppDef:
 
 .. code-block:: shell-session
 
- $ torchx run --dryrun utils.echo --msg  hello_world
+ $ torchx run --dryrun utils.echo --msg hello_world
  === APPLICATION ===
  { 'metadata': {},
    'name': 'echo',

torchx/cli/cmd_run.py

@@ -15,7 +15,7 @@
 from pyre_extensions import none_throws
 from torchx.cli.cmd_base import SubCommand
 from torchx.runner import Runner, get_runner
-from torchx.schedulers import get_scheduler_factories
+from torchx.schedulers import get_scheduler_factories, get_default_scheduler_name
 from torchx.specs.finder import (
     _Component,
     get_components,
@@ -77,7 +77,7 @@ def add_arguments(self, subparser: argparse.ArgumentParser) -> None:
             "--scheduler",
             type=str,
             help=f"Name of the scheduler to use. One of: [{','.join(scheduler_names)}]",
-            default="default",
+            default=get_default_scheduler_name(),
         )
         subparser.add_argument(
             "--scheduler_args",
@@ -140,7 +140,7 @@ def _run(self, runner: Runner, args: argparse.Namespace) -> None:
             app_handle = cast(specs.AppHandle, result)
             print(app_handle)
 
-            if args.scheduler == "local":
+            if args.scheduler.startswith("local"):
                 self._wait_and_exit(runner, app_handle)
             else:
                 logger.info("=== RUN RESULT ===")

torchx/cli/test/cmd_run_test.py

@@ -45,7 +45,7 @@ def test_run_with_user_conf_abs_path(self) -> None:
         args = self.parser.parse_args(
             [
                 "--scheduler",
-                "local",
+                "local_cwd",
                 str(Path(__file__).parent / "components.py:touch"),
                 "--file",
                 str(self.tmpdir / "foobar.txt"),
@@ -60,7 +60,7 @@ def test_run_with_relpath(self) -> None:
             args = self.parser.parse_args(
                 [
                     "--scheduler",
-                    "local",
+                    "local_cwd",
                     str(Path(__file__).parent / "components.py:touch_v2"),
                     "--file",
                     str(self.tmpdir / "foobar.txt"),
@@ -83,7 +83,7 @@ def test_run_terminate_on_received_signal(
             args = self.parser.parse_args(
                 [
                     "--scheduler",
-                    "local",
+                    "local_cwd",
                     str(Path(__file__).parent / "components.py:touch_v2"),
                     "--file",
                     str(self.tmpdir / "foobar.txt"),
@@ -99,7 +99,7 @@ def test_run_missing(self) -> None:
         args = self.parser.parse_args(
             [
                 "--scheduler",
-                "local",
+                "local_cwd",
                 "1234_does_not_exist.torchx",
             ]
         )
@@ -111,7 +111,7 @@ def test_run_dryrun(self, mock_runner_run: MagicMock) -> None:
             [
                 "--dryrun",
                 "--scheduler",
-                "local",
+                "local_cwd",
                 "utils.echo",
                 "--image",
                 "/tmp",

torchx/cli/test/main_test.py

@@ -5,6 +5,7 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
+import os
 import unittest
 from pathlib import Path
 
@@ -17,17 +18,22 @@
 
 
 class CLITest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.old_cwd = os.getcwd()
+        os.chdir(_root / "container")
+
+    def tearDown(self) -> None:
+        os.chdir(self.old_cwd)
+
     def test_run_abs_config_path(self) -> None:
         main(
             [
                 "run",
                 "--scheduler",
-                "local",
+                "local_cwd",
                 str(_root / "components.py:simple"),
                 "--num_trainers",
                 "2",
-                "--trainer_image",
-                str(_root / "container"),
             ]
         )
 
@@ -36,11 +42,9 @@ def test_run_builtin_config(self) -> None:
             [
                 "run",
                 "--scheduler",
-                "local",
+                "local_cwd",
                 _SIMPLE_CONF,
                 "--num_trainers",
                 "2",
-                "--trainer_image",
-                str(_root / "container"),
             ]
         )

torchx/components/__init__.py

@@ -20,11 +20,11 @@
 
   # using via sdk
   from torchx.runner import get_runner
-  get_runner().run_component("distributed.ddp", app_args=[], scheduler="local", ...)
+  get_runner().run_component("distributed.ddp", app_args=[], scheduler="local_cwd", ...)
 
   # using via torchx-cli
 
-  >> torchx run --scheduler local distributed.ddp --param1 --param2
+  >> torchx run --scheduler local_cwd distributed.ddp --param1 --param2
 
 
 Components development