diff options
Diffstat (limited to 'lib/python')
33 files changed, 1892 insertions, 0 deletions
diff --git a/lib/python/kle2xy.py b/lib/python/kle2xy.py new file mode 100644 index 0000000000..bff1d025b7 --- /dev/null +++ b/lib/python/kle2xy.py @@ -0,0 +1,146 @@ +""" Original code from https://github.com/skullydazed/kle2xy +""" + +import hjson +from decimal import Decimal + + +class KLE2xy(list): + """Abstract interface for interacting with a KLE layout. + """ + def __init__(self, layout=None, name='', invert_y=True): + super(KLE2xy, self).__init__() + + self.name = name + self.invert_y = invert_y + self.key_width = Decimal('19.05') + self.key_skel = {'decal': False, 'border_color': 'none', 'keycap_profile': '', 'keycap_color': 'grey', 'label_color': 'black', 'label_size': 3, 'label_style': 4, 'width': Decimal('1'), 'height': Decimal('1'), 'x': Decimal('0'), 'y': Decimal('0')} + self.rows = Decimal(0) + self.columns = Decimal(0) + + if layout: + self.parse_layout(layout) + + @property + def width(self): + """Returns the width of the keyboard plate. + """ + return (Decimal(self.columns) * self.key_width) + self.key_width / 2 + + @property + def height(self): + """Returns the height of the keyboard plate. + """ + return (self.rows * self.key_width) + self.key_width / 2 + + @property + def size(self): + """Returns the size of the keyboard plate. + """ + return (self.width, self.height) + + def attrs(self, properties): + """Parse the keyboard properties dictionary. + """ + # FIXME: Store more than just the keyboard name. + if 'name' in properties: + self.name = properties['name'] + + def parse_layout(self, layout): # noqa FIXME(skullydazed): flake8 says this has a complexity of 25, it should be refactored. + # Wrap this in a dictionary so hjson will parse KLE raw data + layout = '{"layout": [' + layout + ']}' + layout = hjson.loads(layout)['layout'] + + # Initialize our state machine + current_key = self.key_skel.copy() + current_row = Decimal(0) + current_col = Decimal(0) + current_x = 0 + current_y = self.key_width / 2 + + if isinstance(layout[0], dict): + self.attrs(layout[0]) + layout = layout[1:] + + for row_num, row in enumerate(layout): + self.append([]) + + # Process the current row + for key in row: + if isinstance(key, dict): + if 'w' in key and key['w'] != Decimal(1): + current_key['width'] = Decimal(key['w']) + if 'w2' in key and 'h2' in key and key['w2'] == 1.5 and key['h2'] == 1: + # FIXME: ISO Key uses these params: {x:0.25,w:1.25,h:2,w2:1.5,h2:1,x2:-0.25} + current_key['isoenter'] = True + if 'h' in key and key['h'] != Decimal(1): + current_key['height'] = Decimal(key['h']) + if 'a' in key: + current_key['label_style'] = self.key_skel['label_style'] = int(key['a']) + if current_key['label_style'] < 0: + current_key['label_style'] = 0 + elif current_key['label_style'] > 9: + current_key['label_style'] = 9 + if 'f' in key: + font_size = int(key['f']) + if font_size > 9: + font_size = 9 + elif font_size < 1: + font_size = 1 + current_key['label_size'] = self.key_skel['label_size'] = font_size + if 'p' in key: + current_key['keycap_profile'] = self.key_skel['keycap_profile'] = key['p'] + if 'c' in key: + current_key['keycap_color'] = self.key_skel['keycap_color'] = key['c'] + if 't' in key: + # FIXME: Need to do better validation, plus figure out how to support multiple colors + if '\n' in key['t']: + key['t'] = key['t'].split('\n')[0] + if key['t'] == "0": + key['t'] = "#000000" + current_key['label_color'] = self.key_skel['label_color'] = key['t'] + if 'x' in key: + current_col += Decimal(key['x']) + current_x += Decimal(key['x']) * self.key_width + if 'y' in key: + current_row += Decimal(key['y']) + current_y += Decimal(key['y']) * self.key_width + if 'd' in key: + current_key['decal'] = True + + else: + current_key['name'] = key + current_key['row'] = current_row + current_key['column'] = current_col + + # Determine the X center + x_center = (current_key['width'] * self.key_width) / 2 + current_x += x_center + current_key['x'] = current_x + current_x += x_center + + # Determine the Y center + y_center = (current_key['height'] * self.key_width) / 2 + y_offset = y_center - (self.key_width / 2) + current_key['y'] = (current_y + y_offset) + + # Tend to our row/col count + current_col += current_key['width'] + if current_col > self.columns: + self.columns = current_col + + # Invert the y-axis if neccesary + if self.invert_y: + current_key['y'] = -current_key['y'] + + # Store this key + self[-1].append(current_key) + current_key = self.key_skel.copy() + + # Move to the next row + current_x = 0 + current_y += self.key_width + current_col = Decimal(0) + current_row += Decimal(1) + if current_row > self.rows: + self.rows = Decimal(current_row) diff --git a/lib/python/milc.py b/lib/python/milc.py new file mode 100644 index 0000000000..e8599eff3f --- /dev/null +++ b/lib/python/milc.py @@ -0,0 +1,740 @@ +#!/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 shlex +import sys +from decimal import Decimal +from pathlib import Path +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 +from appdirs import user_config_dir + +# Disable logging until we can configure it how the user wants +logging.basicConfig(stream=os.devnull) + +# 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'] +UNICODE_SUPPORT = sys.stdout.encoding.lower().startswith('utf') + +# 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 on UTF capable terminals. + """ + def format(self, record): + if UNICODE_SUPPORT: + 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 = {} + + def __getattr__(self, key): + return self.__getitem__(key) + + 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] = ConfigurationSection(self) + + 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] + if key in self._config: + del self._config[key] + + +class ConfigurationSection(Configuration): + def __init__(self, parent, *args, **kwargs): + super(ConfigurationSection, self).__init__(*args, **kwargs) + self.parent = parent + + def __getitem__(self, key): + """Returns a config value, pulling from the `user` section as a fallback. + """ + if key in self._config: + return self._config[key] + + elif key in self.parent.user: + return self.parent.user[key] + + return None + + +def handle_store_boolean(self, *args, **kwargs): + """Does the add_argument for action='store_boolean'. + """ + disabled_args = None + disabled_kwargs = kwargs.copy() + disabled_kwargs['action'] = 'store_false' + disabled_kwargs['dest'] = self.get_argument_name(*args, **kwargs) + 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 track what options the user passed. + """ + 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): + """Add an argument for this subcommand. + + This also stores the default for the argument in `self.cli.default_arguments`. + """ + if 'action' in kwargs and kwargs['action'] == 'store_boolean': + # Store boolean will call us again with the enable/disable flag arguments + return handle_store_boolean(self, *args, **kwargs) + + self.cli.acquire_lock() + self.subparser.add_argument(*args, **kwargs) + if self.submodule not in self.cli.default_arguments: + self.cli.default_arguments[self.submodule] = {} + self.cli.default_arguments[self.submodule][self.cli.get_argument_name(*args, **kwargs)] = kwargs.get('default') + self.cli.release_lock() + + +class MILC(object): + """MILC - An Opinionated Batteries Included Framework + """ + def __init__(self): + """Initialize the MILC object. + + version + The version string to associate with your CLI program + """ + # 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.arg_only = [] + self.config = None + self.config_file = None + self.default_arguments = {} + self.version = 'unknown' + self.release_lock() + + # Figure out our program name + self.prog_name = sys.argv[0][:-3] if sys.argv[0].endswith('.py') else sys.argv[0] + self.prog_name = self.prog_name.split('/')[-1] + + # Initialize all the things + self.read_config_file() + 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 = value + + def echo(self, text, *args, **kwargs): + """Print colorized text to stdout. + + 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!') + + 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._subparsers = None + self.argwarn = argcomplete.warn + self.args = None + 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 argcomplete completer to this subcommand. + """ + self._arg_parser.completer = completer + + def add_argument(self, *args, **kwargs): + """Wrapper to add arguments and track whether they were passed on the command line. + """ + 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) + if 'general' not in self.default_arguments: + self.default_arguments['general'] = {} + self.default_arguments['general'][self.get_argument_name(*args, **kwargs)] = kwargs.get('default') + + 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('--config-file', help='The location for the configuration file') + self.arg_only.append('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 = 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 '--config-file' in sys.argv: + return Path(sys.argv[sys.argv.index('--config-file') + 1]).expanduser().resolve() + + filedir = user_config_dir(appname='qmk', appauthor='QMK') + filename = '%s.ini' % self.prog_name + return Path(filedir) / filename + + 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 'arg_only' in kwargs and kwargs['arg_only']: + arg_name = self.get_argument_name(*args, **kwargs) + self.arg_only.append(arg_name) + del kwargs['arg_only'] + + name = handler.__name__.replace("_", "-") + if handler is self._entrypoint: + self.add_argument(*args, **kwargs) + + elif name in self.subcommands: + self.subcommands[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.default_arguments.get(arg) != self.args[arg] + + 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() + + if 'entrypoint' in self.args: + self._entrypoint = self.args.entrypoint + + self.release_lock() + + def read_config_file(self): + """Read in the configuration file and store it in self.config. + """ + self.acquire_lock() + self.config = Configuration() + self.config_file = self.find_config_file() + + if self.config_file and self.config_file.exists(): + config = RawConfigParser(self.config) + config.read(str(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', 'off']: + value = False + elif value.lower() in ['none']: + continue + elif value.replace('.', '').isdigit(): + if '.' in value: + value = Decimal(value) + else: + value = int(value) + + self.config[section][option] = value + + self.release_lock() + + def merge_args_into_config(self): + """Merge CLI arguments into self.config to create the runtime configuration. + """ + self.acquire_lock() + for argument in vars(self.args): + if argument in ('subparsers', 'entrypoint'): + continue + + if argument not in self.arg_only: + # Find the argument's section + if self._entrypoint.__name__ in self.default_arguments and argument in self.default_arguments[self._entrypoint.__name__]: + argument_found = True + section = self._entrypoint.__name__ + if argument in self.default_arguments['general']: + argument_found = True + section = 'general' + + if not argument_found: + raise RuntimeError('Could not find argument in `self.default_arguments`. This should be impossible!') + exit(1) + + # Merge this argument into self.config + if argument in self.default_arguments: + arg_value = getattr(self.args, argument) + if arg_value: + self.config[section][argument] = arg_value + else: + if argument not in self.config[section]: + self.config[section][argument] = 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'", str(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() + + # Generate a sanitized version of our running configuration + 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 ['config_file']: + continue + if value is not None: + config.set(section_name, option_name, str(value)) + + # Write out the config file + config_dir = self.config_file.parent + if not config_dir.exists(): + config_dir.mkdir(parents=True, exist_ok=True) + + with NamedTemporaryFile(mode='w', dir=str(config_dir), 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, str(self.config_file)) + else: + self.log.warning('Config file saving failed, not replacing %s with %s.', str(self.config_file), tmpfile.name) + + # Housekeeping + self.release_lock() + cli.log.info('Wrote configuration to %s', shlex.quote(str(self.config_file))) + + 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: + return self.__call__() + + 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__.replace("_", "-") + + self.acquire_lock() + + kwargs['help'] = description + self.subcommands[name] = SubparserWrapper(self, name, self._subparsers.add_parser(name, **kwargs)) + self.subcommands[name].set_defaults(entrypoint=handler) + + 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: + # MILC is the only thing that should have root log handlers + logging.root.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.log_fmt, self.config.general.datetime_fmt) + else: + self.log_format = ANSIStrippingFormatter(self.args.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.merge_args_into_config() + self.setup_logging() + + 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() 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/__init__.py b/lib/python/qmk/cli/__init__.py new file mode 100644 index 0000000000..72ee38f562 --- /dev/null +++ b/lib/python/qmk/cli/__init__.py @@ -0,0 +1,17 @@ +"""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 docs +from . import doctor +from . import flash +from . import hello +from . import json +from . import list +from . import kle2json +from . import new +from . import pyformat +from . import pytest diff --git a/lib/python/qmk/cli/cformat.py b/lib/python/qmk/cli/cformat.py new file mode 100644 index 0000000000..17ca91b3b5 --- /dev/null +++ b/lib/python/qmk/cli/cformat.py @@ -0,0 +1,43 @@ +"""Format C code according to QMK's style. +""" +import os +import subprocess +from shutil import which + +from milc import 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. + """ + # Determine which version of clang-format to use + clang_format = ['clang-format', '-i'] + for clang_version in [10, 9, 8, 7]: + binary = 'clang-format-%d' % clang_version + if which(binary): + clang_format[0] = binary + break + + # Find the list of files to format + if cli.args.files: + cli.args.files = [os.path.join(os.environ['ORIG_CWD'], file) for file in cli.args.files] + else: + for dir in ['drivers', 'quantum', 'tests', 'tmk_core']: + for dirpath, dirnames, filenames in os.walk(dir): + if 'tmk_core/protocol/usb_hid' in dirpath: + continue + + for name in filenames: + if name.endswith('.c') or name.endswith('.h') or name.endswith('.cpp'): + cli.args.files.append(os.path.join(dirpath, name)) + + # Run clang-format on the files we've found + try: + subprocess.run(clang_format + cli.args.files, check=True) + cli.log.info('Successfully formatted the C code.') + + except subprocess.CalledProcessError: + cli.log.error('Error formatting C code!') + return False diff --git a/lib/python/qmk/cli/compile.py b/lib/python/qmk/cli/compile.py new file mode 100755 index 0000000000..234ffb12ca --- /dev/null +++ b/lib/python/qmk/cli/compile.py @@ -0,0 +1,53 @@ +"""Compile a QMK Firmware. + +You can compile a keymap already in the repo or using a QMK Configurator export. +""" +import subprocess +from argparse import FileType + +from milc import cli +from qmk.commands import create_make_command +from qmk.commands import parse_configurator_json +from qmk.commands import compile_configurator_json + +import qmk.keymap +import qmk.path + + +@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.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. + + FIXME(skullydazed): add code to check and warn if the keymap already exists + + If --keyboard and --keymap are provided this command will build a firmware based on that. + + """ + if cli.args.filename: + # Parse the configurator json + user_keymap = parse_configurator_json(cli.args.filename) + + # 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) + + # Compile the keymap + command = compile_configurator_json(cli.args.filename) + + cli.log.info('Wrote keymap to {fg_cyan}%s/%s/keymap.c', keymap_path, user_keymap['keymap']) + + elif cli.config.compile.keyboard and cli.config.compile.keymap: + # Generate the make command for a specific keyboard/keymap. + command = create_make_command(cli.config.compile.keyboard, cli.config.compile.keymap) + + else: + cli.log.error('You must supply a configurator export or both `--keyboard` and `--keymap`.') + return False + + cli.log.info('Compiling keymap with {fg_cyan}%s\n\n', ' '.join(command)) + subprocess.run(command) diff --git a/lib/python/qmk/cli/config.py b/lib/python/qmk/cli/config.py new file mode 100644 index 0000000000..e17d8bb9ba --- /dev/null +++ b/lib/python/qmk/cli/config.py @@ -0,0 +1,116 @@ +"""Read and write configuration settings +""" +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]) + + +def show_config(): + """Print the current configuration to stdout. + """ + for section in cli.config: + for key in cli.config[section]: + print_config(section, key) + + +def parse_config_token(config_token): + """Split a user-supplied configuration-token into its components. + """ + section = option = value = None + + if '=' in config_token and '.' not in config_token: + cli.log.error('Invalid configuration token, the key must be of the form <section>.<option>: %s', config_token) + return section, option, value + + # Separate the key (<section>.<option>) from the value + if '=' in config_token: + key, value = config_token.split('=') + else: + key = config_token + + # Extract the section and option from the key + if '.' in key: + section, option = key.split('.', 1) + else: + section = key + + return section, option, value + + +def set_config(section, option, value): + """Set a config key in the running config. + """ + 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, option, cli.config[section][option], value) + + if not cli.args.read_only: + if value == 'None': + del cli.config[section][option] + else: + cli.config[section][option] = value + + +@cli.argument('-ro', '--read-only', arg_only=True, 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: + return show_config() + + # 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(' '): + section, option, value = parse_config_token(config_token) + + # Validation + if option and '.' in option: + cli.log.error('Config keys may not have more than one period! "%s" is not valid.', config_token) + return False + + # Do what the user wants + if section and option and value: + # Write a configuration option + set_config(section, option, value) + if not cli.args.read_only: + save_config = True + + elif section and option: + # Display a single key + print_config(section, option) + + 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 diff --git a/lib/python/qmk/cli/docs.py b/lib/python/qmk/cli/docs.py new file mode 100644 index 0000000000..b419891396 --- /dev/null +++ b/lib/python/qmk/cli/docs.py @@ -0,0 +1,27 @@ +"""Serve QMK documentation locally +""" +import http.server + +from milc import cli + + +class DocsHandler(http.server.SimpleHTTPRequestHandler): + def __init__(self, *args, **kwargs): + super().__init__(*args, directory='docs', **kwargs) + + +@cli.argument('-p', '--port', default=8936, type=int, help='Port number to use.') +@cli.subcommand('Run a local webserver for QMK documentation.') +def docs(cli): + """Spin up a local HTTPServer instance for the QMK docs. + """ + with http.server.HTTPServer(('', cli.config.docs.port), DocsHandler) as httpd: + cli.log.info("Serving QMK docs at http://localhost:%d/", cli.config.docs.port) + cli.log.info("Press Control+C to exit.") + + try: + httpd.serve_forever() + except KeyboardInterrupt: + cli.log.info("Stopping HTTP server...") + finally: + httpd.shutdown() diff --git a/lib/python/qmk/cli/doctor.py b/lib/python/qmk/cli/doctor.py new file mode 100755 index 0000000000..1010eafb33 --- /dev/null +++ b/lib/python/qmk/cli/doctor.py @@ -0,0 +1,75 @@ +"""QMK Python Doctor + +Check up for QMK environment. +""" +import platform +import shutil +import subprocess + +from milc import 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. + + TODO(unclaimed): + * [ ] Compile a trivial program with each compiler + * [ ] Check for udev entries on linux + """ + cli.log.info('QMK Doctor is checking your environment.') + + # Make sure the basic CLI tools we need are available and can be executed. + binaries = ['dfu-programmer', 'avrdude', 'dfu-util', 'avr-gcc', 'arm-none-eabi-gcc', 'bin/qmk'] + ok = True + + for binary in binaries: + res = shutil.which(binary) + if res is None: + cli.log.error("{fg_red}QMK can't find %s in your path.", binary) + ok = False + else: + check = subprocess.run([binary, '--version'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=5) + if check.returncode in [0, 1]: + cli.log.info('Found {fg_cyan}%s', binary) + else: + cli.log.error("{fg_red}Can't run `%s --version`", binary) + ok = False + + # Determine our OS and run platform specific tests + OS = platform.system() + + if OS == "Darwin": + cli.log.info("Detected {fg_cyan}macOS.") + + elif OS == "Linux": + cli.log.info("Detected {fg_cyan}Linux.") + if shutil.which('systemctl'): + mm_check = subprocess.run(['systemctl', 'list-unit-files'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=10, universal_newlines=True) + if mm_check.returncode == 0: + mm = False + for line in mm_check.stdout.split('\n'): + if 'ModemManager' in line and 'enabled' in line: + mm = True + + if mm: + cli.log.warn("{bg_yellow}Detected ModemManager. Please disable it if you are using a Pro-Micro.") + + else: + cli.log.error('{bg_red}Could not run `systemctl list-unit-files`:') + cli.log.error(mm_check.stderr) + + else: + cli.log.warn("Can't find systemctl to check for ModemManager.") + + else: + cli.log.info("Assuming {fg_cyan}Windows.") + + # Report a summary of our findings to the user + if ok: + cli.log.info('{fg_green}QMK is ready to go') + else: + cli.log.info('{fg_yellow}Problems detected, please fix these problems before proceeding.') + # FIXME(skullydazed): Link to a document about troubleshooting, or discord or something diff --git a/lib/python/qmk/cli/flash.py b/lib/python/qmk/cli/flash.py new file mode 100644 index 0000000000..031cb94967 --- /dev/null +++ b/lib/python/qmk/cli/flash.py @@ -0,0 +1,82 @@ +"""Compile and flash QMK Firmware + +You can compile a keymap already in the repo or using a QMK Configurator export. +A bootloader must be specified. +""" +import subprocess + +import qmk.path +from milc import cli +from qmk.commands import compile_configurator_json, create_make_command, parse_configurator_json + + +def print_bootloader_help(): + """Prints the available bootloaders listed in docs.qmk.fm. + """ + cli.log.info('Here are the available bootloaders:') + cli.echo('\tdfu') + cli.echo('\tdfu-ee') + cli.echo('\tdfu-split-left') + cli.echo('\tdfu-split-right') + cli.echo('\tavrdude') + cli.echo('\tBootloadHID') + cli.echo('\tdfu-util') + cli.echo('\tdfu-util-split-left') + cli.echo('\tdfu-util-split-right') + cli.echo('\tst-link-cli') + cli.echo('For more info, visit https://docs.qmk.fm/#/flashing') + + +@cli.argument('-bl', '--bootloader', default='flash', help='The flash command, corresponding to qmk\'s make options of bootloaders.') +@cli.argument('filename', nargs='?', arg_only=True, help='The configurator export JSON to compile. Use this if you dont want to specify a keymap and keyboard.') +@cli.argument('-km', '--keymap', help='The keymap to build a firmware for. Use this if you dont have a configurator file. Ignored when a configurator file is supplied.') +@cli.argument('-kb', '--keyboard', help='The keyboard to build a firmware for. Use this if you dont have a configurator file. Ignored when a configurator file is supplied.') +@cli.argument('-b', '--bootloaders', action='store_true', help='List the available bootloaders.') +@cli.subcommand('QMK Flash.') +def flash(cli): + """Compile and or flash QMK Firmware or keyboard/layout + + If a Configurator JSON export is supplied this command will create a new keymap. Keymap and Keyboard arguments + will be ignored. + + If no file is supplied, keymap and keyboard are expected. + + If bootloader is omitted, the one according to the rules.mk will be used. + + """ + command = [] + if cli.args.bootloaders: + # Provide usage and list bootloaders + cli.echo('usage: qmk flash [-h] [-b] [-kb KEYBOARD] [-km KEYMAP] [-bl BOOTLOADER] [filename]') + print_bootloader_help() + return False + + elif cli.args.keymap and not cli.args.keyboard: + # If only a keymap was given but no keyboard, suggest listing keyboards + cli.echo('usage: qmk flash [-h] [-b] [-kb KEYBOARD] [-km KEYMAP] [-bl BOOTLOADER] [filename]') + cli.log.error('run \'qmk list_keyboards\' to find out the supported keyboards') + return False + + elif cli.args.filename: + # Get keymap path to log info + user_keymap = parse_configurator_json(cli.args.filename) + 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) + + # Convert the JSON into a C file and write it to disk. + command = compile_configurator_json(cli.args.filename, cli.args.bootloader) + + cli.log.info('Wrote keymap to {fg_cyan}%s/%s/keymap.c', keymap_path, user_keymap['keymap']) + + elif cli.args.keyboard and cli.args.keymap: + # Generate the make command for a specific keyboard/keymap. + command = create_make_command(cli.config.flash.keyboard, cli.config.flash.keymap, cli.args.bootloader) + + else: + cli.echo('usage: qmk flash [-h] [-b] [-kb KEYBOARD] [-km KEYMAP] [-bl BOOTLOADER] [filename]') + cli.log.error('You must supply a configurator export or both `--keyboard` and `--keymap`. You can also specify a bootloader with --bootloader. Use --bootloaders to list the available bootloaders.') + return False + + cli.log.info('Flashing keymap with {fg_cyan}%s\n\n', ' '.join(command)) + subprocess.run(command) diff --git a/lib/python/qmk/cli/hello.py b/lib/python/qmk/cli/hello.py new file mode 100755 index 0000000000..bee28c3013 --- /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.subcommand('QMK Hello World.') +def hello(cli): + """Log a friendly greeting. + """ + cli.log.info('Hello, %s!', cli.config.hello.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..f4ebfc45b4 --- /dev/null +++ b/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 diff --git a/lib/python/qmk/cli/json/keymap.py b/lib/python/qmk/cli/json/keymap.py new file mode 100755 index 0000000000..a030ab53d6 --- /dev/null +++ b/lib/python/qmk/cli/json/keymap.py @@ -0,0 +1,55 @@ +"""Generate a keymap.c from a configurator export. +""" +import json +import os + +from milc import cli + +import qmk.keymap + + +@cli.argument('-o', '--output', arg_only=True, help='File to write to') +@cli.argument('-q', '--quiet', arg_only=True, action='store_true', help="Quiet mode, only output error messages") +@cli.argument('filename', arg_only=True, help='Configurator JSON file') +@cli.subcommand('Creates 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. + """ + # 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) + + if not cli.args.quiet: + cli.log.info('Wrote keymap to %s.', cli.args.output) + + else: + print(keymap_c) diff --git a/lib/python/qmk/cli/kle2json.py b/lib/python/qmk/cli/kle2json.py new file mode 100755 index 0000000000..00f63d3622 --- /dev/null +++ b/lib/python/qmk/cli/kle2json.py @@ -0,0 +1,75 @@ +"""Convert raw KLE to JSON +""" +import json +import os +from pathlib import Path +from decimal import Decimal +from collections import OrderedDict + +from milc import cli +from kle2xy import KLE2xy + +from qmk.converter import kle2qmk + + +class CustomJSONEncoder(json.JSONEncoder): + def default(self, obj): + try: + if isinstance(obj, Decimal): + if obj % 2 in (Decimal(0), Decimal(1)): + return int(obj) + return float(obj) + except TypeError: + pass + return json.JSONEncoder.default(self, obj) + + +@cli.argument('filename', help='The KLE raw txt to convert') +@cli.argument('-f', '--force', action='store_true', help='Flag to overwrite current info.json') +@cli.subcommand('Convert a KLE layout to a Configurator JSON') +def kle2json(cli): + """Convert a KLE layout to QMK's layout format. + """ # If filename is a path + if cli.args.filename.startswith("/") or cli.args.filename.startswith("./"): + file_path = Path(cli.args.filename) + # Otherwise assume it is a file name + else: + file_path = Path(os.environ['ORIG_CWD'], cli.args.filename) + # Check for valid file_path for more graceful failure + if not file_path.exists(): + return cli.log.error('File {fg_cyan}%s{style_reset_all} was not found.', str(file_path)) + out_path = file_path.parent + raw_code = file_path.open().read() + # Check if info.json exists, allow overwrite with force + if Path(out_path, "info.json").exists() and not cli.args.force: + cli.log.error('File {fg_cyan}%s/info.json{style_reset_all} already exists, use -f or --force to overwrite.', str(out_path)) + return False + try: + # Convert KLE raw to x/y coordinates (using kle2xy package from skullydazed) + kle = KLE2xy(raw_code) + except Exception as e: + cli.log.error('Could not parse KLE raw data: %s', raw_code) + cli.log.exception(e) + # FIXME: This should be better + return cli.log.error('Could not parse KLE raw data.') + keyboard = OrderedDict( + keyboard_name=kle.name, + url='', + maintainer='qmk', + width=kle.columns, + height=kle.rows, + layouts={'LAYOUT': { + 'layout': 'LAYOUT_JSON_HERE' + }}, + ) + # Initialize keyboard with json encoded from ordered dict + keyboard = json.dumps(keyboard, indent=4, separators=(', ', ': '), sort_keys=False, cls=CustomJSONEncoder) + # Initialize layout with kle2qmk from converter module + layout = json.dumps(kle2qmk(kle), separators=(', ', ':'), cls=CustomJSONEncoder) + # Replace layout in keyboard json + keyboard = keyboard.replace('"LAYOUT_JSON_HERE"', layout) + # Write our info.json + file = open(str(out_path) + "/info.json", "w") + file.write(keyboard) + file.close() + cli.log.info('Wrote out {fg_cyan}%s/info.json', str(out_path)) diff --git a/lib/python/qmk/cli/list/__init__.py b/lib/python/qmk/cli/list/__init__.py new file mode 100644 index 0000000000..c36ba69548 --- /dev/null +++ b/lib/python/qmk/cli/list/__init__.py @@ -0,0 +1 @@ +from . import keyboards diff --git a/lib/python/qmk/cli/list/keyboards.py b/lib/python/qmk/cli/list/keyboards.py new file mode 100644 index 0000000000..76e7760e84 --- /dev/null +++ b/lib/python/qmk/cli/list/keyboards.py @@ -0,0 +1,27 @@ +"""List the keyboards currently defined within QMK +""" +import os +import glob + +from milc import cli + +BASE_PATH = os.path.join(os.getcwd(), "keyboards") + os.path.sep +KB_WILDCARD = os.path.join(BASE_PATH, "**", "rules.mk") + + +def find_name(path): + """Determine the keyboard name by stripping off the base_path and rules.mk. + """ + return path.replace(BASE_PATH, "").replace(os.path.sep + "rules.mk", "") + + +@cli.subcommand("List the keyboards currently defined within QMK") +def list_keyboards(cli): + """List the keyboards currently defined within QMK + """ + # find everywhere we have rules.mk where keymaps isn't in the path + paths = [path for path in glob.iglob(KB_WILDCARD, recursive=True) if 'keymaps' not in path] + + # Extract the keyboard name from the path and print it + for keyboard_name in sorted(map(find_name, paths)): + print(keyboard_name) diff --git a/lib/python/qmk/cli/new/__init__.py b/lib/python/qmk/cli/new/__init__.py new file mode 100644 index 0000000000..c6a26939b8 --- /dev/null +++ b/lib/python/qmk/cli/new/__init__.py @@ -0,0 +1 @@ +from . import keymap diff --git a/lib/python/qmk/cli/new/keymap.py b/lib/python/qmk/cli/new/keymap.py new file mode 100755 index 0000000000..96525e28e1 --- /dev/null +++ b/lib/python/qmk/cli/new/keymap.py @@ -0,0 +1,40 @@ +"""This script automates the copying of the default keymap into your own keymap. +""" +import os +import shutil + +from milc import 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 keymap was not provided in the command line + 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) + keymap_path_default = os.path.join(kb_path, "keymaps/default") + keymap_path = os.path.join(kb_path, "keymaps/%s" % keymap) + + # check directories + if not os.path.exists(kb_path): + cli.log.error('Keyboard %s does not exist!', kb_path) + exit(1) + if not os.path.exists(keymap_path_default): + cli.log.error('Keyboard default %s does not exist!', keymap_path_default) + exit(1) + if os.path.exists(keymap_path): + cli.log.error('Keymap %s already exists!', keymap_path) + exit(1) + + # create user directory with default keymap files + shutil.copytree(keymap_path_default, keymap_path, symlinks=True) + + # end message to user + cli.log.info("%s keymap directory created in: %s", keymap, keymap_path) + cli.log.info("Compile a firmware with your new keymap by typing: \n" + "qmk compile -kb %s -km %s", keyboard, keymap) diff --git a/lib/python/qmk/cli/pyformat.py b/lib/python/qmk/cli/pyformat.py new file mode 100755 index 0000000000..a53ba40c0a --- /dev/null +++ b/lib/python/qmk/cli/pyformat.py @@ -0,0 +1,17 @@ +"""Format python code according to QMK's style. +""" +from milc import cli + +import subprocess + + +@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!') diff --git a/lib/python/qmk/cli/pytest.py b/lib/python/qmk/cli/pytest.py new file mode 100644 index 0000000000..09611d750f --- /dev/null +++ b/lib/python/qmk/cli/pytest.py @@ -0,0 +1,16 @@ +"""QMK Python Unit Tests + +QMK script to run unit and integration tests against our python code. +""" +import subprocess + +from milc import cli + + +@cli.subcommand('QMK Python Unit Tests') +def pytest(cli): + """Run several linting/testing commands. + """ + flake8 = subprocess.run(['flake8', 'lib/python', 'bin/qmk']) + nose2 = subprocess.run(['nose2', '-v']) + return flake8.returncode | nose2.returncode diff --git a/lib/python/qmk/commands.py b/lib/python/qmk/commands.py new file mode 100644 index 0000000000..f83a89578e --- /dev/null +++ b/lib/python/qmk/commands.py @@ -0,0 +1,59 @@ +"""Functions that build make commands +""" +import json +import qmk.keymap + + +def create_make_command(keyboard, keymap, target=None): + """Create a make compile command + + Args: + keyboard + The path of the keyboard, for example 'plank' + + keymap + The name of the keymap, for example 'algernon' + + target + Usually a bootloader. + + Returns: + A command that can be run to make the specified keyboard and keymap + """ + if target is None: + return ['make', ':'.join((keyboard, keymap))] + return ['make', ':'.join((keyboard, keymap, target))] + + +def parse_configurator_json(configurator_filename): + """Open and parse a configurator json export + """ + file = open(configurator_filename) + user_keymap = json.load(file) + file.close() + return user_keymap + + +def compile_configurator_json(configurator_filename, bootloader=None): + """Convert a configurator export JSON file into a C file + + Args: + configurator_filename + The configurator JSON export file + + bootloader + A bootloader to flash + + Returns: + A command to run to compile and flash the C file. + """ + # Parse the configurator json + user_keymap = parse_configurator_json(configurator_filename) + + # Write the keymap C file + qmk.keymap.write(user_keymap['keyboard'], user_keymap['keymap'], user_keymap['layout'], user_keymap['layers']) + + # Return a command that can be run to make the keymap and flash if given + if bootloader is None: + return create_make_command(user_keymap['keyboard'], user_keymap['keymap']) + return create_make_command(user_keymap['keyboard'], user_keymap['keymap'], bootloader) diff --git a/lib/python/qmk/converter.py b/lib/python/qmk/converter.py new file mode 100644 index 0000000000..bbd3531317 --- /dev/null +++ b/lib/python/qmk/converter.py @@ -0,0 +1,33 @@ +"""Functions to convert to and from QMK formats +""" +from collections import OrderedDict + + +def kle2qmk(kle): + """Convert a KLE layout to QMK's layout format. + """ + layout = [] + + for row in kle: + for key in row: + if key['decal']: + continue + + qmk_key = OrderedDict( + label="", + x=key['column'], + y=key['row'], + ) + + if key['width'] != 1: + qmk_key['w'] = key['width'] + if key['height'] != 1: + qmk_key['h'] = key['height'] + if 'name' in key and key['name']: + qmk_key['label'] = key['name'].split('\n', 1)[0] + else: + del (qmk_key['label']) + + layout.append(qmk_key) + + return layout diff --git a/lib/python/qmk/errors.py b/lib/python/qmk/errors.py new file mode 100644 index 0000000000..4a8a91556b --- /dev/null +++ b/lib/python/qmk/errors.py @@ -0,0 +1,5 @@ +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..f4a2893f38 --- /dev/null +++ b/lib/python/qmk/keymap.py @@ -0,0 +1,96 @@ +"""Functions that help you work with QMK keymaps. +""" +import os + +import qmk.path + +# 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) + + 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..cf087265fb --- /dev/null +++ b/lib/python/qmk/path.py @@ -0,0 +1,35 @@ +"""Functions that help us work with files and folders. +""" +import logging +import os + +from qmk.errors import NoSuchKeyboardError + + +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)) diff --git a/lib/python/qmk/tests/__init__.py b/lib/python/qmk/tests/__init__.py new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/python/qmk/tests/__init__.py diff --git a/lib/python/qmk/tests/attrdict.py b/lib/python/qmk/tests/attrdict.py new file mode 100644 index 0000000000..a2584b9233 --- /dev/null +++ b/lib/python/qmk/tests/attrdict.py @@ -0,0 +1,8 @@ +class AttrDict(dict): + """A dictionary that can be accessed by attributes. + + This should only be used to mock objects for unit testing. Please do not use this outside of qmk.tests. + """ + def __init__(self, *args, **kwargs): + super(AttrDict, self).__init__(*args, **kwargs) + self.__dict__ = self diff --git a/lib/python/qmk/tests/kle.txt b/lib/python/qmk/tests/kle.txt new file mode 100644 index 0000000000..862a899ab9 --- /dev/null +++ b/lib/python/qmk/tests/kle.txt @@ -0,0 +1,5 @@ +["¬\n`","!\n1","\"\n2","£\n3","$\n4","%\n5","^\n6","&\n7","*\n8","(\n9",")\n0","_\n-","+\n=",{w:2},"Backspace"], +[{w:1.5},"Tab","Q","W","E","R","T","Y","U","I","O","P","{\n[","}\n]",{x:0.25,w:1.25,h:2,w2:1.5,h2:1,x2:-0.25},"Enter"], +[{w:1.75},"Caps Lock","A","S","D","F","G","H","J","K","L",":\n;","@\n'","~\n#"], +[{w:1.25},"Shift","|\n\\","Z","X","C","V","B","N","M","<\n,",">\n.","?\n/",{w:2.75},"Shift"], +[{w:1.25},"Ctrl",{w:1.25},"Win",{w:1.25},"Alt",{a:7,w:6.25},"",{a:4,w:1.25},"AltGr",{w:1.25},"Win",{w:1.25},"Menu",{w:1.25},"Ctrl"] diff --git a/lib/python/qmk/tests/onekey_export.json b/lib/python/qmk/tests/onekey_export.json new file mode 100644 index 0000000000..95f0a980fe --- /dev/null +++ b/lib/python/qmk/tests/onekey_export.json @@ -0,0 +1,6 @@ +{ + "keyboard":"handwired/onekey/pytest", + "keymap":"pytest_unittest", + "layout":"LAYOUT", + "layers":[["KC_A"]] +} diff --git a/lib/python/qmk/tests/test_cli_commands.py b/lib/python/qmk/tests/test_cli_commands.py new file mode 100644 index 0000000000..3f75cef3e1 --- /dev/null +++ b/lib/python/qmk/tests/test_cli_commands.py @@ -0,0 +1,56 @@ +import subprocess + + +def check_subcommand(command, *args): + cmd = ['bin/qmk', command] + list(args) + return subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True) + + +def test_cformat(): + assert check_subcommand('cformat', 'tmk_core/common/keyboard.c').returncode == 0 + + +def test_compile(): + assert check_subcommand('compile', '-kb', 'handwired/onekey/pytest', '-km', 'default').returncode == 0 + + +def test_flash(): + assert check_subcommand('flash', '-b').returncode == 1 + assert check_subcommand('flash').returncode == 1 + + +def test_config(): + result = check_subcommand('config') + assert result.returncode == 0 + assert 'general.color' in result.stdout + + +def test_kle2json(): + assert check_subcommand('kle2json', 'kle.txt', '-f').returncode == 0 + + +def test_doctor(): + result = check_subcommand('doctor') + assert result.returncode == 0 + assert 'QMK Doctor is checking your environment.' in result.stderr + assert 'QMK is ready to go' in result.stderr + + +def test_hello(): + result = check_subcommand('hello') + assert result.returncode == 0 + assert 'Hello,' in result.stderr + + +def test_pyformat(): + result = check_subcommand('pyformat') + assert result.returncode == 0 + assert 'Successfully formatted the python code' in result.stderr + + +def test_list_keyboards(): + result = check_subcommand('list-keyboards') + assert result.returncode == 0 + # check to see if a known keyboard is returned + # this will fail if handwired/onekey/pytest is removed + assert 'handwired/onekey/pytest' in result.stdout diff --git a/lib/python/qmk/tests/test_qmk_errors.py b/lib/python/qmk/tests/test_qmk_errors.py new file mode 100644 index 0000000000..1d8690b7ef --- /dev/null +++ b/lib/python/qmk/tests/test_qmk_errors.py @@ -0,0 +1,8 @@ +from qmk.errors import NoSuchKeyboardError + + +def test_NoSuchKeyboardError(): + try: + raise NoSuchKeyboardError("test message") + except NoSuchKeyboardError as e: + assert e.message == 'test message' diff --git a/lib/python/qmk/tests/test_qmk_keymap.py b/lib/python/qmk/tests/test_qmk_keymap.py new file mode 100644 index 0000000000..2db625600e --- /dev/null +++ b/lib/python/qmk/tests/test_qmk_keymap.py @@ -0,0 +1,19 @@ +import qmk.keymap + + +def test_template_onekey_proton_c(): + templ = qmk.keymap.template('handwired/onekey/proton_c') + assert templ == qmk.keymap.DEFAULT_KEYMAP_C + + +def test_template_onekey_pytest(): + templ = qmk.keymap.template('handwired/onekey/pytest') + assert templ == 'const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {__KEYMAP_GOES_HERE__};\n' + + +def test_generate_onekey_pytest(): + templ = qmk.keymap.generate('handwired/onekey/pytest', 'LAYOUT', [['KC_A']]) + assert templ == 'const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [0] = LAYOUT(KC_A)};\n' + + +# FIXME(skullydazed): Add a test for qmk.keymap.write that mocks up an FD. diff --git a/lib/python/qmk/tests/test_qmk_path.py b/lib/python/qmk/tests/test_qmk_path.py new file mode 100644 index 0000000000..d6961a0f65 --- /dev/null +++ b/lib/python/qmk/tests/test_qmk_path.py @@ -0,0 +1,13 @@ +import os + +import qmk.path + + +def test_keymap_onekey_pytest(): + path = qmk.path.keymap('handwired/onekey/pytest') + assert path == 'keyboards/handwired/onekey/keymaps' + + +def test_normpath(): + path = qmk.path.normpath('lib/python') + assert path == os.path.join(os.environ['ORIG_CWD'], 'lib/python') |