diff --git a/README.md b/README.md index 80471d4..b962c7e 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,12 @@ Passing `--exit-after-create` as the second argument renders a newly created env python main.py 100 --exit-after-create ``` +Passing `--help` or `-h` in any position prints a usage line and exits with status `0`, before a window is opened, Viron is contacted, a file is written or usage reporting starts: + +```bash +python main.py --help +``` + Created environments are recorded in `environments.json`, keyed by grid count and grid size (for example `1x50`; the grid count is currently fixed at `1`). Each entry records the environment's `environment_id`, `grid_size`, `num_grids` and `creation_time_seconds`. A key that is already present in that file is re-loaded from Viron rather than re-created, so the file should be deleted to force re-creation. If a recorded environment cannot be loaded — because the Viron server is unreachable, or because it no longer knows the recorded ID — the error is printed, `Error loading environment, please check logs.` is shown in the window for about two seconds, and the program exits with status `0` without re-creating the environment. Deleting `environments.json` (or just the affected entry) lets the next run create it afresh. diff --git a/main.py b/main.py index 414d928..de7035e 100644 --- a/main.py +++ b/main.py @@ -25,9 +25,23 @@ url = "http://localhost" port = 9999 +usage = "Usage: python main.py [gridSize] [--exit-after-create]" + def log(message): print(message) +def wantsUsage(argv): + """ + Check whether the command line asks for the usage line rather than for a run. + + Args: + argv (list): The argument vector, including the program name at index 0 + + Returns: + bool: True if --help or -h is given in any position + """ + return "--help" in argv[1:] or "-h" in argv[1:] + def parseArgs(argv): """ Parse the command line arguments. @@ -169,5 +183,9 @@ def main(gridSize=defaultGridSize, exitAfterCreate=False, locationService=None, window.close() if __name__ == "__main__": + # checked first, so that asking for help never opens a window or reaches Viron + if wantsUsage(sys.argv): + log(usage) + sys.exit(0) gridSize, exitAfterCreate = parseArgs(sys.argv) main(gridSize, exitAfterCreate, reportUsage=True) diff --git a/tests/test_main.py b/tests/test_main.py index ba2da7c..0007931 100644 --- a/tests/test_main.py +++ b/tests/test_main.py @@ -1,3 +1,4 @@ +import io import json import os import runpy @@ -67,6 +68,24 @@ def test_ignores_an_unrecognized_second_argument(self): self.assertEqual(main.parseArgs(["main.py", "100", "--render-forever"]), (100, False)) +class TestWantsUsage(unittest.TestCase): + def test_recognizes_both_spellings_of_the_flag(self): + for flag in ("--help", "-h"): + with self.subTest(flag=flag): + self.assertTrue(main.wantsUsage(["main.py", flag])) + + def test_recognizes_the_flag_after_other_arguments(self): + self.assertTrue(main.wantsUsage(["main.py", "100", "--help"])) + + def test_an_ordinary_run_does_not_ask_for_usage(self): + for argv in (["main.py"], ["main.py", "100", "--exit-after-create"], ["main.py", "wide"]): + with self.subTest(argv=argv): + self.assertFalse(main.wantsUsage(argv)) + + def test_the_program_name_is_not_read_as_a_flag(self): + self.assertFalse(main.wantsUsage(["--help"])) + + class TestGetEnvironmentKey(unittest.TestCase): def test_key_combines_the_grid_count_and_the_grid_size(self): self.assertEqual(main.getEnvironmentKey(50), "1x50") @@ -424,6 +443,28 @@ def get_locations_in_environment(self, environmentId): usageReportingModule.startUsageReporting.assert_called_once_with(log=moduleGlobals["log"]) + def test_asking_for_usage_prints_it_and_exits_without_side_effects(self): + workingDirectory = tempfile.TemporaryDirectory() + self.addCleanup(workingDirectory.cleanup) + self.addCleanup(os.chdir, os.getcwd()) + os.chdir(workingDirectory.name) + + for argv in (["main.py", "--help"], ["main.py", "-h"], ["main.py", "100", "--help"]): + with self.subTest(argv=argv): + output = io.StringIO() + with patch.object(sys, "argv", argv), \ + patch("usage_reporting.startUsageReporting") as mockStartUsageReporting, \ + patch("render_window.RenderWindow") as mockRenderWindow, \ + patch("sys.stdout", output): + with self.assertRaises(SystemExit) as caught: + runpy.run_module("main", run_name="__main__") + + self.assertEqual(caught.exception.code, 0) + self.assertIn("Usage: python main.py [gridSize] [--exit-after-create]", output.getvalue()) + mockStartUsageReporting.assert_not_called() + mockRenderWindow.assert_not_called() + self.assertEqual(os.listdir("."), []) + class TestRenderLoop(MainTestCase): def test_every_frame_is_capped_at_the_target_frame_rate(self):