rhkhm


Namerhkhm JSON
Version 0.2.0 PyPI version JSON
download
home_pagehttps://github.com/fiskhest/rhkhm
SummaryHotKey helper for sxhkd
upload_time2020-08-23 20:20:10
maintainer
docs_urlNone
authorJohan Radivoj
requires_python>=3.6
license
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # HotKey Helper  - standalone sxhkd configuration parser and keybind runner

[![.github/workflows/main.yml](https://github.com/fiskhest/rhkhm/workflows/.github/workflows/main.yml/badge.svg)](https://github.com/fiskhest/rhkhm/actions?query=workflow%3A.github%2Fworkflows%2Fmain.yml)
[![AUR package](https://img.shields.io/aur/version/rhkhm-git)](https://aur.archlinux.org/packages/rhkhm-git/)
[![AUR package](https://img.shields.io/pypi/v/rhkhm?color=green)](https://pypi.org/project/rhkhm/)

rofi HotKey helper/menu -- Easily discover and execute sxhkd keybindings, inspired by [Hotkey-Helper](https://github.com/Triagle/hotkey-helper)

![rhkhm usage](showcase-rhkhm.gif)

# What this is
hkhelper is a python utility that parses `sxhkdhrc`-files for valid blocks of keybinds to create a documented list
associating the description, the keybinding and the action to execute. It can be used in conjunction with rofi/dmenu to have a fuzzy searchable cheatsheet of your configured keybinds.

This program was written using Python 3.8, but should work for 3.6 and greater.

# Installation
# AUR
```sh
sudo aura -A rhkhm-git
```

# PyPI
```sh
pip install --user rhkhm
```

# manual install from git repo
To set this up inside your `$SHELL` (make sure that `${HOME}/.local/bin/` is located somewhere within your `$PATH`, or alternatively specify a directory that is in your `$PATH` after -O: `wget [...] -O <directory>/hkhelper.py`):

```sh
$ mkdir -p ${HOME}/.local/bin/
$ wget https://raw.githubusercontent.com/fiskhest/rhkhm/master/rhkhm/__init__.py -O ${HOME}/.local/bin/hkhelper.py
```

You can also clone the repo and use the bundled install script:

```sh
$ cd /tmp/
$ git clone https://github.com/fiskhest/rhkhm/ && cd rhkhm/
$ make install

# or do what the makefile does manually:
$ python3 -m pip install -f requirements.txt
$ python3 setup.py install
```

# sxhkdrc setup
In order to use the program's functionality, you need to tweak your
`sxhkdrc` to include special comments designed as documentation for
keybindings.

The special syntax for these documentation comments is any line beginning with the value of the variable `descriptor`, which can
be defined with [`--descriptor`, `-d`] or the shell variable `export descriptor='# '`, defaulting to `# ` if none is defined. Set these comments up above every keybinding you wish to document.

```
# Example keybinding with documentation
# Quit bspwm
super + alt + Escape
    bspc quit

# This would show up in the formatted output as:
Quit bspwm                                        super + alt + Escape                              bspc quit
```

Additionally, `{}` can be used to unpack keychains mapping multiple segments of description to keybind and action.
**If the preceeding description does not contain any keychains, all unpacked lines will get the same description.**

```
# Example of segmented documentation
# Move the current window {left,down,up,right}
super + {h,j,k,l}
  bspc node -s {west,south,north,east}

# This would expand in output as:
Move the current window left                      super + h                                         bspc node -s west
Move the current window down                      super + j                                         bspc node -s south
Move the current window up                        super + k                                         bspc node -s north
Move the current window right                     super + l                                         bspc node -s east

# Example of a keychain containing a range
# Focus workspace {1-6,9}
super + {1-6,9}
    bspc desktop -f '^{1-6,9}'

# This would expand in output as:
Focus workspace 1                                 super + 1                                         bspc desktop -f '^1'
Focus workspace 2                                 super + 2                                         bspc desktop -f '^2'
Focus workspace 3                                 super + 3                                         bspc desktop -f '^3'
Focus workspace 4                                 super + 4                                         bspc desktop -f '^4'
Focus workspace 5                                 super + 5                                         bspc desktop -f '^5'
Focus workspace 6                                 super + 6                                         bspc desktop -f '^6'
Focus workspace 9                                 super + 6                                         bspc desktop -f '^6'
```

This allows for fast, compact documentation for keybindings of
arbitrary complexity.

# Usage
To use the program, run `hkhelper.py`. This will attempt to parse the configuration stored at the default location with the default descriptor, finally printing back to console (same as `--print`).

```
python hkhelper.py
```

Pass `--help` for a usage table:

```
usage: hkhelper.py [-h] [-f FILE] [-d DESCRIPTOR] [-e EXEC] [-p] [-m] [-r]

hotkey helper - standalone sxhkd configuration parser and keystroke runner

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  path to configuration file
  -d DESCRIPTOR, --descriptor DESCRIPTOR
                        comment descriptor
  -e EXEC, --exec EXEC  execute the passed shortcut
  -p, --print           Print fully unpacked keybind table
  -m, --markdown        Print fully unpacked keybind table in markdown format(for cheatsheets)
  -r, --raw             Print the raw configuration

```

By default, `hkhelper` will look for sxhkdrc in `~/.config/sxhkd/sxhkdrc`, but can be overridden by passing a path to the [`--file`, `-f`] argument or the shell variable `sxhkd_config=$CFGPATH/sxhkdrc`,

```sh
python hkhelper.py -f path/to/sxhkdrc
```

This will print an unpacked table of possible keybinds. passing [--exec,-e] instead executes the action defined for that keystroke (if one was found)

```
Split horizontal                                  super + period                                    bspc node -p east
Split vertical                                    super + minus                                     bspc node -p south
Split cancelation                                 super + comma                                     bspc node -p cancel
Preselect the ratio                               super + ctrl + 1                                  bspc node -o 0.1
Preselect the ratio                               super + ctrl + 2                                  bspc node -o 0.2
Preselect the ratio                               super + ctrl + 3                                  bspc node -o 0.3
Preselect the ratio                               super + ctrl + 4                                  bspc node -o 0.4
Preselect the ratio                               super + ctrl + 5                                  bspc node -o 0.5
Preselect the ratio                               super + ctrl + 6                                  bspc node -o 0.6
Preselect the ratio                               super + ctrl + 7                                  bspc node -o 0.7
Preselect the ratio                               super + ctrl + 8                                  bspc node -o 0.8
Preselect the ratio                               super + ctrl + 9                                  bspc node -o 0.9
Bspwm mode pseudotiled                            super + p                                         bspc node -t
Bspwm mode tiled                                  super + t                                         bspc node -t tiled
Set the node flags marked                         super + ctrl + m                                  bspc node -g marked
Set the node flags locked                         super + ctrl + x                                  bspc node -g locked
Set the node flags sticky                         super + ctrl + y                                  bspc node -g sticky
Set the node flags private                        super + ctrl + z                                  bspc node -g private
Move or swap node to the left (desktop/leaf)      super + shift + h                                 if ! bspc node -s west.local; then bspc node -d prev -f ; fi
Move or swap node to the right (desktop/leaf)     super + shift + l                                 if ! bspc node -s east.local; then bspc node -d next -f ; fi
```

The output is tabulated so that the columns descriptions are neatly aligned and easy to interpret.

This output can be piped to tools such as rofi or dmenu for further processing.

Doing this with a program like rofi allows for powerful searching of
hotkeys on the system.

By running `python hkhelper.py --exec`, you can execute a command associated with a keybinding. For instance, from
the above configuration `super + w` is bound to closing a window. Therefore, executing the following will close a window, as expected:

```sh
python hkhelper.py --exec "super + w"
```

By combining the `--print` flag, and the `--exec` flag, you can create a relatively
powerful system for discovery and remembering your keybindings by
having `hkhelper.py --exec` run the output of the hotkeys searching script from
earlier. A simple bash helper script `rhkhmenu` is bundled with this repo, essentially doing the following:

```sh
python hkhelper.py -e "$(python hkhelper.py -p | rofi -p Hotkeys -i -dmenu -width 75 | grep -Po '(?<=\s\s)(?=\S).*(?=\b\s\s)(?!$)')"
```

If you wish to use the bundled `rhkhmenu`, installation is as simple as:

```sh
# skip this if you used any installation method
$ wget https://raw.githubusercontent.com/fiskhest/rhkhm/master/rhkhmenu -O ${HOME}/.local/bin/rhkhmenu
```

create a bind in your sxhkd-configuration:
```sh
# Display keybind rofi menu
super + b
    rhkhmenu
    # if you installed manually by wgetting the files:
    # ${HOME}/.local/bin/rhkhmenu
```

# Print to markdown
An option to parse and print the result as markdown for exporting to cheatsheet/blogs/dev/null is available using the `[--markdown,-m]` argument. To try and categorise, and abusing the fact that most configurations of sxhkd are categorised (and /or formated) with comments, this function parses all keybinds and looks for the immediate-most related ancestor, iterating over the categories and prints back any keybinds related to that category. One may control how the parsing of ancestors is performed by passing `[--category_descriptor,-cd]` (default: `### `)

Example:
```sh
# original sxhkdrc
### -- BSPWM | Preselect -- ###

# Preselect {horizontal,vertical,cancel} split
super + {period,minus,comma}
    bspc node -p {east,south,cancel}

### -- System Control | Audio & Brightness -- ###

# {raise,lower} brightness
XF86MonBrightness{Up,Down}
    backlight{-up,-down}

----------------------------------

# unpacked example:
# BSPWM | Preselect
* `super + period`: Preselect horizontal split - `bspc node -p east`
* `super + minus`: Preselect vertical split - `bspc node -p south`
* `super + comma`: Preselect cancel split - `bspc node -p cancel`

# System Control | Audio & Brightness
* `XF86MonBrightnessUp`: raise brightness - `backlight-up`
* `XF86MonBrightnessDown`: lower brightness - `backlight-down`
```

# release workflow
run `make release VERSION=x.y.z`, trying to follow semver.

# misc
There are sure to be some bugs and use cases that wasn't foreseeable. PR's and issues are gladly appreciated!

Alternative: [dmenu-hotkey](https://github.com/maledorak/dmenu-hotkeys)

Todo:
- fix the horrible regex matching...
- cleaner readme/installation instructions



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/fiskhest/rhkhm",
    "name": "rhkhm",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "",
    "keywords": "",
    "author": "Johan Radivoj",
    "author_email": "johan+rhkhm@radivoj.se",
    "download_url": "https://files.pythonhosted.org/packages/3d/6f/166349da6b78d6a609a83e5776efdb9f0ad93f7c230462fd4e6a067be448/rhkhm-0.2.0.tar.gz",
    "platform": "",
    "description": "# HotKey Helper  - standalone sxhkd configuration parser and keybind runner\n\n[![.github/workflows/main.yml](https://github.com/fiskhest/rhkhm/workflows/.github/workflows/main.yml/badge.svg)](https://github.com/fiskhest/rhkhm/actions?query=workflow%3A.github%2Fworkflows%2Fmain.yml)\n[![AUR package](https://img.shields.io/aur/version/rhkhm-git)](https://aur.archlinux.org/packages/rhkhm-git/)\n[![AUR package](https://img.shields.io/pypi/v/rhkhm?color=green)](https://pypi.org/project/rhkhm/)\n\nrofi HotKey helper/menu -- Easily discover and execute sxhkd keybindings, inspired by [Hotkey-Helper](https://github.com/Triagle/hotkey-helper)\n\n![rhkhm usage](showcase-rhkhm.gif)\n\n# What this is\nhkhelper is a python utility that parses `sxhkdhrc`-files for valid blocks of keybinds to create a documented list\nassociating the description, the keybinding and the action to execute. It can be used in conjunction with rofi/dmenu to have a fuzzy searchable cheatsheet of your configured keybinds.\n\nThis program was written using Python 3.8, but should work for 3.6 and greater.\n\n# Installation\n# AUR\n```sh\nsudo aura -A rhkhm-git\n```\n\n# PyPI\n```sh\npip install --user rhkhm\n```\n\n# manual install from git repo\nTo set this up inside your `$SHELL` (make sure that `${HOME}/.local/bin/` is located somewhere within your `$PATH`, or alternatively specify a directory that is in your `$PATH` after -O: `wget [...] -O <directory>/hkhelper.py`):\n\n```sh\n$ mkdir -p ${HOME}/.local/bin/\n$ wget https://raw.githubusercontent.com/fiskhest/rhkhm/master/rhkhm/__init__.py -O ${HOME}/.local/bin/hkhelper.py\n```\n\nYou can also clone the repo and use the bundled install script:\n\n```sh\n$ cd /tmp/\n$ git clone https://github.com/fiskhest/rhkhm/ && cd rhkhm/\n$ make install\n\n# or do what the makefile does manually:\n$ python3 -m pip install -f requirements.txt\n$ python3 setup.py install\n```\n\n# sxhkdrc setup\nIn order to use the program's functionality, you need to tweak your\n`sxhkdrc` to include special comments designed as documentation for\nkeybindings.\n\nThe special syntax for these documentation comments is any line beginning with the value of the variable `descriptor`, which can\nbe defined with [`--descriptor`, `-d`] or the shell variable `export descriptor='# '`, defaulting to `# ` if none is defined. Set these comments up above every keybinding you wish to document.\n\n```\n# Example keybinding with documentation\n# Quit bspwm\nsuper + alt + Escape\n    bspc quit\n\n# This would show up in the formatted output as:\nQuit bspwm                                        super + alt + Escape                              bspc quit\n```\n\nAdditionally, `{}` can be used to unpack keychains mapping multiple segments of description to keybind and action.\n**If the preceeding description does not contain any keychains, all unpacked lines will get the same description.**\n\n```\n# Example of segmented documentation\n# Move the current window {left,down,up,right}\nsuper + {h,j,k,l}\n  bspc node -s {west,south,north,east}\n\n# This would expand in output as:\nMove the current window left                      super + h                                         bspc node -s west\nMove the current window down                      super + j                                         bspc node -s south\nMove the current window up                        super + k                                         bspc node -s north\nMove the current window right                     super + l                                         bspc node -s east\n\n# Example of a keychain containing a range\n# Focus workspace {1-6,9}\nsuper + {1-6,9}\n    bspc desktop -f '^{1-6,9}'\n\n# This would expand in output as:\nFocus workspace 1                                 super + 1                                         bspc desktop -f '^1'\nFocus workspace 2                                 super + 2                                         bspc desktop -f '^2'\nFocus workspace 3                                 super + 3                                         bspc desktop -f '^3'\nFocus workspace 4                                 super + 4                                         bspc desktop -f '^4'\nFocus workspace 5                                 super + 5                                         bspc desktop -f '^5'\nFocus workspace 6                                 super + 6                                         bspc desktop -f '^6'\nFocus workspace 9                                 super + 6                                         bspc desktop -f '^6'\n```\n\nThis allows for fast, compact documentation for keybindings of\narbitrary complexity.\n\n# Usage\nTo use the program, run `hkhelper.py`. This will attempt to parse the configuration stored at the default location with the default descriptor, finally printing back to console (same as `--print`).\n\n```\npython hkhelper.py\n```\n\nPass `--help` for a usage table:\n\n```\nusage: hkhelper.py [-h] [-f FILE] [-d DESCRIPTOR] [-e EXEC] [-p] [-m] [-r]\n\nhotkey helper - standalone sxhkd configuration parser and keystroke runner\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -f FILE, --file FILE  path to configuration file\n  -d DESCRIPTOR, --descriptor DESCRIPTOR\n                        comment descriptor\n  -e EXEC, --exec EXEC  execute the passed shortcut\n  -p, --print           Print fully unpacked keybind table\n  -m, --markdown        Print fully unpacked keybind table in markdown format(for cheatsheets)\n  -r, --raw             Print the raw configuration\n\n```\n\nBy default, `hkhelper` will look for sxhkdrc in `~/.config/sxhkd/sxhkdrc`, but can be overridden by passing a path to the [`--file`, `-f`] argument or the shell variable `sxhkd_config=$CFGPATH/sxhkdrc`,\n\n```sh\npython hkhelper.py -f path/to/sxhkdrc\n```\n\nThis will print an unpacked table of possible keybinds. passing [--exec,-e] instead executes the action defined for that keystroke (if one was found)\n\n```\nSplit horizontal                                  super + period                                    bspc node -p east\nSplit vertical                                    super + minus                                     bspc node -p south\nSplit cancelation                                 super + comma                                     bspc node -p cancel\nPreselect the ratio                               super + ctrl + 1                                  bspc node -o 0.1\nPreselect the ratio                               super + ctrl + 2                                  bspc node -o 0.2\nPreselect the ratio                               super + ctrl + 3                                  bspc node -o 0.3\nPreselect the ratio                               super + ctrl + 4                                  bspc node -o 0.4\nPreselect the ratio                               super + ctrl + 5                                  bspc node -o 0.5\nPreselect the ratio                               super + ctrl + 6                                  bspc node -o 0.6\nPreselect the ratio                               super + ctrl + 7                                  bspc node -o 0.7\nPreselect the ratio                               super + ctrl + 8                                  bspc node -o 0.8\nPreselect the ratio                               super + ctrl + 9                                  bspc node -o 0.9\nBspwm mode pseudotiled                            super + p                                         bspc node -t\nBspwm mode tiled                                  super + t                                         bspc node -t tiled\nSet the node flags marked                         super + ctrl + m                                  bspc node -g marked\nSet the node flags locked                         super + ctrl + x                                  bspc node -g locked\nSet the node flags sticky                         super + ctrl + y                                  bspc node -g sticky\nSet the node flags private                        super + ctrl + z                                  bspc node -g private\nMove or swap node to the left (desktop/leaf)      super + shift + h                                 if ! bspc node -s west.local; then bspc node -d prev -f ; fi\nMove or swap node to the right (desktop/leaf)     super + shift + l                                 if ! bspc node -s east.local; then bspc node -d next -f ; fi\n```\n\nThe output is tabulated so that the columns descriptions are neatly aligned and easy to interpret.\n\nThis output can be piped to tools such as rofi or dmenu for further processing.\n\nDoing this with a program like rofi allows for powerful searching of\nhotkeys on the system.\n\nBy running `python hkhelper.py --exec`, you can execute a command associated with a keybinding. For instance, from\nthe above configuration `super + w` is bound to closing a window. Therefore, executing the following will close a window, as expected:\n\n```sh\npython hkhelper.py --exec \"super + w\"\n```\n\nBy combining the `--print` flag, and the `--exec` flag, you can create a relatively\npowerful system for discovery and remembering your keybindings by\nhaving `hkhelper.py --exec` run the output of the hotkeys searching script from\nearlier. A simple bash helper script `rhkhmenu` is bundled with this repo, essentially doing the following:\n\n```sh\npython hkhelper.py -e \"$(python hkhelper.py -p | rofi -p Hotkeys -i -dmenu -width 75 | grep -Po '(?<=\\s\\s)(?=\\S).*(?=\\b\\s\\s)(?!$)')\"\n```\n\nIf you wish to use the bundled `rhkhmenu`, installation is as simple as:\n\n```sh\n# skip this if you used any installation method\n$ wget https://raw.githubusercontent.com/fiskhest/rhkhm/master/rhkhmenu -O ${HOME}/.local/bin/rhkhmenu\n```\n\ncreate a bind in your sxhkd-configuration:\n```sh\n# Display keybind rofi menu\nsuper + b\n    rhkhmenu\n    # if you installed manually by wgetting the files:\n    # ${HOME}/.local/bin/rhkhmenu\n```\n\n# Print to markdown\nAn option to parse and print the result as markdown for exporting to cheatsheet/blogs/dev/null is available using the `[--markdown,-m]` argument. To try and categorise, and abusing the fact that most configurations of sxhkd are categorised (and /or formated) with comments, this function parses all keybinds and looks for the immediate-most related ancestor, iterating over the categories and prints back any keybinds related to that category. One may control how the parsing of ancestors is performed by passing `[--category_descriptor,-cd]` (default: `### `)\n\nExample:\n```sh\n# original sxhkdrc\n### -- BSPWM | Preselect -- ###\n\n# Preselect {horizontal,vertical,cancel} split\nsuper + {period,minus,comma}\n    bspc node -p {east,south,cancel}\n\n### -- System Control | Audio & Brightness -- ###\n\n# {raise,lower} brightness\nXF86MonBrightness{Up,Down}\n    backlight{-up,-down}\n\n----------------------------------\n\n# unpacked example:\n# BSPWM | Preselect\n* `super + period`: Preselect horizontal split - `bspc node -p east`\n* `super + minus`: Preselect vertical split - `bspc node -p south`\n* `super + comma`: Preselect cancel split - `bspc node -p cancel`\n\n# System Control | Audio & Brightness\n* `XF86MonBrightnessUp`: raise brightness - `backlight-up`\n* `XF86MonBrightnessDown`: lower brightness - `backlight-down`\n```\n\n# release workflow\nrun `make release VERSION=x.y.z`, trying to follow semver.\n\n# misc\nThere are sure to be some bugs and use cases that wasn't foreseeable. PR's and issues are gladly appreciated!\n\nAlternative: [dmenu-hotkey](https://github.com/maledorak/dmenu-hotkeys)\n\nTodo:\n- fix the horrible regex matching...\n- cleaner readme/installation instructions\n\n\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "HotKey helper for sxhkd",
    "version": "0.2.0",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "12956fadc9741d06dd796fa050f61ceb",
                "sha256": "53ebf1ea30c047b3a9932dbc8f0b2f5a33e3e0ef7dfac391019490c44d314264"
            },
            "downloads": -1,
            "filename": "rhkhm-0.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "12956fadc9741d06dd796fa050f61ceb",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 11001,
            "upload_time": "2020-08-23T20:20:09",
            "upload_time_iso_8601": "2020-08-23T20:20:09.257430Z",
            "url": "https://files.pythonhosted.org/packages/00/c0/aa58d42cd4052d7d70cf944a8dc6fec49b8ca056029fd24ac1d9b7109c9d/rhkhm-0.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "f8acdabd6655f0f7af4d0959d0c02fda",
                "sha256": "1529421546f0ed9dea4d1c58b3b5f48499c8b869abe18f3230a7e40c88f9b1d2"
            },
            "downloads": -1,
            "filename": "rhkhm-0.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "f8acdabd6655f0f7af4d0959d0c02fda",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 11256,
            "upload_time": "2020-08-23T20:20:10",
            "upload_time_iso_8601": "2020-08-23T20:20:10.455114Z",
            "url": "https://files.pythonhosted.org/packages/3d/6f/166349da6b78d6a609a83e5776efdb9f0ad93f7c230462fd4e6a067be448/rhkhm-0.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-08-23 20:20:10",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "fiskhest",
    "error": "Could not fetch GitHub repository",
    "lcname": "rhkhm"
}
        
Elapsed time: 0.13990s