summaryrefslogtreecommitdiff
path: root/lib/python
diff options
context:
space:
mode:
authorskullydazed <skullydazed@users.noreply.github.com>2019-07-15 12:14:27 -0700
committerFlorian Didron <fdidron@users.noreply.github.com>2019-07-19 10:05:36 +0900
commit7e080e7ecd6dff6f06579ce8b1623bc22326e166 (patch)
treeb5b45a7f6ebe4c60e9ae1835b2c8873178ccd592 /lib/python
parent1879c6e7342c78995b38dfbd62cd4504cc40b39f (diff)
QMK CLI and JSON keymap support (#6176)
* Script to generate keymap.c from JSON file. * Support for keymap.json * Add a warning about the keymap.c getting overwritten. * Fix keymap generating * Install the python deps * Flesh out more of the python environment * Remove defunct json2keymap * Style everything with yapf * Polish up python support * Hide json keymap.c into the .build dir * Polish up qmk-compile-json * Make milc work with positional arguments * Fix a couple small things * Fix some errors and make the CLI more understandable * Make the qmk wrapper more robust * Add basic QMK Doctor * Clean up docstrings and flesh them out as needed * remove unused compile_firmware() function
Diffstat (limited to 'lib/python')
-rw-r--r--lib/python/milc.py716
-rw-r--r--lib/python/qmk/__init__.py0
-rw-r--r--lib/python/qmk/cli/compile/__init__.py0
-rwxr-xr-xlib/python/qmk/cli/compile/json.py44
-rwxr-xr-xlib/python/qmk/cli/doctor.py47
-rwxr-xr-xlib/python/qmk/cli/hello.py13
-rw-r--r--lib/python/qmk/cli/json/__init__.py0
-rwxr-xr-xlib/python/qmk/cli/json/keymap.py54
-rw-r--r--lib/python/qmk/errors.py6
-rw-r--r--lib/python/qmk/keymap.py100
-rw-r--r--lib/python/qmk/path.py32
11 files changed, 1012 insertions, 0 deletions
diff --git a/lib/python/milc.py b/lib/python/milc.py
new file mode 100644
index 0000000000..6e82edf8b1
--- /dev/null
+++ b/lib/python/milc.py
@@ -0,0 +1,716 @@
+#!/usr/bin/env python3
+# coding=utf-8
+"""MILC - A CLI Framework
+
+PYTHON_ARGCOMPLETE_OK
+
+MILC is an opinionated framework for writing CLI apps. It optimizes for the
+most common unix tool pattern- small tools that are run from the command
+line but generally do not feature any user interaction while they run.
+
+For more details see the MILC documentation:
+
+ <https://github.com/clueboard/milc/tree/master/docs>
+"""
+from __future__ import division, print_function, unicode_literals
+import argparse
+import logging
+import os
+import re
+import sys
+from decimal import Decimal
+from tempfile import NamedTemporaryFile
+from time import sleep
+
+try:
+ from ConfigParser import RawConfigParser
+except ImportError:
+ from configparser import RawConfigParser
+
+try:
+ import thread
+ import threading
+except ImportError:
+ thread = None
+
+import argcomplete
+import colorama
+
+# Log Level Representations
+EMOJI_LOGLEVELS = {
+ 'CRITICAL': '{bg_red}{fg_white}¬_¬{style_reset_all}',
+ 'ERROR': '{fg_red}☒{style_reset_all}',
+ 'WARNING': '{fg_yellow}⚠{style_reset_all}',
+ 'INFO': '{fg_blue}ℹ{style_reset_all}',
+ 'DEBUG': '{fg_cyan}☐{style_reset_all}',
+ 'NOTSET': '{style_reset_all}¯\\_(o_o)_/¯'
+}
+EMOJI_LOGLEVELS['FATAL'] = EMOJI_LOGLEVELS['CRITICAL']
+EMOJI_LOGLEVELS['WARN'] = EMOJI_LOGLEVELS['WARNING']
+
+# ANSI Color setup
+# Regex was gratefully borrowed from kfir on stackoverflow:
+# https://stackoverflow.com/a/45448194
+ansi_regex = r'\x1b(' \
+ r'(\[\??\d+[hl])|' \
+ r'([=<>a-kzNM78])|' \
+ r'([\(\)][a-b0-2])|' \
+ r'(\[\d{0,2}[ma-dgkjqi])|' \
+ r'(\[\d+;\d+[hfy]?)|' \
+ r'(\[;?[hf])|' \
+ r'(#[3-68])|' \
+ r'([01356]n)|' \
+ r'(O[mlnp-z]?)|' \
+ r'(/Z)|' \
+ r'(\d+)|' \
+ r'(\[\?\d;\d0c)|' \
+ r'(\d;\dR))'
+ansi_escape = re.compile(ansi_regex, flags=re.IGNORECASE)
+ansi_styles = (
+ ('fg', colorama.ansi.AnsiFore()),
+ ('bg', colorama.ansi.AnsiBack()),
+ ('style', colorama.ansi.AnsiStyle()),
+)
+ansi_colors = {}
+
+for prefix, obj in ansi_styles:
+ for color in [x for x in obj.__dict__ if not x.startswith('_')]:
+ ansi_colors[prefix + '_' + color.lower()] = getattr(obj, color)
+
+
+def format_ansi(text):
+ """Return a copy of text with certain strings replaced with ansi.
+ """
+ # Avoid .format() so we don't have to worry about the log content
+ for color in ansi_colors:
+ text = text.replace('{%s}' % color, ansi_colors[color])
+ return text + ansi_colors['style_reset_all']
+
+
+class ANSIFormatter(logging.Formatter):
+ """A log formatter that inserts ANSI color.
+ """
+
+ def format(self, record):
+ msg = super(ANSIFormatter, self).format(record)
+ return format_ansi(msg)
+
+
+class ANSIEmojiLoglevelFormatter(ANSIFormatter):
+ """A log formatter that makes the loglevel an emoji.
+ """
+
+ def format(self, record):
+ record.levelname = EMOJI_LOGLEVELS[record.levelname].format(**ansi_colors)
+ return super(ANSIEmojiLoglevelFormatter, self).format(record)
+
+
+class ANSIStrippingFormatter(ANSIFormatter):
+ """A log formatter that strips ANSI.
+ """
+
+ def format(self, record):
+ msg = super(ANSIStrippingFormatter, self).format(record)
+ return ansi_escape.sub('', msg)
+
+
+class Configuration(object):
+ """Represents the running configuration.
+
+ This class never raises IndexError, instead it will return None if a
+ section or option does not yet exist.
+ """
+
+ def __contains__(self, key):
+ return self._config.__contains__(key)
+
+ def __iter__(self):
+ return self._config.__iter__()
+
+ def __len__(self):
+ return self._config.__len__()
+
+ def __repr__(self):
+ return self._config.__repr__()
+
+ def keys(self):
+ return self._config.keys()
+
+ def items(self):
+ return self._config.items()
+
+ def values(self):
+ return self._config.values()
+
+ def __init__(self, *args, **kwargs):
+ self._config = {}
+ self.default_container = ConfigurationOption
+
+ def __getitem__(self, key):
+ """Returns a config section, creating it if it doesn't exist yet.
+ """
+ if key not in self._config:
+ self.__dict__[key] = self._config[key] = ConfigurationOption()
+
+ return self._config[key]
+
+ def __setitem__(self, key, value):
+ self.__dict__[key] = value
+ self._config[key] = value
+
+ def __delitem__(self, key):
+ if key in self.__dict__ and key[0] != '_':
+ del self.__dict__[key]
+ del self._config[key]
+
+
+class ConfigurationOption(Configuration):
+ def __init__(self, *args, **kwargs):
+ super(ConfigurationOption, self).__init__(*args, **kwargs)
+ self.default_container = dict
+
+ def __getitem__(self, key):
+ """Returns a config section, creating it if it doesn't exist yet.
+ """
+ if key not in self._config:
+ self.__dict__[key] = self._config[key] = None
+
+ return self._config[key]
+
+
+def handle_store_boolean(self, *args, **kwargs):
+ """Does the add_argument for action='store_boolean'.
+ """
+ kwargs['add_dest'] = False
+ disabled_args = None
+ disabled_kwargs = kwargs.copy()
+ disabled_kwargs['action'] = 'store_false'
+ disabled_kwargs['help'] = 'Disable ' + kwargs['help']
+ kwargs['action'] = 'store_true'
+ kwargs['help'] = 'Enable ' + kwargs['help']
+
+ for flag in args:
+ if flag[:2] == '--':
+ disabled_args = ('--no-' + flag[2:],)
+ break
+
+ self.add_argument(*args, **kwargs)
+ self.add_argument(*disabled_args, **disabled_kwargs)
+
+ return (args, kwargs, disabled_args, disabled_kwargs)
+
+
+class SubparserWrapper(object):
+ """Wrap subparsers so we can populate the normal and the shadow parser.
+ """
+
+ def __init__(self, cli, submodule, subparser):
+ self.cli = cli
+ self.submodule = submodule
+ self.subparser = subparser
+
+ for attr in dir(subparser):
+ if not hasattr(self, attr):
+ setattr(self, attr, getattr(subparser, attr))
+
+ def completer(self, completer):
+ """Add an arpcomplete completer to this subcommand.
+ """
+ self.subparser.completer = completer
+
+ def add_argument(self, *args, **kwargs):
+ if kwargs.get('add_dest', True):
+ kwargs['dest'] = self.submodule + '_' + self.cli.get_argument_name(*args, **kwargs)
+ if 'add_dest' in kwargs:
+ del kwargs['add_dest']
+
+ if 'action' in kwargs and kwargs['action'] == 'store_boolean':
+ return handle_store_boolean(self, *args, **kwargs)
+
+ self.cli.acquire_lock()
+ self.subparser.add_argument(*args, **kwargs)
+
+ if 'default' in kwargs:
+ del kwargs['default']
+ if 'action' in kwargs and kwargs['action'] == 'store_false':
+ kwargs['action'] == 'store_true'
+ self.cli.subcommands_default[self.submodule].add_argument(*args, **kwargs)
+ self.cli.release_lock()
+
+
+class MILC(object):
+ """MILC - An Opinionated Batteries Included Framework
+ """
+
+ def __init__(self):
+ """Initialize the MILC object.
+ """
+ # Setup a lock for thread safety
+ self._lock = threading.RLock() if thread else None
+
+ # Define some basic info
+ self.acquire_lock()
+ self._description = None
+ self._entrypoint = None
+ self._inside_context_manager = False
+ self.ansi = ansi_colors
+ self.config = Configuration()
+ self.config_file = None
+ self.prog_name = sys.argv[0][:-3] if sys.argv[0].endswith('.py') else sys.argv[0]
+ self.version = os.environ.get('QMK_VERSION', 'unknown')
+ self.release_lock()
+
+ # Initialize all the things
+ self.initialize_argparse()
+ self.initialize_logging()
+
+ @property
+ def description(self):
+ return self._description
+
+ @description.setter
+ def description(self, value):
+ self._description = self._arg_parser.description = self._arg_defaults.description = value
+
+ def echo(self, text, *args, **kwargs):
+ """Print colorized text to stdout, as long as stdout is a tty.
+
+ ANSI color strings (such as {fg-blue}) will be converted into ANSI
+ escape sequences, and the ANSI reset sequence will be added to all
+ strings.
+
+ If *args or **kwargs are passed they will be used to %-format the strings.
+ """
+ if args and kwargs:
+ raise RuntimeError('You can only specify *args or **kwargs, not both!')
+
+ if sys.stdout.isatty():
+ args = args or kwargs
+ text = format_ansi(text)
+
+ print(text % args)
+
+ def initialize_argparse(self):
+ """Prepare to process arguments from sys.argv.
+ """
+ kwargs = {
+ 'fromfile_prefix_chars': '@',
+ 'conflict_handler': 'resolve',
+ }
+
+ self.acquire_lock()
+ self.subcommands = {}
+ self.subcommands_default = {}
+ self._subparsers = None
+ self._subparsers_default = None
+ self.argwarn = argcomplete.warn
+ self.args = None
+ self._arg_defaults = argparse.ArgumentParser(**kwargs)
+ self._arg_parser = argparse.ArgumentParser(**kwargs)
+ self.set_defaults = self._arg_parser.set_defaults
+ self.print_usage = self._arg_parser.print_usage
+ self.print_help = self._arg_parser.print_help
+ self.release_lock()
+
+ def completer(self, completer):
+ """Add an arpcomplete completer to this subcommand.
+ """
+ self._arg_parser.completer = completer
+
+ def add_argument(self, *args, **kwargs):
+ """Wrapper to add arguments to both the main and the shadow argparser.
+ """
+ if kwargs.get('add_dest', True) and args[0][0] == '-':
+ kwargs['dest'] = 'general_' + self.get_argument_name(*args, **kwargs)
+ if 'add_dest' in kwargs:
+ del kwargs['add_dest']
+
+ if 'action' in kwargs and kwargs['action'] == 'store_boolean':
+ return handle_store_boolean(self, *args, **kwargs)
+
+ self.acquire_lock()
+ self._arg_parser.add_argument(*args, **kwargs)
+
+ # Populate the shadow parser
+ if 'default' in kwargs:
+ del kwargs['default']
+ if 'action' in kwargs and kwargs['action'] == 'store_false':
+ kwargs['action'] == 'store_true'
+ self._arg_defaults.add_argument(*args, **kwargs)
+ self.release_lock()
+
+ def initialize_logging(self):
+ """Prepare the defaults for the logging infrastructure.
+ """
+ self.acquire_lock()
+ self.log_file = None
+ self.log_file_mode = 'a'
+ self.log_file_handler = None
+ self.log_print = True
+ self.log_print_to = sys.stderr
+ self.log_print_level = logging.INFO
+ self.log_file_level = logging.DEBUG
+ self.log_level = logging.INFO
+ self.log = logging.getLogger(self.__class__.__name__)
+ self.log.setLevel(logging.DEBUG)
+ logging.root.setLevel(logging.DEBUG)
+ self.release_lock()
+
+ self.add_argument('-V', '--version', version=self.version, action='version', help='Display the version and exit')
+ self.add_argument('-v', '--verbose', action='store_true', help='Make the logging more verbose')
+ self.add_argument('--datetime-fmt', default='%Y-%m-%d %H:%M:%S', help='Format string for datetimes')
+ self.add_argument('--log-fmt', default='%(levelname)s %(message)s', help='Format string for printed log output')
+ self.add_argument('--log-file-fmt', default='[%(levelname)s] [%(asctime)s] [file:%(pathname)s] [line:%(lineno)d] %(message)s', help='Format string for log file.')
+ self.add_argument('--log-file', help='File to write log messages to')
+ self.add_argument('--color', action='store_boolean', default=True, help='color in output')
+ self.add_argument('-c', '--config-file', help='The config file to read and/or write')
+ self.add_argument('--save-config', action='store_true', help='Save the running configuration to the config file')
+
+ def add_subparsers(self, title='Sub-commands', **kwargs):
+ if self._inside_context_manager:
+ raise RuntimeError('You must run this before the with statement!')
+
+ self.acquire_lock()
+ self._subparsers_default = self._arg_defaults.add_subparsers(title=title, dest='subparsers', **kwargs)
+ self._subparsers = self._arg_parser.add_subparsers(title=title, dest='subparsers', **kwargs)
+ self.release_lock()
+
+ def acquire_lock(self):
+ """Acquire the MILC lock for exclusive access to properties.
+ """
+ if self._lock:
+ self._lock.acquire()
+
+ def release_lock(self):
+ """Release the MILC lock.
+ """
+ if self._lock:
+ self._lock.release()
+
+ def find_config_file(self):
+ """Locate the config file.
+ """
+ if self.config_file:
+ return self.config_file
+
+ if self.args and self.args.general_config_file:
+ return self.args.general_config_file
+
+ return os.path.abspath(os.path.expanduser('~/.%s.ini' % self.prog_name))
+
+ def get_argument_name(self, *args, **kwargs):
+ """Takes argparse arguments and returns the dest name.
+ """
+ try:
+ return self._arg_parser._get_optional_kwargs(*args, **kwargs)['dest']
+ except ValueError:
+ return self._arg_parser._get_positional_kwargs(*args, **kwargs)['dest']
+
+ def argument(self, *args, **kwargs):
+ """Decorator to call self.add_argument or self.<subcommand>.add_argument.
+ """
+ if self._inside_context_manager:
+ raise RuntimeError('You must run this before the with statement!')
+
+ def argument_function(handler):
+ if handler is self._entrypoint:
+ self.add_argument(*args, **kwargs)
+
+ elif handler.__name__ in self.subcommands:
+ self.subcommands[handler.__name__].add_argument(*args, **kwargs)
+
+ else:
+ raise RuntimeError('Decorated function is not entrypoint or subcommand!')
+
+ return handler
+
+ return argument_function
+
+ def arg_passed(self, arg):
+ """Returns True if arg was passed on the command line.
+ """
+ return self.args_passed[arg] in (None, False)
+
+ def parse_args(self):
+ """Parse the CLI args.
+ """
+ if self.args:
+ self.log.debug('Warning: Arguments have already been parsed, ignoring duplicate attempt!')
+ return
+
+ argcomplete.autocomplete(self._arg_parser)
+
+ self.acquire_lock()
+ self.args = self._arg_parser.parse_args()
+ self.args_passed = self._arg_defaults.parse_args()
+
+ if 'entrypoint' in self.args:
+ self._entrypoint = self.args.entrypoint
+
+ if self.args.general_config_file:
+ self.config_file = self.args.general_config_file
+
+ self.release_lock()
+
+ def read_config(self):
+ """Parse the configuration file and determine the runtime configuration.
+ """
+ self.acquire_lock()
+ self.config_file = self.find_config_file()
+
+ if self.config_file and os.path.exists(self.config_file):
+ config = RawConfigParser(self.config)
+ config.read(self.config_file)
+
+ # Iterate over the config file options and write them into self.config
+ for section in config.sections():
+ for option in config.options(section):
+ value = config.get(section, option)
+
+ # Coerce values into useful datatypes
+ if value.lower() in ['1', 'yes', 'true', 'on']:
+ value = True
+ elif value.lower() in ['0', 'no', 'false', 'none', 'off']:
+ value = False
+ elif value.replace('.', '').isdigit():
+ if '.' in value:
+ value = Decimal(value)
+ else:
+ value = int(value)
+
+ self.config[section][option] = value
+
+ # Fold the CLI args into self.config
+ for argument in vars(self.args):
+ if argument in ('subparsers', 'entrypoint'):
+ continue
+
+ if '_' not in argument:
+ continue
+
+ section, option = argument.split('_', 1)
+ if hasattr(self.args_passed, argument):
+ self.config[section][option] = getattr(self.args, argument)
+ else:
+ if option not in self.config[section]:
+ self.config[section][option] = getattr(self.args, argument)
+
+ self.release_lock()
+
+ def save_config(self):
+ """Save the current configuration to the config file.
+ """
+ self.log.debug("Saving config file to '%s'", self.config_file)
+
+ if not self.config_file:
+ self.log.warning('%s.config_file file not set, not saving config!', self.__class__.__name__)
+ return
+
+ self.acquire_lock()
+
+ config = RawConfigParser()
+ for section_name, section in self.config._config.items():
+ config.add_section(section_name)
+ for option_name, value in section.items():
+ if section_name == 'general':
+ if option_name in ['save_config']:
+ continue
+ config.set(section_name, option_name, str(value))
+
+ with NamedTemporaryFile(mode='w', dir=os.path.dirname(self.config_file), delete=False) as tmpfile:
+ config.write(tmpfile)
+
+ # Move the new config file into place atomically
+ if os.path.getsize(tmpfile.name) > 0:
+ os.rename(tmpfile.name, self.config_file)
+ else:
+ self.log.warning('Config file saving failed, not replacing %s with %s.', self.config_file, tmpfile.name)
+
+ self.release_lock()
+
+ def __call__(self):
+ """Execute the entrypoint function.
+ """
+ if not self._inside_context_manager:
+ # If they didn't use the context manager use it ourselves
+ with self:
+ self.__call__()
+ return
+
+ if not self._entrypoint:
+ raise RuntimeError('No entrypoint provided!')
+
+ return self._entrypoint(self)
+
+ def entrypoint(self, description):
+ """Set the entrypoint for when no subcommand is provided.
+ """
+ if self._inside_context_manager:
+ raise RuntimeError('You must run this before cli()!')
+
+ self.acquire_lock()
+ self.description = description
+ self.release_lock()
+
+ def entrypoint_func(handler):
+ self.acquire_lock()
+ self._entrypoint = handler
+ self.release_lock()
+
+ return handler
+
+ return entrypoint_func
+
+ def add_subcommand(self, handler, description, name=None, **kwargs):
+ """Register a subcommand.
+
+ If name is not provided we use `handler.__name__`.
+ """
+ if self._inside_context_manager:
+ raise RuntimeError('You must run this before the with statement!')
+
+ if self._subparsers is None:
+ self.add_subparsers()
+
+ if not name:
+ name = handler.__name__
+
+ self.acquire_lock()
+ kwargs['help'] = description
+ self.subcommands_default[name] = self._subparsers_default.add_parser(name, **kwargs)
+ self.subcommands[name] = SubparserWrapper(self, name, self._subparsers.add_parser(name, **kwargs))
+ self.subcommands[name].set_defaults(entrypoint=handler)
+
+ if name not in self.__dict__:
+ self.__dict__[name] = self.subcommands[name]
+ else:
+ self.log.debug("Could not add subcommand '%s' to attributes, key already exists!", name)
+
+ self.release_lock()
+
+ return handler
+
+ def subcommand(self, description, **kwargs):
+ """Decorator to register a subcommand.
+ """
+
+ def subcommand_function(handler):
+ return self.add_subcommand(handler, description, **kwargs)
+
+ return subcommand_function
+
+ def setup_logging(self):
+ """Called by __enter__() to setup the logging configuration.
+ """
+ if len(logging.root.handlers) != 0:
+ # This is not a design decision. This is what I'm doing for now until I can examine and think about this situation in more detail.
+ raise RuntimeError('MILC should be the only system installing root log handlers!')
+
+ self.acquire_lock()
+
+ if self.config['general']['verbose']:
+ self.log_print_level = logging.DEBUG
+
+ self.log_file = self.config['general']['log_file'] or self.log_file
+ self.log_file_format = self.config['general']['log_file_fmt']
+ self.log_file_format = ANSIStrippingFormatter(self.config['general']['log_file_fmt'], self.config['general']['datetime_fmt'])
+ self.log_format = self.config['general']['log_fmt']
+
+ if self.config.general.color:
+ self.log_format = ANSIEmojiLoglevelFormatter(self.args.general_log_fmt, self.config.general.datetime_fmt)
+ else:
+ self.log_format = ANSIStrippingFormatter(self.args.general_log_fmt, self.config.general.datetime_fmt)
+
+ if self.log_file:
+ self.log_file_handler = logging.FileHandler(self.log_file, self.log_file_mode)
+ self.log_file_handler.setLevel(self.log_file_level)
+ self.log_file_handler.setFormatter(self.log_file_format)
+ logging.root.addHandler(self.log_file_handler)
+
+ if self.log_print:
+ self.log_print_handler = logging.StreamHandler(self.log_print_to)
+ self.log_print_handler.setLevel(self.log_print_level)
+ self.log_print_handler.setFormatter(self.log_format)
+ logging.root.addHandler(self.log_print_handler)
+
+ self.release_lock()
+
+ def __enter__(self):
+ if self._inside_context_manager:
+ self.log.debug('Warning: context manager was entered again. This usually means that self.__call__() was called before the with statement. You probably do not want to do that.')
+ return
+
+ self.acquire_lock()
+ self._inside_context_manager = True
+ self.release_lock()
+
+ colorama.init()
+ self.parse_args()
+ self.read_config()
+ self.setup_logging()
+
+ if self.config.general.save_config:
+ self.save_config()
+
+ return self
+
+ def __exit__(self, exc_type, exc_val, exc_tb):
+ self.acquire_lock()
+ self._inside_context_manager = False
+ self.release_lock()
+
+ if exc_type is not None and not isinstance(SystemExit(), exc_type):
+ print(exc_type)
+ logging.exception(exc_val)
+ exit(255)
+
+
+cli = MILC()
+
+if __name__ == '__main__':
+
+ @cli.argument('-c', '--comma', help='comma in output', default=True, action='store_boolean')
+ @cli.entrypoint('My useful CLI tool with subcommands.')
+ def main(cli):
+ comma = ',' if cli.config.general.comma else ''
+ cli.log.info('{bg_green}{fg_red}Hello%s World!', comma)
+
+ @cli.argument('-n', '--name', help='Name to greet', default='World')
+ @cli.subcommand('Description of hello subcommand here.')
+ def hello(cli):
+ comma = ',' if cli.config.general.comma else ''
+ cli.log.info('{fg_blue}Hello%s %s!', comma, cli.config.hello.name)
+
+ def goodbye(cli):
+ comma = ',' if cli.config.general.comma else ''
+ cli.log.info('{bg_red}Goodbye%s %s!', comma, cli.config.goodbye.name)
+
+ @cli.argument('-n', '--name', help='Name to greet', default='World')
+ @cli.subcommand('Think a bit before greeting the user.')
+ def thinking(cli):
+ comma = ',' if cli.config.general.comma else ''
+ spinner = cli.spinner(text='Just a moment...', spinner='earth')
+ spinner.start()
+ sleep(2)
+ spinner.stop()
+
+ with cli.spinner(text='Almost there!', spinner='moon'):
+ sleep(2)
+
+ cli.log.info('{fg_cyan}Hello%s %s!', comma, cli.config.thinking.name)
+
+ @cli.subcommand('Show off our ANSI colors.')
+ def pride(cli):
+ cli.echo('{bg_red} ')
+ cli.echo('{bg_lightred_ex} ')
+ cli.echo('{bg_lightyellow_ex} ')
+ cli.echo('{bg_green} ')
+ cli.echo('{bg_blue} ')
+ cli.echo('{bg_magenta} ')
+
+ # You can register subcommands using decorators as seen above, or using functions like like this:
+ cli.add_subcommand(goodbye, 'This will show up in --help output.')
+ cli.goodbye.add_argument('-n', '--name', help='Name to bid farewell to', default='World')
+
+ cli() # Automatically picks between main(), hello() and goodbye()
+ print(sorted(ansi_colors.keys()))
diff --git a/lib/python/qmk/__init__.py b/lib/python/qmk/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/python/qmk/__init__.py
diff --git a/lib/python/qmk/cli/compile/__init__.py b/lib/python/qmk/cli/compile/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/python/qmk/cli/compile/__init__.py
diff --git a/lib/python/qmk/cli/compile/json.py b/lib/python/qmk/cli/compile/json.py
new file mode 100755
index 0000000000..89c16b2063
--- /dev/null
+++ b/lib/python/qmk/cli/compile/json.py
@@ -0,0 +1,44 @@
+"""Create a keymap directory from a configurator export.
+"""
+import json
+import os
+import sys
+import subprocess
+
+from milc import cli
+
+import qmk.keymap
+import qmk.path
+
+
+@cli.argument('filename', help='Configurator JSON export')
+@cli.entrypoint('Compile a QMK Configurator export.')
+def main(cli):
+ """Compile a QMK Configurator export.
+
+ This command creates a new keymap from a configurator export, overwriting an existing keymap if one exists.
+
+ FIXME(skullydazed): add code to check and warn if the keymap already exists
+ """
+ # Error checking
+ if cli.args.filename == ('-'):
+ cli.log.error('Reading from STDIN is not (yet) supported.')
+ exit(1)
+ if not os.path.exists(qmk.path.normpath(cli.args.filename)):
+ cli.log.error('JSON file does not exist!')
+ exit(1)
+
+ # Parse the configurator json
+ with open(qmk.path.normpath(cli.args.filename), 'r') as fd:
+ user_keymap = json.load(fd)
+
+ # Generate the keymap
+ keymap_path = qmk.path.keymap(user_keymap['keyboard'])
+ cli.log.info('Creating {fg_cyan}%s{style_reset_all} keymap in {fg_cyan}%s', user_keymap['keymap'], keymap_path)
+ qmk.keymap.write(user_keymap['keyboard'], user_keymap['keymap'], user_keymap['layout'], user_keymap['layers'])
+ cli.log.info('Wrote keymap to {fg_cyan}%s/%s/keymap.c', keymap_path, user_keymap['keymap'])
+
+ # Compile the keymap
+ command = ['make', ':'.join((user_keymap['keyboard'], user_keymap['keymap']))]
+ cli.log.info('Compiling keymap with {fg_cyan}%s\n\n', ' '.join(command))
+ subprocess.run(command)
diff --git a/lib/python/qmk/cli/doctor.py b/lib/python/qmk/cli/doctor.py
new file mode 100755
index 0000000000..9ce765a4b5
--- /dev/null
+++ b/lib/python/qmk/cli/doctor.py
@@ -0,0 +1,47 @@
+"""QMK Python Doctor
+
+Check up for QMK environment.
+"""
+import shutil
+import platform
+import os
+
+from milc import cli
+
+
+@cli.entrypoint('Basic QMK environment checks')
+def main(cli):
+ """Basic QMK environment checks.
+
+ This is currently very simple, it just checks that all the expected binaries are on your system.
+
+ TODO(unclaimed):
+ * [ ] Run the binaries to make sure they work
+ * [ ] Compile a trivial program with each compiler
+ * [ ] Check for udev entries on linux
+ """
+
+ binaries = ['dfu-programmer', 'avrdude', 'dfu-util', 'avr-gcc', 'arm-none-eabi-gcc']
+
+ cli.log.info('QMK Doctor is Checking your environment')
+
+ ok = True
+ for binary in binaries:
+ res = shutil.which(binary)
+ if res is None:
+ cli.log.error('{fg_red}QMK can\'t find ' + binary + ' in your path')
+ ok = False
+
+ OS = platform.system()
+ if OS == "Darwin":
+ cli.log.info("Detected {fg_cyan}macOS")
+ elif OS == "Linux":
+ cli.log.info("Detected {fg_cyan}linux")
+ test = 'systemctl list-unit-files | grep enabled | grep -i ModemManager'
+ if os.system(test) == 0:
+ cli.log.warn("{bg_yellow}Detected modem manager. Please disable it if you are using Pro Micros")
+ else:
+ cli.log.info("Assuming {fg_cyan}Windows")
+
+ if ok:
+ cli.log.info('{fg_green}QMK is ready to go')
diff --git a/lib/python/qmk/cli/hello.py b/lib/python/qmk/cli/hello.py
new file mode 100755
index 0000000000..bc0cb6de18
--- /dev/null
+++ b/lib/python/qmk/cli/hello.py
@@ -0,0 +1,13 @@
+"""QMK Python Hello World
+
+This is an example QMK CLI script.
+"""
+from milc import cli
+
+
+@cli.argument('-n', '--name', default='World', help='Name to greet.')
+@cli.entrypoint('QMK Hello World.')
+def main(cli):
+ """Log a friendly greeting.
+ """
+ cli.log.info('Hello, %s!', cli.config.general.name)
diff --git a/lib/python/qmk/cli/json/__init__.py b/lib/python/qmk/cli/json/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/python/qmk/cli/json/__init__.py
diff --git a/lib/python/qmk/cli/json/keymap.py b/lib/python/qmk/cli/json/keymap.py
new file mode 100755
index 0000000000..35fc8f9c0e
--- /dev/null
+++ b/lib/python/qmk/cli/json/keymap.py
@@ -0,0 +1,54 @@
+"""Generate a keymap.c from a configurator export.
+"""
+import json
+import os
+import sys
+
+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):
+ """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.
+ """
+ # Error checking
+ if cli.args.filename == ('-'):
+ cli.log.error('Reading from STDIN is not (yet) supported.')
+ cli.print_usage()
+ exit(1)
+ if not os.path.exists(qmk.path.normpath(cli.args.filename)):
+ cli.log.error('JSON file does not exist!')
+ cli.print_usage()
+ exit(1)
+
+ # Environment processing
+ if cli.args.output == ('-'):
+ cli.args.output = None
+
+ # Parse the configurator json
+ with open(qmk.path.normpath(cli.args.filename), 'r') as fd:
+ user_keymap = json.load(fd)
+
+ # Generate the keymap
+ keymap_c = qmk.keymap.generate(user_keymap['keyboard'], user_keymap['layout'], user_keymap['layers'])
+
+ 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.args.output)
+ with open(output_file, 'w') as keymap_fd:
+ keymap_fd.write(keymap_c)
+
+ cli.log.info('Wrote keymap to %s.', cli.args.output)
+
+ else:
+ print(keymap_c)
diff --git a/lib/python/qmk/errors.py b/lib/python/qmk/errors.py
new file mode 100644
index 0000000000..f9bf5b9af9
--- /dev/null
+++ b/lib/python/qmk/errors.py
@@ -0,0 +1,6 @@
+class NoSuchKeyboardError(Exception):
+ """Raised when we can't find a keyboard/keymap directory.
+ """
+
+ def __init__(self, message):
+ self.message = message
diff --git a/lib/python/qmk/keymap.py b/lib/python/qmk/keymap.py
new file mode 100644
index 0000000000..6eccab788a
--- /dev/null
+++ b/lib/python/qmk/keymap.py
@@ -0,0 +1,100 @@
+"""Functions that help you work with QMK keymaps.
+"""
+import json
+import logging
+import os
+from traceback import format_exc
+
+import qmk.path
+from qmk.errors import NoSuchKeyboardError
+
+# The `keymap.c` template to use when a keyboard doesn't have its own
+DEFAULT_KEYMAP_C = """#include QMK_KEYBOARD_H
+
+/* THIS FILE WAS GENERATED!
+ *
+ * This file was generated by qmk-compile-json. You may or may not want to
+ * edit it directly.
+ */
+
+const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+__KEYMAP_GOES_HERE__
+};
+"""
+
+
+def template(keyboard):
+ """Returns the `keymap.c` template for a keyboard.
+
+ If a template exists in `keyboards/<keyboard>/templates/keymap.c` that
+ text will be used instead of `DEFAULT_KEYMAP_C`.
+
+ Args:
+ keyboard
+ The keyboard to return a template for.
+ """
+ template_name = 'keyboards/%s/templates/keymap.c' % keyboard
+
+ if os.path.exists(template_name):
+ with open(template_name, 'r') as fd:
+ return fd.read()
+
+ return DEFAULT_KEYMAP_C
+
+
+def generate(keyboard, layout, layers):
+ """Returns a keymap.c for the specified keyboard, layout, and layers.
+
+ Args:
+ keyboard
+ The name of the keyboard
+
+ layout
+ The LAYOUT macro this keymap uses.
+
+ layers
+ An array of arrays describing the keymap. Each item in the inner array should be a string that is a valid QMK keycode.
+ """
+ layer_txt = []
+ for layer_num, layer in enumerate(layers):
+ if layer_num != 0:
+ layer_txt[-1] = layer_txt[-1] + ','
+ layer_keys = ', '.join(layer)
+ layer_txt.append('\t[%s] = %s(%s)' % (layer_num, layout, layer_keys))
+
+ keymap = '\n'.join(layer_txt)
+ keymap_c = template(keyboard, keymap)
+
+ return keymap_c.replace('__KEYMAP_GOES_HERE__', keymap)
+
+
+def write(keyboard, keymap, layout, layers):
+ """Generate the `keymap.c` and write it to disk.
+
+ Returns the filename written to.
+
+ Args:
+ keyboard
+ The name of the keyboard
+
+ keymap
+ The name of the keymap
+
+ layout
+ The LAYOUT macro this keymap uses.
+
+ layers
+ An array of arrays describing the keymap. Each item in the inner array should be a string that is a valid QMK keycode.
+ """
+ keymap_c = generate(keyboard, layout, layers)
+ keymap_path = qmk.path.keymap(keyboard)
+ keymap_dir = os.path.join(keymap_path, keymap)
+ keymap_file = os.path.join(keymap_dir, 'keymap.c')
+
+ if not os.path.exists(keymap_dir):
+ os.makedirs(keymap_dir)
+
+ with open(keymap_file, 'w') as keymap_fd:
+ keymap_fd.write(keymap_c)
+
+ return keymap_file
diff --git a/lib/python/qmk/path.py b/lib/python/qmk/path.py
new file mode 100644
index 0000000000..f2a8346a51
--- /dev/null
+++ b/lib/python/qmk/path.py
@@ -0,0 +1,32 @@
+"""Functions that help us work with files and folders.
+"""
+import os
+
+
+def keymap(keyboard):
+ """Locate the correct directory for storing a keymap.
+
+ Args:
+ keyboard
+ The name of the keyboard. Example: clueboard/66/rev3
+ """
+ for directory in ['.', '..', '../..', '../../..', '../../../..', '../../../../..']:
+ basepath = os.path.normpath(os.path.join('keyboards', keyboard, directory, 'keymaps'))
+
+ if os.path.exists(basepath):
+ return basepath
+
+ logging.error('Could not find keymaps directory!')
+ raise NoSuchKeyboardError('Could not find keymaps directory for: %s' % keyboard)
+
+
+def normpath(path):
+ """Returns the fully resolved absolute path to a file.
+
+ This function will return the absolute path to a file as seen from the
+ directory the script was called from.
+ """
+ if path and path[0] == '/':
+ return os.path.normpath(path)
+
+ return os.path.normpath(os.path.join(os.environ['ORIG_CWD'], path))