diff options
author | skullydazed <skullydazed@users.noreply.github.com> | 2019-07-15 12:14:27 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-07-15 12:14:27 -0700 |
commit | a25dd58bc56b0c4010673723ac44eaff914979bb (patch) | |
tree | e4c08289df1b72db4ef8447ab7fdc13f604cffac /docs/python_development.md | |
parent | 7ba82cb5b751d69dda6cc77ec8877c89defad3e4 (diff) | |
download | firmware-a25dd58bc56b0c4010673723ac44eaff914979bb.tar.gz firmware-a25dd58bc56b0c4010673723ac44eaff914979bb.tar.bz2 firmware-a25dd58bc56b0c4010673723ac44eaff914979bb.zip |
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 'docs/python_development.md')
-rw-r--r-- | docs/python_development.md | 45 |
1 files changed, 45 insertions, 0 deletions
diff --git a/docs/python_development.md b/docs/python_development.md new file mode 100644 index 000000000..b976a7c0e --- /dev/null +++ b/docs/python_development.md @@ -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) +``` |