Use argparse for arg parsing (#2586)

* encapsulate commandline args

* fix tests

* add tests on cmdline parsing

* cleanup

* remove docopt

* simplify --slow

docs/Training-on-Microsoft-Azure-Custom-Instance.md

     ```sh
     pip3 install pillow
     pip3 install numpy
-    pip3 install docopt
     ```
 
 13. You can now return to the

docs/Training-on-Microsoft-Azure.md

 A pre-configured virtual machine image is available in the Azure Marketplace and
 is nearly completely ready for training.  You can start by deploying the
 [Data Science Virtual Machine for Linux (Ubuntu)](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/microsoft-dsvm.linux-data-science-vm-ubuntu)
-into your Azure subscription.  Once your VM is deployed, SSH into it and run the
-following command to complete dependency installation:
-
-```sh
-pip3 install docopt
-```
+into your Azure subscription.
 
 Note that, if you choose to deploy the image to an
 [N-Series GPU optimized VM](https://docs.microsoft.com/azure/virtual-machines/linux/sizes-gpu),

ml-agents/mlagents/trainers/learn.py

 # # Unity ML-Agents Toolkit
 
 import logging
+import argparse
 
 from multiprocessing import Process, Queue
 import os
 import yaml
-from docopt import docopt
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, Dict, Optional, List, NamedTuple
 
 
 from mlagents.trainers.trainer_controller import TrainerController
 from mlagents.envs.subprocess_env_manager import SubprocessEnvManager
 
 
+class CommandLineOptions(NamedTuple):
+    debug: bool
+    num_runs: int
+    seed: int
+    env_path: str
+    run_id: str
+    load_model: bool
+    train_model: bool
+    save_freq: int
+    keep_checkpoints: int
+    base_port: int
+    num_envs: int
+    curriculum_folder: Optional[str]
+    lesson: int
+    slow: bool
+    no_graphics: bool
+    multi_gpu: bool  # ?
+    trainer_config_path: str
+    sampler_file_path: Optional[str]
+    docker_target_name: Optional[str]
+
+    @property
+    def fast_simulation(self) -> bool:
+        return not self.slow
+
+    @staticmethod
+    def from_argparse(args: Any) -> "CommandLineOptions":
+        return CommandLineOptions(**vars(args))
+
+
+def parse_command_line(argv: Optional[List[str]] = None) -> CommandLineOptions:
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter
+    )
+    parser.add_argument("trainer_config_path")
+    parser.add_argument(
+        "--env", default=None, dest="env_path", help="Name of the Unity executable "
+    )
+    parser.add_argument(
+        "--curriculum",
+        default=None,
+        dest="curriculum_folder",
+        help="Curriculum json directory for environment",
+    )
+    parser.add_argument(
+        "--sampler",
+        default=None,
+        dest="sampler_file_path",
+        help="Reset parameter yaml file for environment",
+    )
+    parser.add_argument(
+        "--keep-checkpoints",
+        default=5,
+        type=int,
+        help="How many model checkpoints to keep",
+    )
+    parser.add_argument(
+        "--lesson", default=0, type=int, help="Start learning from this lesson"
+    )
+    parser.add_argument(
+        "--load",
+        default=False,
+        dest="load_model",
+        action="store_true",
+        help="Whether to load the model or randomly initialize",
+    )
+    parser.add_argument(
+        "--run-id",
+        default="ppo",
+        help="The directory name for model and summary statistics",
+    )
+    parser.add_argument(
+        "--num-runs", default=1, type=int, help="Number of concurrent training sessions"
+    )
+    parser.add_argument(
+        "--save-freq", default=50000, type=int, help="Frequency at which to save model"
+    )
+    parser.add_argument(
+        "--seed", default=-1, type=int, help="Random seed used for training"
+    )
+    parser.add_argument(
+        "--slow", action="store_true", help="Whether to run the game at training speed"
+    )
+    parser.add_argument(
+        "--train",
+        default=False,
+        dest="train_model",
+        action="store_true",
+        help="Whether to train model, or only run inference",
+    )
+    parser.add_argument(
+        "--base-port",
+        default=5005,
+        type=int,
+        help="Base port for environment communication",
+    )
+    parser.add_argument(
+        "--num-envs",
+        default=1,
+        type=int,
+        help="Number of parallel environments to use for training",
+    )
+    parser.add_argument(
+        "--docker-target-name",
+        default=None,
+        dest="docker_target_name",
+        help="Docker volume to store training-specific files",
+    )
+    parser.add_argument(
+        "--no-graphics",
+        default=False,
+        action="store_true",
+        help="Whether to run the environment in no-graphics mode",
+    )
+    parser.add_argument(
+        "--debug",
+        default=False,
+        action="store_true",
+        help="Whether to run ML-Agents in debug mode with detailed logging",
+    )
+    parser.add_argument(
+        "--multi-gpu",
+        default=False,
+        action="store_true",
+        help="Setting this flag enables the use of multiple GPU's (if available) during training",
+    )
+
+    args = parser.parse_args(argv)
+    return CommandLineOptions.from_argparse(args)
+
+
-    sub_id: int, run_seed: int, run_options: Dict[str, Any], process_queue: Queue
+    sub_id: int, run_seed: int, options: CommandLineOptions, process_queue: Queue
+    :param options: parsed command line arguments
-    docker_target_name = (
-        run_options["--docker-target-name"]
-        if run_options["--docker-target-name"] != "None"
-        else None
-    )
-
-    # General parameters
-    env_path = run_options["--env"] if run_options["--env"] != "None" else None
-    run_id = run_options["--run-id"]
-    load_model = run_options["--load"]
-    train_model = run_options["--train"]
-    save_freq = int(run_options["--save-freq"])
-    keep_checkpoints = int(run_options["--keep-checkpoints"])
-    base_port = int(run_options["--base-port"])
-    num_envs = int(run_options["--num-envs"])
-    curriculum_folder = (
-        run_options["--curriculum"] if run_options["--curriculum"] != "None" else None
-    )
-    lesson = int(run_options["--lesson"])
-    fast_simulation = not bool(run_options["--slow"])
-    no_graphics = run_options["--no-graphics"]
-    multi_gpu = run_options["--multi-gpu"]
-    trainer_config_path = run_options["<trainer-config-path>"]
-    sampler_file_path = (
-        run_options["--sampler"] if run_options["--sampler"] != "None" else None
-    )
+    trainer_config_path = options.trainer_config_path
+    curriculum_folder = options.curriculum_folder
-    if not docker_target_name:
-        model_path = "./models/{run_id}-{sub_id}".format(run_id=run_id, sub_id=sub_id)
+    if not options.docker_target_name:
+        model_path = "./models/{run_id}-{sub_id}".format(
+            run_id=options.run_id, sub_id=sub_id
+        )
-            docker_target_name=docker_target_name,
+            docker_target_name=options.docker_target_name,
-                docker_target_name=docker_target_name,
+                docker_target_name=options.docker_target_name,
-            docker_target_name=docker_target_name, run_id=run_id, sub_id=sub_id
+            docker_target_name=options.docker_target_name,
+            run_id=options.run_id,
+            sub_id=sub_id,
-            docker_target_name=docker_target_name
+            docker_target_name=options.docker_target_name
-        env_path,
-        docker_target_name,
-        no_graphics,
+        options.env_path,
+        options.docker_target_name,
+        options.no_graphics,
-        base_port + (sub_id * num_envs),
+        options.base_port + (sub_id * options.num_envs),
-    env = SubprocessEnvManager(env_factory, num_envs)
-    maybe_meta_curriculum = try_create_meta_curriculum(curriculum_folder, env, lesson)
+    env = SubprocessEnvManager(env_factory, options.num_envs)
+    maybe_meta_curriculum = try_create_meta_curriculum(
+        curriculum_folder, env, options.lesson
+    )
-        sampler_file_path, env.reset_parameters, run_seed
+        options.sampler_file_path, env.reset_parameters, run_seed
     )
 
     trainers = initialize_trainers(
-        run_id,
+        options.run_id,
-        keep_checkpoints,
-        train_model,
-        load_model,
+        options.keep_checkpoints,
+        options.train_model,
+        options.load_model,
-        multi_gpu,
+        options.multi_gpu,
     )
 
     # Create controller and begin training.
         summaries_dir,
-        run_id + "-" + str(sub_id),
-        save_freq,
+        options.run_id + "-" + str(sub_id),
+        options.save_freq,
-        train_model,
+        options.train_model,
-        fast_simulation,
+        options.fast_simulation,
         sampler_manager,
         resampling_interval,
     )
 
 def create_environment_factory(
     env_path: str,
-    docker_target_name: str,
+    docker_target_name: Optional[str],
     no_graphics: bool,
     seed: Optional[int],
     start_port: int,
     except Exception:
         print("\n\n\tUnity Technologies\n")
 
-    _USAGE = """
-    Usage:
-      mlagents-learn <trainer-config-path> [options]
-      mlagents-learn --help
-
-    Options:
-      --env=<file>                Name of the Unity executable [default: None].
-      --curriculum=<directory>    Curriculum json directory for environment [default: None].
-      --sampler=<file>            Reset parameter yaml file for environment [default: None].
-      --keep-checkpoints=<n>      How many model checkpoints to keep [default: 5].
-      --lesson=<n>                Start learning from this lesson [default: 0].
-      --load                      Whether to load the model or randomly initialize [default: False].
-      --run-id=<path>             The directory name for model and summary statistics [default: ppo].
-      --num-runs=<n>              Number of concurrent training sessions [default: 1].
-      --save-freq=<n>             Frequency at which to save model [default: 50000].
-      --seed=<n>                  Random seed used for training [default: -1].
-      --slow                      Whether to run the game at training speed [default: False].
-      --train                     Whether to train model, or only run inference [default: False].
-      --base-port=<n>             Base port for environment communication [default: 5005].
-      --num-envs=<n>              Number of parallel environments to use for training [default: 1]
-      --docker-target-name=<dt>   Docker volume to store training-specific files [default: None].
-      --no-graphics               Whether to run the environment in no-graphics mode [default: False].
-      --debug                     Whether to run ML-Agents in debug mode with detailed logging [default: False].
-      --multi-gpu                 Setting this flag enables the use of multiple GPU's (if available) during training
-                                  [default: False].
-    """
-
-    options = docopt(_USAGE)
+    options = parse_command_line()
-    if options["--debug"]:
+    if options.debug:
-    num_runs = int(options["--num-runs"])
-    seed = int(options["--seed"])
-    if options["--env"] == "None" and num_runs > 1:
+    if options.env_path is None and options.num_runs > 1:
         raise TrainerError(
             "It is not possible to launch more than one concurrent training session "
             "when training from the editor."
-    run_seed = seed
+    run_seed = options.seed
-    if num_runs == 1:
-        if seed == -1:
+    if options.num_runs == 1:
+        if options.seed == -1:
-        for i in range(num_runs):
-            if seed == -1:
+        for i in range(options.num_runs):
+            if options.seed == -1:
                 run_seed = np.random.randint(0, 10000)
             process_queue = Queue()
             p = Process(target=run_training, args=(i, run_seed, options, process_queue))

ml-agents/mlagents/trainers/tests/test_learn.py

 from unittest.mock import MagicMock, patch
 from mlagents.trainers import learn
 from mlagents.trainers.trainer_controller import TrainerController
+from mlagents.trainers.learn import parse_command_line
-def basic_options():
-    return {
-        "--docker-target-name": "None",
-        "--env": "None",
-        "--run-id": "ppo",
-        "--load": False,
-        "--train": False,
-        "--save-freq": "50000",
-        "--keep-checkpoints": "5",
-        "--base-port": "5005",
-        "--num-envs": "1",
-        "--curriculum": "None",
-        "--lesson": "0",
-        "--slow": False,
-        "--no-graphics": False,
-        "<trainer-config-path>": "basic_path",
-        "--debug": False,
-        "--multi-gpu": False,
-        "--sampler": None,
-    }
+def basic_options(extra_args=None):
+    extra_args = extra_args or {}
+    args = ["basic_path"]
+    if extra_args:
+        args += [f"{k}={v}" for k, v in extra_args.items()]
+    return parse_command_line(args)
 
 
 @patch("mlagents.trainers.learn.SamplerManager")
     trainer_config_mock = MagicMock()
     load_config.return_value = trainer_config_mock
 
-    options_with_docker_target = basic_options()
-    options_with_docker_target["--docker-target-name"] = "dockertarget"
+    options_with_docker_target = basic_options({"--docker-target-name": "dockertarget"})
 
     mock_init = MagicMock(return_value=None)
     with patch.object(TrainerController, "__init__", mock_init):
             assert mock_init.call_args[0][1] == "/dockertarget/models/ppo-0"
             assert mock_init.call_args[0][2] == "/dockertarget/summaries"
+
+
+def test_commandline_args():
+
+    # No args raises
+    with pytest.raises(SystemExit):
+        parse_command_line([])
+
+    # Test with defaults
+    opt = parse_command_line(["mytrainerpath"])
+    assert opt.trainer_config_path == "mytrainerpath"
+    assert opt.env_path is None
+    assert opt.curriculum_folder is None
+    assert opt.sampler_file_path is None
+    assert opt.keep_checkpoints == 5
+    assert opt.lesson == 0
+    assert opt.load_model is False
+    assert opt.run_id == "ppo"
+    assert opt.save_freq == 50000
+    assert opt.seed == -1
+    assert opt.fast_simulation is True
+    assert opt.train_model is False
+    assert opt.base_port == 5005
+    assert opt.num_envs == 1
+    assert opt.docker_target_name is None
+    assert opt.no_graphics is False
+    assert opt.debug is False
+    assert opt.multi_gpu is False
+
+    full_args = [
+        "mytrainerpath",
+        "--env=./myenvfile",
+        "--curriculum=./mycurriculum",
+        "--sampler=./mysample",
+        "--keep-checkpoints=42",
+        "--lesson=3",
+        "--load",
+        "--run-id=myawesomerun",
+        "--num-runs=3",
+        "--save-freq=123456",
+        "--seed=7890",
+        "--slow",
+        "--train",
+        "--base-port=4004",
+        "--num-envs=2",
+        "--docker-target-name=mydockertarget",
+        "--no-graphics",
+        "--debug",
+        "--multi-gpu",
+    ]
+
+    opt = parse_command_line(full_args)
+    assert opt.trainer_config_path == "mytrainerpath"
+    assert opt.env_path == "./myenvfile"
+    assert opt.curriculum_folder == "./mycurriculum"
+    assert opt.sampler_file_path == "./mysample"
+    assert opt.keep_checkpoints == 42
+    assert opt.lesson == 3
+    assert opt.load_model is True
+    assert opt.run_id == "myawesomerun"
+    assert opt.save_freq == 123456
+    assert opt.seed == 7890
+    assert opt.fast_simulation is False
+    assert opt.train_model is True
+    assert opt.base_port == 4004
+    assert opt.num_envs == 2
+    assert opt.docker_target_name == "mydockertarget"
+    assert opt.no_graphics is True
+    assert opt.debug is True
+    assert opt.multi_gpu is True

ml-agents/setup.py

     zip_safe=False,
     install_requires=[
         # Test-only dependencies should go in test_requirements.txt, not here.
-        "docopt",
         "grpcio>=1.11.0",
         "h5py>=2.9.0",
         "jupyter",