Configuration system for CLI (#6708)

* Rework how bin/qmk handles subcommands

* qmk config wip

* Code to show all configs

* Fully working `qmk config` command

* Mark some CLI arguments so they don't pollute the config file

* Fleshed out config support, nicer subcommand support

* sync with installable cli

* pyformat

* Add a test for subcommand_modules

* Documentation for the `qmk config` command

* split config_token on space so qmk config is more predictable

* Rework how subcommands are imported

* Document `arg_only`

* Document deleting from CLI

* Document how multiple operations work

* Add cli config to the doc index

* Add tests for the cli commands

* Make running the tests more reliable

* Be more selective about building all default keymaps

* Update new-keymap to fit the new subcommand style

* Add documentation about writing CLI scripts

* Document new-keyboard

* Update docs/cli_configuration.md

Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com>

* Update docs/cli_development.md

Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com>

* Update docs/cli_development.md

Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com>

* Update docs/cli_development.md

Co-Authored-By: noroadsleft <18669334+noroadsleft@users.noreply.github.com>

* Address yan's comments.

* Apply suggestions from code review

suggestions from @noahfrederick

Co-Authored-By: Noah Frederick <code@noahfrederick.com>

* Apply suggestions from code review

Co-Authored-By: Noah Frederick <code@noahfrederick.com>

* Remove pip3 from the test runner

lib/python/qmk/cli/__init__.py

@@ -0,0 +1,13 @@
+"""QMK CLI Subcommands
+
+We list each subcommand here explicitly because all the reliable ways of searching for modules are slow and delay startup.
+"""
+from . import cformat
+from . import compile
+from . import config
+from . import doctor
+from . import hello
+from . import json
+from . import new
+from . import pyformat
+from . import pytest

lib/python/qmk/cli/cformat.py

@@ -6,9 +6,9 @@ import subprocess
 from milc import cli
 
 
-@cli.argument('files', nargs='*', help='Filename(s) to format.')
-@cli.entrypoint("Format C code according to QMK's style.")
-def main(cli):
+@cli.argument('files', nargs='*', arg_only=True, help='Filename(s) to format.')
+@cli.subcommand("Format C code according to QMK's style.")
+def cformat(cli):
     """Format C code according to QMK's style.
     """
     clang_format = ['clang-format', '-i']

lib/python/qmk/cli/compile.py

@@ -14,11 +14,11 @@ import qmk.keymap
 import qmk.path
 
 
-@cli.argument('filename', nargs='?', type=FileType('r'), help='The configurator export to compile')
+@cli.argument('filename', nargs='?', arg_only=True, type=FileType('r'), help='The configurator export to compile')
 @cli.argument('-kb', '--keyboard', help='The keyboard to build a firmware for. Ignored when a configurator export is supplied.')
 @cli.argument('-km', '--keymap', help='The keymap to build a firmware for. Ignored when a configurator export is supplied.')
-@cli.entrypoint('Compile a QMK Firmware.')
-def main(cli):
+@cli.subcommand('Compile a QMK Firmware.')
+def compile(cli):
     """Compile a QMK Firmware.
 
     If a Configurator export is supplied this command will create a new keymap, overwriting an existing keymap if one exists.
@@ -41,9 +41,9 @@ def main(cli):
         # Compile the keymap
         command = ['make', ':'.join((user_keymap['keyboard'], user_keymap['keymap']))]
 
-    elif cli.config.general.keyboard and cli.config.general.keymap:
+    elif cli.config.compile.keyboard and cli.config.compile.keymap:
         # Generate the make command for a specific keyboard/keymap.
-        command = ['make', ':'.join((cli.config.general.keyboard, cli.config.general.keymap))]
+        command = ['make', ':'.join((cli.config.compile.keyboard, cli.config.compile.keymap))]
 
     else:
         cli.log.error('You must supply a configurator export or both `--keyboard` and `--keymap`.')

lib/python/qmk/cli/config.py

@@ -0,0 +1,96 @@
+"""Read and write configuration settings
+"""
+import os
+import subprocess
+
+from milc import cli
+
+
+def print_config(section, key):
+    """Print a single config setting to stdout.
+    """
+    cli.echo('%s.%s{fg_cyan}={fg_reset}%s', section, key, cli.config[section][key])
+
+
+@cli.argument('-ro', '--read-only', action='store_true', help='Operate in read-only mode.')
+@cli.argument('configs', nargs='*', arg_only=True, help='Configuration options to read or write.')
+@cli.subcommand("Read and write configuration settings.")
+def config(cli):
+    """Read and write config settings.
+
+    This script iterates over the config_tokens supplied as argument. Each config_token has the following form:
+
+        section[.key][=value]
+
+    If only a section (EG 'compile') is supplied all keys for that section will be displayed.
+
+    If section.key is supplied the value for that single key will be displayed.
+
+    If section.key=value is supplied the value for that single key will be set.
+
+    If section.key=None is supplied the key will be deleted.
+
+    No validation is done to ensure that the supplied section.key is actually used by qmk scripts.
+    """
+    if not cli.args.configs:
+        # Walk the config tree
+        for section in cli.config:
+            for key in cli.config[section]:
+                print_config(section, key)
+
+        return True
+
+    # Process config_tokens
+    save_config = False
+
+    for argument in cli.args.configs:
+        # Split on space in case they quoted multiple config tokens
+        for config_token in argument.split(' '):
+            # Extract the section, config_key, and value to write from the supplied config_token.
+            if '=' in config_token:
+                key, value = config_token.split('=')
+            else:
+                key = config_token
+                value = None
+
+            if '.' in key:
+                section, config_key = key.split('.', 1)
+            else:
+                section = key
+                config_key = None
+
+            # Validation
+            if config_key and '.' in config_key:
+                cli.log.error('Config keys may not have more than one period! "%s" is not valid.', key)
+                return False
+
+            # Do what the user wants
+            if section and config_key and value:
+                # Write a config key
+                log_string = '%s.%s{fg_cyan}:{fg_reset} %s {fg_cyan}->{fg_reset} %s'
+                if cli.args.read_only:
+                    log_string += ' {fg_red}(change not written)'
+
+                cli.echo(log_string, section, config_key, cli.config[section][config_key], value)
+
+                if not cli.args.read_only:
+                    if value == 'None':
+                        del cli.config[section][config_key]
+                    else:
+                        cli.config[section][config_key] = value
+                    save_config = True
+
+            elif section and config_key:
+                # Display a single key
+                print_config(section, config_key)
+
+            elif section:
+                # Display an entire section
+                for key in cli.config[section]:
+                    print_config(section, key)
+
+    # Ending actions
+    if save_config:
+        cli.save_config()
+
+    return True

lib/python/qmk/cli/doctor.py

@@ -11,8 +11,8 @@ from glob import glob
 from milc import cli
 
 
-@cli.entrypoint('Basic QMK environment checks')
-def main(cli):
+@cli.subcommand('Basic QMK environment checks')
+def doctor(cli):
     """Basic QMK environment checks.
 
     This is currently very simple, it just checks that all the expected binaries are on your system.
@@ -36,6 +36,7 @@ def main(cli):
         else:
             try:
                 subprocess.run([binary, '--version'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=5, check=True)
+                cli.log.info('Found {fg_cyan}%s', binary)
             except subprocess.CalledProcessError:
                 cli.log.error("{fg_red}Can't run `%s --version`", binary)
                 ok = False

lib/python/qmk/cli/hello.py

@@ -6,8 +6,8 @@ from milc import cli
 
 
 @cli.argument('-n', '--name', default='World', help='Name to greet.')
-@cli.entrypoint('QMK Hello World.')
-def main(cli):
+@cli.subcommand('QMK Hello World.')
+def hello(cli):
     """Log a friendly greeting.
     """
-    cli.log.info('Hello, %s!', cli.config.general.name)
+    cli.log.info('Hello, %s!', cli.config.hello.name)

lib/python/qmk/cli/json/__init__.py

@@ -0,0 +1,5 @@
+"""QMK CLI JSON Subcommands
+
+We list each subcommand here explicitly because all the reliable ways of searching for modules are slow and delay startup.
+"""
+from . import keymap

lib/python/qmk/cli/json/keymap.py

@@ -9,10 +9,10 @@ from milc import cli
 import qmk.keymap
 
 
-@cli.argument('-o', '--output', help='File to write to')
-@cli.argument('filename', help='Configurator JSON file')
-@cli.entrypoint('Create a keymap.c from a QMK Configurator export.')
-def main(cli):
+@cli.argument('-o', '--output', arg_only=True, help='File to write to')
+@cli.argument('filename', arg_only=True, help='Configurator JSON file')
+@cli.subcommand('Create a keymap.c from a QMK Configurator export.')
+def json_keymap(cli):
     """Generate a keymap.c from a configurator export.
 
     This command uses the `qmk.keymap` module to generate a keymap.c from a configurator export. The generated keymap is written to stdout, or to a file if -o is provided.
@@ -28,8 +28,8 @@ def main(cli):
         exit(1)
 
     # Environment processing
-    if cli.config.general.output == ('-'):
-        cli.config.general.output = None
+    if cli.args.output == ('-'):
+        cli.args.output = None
 
     # Parse the configurator json
     with open(qmk.path.normpath(cli.args.filename), 'r') as fd:
@@ -38,17 +38,17 @@ def main(cli):
     # Generate the keymap
     keymap_c = qmk.keymap.generate(user_keymap['keyboard'], user_keymap['layout'], user_keymap['layers'])
 
-    if cli.config.general.output:
-        output_dir = os.path.dirname(cli.config.general.output)
+    if cli.args.output:
+        output_dir = os.path.dirname(cli.args.output)
 
         if not os.path.exists(output_dir):
             os.makedirs(output_dir)
 
-        output_file = qmk.path.normpath(cli.config.general.output)
+        output_file = qmk.path.normpath(cli.args.output)
         with open(output_file, 'w') as keymap_fd:
             keymap_fd.write(keymap_c)
 
-        cli.log.info('Wrote keymap to %s.', cli.config.general.output)
+        cli.log.info('Wrote keymap to %s.', cli.args.output)
 
     else:
         print(keymap_c)

lib/python/qmk/cli/new/__init__.py

@@ -0,0 +1 @@
+from . import keymap

lib/python/qmk/cli/new/keymap.py

@@ -6,15 +6,15 @@ import shutil
 from milc import cli
 
 
-@cli.argument('-k', '--keyboard', help='Specify keyboard name. Example: 1upkeyboards/1up60hse')
-@cli.argument('-u', '--username', help='Specify any name for the new keymap directory')
-@cli.entrypoint('Creates a new keymap for the keyboard of your choosing')
-def main(cli):
+@cli.argument('-kb', '--keyboard', help='Specify keyboard name. Example: 1upkeyboards/1up60hse')
+@cli.argument('-km', '--keymap', help='Specify the name for the new keymap directory')
+@cli.subcommand('Creates a new keymap for the keyboard of your choosing')
+def new_keymap(cli):
     """Creates a new keymap for the keyboard of your choosing.
     """
     # ask for user input if keyboard or username was not provided in the command line
-    keyboard = cli.config.general.keyboard if cli.config.general.keyboard else input("Keyboard Name: ")
-    username = cli.config.general.username if cli.config.general.username else input("Username: ")
+    keyboard = cli.config.new_keymap.keyboard if cli.config.new_keymap.keyboard else input("Keyboard Name: ")
+    keymap = cli.config.new_keymap.keymap if cli.config.new_keymap.keymap else input("Keymap Name: ")
 
     # generate keymap paths
     kb_path = os.path.join(os.getcwd(), "keyboards", keyboard)
@@ -36,6 +36,5 @@ def main(cli):
     shutil.copytree(keymap_path_default, keymap_path, symlinks=True)
 
     # end message to user
-    cli.log.info("%s keymap directory created in: %s\n" +
-                 "Compile a firmware file with your new keymap by typing: \n" +
-                 "qmk compile -kb %s -km %s", username, keymap_path, keyboard, username)
+    cli.log.info("%s keymap directory created in: %s", username, keymap_path)
+    cli.log.info("Compile a firmware with your new keymap by typing: \n" + "qmk compile -kb %s -km %s", keyboard, username)

lib/python/qmk/cli/pyformat.py

@@ -5,12 +5,13 @@ from milc import cli
 import subprocess
 
 
-@cli.entrypoint("Format python code according to QMK's style.")
-def main(cli):
+@cli.subcommand("Format python code according to QMK's style.")
+def pyformat(cli):
     """Format python code according to QMK's style.
     """
     try:
         subprocess.run(['yapf', '-vv', '-ri', 'bin/qmk', 'lib/python'], check=True)
         cli.log.info('Successfully formatted the python code in `bin/qmk` and `lib/python`.')
+
     except subprocess.CalledProcessError:
         cli.log.error('Error formatting python code!')

lib/python/qmk/cli/pytest.py

@@ -2,17 +2,19 @@
 
 QMK script to run unit and integration tests against our python code.
 """
+import sys
 from milc import cli
 
 
-@cli.entrypoint('QMK Python Unit Tests')
-def main(cli):
+@cli.subcommand('QMK Python Unit Tests')
+def pytest(cli):
     """Use nose2 to run unittests
     """
     try:
         import nose2
+
     except ImportError:
         cli.log.error('Could not import nose2! Please install it with {fg_cyan}pip3 install nose2')
         return False
 
-    nose2.discover()
+    nose2.discover(argv=['nose2', '-v'])