# PyHotKey
PyHotKey is a **cross-platform** hotkey module for Python. Based on "pynput".
## Usage
***Note***: To get the best experience of this module, you must run your application with the highest privileges.
- Windows: run your application as administrator.
- Linux: run your application as root or use "sudo" command to launch your application.
- Mac OS: same as Linux or whitelist your application: open "System Preferences -> Security & Privacy -> Privacy -> Accessibility (on the left)", click the lock to make changes (at the bottom), check your application on the right.
### Install
```
pip install PyHotKey
```
### Import:
```python
from PyHotKey import Key, keyboard_manager as manager
```
### Register hotkey:
```python
# Register a hotkey (multiple keys)
id1 = manager.register_hotkey([Key.ctrl_l, Key.alt_l, 'z'], None,
func, func_arg1, func_arg2=1)
if -1 == id1:
print('Already registered!')
elif 0 == id1:
print('Invalid parameters!')
else:
print('Hotkey id: {}'.format(id1))
# Register a hotkey (single key)
# 2 means tap twice to trigger the hotkey
id2 = manager.register_hotkey([Key.caps_lock], 2, func,
func_arg1, func_arg2, func_arg3=3)
# Unregister hotkey by key list
r1 = manager.unregister_hotkey_by_keys([Key.ctrl_l, Key.alt_l, 'z'])
# Unregister hotkey by hotkey id
r2 = manager.unregister_hotkey_by_id(id2)
# Unregister all hotkeys
r3 = manager.unregister_all_hotkeys()
```
### Record hotkey:
```python
# The callback function for recording hotkey
# You can use "key_list" to register hotkey later
def callback(key_list):
print(key_list)
# Start recording a hotkey with multiple keys
manager.start_recording_hotkey_multiple(callback)
# Start recording a hotkey with single key
manager.start_recording_hotkey_single(callback)
# Stop recording hotkey
manager.stop_recording()
```
***PS***: Check the example on [GitHub](https://github.com/Xpp521/PyHotKey/tree/master/examples) for details.
### Wetkey
Do something when a single key is pressed or released, I call it "Wetkey".
```python
def func(key, pressed):
print('{} is {}'.format(key, 'pressed' if pressed else 'released'))
# Set a wetkey to trigger when "ctrl" is pressed
r1 = manager.set_wetkey_on_press(Key.ctrl_l, func, 'ctrl', 1)
# Set a wetkey to trigger when "x" is released
r2 = manager.set_wetkey_on_release('x', func, 'x', 0)
# Remove the wetkey triggered when x is pressed
r3 = manager.remove_wetkey_on_press('x')
# Remove all wetkeys
r4 = manager.remove_all_wetkeys()
```
### Control keyboard
```python
# Press
manager.press(Key.space)
# Release
manager.release('z')
# Tap (press and release)
manager.tap('x')
# Do something while holding down certain keys
with manager.pressed(Key.ctrl, Key.shift) as r:
if r:
do_something()
# Type a string
manager.type('Xpp521')
```
***PS***: If you're recording hotkey, these apis won't work.
### Other APIs
```python
# Print all hotkeys
print(manager.hotkeys)
# Print all wetkeys
print(manager.wetkeys)
# Print the currently pressed keys
print(manager.pressed_keys)
# Check whether a key is pressed
if 'z' in manager.pressed_keys:
print("'z' is pressed")
# Print recording state
print(manager.recording)
# Suppress the last key after triggering a hotkey
# With this api, you can even override the function of system hotkeys
# PS: doesn't work in Linux
manager.suppress = True
# Strict mode (for hotkeys with multiple keys)
# The pressed keys must be strictly equal to
# the hotkey's key list
manager.strict_mode = False
# ttl: time to live (for hotkeys with multiple keys)
# When a key is pressed for more than ttl seconds,
# it will be removed from the currently pressed keys
# in the next key press/release event.
manager.ttl = 7
# Interval: the max interval time between each tap
# (for hotkeys with single key)
manager.interval = 0.5
```
### Keyboard Listener
```python
# Print keyboard listener's running state
print(manager.running)
# Stop keyboard listener
# When stopped, hotkey and wetkey related functions won't work
manager.stop()
# Start keyboard listener
# You can restart the listener after stopping it
manager.start()
```
***PS***: Generally, you may not use these apis.
### Logger:
```python
# Turn on the logger
manager.logger = True
# Set a file for logging ("append" mode)
manager.set_log_file('Loggggggg.log', 'a')
```
## TODO:
- [ ] ~~Detect conflicts with system hotkeys~~ No longer needed
- [x] Suppress the last key after triggering a hotkey
- [x] ~~Support to trigger hotkeys on press or on release~~ Use wetkey instead
# Release Note
## v1.5.0
- [+] Wetkey: triggered when a single key is pressed or released.
- [+] Suppress: Suppress the last key after triggering a hotkey.
___
## v1.4.1
- Add api: "unregister_all_hotkeys".
- Change the parameter order of "register_hotkey".
- Now you can use "pressed_keys" to check whether a key is pressed.
___
## v1.4.0 - 2022 Reborn
After 3 years I'm back with the new "PyHotKey".
Changes:
- Fixed a lot of bugs.
- Now you can record hotkey and control keyboard.
- Real cross platform this time.
- And more convenient apis...
Check "README.md".
___
## v1.3.3
#### Bug Fixes
- Combination hot key: Fix the keystroke value error of combination hot key.
#### Refactor
- Simplify README.md.
___
## v1.3.2
#### Bug Fixes
- Log path: fix the default log path overwrites the custom log path when setting "manager.logger = True".
#### Refactor
- Adjust code structure.
- Rewrite README.md.
___
## v1.3.1
- Delete a deprecated class.
- Replace root logger with a separate logger.
- Rename property "hot_keys" to "hotKeyList".
- Change documents and some code comments.
___
## v1.3.0
- Currently, users can customize the log path.
- Optimize code.
___
## v1.2.0
- Add logger.
- Optimize code.
- Attempt to fix a potential bug.
___
## v1.1.1
- Remove log message.
___
## v1.1.0
- Currently, the trigger function supports arguments.
- No longer need to call manager.start() manually.
- Fix multiple type hot key bug.
___
## v1.0
- The first version.
Raw data
{
"_id": null,
"home_page": "https://github.com/Xpp521/PyHotKey",
"name": "PyHotKey",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "hotkey,keyboard,hot+key",
"author": "Xpp",
"author_email": "xpp233@foxmail.com",
"download_url": "https://files.pythonhosted.org/packages/c3/c1/233a8b9bf97b2eaf4e7ebd4b26bcd724cd9dfc1fa6266cde922d915dc575/PyHotKey-1.5.0.tar.gz",
"platform": null,
"description": "# PyHotKey\r\nPyHotKey is a **cross-platform** hotkey module for Python. Based on \"pynput\".\r\n\r\n## Usage\r\n***Note***: To get the best experience of this module, you must run your application with the highest privileges.\r\n- Windows: run your application as administrator.\r\n- Linux: run your application as root or use \"sudo\" command to launch your application.\r\n- Mac OS: same as Linux or whitelist your application: open \"System Preferences -> Security & Privacy -> Privacy -> Accessibility (on the left)\", click the lock to make changes (at the bottom), check your application on the right.\r\n\r\n### Install\r\n```\r\npip install PyHotKey\r\n```\r\n\r\n### Import:\r\n```python\r\nfrom PyHotKey import Key, keyboard_manager as manager\r\n```\r\n\r\n### Register hotkey:\r\n```python\r\n# Register a hotkey (multiple keys)\r\nid1 = manager.register_hotkey([Key.ctrl_l, Key.alt_l, 'z'], None,\r\n func, func_arg1, func_arg2=1)\r\n\r\nif -1 == id1:\r\n print('Already registered!')\r\nelif 0 == id1:\r\n print('Invalid parameters!')\r\nelse:\r\n print('Hotkey id: {}'.format(id1))\r\n\r\n# Register a hotkey (single key)\r\n# 2 means tap twice to trigger the hotkey\r\nid2 = manager.register_hotkey([Key.caps_lock], 2, func,\r\n func_arg1, func_arg2, func_arg3=3)\r\n\r\n# Unregister hotkey by key list\r\nr1 = manager.unregister_hotkey_by_keys([Key.ctrl_l, Key.alt_l, 'z'])\r\n\r\n# Unregister hotkey by hotkey id\r\nr2 = manager.unregister_hotkey_by_id(id2)\r\n\r\n# Unregister all hotkeys\r\nr3 = manager.unregister_all_hotkeys()\r\n```\r\n\r\n### Record hotkey:\r\n```python\r\n# The callback function for recording hotkey\r\n# You can use \"key_list\" to register hotkey later\r\ndef callback(key_list):\r\n print(key_list)\r\n\r\n# Start recording a hotkey with multiple keys\r\nmanager.start_recording_hotkey_multiple(callback)\r\n\r\n# Start recording a hotkey with single key\r\nmanager.start_recording_hotkey_single(callback)\r\n\r\n# Stop recording hotkey\r\nmanager.stop_recording()\r\n```\r\n***PS***: Check the example on [GitHub](https://github.com/Xpp521/PyHotKey/tree/master/examples) for details.\r\n\r\n### Wetkey\r\nDo something when a single key is pressed or released, I call it \"Wetkey\".\r\n```python\r\ndef func(key, pressed):\r\n print('{} is {}'.format(key, 'pressed' if pressed else 'released'))\r\n\r\n# Set a wetkey to trigger when \"ctrl\" is pressed\r\nr1 = manager.set_wetkey_on_press(Key.ctrl_l, func, 'ctrl', 1)\r\n\r\n# Set a wetkey to trigger when \"x\" is released\r\nr2 = manager.set_wetkey_on_release('x', func, 'x', 0)\r\n\r\n# Remove the wetkey triggered when x is pressed\r\nr3 = manager.remove_wetkey_on_press('x')\r\n\r\n# Remove all wetkeys\r\nr4 = manager.remove_all_wetkeys()\r\n```\r\n\r\n### Control keyboard\r\n```python\r\n# Press\r\nmanager.press(Key.space)\r\n\r\n# Release\r\nmanager.release('z')\r\n\r\n# Tap (press and release)\r\nmanager.tap('x')\r\n\r\n# Do something while holding down certain keys\r\nwith manager.pressed(Key.ctrl, Key.shift) as r:\r\n if r:\r\n do_something()\r\n\r\n# Type a string\r\nmanager.type('Xpp521')\r\n```\r\n***PS***: If you're recording hotkey, these apis won't work.\r\n\r\n### Other APIs\r\n```python\r\n# Print all hotkeys\r\nprint(manager.hotkeys)\r\n\r\n# Print all wetkeys\r\nprint(manager.wetkeys)\r\n\r\n# Print the currently pressed keys\r\nprint(manager.pressed_keys)\r\n\r\n# Check whether a key is pressed\r\nif 'z' in manager.pressed_keys:\r\n print(\"'z' is pressed\")\r\n\r\n# Print recording state\r\nprint(manager.recording)\r\n\r\n# Suppress the last key after triggering a hotkey\r\n# With this api, you can even override the function of system hotkeys\r\n# PS: doesn't work in Linux\r\nmanager.suppress = True\r\n\r\n# Strict mode (for hotkeys with multiple keys)\r\n# The pressed keys must be strictly equal to\r\n# the hotkey's key list\r\nmanager.strict_mode = False\r\n\r\n# ttl: time to live (for hotkeys with multiple keys)\r\n# When a key is pressed for more than ttl seconds,\r\n# it will be removed from the currently pressed keys\r\n# in the next key press/release event.\r\nmanager.ttl = 7\r\n\r\n# Interval: the max interval time between each tap\r\n# (for hotkeys with single key)\r\nmanager.interval = 0.5\r\n```\r\n\r\n### Keyboard Listener\r\n```python\r\n# Print keyboard listener's running state\r\nprint(manager.running)\r\n\r\n# Stop keyboard listener\r\n# When stopped, hotkey and wetkey related functions won't work\r\nmanager.stop()\r\n\r\n# Start keyboard listener\r\n# You can restart the listener after stopping it\r\nmanager.start()\r\n```\r\n***PS***: Generally, you may not use these apis.\r\n\r\n### Logger:\r\n```python\r\n# Turn on the logger\r\nmanager.logger = True\r\n\r\n# Set a file for logging (\"append\" mode)\r\nmanager.set_log_file('Loggggggg.log', 'a')\r\n```\r\n\r\n## TODO:\r\n- [ ] ~~Detect conflicts with system hotkeys~~ No longer needed\r\n- [x] Suppress the last key after triggering a hotkey\r\n- [x] ~~Support to trigger hotkeys on press or on release~~ Use wetkey instead\r\n# Release Note\r\n## v1.5.0\r\n- [+] Wetkey: triggered when a single key is pressed or released.\r\n- [+] Suppress: Suppress the last key after triggering a hotkey.\r\n___\r\n## v1.4.1\r\n- Add api: \"unregister_all_hotkeys\".\r\n- Change the parameter order of \"register_hotkey\".\r\n- Now you can use \"pressed_keys\" to check whether a key is pressed.\r\n___\r\n## v1.4.0 - 2022 Reborn\r\nAfter 3 years I'm back with the new \"PyHotKey\".\r\n\r\nChanges:\r\n- Fixed a lot of bugs.\r\n- Now you can record hotkey and control keyboard.\r\n- Real cross platform this time.\r\n- And more convenient apis...\r\n\r\nCheck \"README.md\".\r\n___\r\n## v1.3.3\r\n#### Bug Fixes\r\n- Combination hot key: Fix the keystroke value error of combination hot key.\r\n#### Refactor\r\n- Simplify README.md.\r\n___\r\n## v1.3.2\r\n#### Bug Fixes\r\n- Log path: fix the default log path overwrites the custom log path when setting \"manager.logger = True\".\r\n#### Refactor\r\n- Adjust code structure.\r\n- Rewrite README.md.\r\n___\r\n## v1.3.1\r\n- Delete a deprecated class.\r\n- Replace root logger with a separate logger.\r\n- Rename property \"hot_keys\" to \"hotKeyList\".\r\n- Change documents and some code comments.\r\n___\r\n## v1.3.0\r\n- Currently, users can customize the log path.\r\n- Optimize code.\r\n___\r\n## v1.2.0\r\n- Add logger.\r\n- Optimize code.\r\n- Attempt to fix a potential bug.\r\n___\r\n## v1.1.1\r\n- Remove log message.\r\n___\r\n## v1.1.0\r\n- Currently, the trigger function supports arguments.\r\n- No longer need to call manager.start() manually.\r\n- Fix multiple type hot key bug.\r\n___\r\n## v1.0\r\n- The first version.\r\n\r\n",
"bugtrack_url": null,
"license": "LGPLv3",
"summary": "A cross-platform hotkey module.",
"version": "1.5.0",
"split_keywords": [
"hotkey",
"keyboard",
"hot+key"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "ffb9444a80c01d7d9e5ee4a85d6aba77",
"sha256": "6ef5a38298df85f84fde6ad3277bd207fba635dea3547185afbcbb91ef9755b1"
},
"downloads": -1,
"filename": "PyHotKey-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ffb9444a80c01d7d9e5ee4a85d6aba77",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18371,
"upload_time": "2022-12-21T12:56:41",
"upload_time_iso_8601": "2022-12-21T12:56:41.152072Z",
"url": "https://files.pythonhosted.org/packages/ea/53/5a972431419bf74ef7872503e00c649a4913bec61c8905f258565d7975fe/PyHotKey-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "ae9c17e6205f6ec8c2f2fd607aa910e1",
"sha256": "a502b4d127d652ea089d39c447e313cf895cdc08fbafdf21a2cbc1d3cb0ff4a1"
},
"downloads": -1,
"filename": "PyHotKey-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "ae9c17e6205f6ec8c2f2fd607aa910e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16831,
"upload_time": "2022-12-21T12:56:42",
"upload_time_iso_8601": "2022-12-21T12:56:42.789542Z",
"url": "https://files.pythonhosted.org/packages/c3/c1/233a8b9bf97b2eaf4e7ebd4b26bcd724cd9dfc1fa6266cde922d915dc575/PyHotKey-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-21 12:56:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Xpp521",
"github_project": "PyHotKey",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyhotkey"
}
JSON
