1commands.json 2============= 3 4:code:`commands.json` files define how subcommands are executed by the 5:code:`./wpt` command. :code:`wpt` searches all command.json files under the top 6directory and sets up subcommands from these JSON files. A typical commands.json 7would look like the following:: 8 9 { 10 "foo": { 11 "path": "foo.py", 12 "script": "run", 13 "parser": "get_parser", 14 "help": "Run foo" 15 }, 16 "bar": { 17 "path": "bar.py", 18 "script": "run", 19 "virtualenv": true, 20 "requirements": [ 21 "requirements.txt" 22 ] 23 } 24 } 25 26Each key of the top level object defines a name of a subcommand, and its value 27(a properties object) specifies how the subcommand is executed. Each properties 28object must contain :code:`path` and :code:`script` fields and may contain 29additional fields. All paths are relative to the commands.json. 30 31:code:`path` 32 The path to a Python script that implements the subcommand. 33 34:code:`script` 35 The name of a function that is used as the entry point of the subcommand. 36 37:code:`parser` 38 The name of a function that creates an argparse parser for the subcommand. 39 40:code:`parse_known` 41 When True, `parse_known_args() <https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_known_args>`_ 42 is used instead of parse_args() for the subcommand. Default to False. 43 44:code:`help` 45 Brief description of the subcommand. 46 47:code:`virtualenv` 48 When True, the subcommand is executed with a virtualenv environment. Default 49 to True. 50 51:code:`install` 52 A list of strings where each string represents a 53 `requirement object <https://setuptools.readthedocs.io/en/latest/pkg_resources.html#requirement-objects>`_. 54 These requirements are installed into the virtualenv environment before 55 running the subcommand. :code:`virtualenv` must be true when this field is 56 set. 57 58:code:`requirements` 59 A list of paths where each path specifies a requirements.txt. All requirements 60 listed in these files are installed into the virtualenv environment before 61 running the subcommand. :code:`virtualenv` must be true when this field is 62 set. 63 64:code:`conditional_requirements` 65 A key-value object. Each key represents a condition, and value represents 66 additional requirements when the condition is met. The requirements have the 67 same format as :code:`requirements`. Currently "commandline_flag" is the only 68 supported key. "commandline_flag" is used to specify requirements needed for a 69 certain command line flag of the subcommand. For example, given the following 70 commands.json:: 71 72 "baz": { 73 "path": "baz.py", 74 "script": "run", 75 "virtualenv": true, 76 "conditional_requirements": { 77 "commandline_flag": { 78 "enable_feature1": [ 79 "requirements_feature1.txt" 80 ] 81 } 82 } 83 } 84 85 Requirements in :code:`requirements_features1.txt` are installed only when 86 :code:`--enable-feature1` is specified to :code:`./wpt baz`. 87