commands.rst (2630B)
1 commands.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 6 directory and sets up subcommands from these JSON files. A typical commands.json 7 would 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 26 Each 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 28 object must contain :code:`path` and :code:`script` fields and may contain 29 additional 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:`requirements` 52 A list of paths where each path specifies a requirements.txt. All requirements 53 listed in these files are installed into the virtualenv environment before 54 running the subcommand. :code:`virtualenv` must be true when this field is 55 set. 56 57 :code:`conditional_requirements` 58 A key-value object. Each key represents a condition, and value represents 59 additional requirements when the condition is met. The requirements have the 60 same format as :code:`requirements`. Currently "commandline_flag" is the only 61 supported key. "commandline_flag" is used to specify requirements needed for a 62 certain command line flag of the subcommand. For example, given the following 63 commands.json:: 64 65 "baz": { 66 "path": "baz.py", 67 "script": "run", 68 "virtualenv": true, 69 "conditional_requirements": { 70 "commandline_flag": { 71 "enable_feature1": [ 72 "requirements_feature1.txt" 73 ] 74 } 75 } 76 } 77 78 Requirements in :code:`requirements_features1.txt` are installed only when 79 :code:`--enable-feature1` is specified to :code:`./wpt baz`.