New release: 0.0.40 → 0.0.41

* refactor to make the code clearer in some places
* don't call bin/qmk anymore
* ask the user if they want to install python modules when they're missing

.github/workflows/cli_setup.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       matrix:
         os: [macos-latest, ubuntu-latest]
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@v1
@@ -27,7 +27,7 @@ jobs:
     - name: Install Python dependencies
       run: |
         python3 -m pip install wheel
-        echo "::add-path::$HOME/.local/bin"
+        echo "$HOME/.local/bin" >> $GITHUB_PATH
 
     - name: Install QMK CLI from source
       run: |
@@ -53,10 +53,9 @@ jobs:
         update: true
         install: git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python-pip
 
-    - name: (MSYS2) Upgrade pip and setuptools and install wheel
+    - name: (MSYS2) Install Python dependencies
       shell: msys2 {0}
       run: |
-        python3 -m pip install --upgrade pip setuptools
         python3 -m pip install wheel
 
     - name: (MSYS2) Install QMK CLI from source

CODE_OF_CONDUCT.md

@@ -1,15 +0,0 @@
-# Code Of Conduct
-
-QMK strives to be an inclusive, tolerant, and welcoming community. We encourage participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation.
-
-> “A gentle word turns away wrath, but a harsh word stirs up anger."
-
-Our users, contributors, and collaborators are expected to treat each other with kindness and respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. While our goal is to be as accurate as possible, kindness and understanding are more valuable than correctness. Some examples of behavior we will not tolerate include, but is not limited to:
-
-* The use of sexualized language or imagery
-* Unwelcome advances, sexual or otherwise
-* Insults or derogatory comments, or personal or political attacks
-* Publishing others’ private information without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
-
-If someone is violating this Code of Conduct you may email hello@qmk.fm to bring your concern to the Members. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. 

README.md

@@ -14,4 +14,9 @@ A program to help users work with [QMK Firmware](https://qmk.fm/).
 
 # Quickstart
 
-To be written.
+Full documentation: <https://docs.qmk.fm/#/tutorial>
+
+Basic steps:
+
+* `python3 -m pip install qmk`
+* `qmk setup`

qmk_cli/__init__.py

@@ -1,3 +1,3 @@
 """A program to help you work with qmk_firmware."""
 
-__version__ = '0.0.36'
+__version__ = '0.0.41'

qmk_cli/git.py

@@ -16,17 +16,25 @@ def git_clone(url, destination, branch):
         '--recurse-submodules',
         '--branch=' + branch,
         url,
-        destination,
+        str(destination),
     ]
     cli.log.debug('Git clone command: %s', git_clone)
 
-    with subprocess.Popen(git_clone, stderr=subprocess.STDOUT, stdout=subprocess.PIPE, bufsize=1, universal_newlines=True, encoding='utf-8') as p:
-        for line in p.stdout:
-            print(line, end='')
+    try:
+        with subprocess.Popen(git_clone, stderr=subprocess.STDOUT, stdout=subprocess.PIPE, bufsize=1, universal_newlines=True, encoding='utf-8') as p:
+            for line in p.stdout:
+                print(line, end='')
+
+    except Exception as e:
+        git_cmd = ' '.join([s.replace(' ', r'\ ') for s in git_clone])
+
+        cli.log.error("Could not run '%s': %s: %s", git_cmd, e.__class__.__name__, e)
+        return False
 
     if p.returncode == 0:
         cli.log.info('Successfully cloned %s to %s!', url, destination)
         return True
+
     else:
         cli.log.error('git clone exited %d', p.returncode)
         return False

qmk_cli/helpers.py

@@ -1,36 +1,98 @@
 """Useful helper functions.
 """
-from milc import cli, format_ansi
+import os
+from functools import lru_cache
+from importlib.util import find_spec
+from pathlib import Path
+
+from milc import cli
 
 
-def question(question, boolean=True, default=''):
-    """Asks the user to answer a question.
-
-    This keeps re-asking until it gets acceptible input.
+def broken_module_imports():
+    """Make sure we can import all the python modules.
     """
-    if cli.args.yes:
-        return True
+    broken_modules = find_broken_requirements('requirements.txt')
+    broken_dev_modules = find_broken_requirements('requirements-dev.txt') if cli.config.user.developer else []
+    to_return = [False, False]
 
-    if default and default.lower() == 'y':
-        answer_key = 'Y/n'
-    elif default and default.lower() == 'n':
-        answer_key = 'y/N'
-    else:
-        answer_key = 'y/n'
+    if broken_modules:
+        to_return[0] = True
 
-    prompt = format_ansi('\n*** %s [%s] ' % (question, answer_key))
+    if broken_dev_modules:
+        to_return[1] = True
 
-    while True:
-        answer = input(prompt)
-        print()
-        if answer == '' and default.lower() == 'y':
-            answer = 'y'
-        elif answer == '' and default.lower() == 'n':
-            answer = 'n'
+    for module in broken_modules + broken_dev_modules:
+        print('Could not find module %s!' % module)
 
-        if answer.lower() in ['y', 'yes']:
-            return True
-        elif answer.lower() in ['n', 'no']:
-            return False
-        else:
-            cli.echo('Invalid answer!')
+    return to_return
+
+
+def find_broken_requirements(requirements):
+    """ Check if the modules in the given requirements.txt are available.
+
+    Args:
+
+        requirements
+            The path to a requirements.txt file
+
+    Returns a list of modules that couldn't be imported
+    """
+    with Path(requirements).open() as fd:
+        broken_modules = []
+
+        for line in fd.readlines():
+            line = line.strip().replace('<', '=').replace('>', '=')
+
+            if len(line) == 0 or line[0] == '#' or line.startswith('-r'):
+                continue
+
+            if '#' in line:
+                line = line.split('#')[0]
+
+            module_name = line.split('=')[0] if '=' in line else line
+            module_import_name = module_name.replace('-', '_')
+
+            # Not every module is importable by its own name.
+            if module_name == "pep8-naming":
+                module_import_name = "pep8ext_naming"
+
+            if not find_spec(module_import_name):
+                broken_modules.append(module_name)
+
+        return broken_modules
+
+
+@lru_cache(maxsize=2)
+def find_qmk_firmware():
+    """Look for qmk_firmware in the usual places.
+
+    This function returns the path to qmk_firmware, or the default location if one does not exist.
+    """
+    if in_qmk_firmware():
+        return in_qmk_firmware()
+
+    if cli.config.user.qmk_home:
+        return Path(cli.config.user.qmk_home).expanduser().resolve()
+
+    if 'QMK_HOME' in os.environ:
+        path = Path(os.environ['QMK_HOME']).expanduser()
+        if path.exists():
+            return path.resolve()
+        return path
+
+    return Path.home() / 'qmk_firmware'
+
+
+def in_qmk_firmware():
+    """Returns the path to the qmk_firmware we are currently in, or None if we are not inside qmk_firmware.
+    """
+    cur_dir = Path.cwd()
+    while len(cur_dir.parents) > 0:
+        found_lib = cur_dir / 'lib/python/qmk/cli/__init__.py'
+        found_quantum = cur_dir / 'quantum'
+        if found_lib.is_file() and found_quantum.is_dir():
+            return cur_dir
+
+        # Move up a directory before the next iteration
+        cur_dir = cur_dir / '..'
+        cur_dir = cur_dir.resolve()

qmk_cli/script_qmk.py

@@ -3,15 +3,18 @@
 
 This program can be run from anywhere, with or without a qmk_firmware repository. If a qmk_firmware repository can be located we will use that to augment our available subcommands.
 """
-import argparse
-import platform
 import os
+import shlex
 import subprocess
 import sys
-from functools import lru_cache
-from pathlib import Path
+from platform import platform
+from traceback import print_exc
 
 import milc
+import milc.subcommand.config  # noqa
+from milc.questions import yesno
+
+from .helpers import broken_module_imports, find_qmk_firmware
 
 milc.EMOJI_LOGLEVELS['INFO'] = '{fg_blue}Ψ{style_reset_all}'
 
@@ -23,59 +26,27 @@ def qmk_main(cli):
     cli.print_help()
 
 
-@lru_cache(maxsize=2)
-def in_qmk_firmware():
-    """Returns the path to the qmk_firmware we are currently in, or None if we are not inside qmk_firmware.
+def run_cmd(*command):
+    """Run a command in a subshell.
     """
-    cur_dir = Path.cwd()
-    while len(cur_dir.parents) > 0:
-        found_bin = cur_dir / 'bin' / 'qmk'
-        # An additional check for something that exists in the root of qmk_firmware,
-        # but not in the script's install directory, to avoid recursive execution,
-        # if started from install directory.
-        # e.g.: cd ~/.local/bin && ./qmk
-        found_quantum = cur_dir / 'quantum'
-        if found_bin.is_file() and found_quantum.is_dir():
-            command = [sys.executable, found_bin.as_posix()]
-            result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if 'windows' in milc.cli.platform.lower():
+        safecmd = map(shlex.quote, command)
+        safecmd = ' '.join(safecmd)
+        command = [os.environ['SHELL'], '-c', safecmd]
 
-            if result.returncode == 0:
-                return cur_dir
-
-        # Move up a directory before the next iteration
-        cur_dir = cur_dir / '..'
-        cur_dir = cur_dir.resolve()
-
-
-def find_qmk_firmware():
-    """Look for qmk_firmware in the usual places.
-
-    This function returns the path to qmk_firmware, or the default location if one does not exist.
-    """
-    if in_qmk_firmware():
-        return in_qmk_firmware()
-
-    if milc.cli.config.user.qmk_home:
-        return Path(milc.cli.config.user.qmk_home).expanduser().resolve()
-
-    if 'QMK_HOME' in os.environ:
-        path = Path(os.environ['QMK_HOME']).expanduser()
-        if path.exists():
-            return path.resolve()
-        return path
-
-    return Path.home() / 'qmk_firmware'
+    return subprocess.run(command)
 
 
+# Python setuptools entrypoint
 def main():
     """Setup the environment before dispatching to the entrypoint.
     """
     # Warn if they use an outdated python version
-    if sys.version_info < (3, 6):
+    if sys.version_info < (3, 7):
         print('Warning: Your Python version is out of date! Some subcommands may not work!')
-        print('Please upgrade to Python 3.6 or later.')
+        print('Please upgrade to Python 3.7 or later.')
 
-    if 'windows' in platform.platform().lower():
+    if 'windows' in platform().lower():
         msystem = os.environ.get('MSYSTEM', '')
 
         if 'mingw64' not in sys.executable or 'MINGW64' not in msystem:
@@ -91,20 +62,48 @@ def main():
     os.environ['QMK_HOME'] = str(qmk_firmware)
     os.environ['ORIG_CWD'] = os.getcwd()
 
-    # Import the subcommand modules
     import qmk_cli.subcommands
 
+    # Check out and initialize the qmk_firmware environment
     if qmk_firmware.exists():
+        # All subcommands are run relative to the qmk_firmware root to make it easier to use the right copy of qmk_firmware.
         os.chdir(str(qmk_firmware))
-        sys.path.append(str(qmk_firmware / 'lib' / 'python'))
-        try:
-            import qmk.cli
-        except ImportError:
-            if qmk_firmware.name != 'qmk_firmware':
-                print('Warning: %s does not end in "qmk_firmware". Do you need to set QMK_HOME to "%s/qmk_firmware"?' % (qmk_firmware,qmk_firmware))
 
-            print('Error: %s is too old or not set up correctly!' % qmk_firmware)
-            print('Please update it or remove it completely before continuing.')
+        # Check to make sure we have all the requirements
+        broken_modules, broken_dev_modules = broken_module_imports()
+        msg_install = 'Please run `python3 -m pip install -r %s` to install required python dependencies.'
+
+        if broken_modules:
+            if yesno('Would you like to install the required Python modules?'):
+                run_cmd(sys.executable, '-m', 'pip', 'install', '-r', 'requirements.txt')
+            else:
+                print()
+                print(msg_install % (os.environ['QMK_HOME'] + '/requirements.txt',))
+                print()
+                exit(1)
+
+        if broken_dev_modules:
+            if yesno('Would you like to install the required developer Python modules?'):
+                run_cmd(sys.executable, '-m', 'pip', 'install', '-r', 'requirements.txt')
+            else:
+                print()
+                print(msg_install % (os.environ['QMK_HOME'] + '/requirements-dev.txt',))
+                print('You can also turn off developer mode: qmk config user.developer=None')
+                print()
+                exit(1)
+
+        # Environment looks good, include the qmk_firmware subcommands
+        sys.path.append(str(qmk_firmware / 'lib/python'))
+
+        try:
+            import qmk.cli  # noqa
+
+        except ImportError as e:
+            if qmk_firmware.name != 'qmk_firmware':
+                print('Warning: %s does not end in "qmk_firmware". Do you need to set QMK_HOME to "%s/qmk_firmware"?' % (qmk_firmware, qmk_firmware))
+
+            print('Error: %s: %s', (e.__class__.__name__, e))
+            print_exc()
             sys.exit(1)
 
     # Call the entrypoint

qmk_cli/subcommands/__init__.py

@@ -2,5 +2,5 @@
 
 We list each subcommand here explicitly because all the reliable ways of searching for modules are slow and delay startup.
 """
-from . import clone
-from . import setup
+from . import clone  # noqa
+from . import setup  # noqa

qmk_cli/subcommands/setup.py

@@ -42,6 +42,24 @@ def git_upstream(destination):
         return False
 
 
+def is_qmk_firmware(qmk_firmware):
+    """Returns True if the given Path() is a qmk_firmware clone.
+    """
+    paths = [
+        qmk_firmware,
+        qmk_firmware / 'Makefile',
+        qmk_firmware / 'requirements.txt',
+        qmk_firmware / 'requirements-dev.txt',
+        qmk_firmware / 'lib/python/qmk/cli/doctor.py'
+    ]
+
+    for path in paths:
+        if not path.exists():
+            return False
+
+    return True
+
+
 @cli.argument('-n', '--no', arg_only=True, action='store_true', help='Answer no to all questions')
 @cli.argument('-y', '--yes', arg_only=True, action='store_true', help='Answer yes to all questions')
 @cli.argument('--baseurl', default=default_base, help='The URL all git operations start from. Default: %s' % default_base)
@@ -61,8 +79,18 @@ def setup(cli):
         exit(1)
 
     # Check on qmk_firmware, and if it doesn't exist offer to check it out.
-    if (cli.args.home / 'Makefile').exists():
+    if is_qmk_firmware(cli.args.home):
         cli.log.info('Found qmk_firmware at %s.', str(cli.args.home))
+
+    elif cli.args.home.exists():
+        path_str = str(cli.args.home)
+
+        if cli.args.home.name != 'qmk_firmware':
+            cli.log.warning('Warning: %s does not end in "qmk_firmware". Did you mean to use "--home %s/qmk_firmware"?' % (path_str, path_str))
+
+        cli.log.error("Path '%s' exists but is not a qmk_firmware clone!", path_str)
+        exit(1)
+
     else:
         cli.log.error('Could not find qmk_firmware!')
         if yesno(clone_prompt):
@@ -74,18 +102,17 @@ def setup(cli):
                 exit(1)
 
     # Offer to set `user.qmk_home` for them.
-    if cli.args.home != os.environ['QMK_HOME'] and yesno(home_prompt):
+    if str(cli.args.home) != os.environ['QMK_HOME'] and yesno(home_prompt):
         cli.config['user']['qmk_home'] = str(cli.args.home.absolute())
         cli.write_config_option('user', 'qmk_home')
 
-    # Run `qmk_firmware/bin/qmk doctor` to check the rest of the environment out
-    qmk_bin = cli.args.home / 'bin/qmk'
-    doctor_cmd = [sys.executable, qmk_bin.as_posix(), 'doctor']
-
-    if cli.args.yes:
-        doctor_cmd.append('--yes')
+    # Run `qmk doctor` to check the rest of the environment out
+    doctor_command = [sys.executable, sys.argv[0], 'doctor']
 
     if cli.args.no:
-        doctor_cmd.append('--no')
+        doctor_command.append('--no')
 
-    subprocess.run(doctor_cmd)
+    if cli.args.yes:
+        doctor_command.append('--yes')
+
+    cli.run(doctor_command, capture_output=False)

release

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 # Increment the verison number and release a new version of qmk_cli.
 #
 # Required packages: pip3 install bumpversion twine
@@ -12,13 +12,21 @@ TWINE_USERNAME=$PYPI_USERNAME
 
 export FLIT_USERNAME TWINE_USERNAME
 
+if ! bumpversion -h &> /dev/null; then
+	echo "Missing bumpversion! Please run: pip3 install -U -r requirements-dev.txt"
+	exit 1
+fi
+
+if ! twine -h &> /dev/null; then
+	echo "Missing twine! Please run: pip3 install -U -r requirements-dev.txt"
+	exit 1
+fi
+
+# Bump the version, tag, and push
 rm -f dist/*
 bumpversion patch
 git push origin master --tags
 
-# For now we don't use flit
-#flit publish
-
-# Use setuptools until flit works with homebrew
+# Build and upload
 python3 setup.py sdist bdist_wheel
 twine upload dist/qmk-*

requirements-dev.txt

@@ -0,0 +1,2 @@
+bumpversion
+twine

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.36
+current_version = 0.0.41
 commit = True
 tag = True
 tag_name = {new_version}
@@ -23,7 +23,7 @@ dist-name = qmk
 license_file = LICENSE
 module = qmk_cli
 home-page = https://github.com/qmk/qmk_cli
-requires-python = >=3.5
+requires-python = >=3.7
 
 [entry_points]
 qmk = qmk_cli.script_qmk:main

setup.py

@@ -7,12 +7,12 @@ metadata = setup_cfg['metadata']
 
 if __name__ == "__main__":
     with open('README.md', encoding='utf-8') as readme_file:
-        long_description=readme_file.read()
+        long_description = readme_file.read()
     setup(
         name=metadata['dist-name'],
         description='A program to help users work with QMK Firmware.',
         entry_points={
-            'console_scripts': ['%s = %s' % l for l in setup_cfg['entry_points'].items()],
+            'console_scripts': ['%s = %s' % i for i in setup_cfg['entry_points'].items()],
         },
         license='MIT License',
         url=metadata['home-page'],
@@ -24,7 +24,7 @@ if __name__ == "__main__":
         long_description=long_description,
         long_description_content_type="text/markdown",
         packages=find_packages(),
-        py_modules = ['milc'],
+        py_modules=['milc'],
         classifiers=[
             'Development Status :: 3 - Alpha',
             'Environment :: Console',
@@ -38,13 +38,15 @@ if __name__ == "__main__":
             'Topic :: Software Development',
             'Topic :: Utilities',
         ],
-        requires_python=metadata['requires-python'],
+        python_requires=metadata['requires-python'],
         install_requires=[
             "appdirs",
             "argcomplete",
             "colorama",
+            "dotty-dict",
             "flake8",
             "hjson",
+            "jsonschema>=3",
             "milc>=1.0.8",
             "nose2",
             "pygments",