[bin] Positional config param is now --config or -c

Explicit is better than implicit
openwisp · Dec 11, 2015 · 5ff7360c284d442d95f9a28f4f8c4d70f01e17c3 · 5ff7360
1 parent 6f8380d
commit 5ff7360c284d442d95f9a28f4f8c4d70f01e17c3
Unified Split

Showing with 58 additions and 47 deletions.

+30 −24 bin/netjsonconfig

+22 −17 docs/source/general/commandline_utility.rst

+6 −6 tests/test_bin.py
diff --git a/bin/netjsonconfig b/bin/netjsonconfig
@@ -20,44 +20,50 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 """

-parser = argparse.ArgumentParser(description='Converts a NetJSON DeviceConfiguration object'
-                                             'to working router configurations.',
+parser = argparse.ArgumentParser(description='Converts a NetJSON DeviceConfiguration object '
+                                             'to native router configurations.',
                                 epilog=license,
                                 prog='netjsonconfig')

-parser.add_argument('config',
+config = parser.add_argument_group('input')
+
+config.add_argument('--config', '-c',
                    action='store',
                    type=str,
                    help='config file or string, must be valid NetJSON DeviceConfiguration')

-parser.add_argument('--templates', '-t',
+config.add_argument('--templates', '-t',
                    nargs='*',  # zero or more
                    action='store',
                    type=str,
                    default=[],
                    help='list of template config files or strings separated by space')

-parser.add_argument('--backend', '-b',
-                    choices=['openwrt', 'openwisp'],
-                    action='store',
-                    type=str,
-                    help='Configuration backend: openwrt or openwisp')
+output = parser.add_argument_group('output')

-parser.add_argument('--method', '-m',
-                    choices=['generate', 'render'],
-                    action='store',
-                    help='Backend method to use. '\
-                         '"generate" returns a tar.gz archive as output; '
-                         '"render" returns the configuration in text format')
-
-parser.add_argument('--verbose',
-                    action='store_true',
-                    default=False,
-                    help='verbose output')
-
-parser.add_argument('--version', '-v',
-                    action='version',
-                    version=netjsonconfig.get_version())
+output.add_argument('--backend', '-b',
+                 choices=['openwrt', 'openwisp'],
+                 action='store',
+                 type=str,
+                 help='Configuration backend: openwrt or openwisp')
+
+output.add_argument('--method', '-m',
+                 choices=['render', 'generate'],
+                 action='store',
+                 help='Backend method to use. '\
+                      '"render" returns the configuration in text format'\
+                      '"generate" returns a tar.gz archive as output; ')
+
+debug = parser.add_argument_group('debug')
+
+debug.add_argument('--verbose',
+                   action='store_true',
+                   default=False,
+                   help='verbose output')
+
+debug.add_argument('--version', '-v',
+                   action='version',
+                   version=netjsonconfig.get_version())

 def _load(config):
    """
diff --git a/docs/source/general/commandline_utility.rst b/docs/source/general/commandline_utility.rst
@@ -9,45 +9,50 @@ languages (via system calls).
 Check out the available options yourself with::

    $ netjsonconfig --help
-    usage: netjsonconfig [-h] [--templates [TEMPLATES [TEMPLATES ...]]]
+    usage: netjsonconfig [-h] [--config CONFIG]
+                         [--templates [TEMPLATES [TEMPLATES ...]]]
                         [--backend {openwrt,openwisp}]
-                         [--method {generate,render}] [--verbose] [--version]
-                         config
+                         [--method {render,generate}] [--verbose] [--version]

-    Converts a NetJSON DeviceConfiguration objectto working router configurations.
-
-    positional arguments:
-      config                config file or string, must be valid NetJSON
-                            DeviceConfiguration
+    Converts a NetJSON DeviceConfiguration object to native router configurations.

    optional arguments:
      -h, --help            show this help message and exit
+
+    input:
+      --config CONFIG, -c CONFIG
+                            config file or string, must be valid NetJSON
+                            DeviceConfiguration
      --templates [TEMPLATES [TEMPLATES ...]], -t [TEMPLATES [TEMPLATES ...]]
                            list of template config files or strings separated by
                            space
+
+    output:
      --backend {openwrt,openwisp}, -b {openwrt,openwisp}
                            Configuration backend: openwrt or openwisp
-      --method {generate,render}, -m {generate,render}
-                            Backend method to use. "generate" returns a tar.gz
-                            archive as output; "render" returns the configuration
-                            in text format
+      --method {render,generate}, -m {render,generate}
+                            Backend method to use. "render" returns the
+                            configuration in text format"generate" returns a
+                            tar.gz archive as output;
+
+    debug:
      --verbose             verbose output
      --version, -v         show program's version number and exit

 Here's the common use cases explained::

   # generate tar.gz from a NetJSON DeviceConfiguration object and save it to a file
-   netjsonconfig --backend openwrt --method generate config.json > config.tar.gz
+   netjsonconfig --config config.json --backend openwrt --method generate > config.tar.gz

   # see output of OpenWrt render method
-   netjsonconfig --backend openwrt --method render config.json
+   netjsonconfig --config config.json --backend openwrt --method render

   # abbreviated options
-   netjsonconfig -b openwrt -m render config.json
+   netjsonconfig -c config.json -b openwrt -m render

   # passing a JSON string instead of a file path
-   netjsonconfig -b openwrt -m render '{"general": { "hostname": "example" }}'
+   netjsonconfig -c '{"general": { "hostname": "example" }}' -b openwrt -m render

 Using templates::

-    netjsonconfig config.json -t template1.json template2.json -b openwrt -m render
+    netjsonconfig -c config.json -t template1.json template2.json -b openwrt -m render
diff --git a/tests/test_bin.py b/tests/test_bin.py
@@ -11,20 +11,20 @@ class TestBin(unittest.TestCase, _TabsMixin):
    """
    def test_file_not_found(self):
        with self.assertRaises(subprocess.CalledProcessError):
-            output = subprocess.check_output("netjsonconfig WRONG -b openwrt -m generate", shell=True)
+            output = subprocess.check_output("netjsonconfig -c WRONG -b openwrt -m generate", shell=True)

    def test_invalid_netjson(self):
-        command = '''netjsonconfig '{ "interfaces":["w"] }' -b openwrt -m render'''
+        command = '''netjsonconfig -c '{ "interfaces":["w"] }' -b openwrt -m render'''
        with self.assertRaises(subprocess.CalledProcessError):
            output = subprocess.check_output(command, shell=True)

    def test_invalid_netjson_verbose(self):
-        command = '''netjsonconfig '{ "interfaces":["w"] }' -b openwrt -m render --verbose'''
+        command = '''netjsonconfig -c '{ "interfaces":["w"] }' -b openwrt -m render --verbose'''
        with self.assertRaises(subprocess.CalledProcessError):
            output = subprocess.check_output(command, shell=True)

    def test_empty_netjson(self):
-        output = subprocess.check_output("netjsonconfig '{}' -b openwrt -m render", shell=True)
+        output = subprocess.check_output("netjsonconfig -c '{}' -b openwrt -m render", shell=True)
        self.assertEqual(output.decode(), '')

    def test_templates(self):
@@ -59,15 +59,15 @@ def test_templates(self):
                }
            ]
        })
-        command = """netjsonconfig '{0}' -b openwrt -m render --templates '{1}' '{2}'"""
+        command = """netjsonconfig --config '{0}' -b openwrt -m render --templates '{1}' '{2}'"""
        command = command.format(config, template1, template2)
        output = subprocess.check_output(command, shell=True).decode()
        self.assertIn("hostname 'template_test'", output)
        self.assertIn("interface 'eth0'", output)
        self.assertIn("interface 'wlan0'", output)

    def test_invalid_template(self):
-        command = "netjsonconfig '{}' -b openwrt -t WRONG -m render"
+        command = "netjsonconfig -c '{}' -b openwrt -t WRONG -m render"
        try:
            output = subprocess.check_output(command, shell=True)
        except subprocess.CalledProcessError as e: