diff options
Diffstat (limited to 'docs/python_development.md')
| -rw-r--r-- | docs/python_development.md | 45 |
1 files changed, 0 insertions, 45 deletions
diff --git a/docs/python_development.md b/docs/python_development.md deleted file mode 100644 index b976a7c0e..000000000 --- a/docs/python_development.md +++ /dev/null | |||
| @@ -1,45 +0,0 @@ | |||
| 1 | # Python Development in QMK | ||
| 2 | |||
| 3 | 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. | ||
| 4 | |||
| 5 | ## Script directories | ||
| 6 | |||
| 7 | 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`. | ||
| 8 | |||
| 9 | 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. | ||
| 10 | |||
| 11 | ## Python Modules | ||
| 12 | |||
| 13 | Most of the QMK python modules can be found in `qmk_firmware/lib/python`. This is the path that we append to `sys.path`. | ||
| 14 | |||
| 15 | We have a module hierarchy under that path: | ||
| 16 | |||
| 17 | * `qmk_firmware/lib/python` | ||
| 18 | * `milc.py` - The CLI library we use. Will be pulled out into its own module in the future. | ||
| 19 | * `qmk` - Code associated with QMK | ||
| 20 | * `cli` - Modules that will be imported for CLI commands. | ||
| 21 | * `errors.py` - Errors that can be raised within QMK apps | ||
| 22 | * `keymap.py` - Functions for working with keymaps | ||
| 23 | |||
| 24 | ## CLI Scripts | ||
| 25 | |||
| 26 | 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. | ||
| 27 | |||
| 28 | 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. | ||
| 29 | |||
| 30 | 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. | ||
| 31 | |||
| 32 | The module uses `@cli.entrypoint()` and `@cli.argument()` decorators to define an entrypoint, which is where execution starts. | ||
| 33 | |||
| 34 | ## Example CLI Script | ||
| 35 | |||
| 36 | 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. | ||
| 37 | |||
| 38 | ``` | ||
| 39 | from milc import cli | ||
| 40 | |||
| 41 | @cli.argument('-n', '--name', default='World', help='Name to greet.') | ||
| 42 | @cli.entrypoint('QMK Python Hello World.') | ||
| 43 | def main(cli): | ||
| 44 | cli.echo('Hello, %s!', cli.config.general.name) | ||
| 45 | ``` | ||
