drashna/qmk_firmware
1
0
Fork 0
Code Activity Actions

QMK CLI and JSON keymap support (#6176)

Browse source 
* 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
This commit is contained in:
skullydazed 2019-07-15 12:14:27 -07:00 • committed by GitHub
parent 7ba82cb5b7
commit a25dd58bc5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
34 changed files with 1988 additions and 83 deletions
Download patch file Download diff file Expand all files Collapse all files

45
docs/python_development.md Normal file
View file

@ -0,0 +1,45 @@
# Python Development in QMK
This document gives an overview of how QMK has structured its python code. You should read this before working on any of the python code.
## Script directories
There are two places scripts live in QMK: `qmk_firmware/bin` and `qmk_firmware/util`. You should use `bin` for any python scripts that utilize the `qmk` wrapper. Scripts that are standalone and not run very often live in `util`.
We discourage putting anything into `bin` that does not utilize the `qmk` wrapper. If you think you have a good reason for doing so please talk to us about your use case.
## Python Modules
Most of the QMK python modules can be found in `qmk_firmware/lib/python`. This is the path that we append to `sys.path`.
We have a module hierarchy under that path:
* `qmk_firmware/lib/python`
* `milc.py` - The CLI library we use. Will be pulled out into its own module in the future.
* `qmk` - Code associated with QMK
* `cli` - Modules that will be imported for CLI commands.
* `errors.py` - Errors that can be raised within QMK apps
* `keymap.py` - Functions for working with keymaps
## CLI Scripts
We have a CLI wrapper that you should utilize for any user facing scripts. We think it's pretty easy to use and it gives you a lot of nice things for free.
To use the wrapper simply place a module into `qmk_firmware/lib/python/qmk/cli`, and create a symlink to `bin/qmk` named after your module. Dashes in command names will be converted into dots so you can use hierarchy to manage commands.
When `qmk` is run it checks to see how it was invoked. If it was invoked as `qmk` the module name is take from `sys.argv[1]`. If it was invoked as `qmk-<module-name>` then everything after the first dash is taken as the module name. Dashes and underscores are converted to dots, and then `qmk.cli` is prepended before the module is imported.
The module uses `@cli.entrypoint()` and `@cli.argument()` decorators to define an entrypoint, which is where execution starts.
## Example CLI Script
We have provided a QMK Hello World script you can use as an example. To run it simply run `qmk hello` or `qmk-hello`. The source code is listed below.
```
from milc import cli
@cli.argument('-n', '--name', default='World', help='Name to greet.')
@cli.entrypoint('QMK Python Hello World.')
def main(cli):
cli.echo('Hello, %s!', cli.config.general.name)
```