# PyHotKey
PyHotKey is a **cross-platform** keyboard module for Python. Based on "pynput".
Features:
- Control keyboard.
- Record and register hotkey.
- "MagicKey".
- Record keyboard history.
## ***! Attention !***
To activate all functions of this module, such as suppress hotkeys and interact with the task manager (Windows)...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
```
## Usage
### Import:
```python
from PyHotKey import Key, keyboard
```
### Control keyboard
```python
# Press
keyboard.press(Key.space)
# Release
keyboard.release('z')
# Tap (on_press and release)
keyboard.tap('x')
# Do something while holding down certain keys
with keyboard.pressed(Key.ctrl, Key.shift):
do_something()
# Type a string
keyboard.type('Xpp521')
```
***PS***: If you're recording hotkey, these apis won't work.
### Hotkey:
```python
# Register a hotkey (multiple keys)
id1 = keyboard.register_hotkey([Key.ctrl_l, Key.alt_l, 'z'], None,
func, func_arg1, func_arg2=1)
if id1 == -1:
print('Already registered!')
elif id1 == 0:
print('Invalid parameters!')
else:
print('Hotkey id: {}'.format(id1))
# Register a hotkey (single key)
# 3 means tap three times to trigger the hotkey (must >= 2)
id2 = keyboard.register_hotkey([Key.caps_lock], 3, func,
func_arg1, func_arg2, func_arg3=233)
# Unregister hotkey by keys
r1 = keyboard.unregister_hotkey_by_keys([Key.ctrl_l, Key.alt_l, 'z'])
r2 = keyboard.unregister_hotkey_by_keys([Key.caps_lock], 2)
# Unregister hotkey by hotkey id
r3 = keyboard.unregister_hotkey_by_id(id2)
# Unregister all hotkeys
keyboard.unregister_all_hotkeys()
# Print all hotkeys
print(keyboard.hotkeys)
# Suppress the last key after triggering a hotkey
# With this api, you can even override system hotkeys
# PS1: Require the highest privileges
# PS2: Currently doesn't work in Linux
keyboard.suppress_hotkey = True
# ttl: time to live (for hotkeys with multiple keys)
# When a key is pressed for more than "ttl" seconds,
# it will be ignored in the next key on_press/release event.
keyboard.ttl = 7
# Interval: the max interval time between each tap
# (for hotkeys with single key)
keyboard.interval = 0.5
```
### Record hotkey:
```python
# The callback function for recording hotkey
# Use "key_list" to register hotkey later
def callback(key_list):
print(key_list)
# Start recording a hotkey (multiple keys)
keyboard.start_recording_hotkey_multiple(callback)
# Start recording a hotkey (single key)
keyboard.start_recording_hotkey_single(callback)
# Stop recording hotkey
keyboard.stop_recording_hotkey()
# Print recording state
print(keyboard.recording_state)
```
***PS***: Check the example: [Recording.py](https://github.com/Xpp521/PyHotKey/tree/master/examples).
### MagicKey
MagicKey can change the behaviour of a single key:
- trigger functions for pressed and released event.
- Suppress the original function.
```python
# Set a magickey to trigger when "ctrl" is pressed (suppress)
r1 = keyboard.set_magickey_on_press(Key.ctrl_l, func,
func_arg1, func_arg2=233)
# Set a magickey to trigger when "x" is released (don't suppress)
r2 = keyboard.set_magickey_on_release('x', func,
func_arg1, func_arg2='Xpp')
# Remove the magickey triggered when x is pressed
r3 = keyboard.remove_magickey_on_press('x')
# Remove the magickey triggered when x is pressed or released
r3 = keyboard.remove_magickey('x')
# Remove all magickeys
r5 = keyboard.remove_all_magickeys()
# Print all magickeys
print(keyboard.magickeys)
# Suppress the single key after triggering a magickey
# Use this api to change the function of a single key
# PS1: Require the highest privileges
# PS2: Currently doesn't work in Linux
# PS3: May cause unknown bugs, be careful
keybord.suppress_magickey = True
```
***PS***: Check the example: [magickey.py](https://github.com/Xpp521/PyHotKey/tree/master/examples).
### Other APIs
```python
# Print the currently pressed keys
print(keyboard.pressed_keys)
# Check whether a key is pressed
if 'z' in keyboard.pressed_keys:
print("'z' is pressed")
```
### Toggle Listener
```python
# Print keyboard listener's running state
print(keyboard.listener_running)
# Stop keyboard listener
# When stopped, hotkey and magickey related functions won't work
keyboard.stop_listener()
# Start keyboard listener
# You can restart the listener after stopping it
keyboard.start_listener()
```
***PS***: Generally, you may not use these apis.
### Logger:
There is a classic logger by default, you can also set a custom logger.
```python
# Turn on the logger
keyboard.toggle_logger(1)
# Get the current logger
logger = keyboard.logger
# Add a file handler to the default logger
from logging import FileHandler
keyboard.logger.addHandler(FileHandler('Keyboard History.txt', 'a', 'utf-8'))
# Set a custom logger
# PS: The custom logger must have the following method:
# 'trace', 'debug', 'info', 'success', 'log',
# 'warning', 'error', 'critical', 'exception'
from loguru import logger
r = keyboard.set_logger(logger)
```
# Release Note
## v1.5.2
- [Fix] some hotkey can't be recorded.
- [Change] Hotkeys with single keystroke won't be triggered if the tapping is interrupted.
- [Change] Rename several apis.
- [Change] Rebuild logging function.
- [Remove] "strict mode".
___
## 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": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "hotkey, keyboard, hot+key",
"author": "Xpp",
"author_email": "xpp233@foxmail.com",
"download_url": "https://files.pythonhosted.org/packages/5d/0b/f61560ed6cb554b5973b1902419adf616ed678781e40d7c0de2f4600593f/PyHotKey-1.5.2.tar.gz",
"platform": null,
"description": "# PyHotKey\r\nPyHotKey is a **cross-platform** keyboard module for Python. Based on \"pynput\".\r\n\r\nFeatures:\r\n- Control keyboard.\r\n- Record and register hotkey.\r\n- \"MagicKey\".\r\n- Record keyboard history.\r\n\r\n## ***! Attention !***\r\nTo activate all functions of this module, such as suppress hotkeys and interact with the task manager (Windows)...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## Usage\r\n### Import:\r\n```python\r\nfrom PyHotKey import Key, keyboard\r\n```\r\n\r\n### Control keyboard\r\n```python\r\n# Press\r\nkeyboard.press(Key.space)\r\n\r\n# Release\r\nkeyboard.release('z')\r\n\r\n# Tap (on_press and release)\r\nkeyboard.tap('x')\r\n\r\n# Do something while holding down certain keys\r\nwith keyboard.pressed(Key.ctrl, Key.shift):\r\n do_something()\r\n\r\n# Type a string\r\nkeyboard.type('Xpp521')\r\n```\r\n***PS***: If you're recording hotkey, these apis won't work.\r\n\r\n### Hotkey:\r\n```python\r\n# Register a hotkey (multiple keys)\r\nid1 = keyboard.register_hotkey([Key.ctrl_l, Key.alt_l, 'z'], None,\r\n func, func_arg1, func_arg2=1)\r\n\r\nif id1 == -1:\r\n print('Already registered!')\r\nelif id1 == 0:\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# 3 means tap three times to trigger the hotkey (must >= 2)\r\nid2 = keyboard.register_hotkey([Key.caps_lock], 3, func,\r\n func_arg1, func_arg2, func_arg3=233)\r\n\r\n# Unregister hotkey by keys\r\nr1 = keyboard.unregister_hotkey_by_keys([Key.ctrl_l, Key.alt_l, 'z'])\r\nr2 = keyboard.unregister_hotkey_by_keys([Key.caps_lock], 2)\r\n\r\n# Unregister hotkey by hotkey id\r\nr3 = keyboard.unregister_hotkey_by_id(id2)\r\n\r\n# Unregister all hotkeys\r\nkeyboard.unregister_all_hotkeys()\r\n\r\n# Print all hotkeys\r\nprint(keyboard.hotkeys)\r\n\r\n# Suppress the last key after triggering a hotkey\r\n# With this api, you can even override system hotkeys\r\n# PS1: Require the highest privileges\r\n# PS2: Currently doesn't work in Linux\r\nkeyboard.suppress_hotkey = True\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 ignored in the next key on_press/release event.\r\nkeyboard.ttl = 7\r\n\r\n# Interval: the max interval time between each tap\r\n# (for hotkeys with single key)\r\nkeyboard.interval = 0.5\r\n```\r\n\r\n### Record hotkey:\r\n```python\r\n# The callback function for recording hotkey\r\n# 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 (multiple keys)\r\nkeyboard.start_recording_hotkey_multiple(callback)\r\n\r\n# Start recording a hotkey (single key)\r\nkeyboard.start_recording_hotkey_single(callback)\r\n\r\n# Stop recording hotkey\r\nkeyboard.stop_recording_hotkey()\r\n\r\n# Print recording state\r\nprint(keyboard.recording_state)\r\n```\r\n***PS***: Check the example: [Recording.py](https://github.com/Xpp521/PyHotKey/tree/master/examples).\r\n\r\n### MagicKey\r\nMagicKey can change the behaviour of a single key:\r\n- trigger functions for pressed and released event.\r\n- Suppress the original function.\r\n```python\r\n# Set a magickey to trigger when \"ctrl\" is pressed (suppress)\r\nr1 = keyboard.set_magickey_on_press(Key.ctrl_l, func,\r\n func_arg1, func_arg2=233)\r\n\r\n# Set a magickey to trigger when \"x\" is released (don't suppress)\r\nr2 = keyboard.set_magickey_on_release('x', func,\r\n func_arg1, func_arg2='Xpp')\r\n\r\n# Remove the magickey triggered when x is pressed\r\nr3 = keyboard.remove_magickey_on_press('x')\r\n\r\n# Remove the magickey triggered when x is pressed or released\r\nr3 = keyboard.remove_magickey('x')\r\n\r\n# Remove all magickeys\r\nr5 = keyboard.remove_all_magickeys()\r\n\r\n# Print all magickeys\r\nprint(keyboard.magickeys)\r\n\r\n# Suppress the single key after triggering a magickey\r\n# Use this api to change the function of a single key\r\n# PS1: Require the highest privileges\r\n# PS2: Currently doesn't work in Linux\r\n# PS3: May cause unknown bugs, be careful\r\nkeybord.suppress_magickey = True\r\n```\r\n***PS***: Check the example: [magickey.py](https://github.com/Xpp521/PyHotKey/tree/master/examples).\r\n\r\n### Other APIs\r\n```python\r\n# Print the currently pressed keys\r\nprint(keyboard.pressed_keys)\r\n\r\n# Check whether a key is pressed\r\nif 'z' in keyboard.pressed_keys:\r\n print(\"'z' is pressed\")\r\n```\r\n\r\n### Toggle Listener\r\n```python\r\n# Print keyboard listener's running state\r\nprint(keyboard.listener_running)\r\n\r\n# Stop keyboard listener\r\n# When stopped, hotkey and magickey related functions won't work\r\nkeyboard.stop_listener()\r\n\r\n# Start keyboard listener\r\n# You can restart the listener after stopping it\r\nkeyboard.start_listener()\r\n```\r\n***PS***: Generally, you may not use these apis.\r\n\r\n### Logger:\r\nThere is a classic logger by default, you can also set a custom logger.\r\n```python\r\n# Turn on the logger\r\nkeyboard.toggle_logger(1)\r\n\r\n# Get the current logger\r\nlogger = keyboard.logger\r\n\r\n# Add a file handler to the default logger\r\nfrom logging import FileHandler\r\nkeyboard.logger.addHandler(FileHandler('Keyboard History.txt', 'a', 'utf-8'))\r\n\r\n# Set a custom logger\r\n# PS: The custom logger must have the following method:\r\n# 'trace', 'debug', 'info', 'success', 'log',\r\n# 'warning', 'error', 'critical', 'exception'\r\nfrom loguru import logger\r\nr = keyboard.set_logger(logger)\r\n```\r\n# Release Note\r\n## v1.5.2\r\n- [Fix] some hotkey can't be recorded.\r\n- [Change] Hotkeys with single keystroke won't be triggered if the tapping is interrupted.\r\n- [Change] Rename several apis.\r\n- [Change] Rebuild logging function.\r\n- [Remove] \"strict mode\".\r\n___\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",
"bugtrack_url": null,
"license": "LGPLv3",
"summary": "A cross-platform keyboard module.",
"version": "1.5.2",
"project_urls": {
"Documentation": "https://github.com/Xpp521/PyHotKey",
"Homepage": "https://github.com/Xpp521/PyHotKey",
"Source": "https://github.com/Xpp521/PyHotKey",
"Tracker": "https://github.com/Xpp521/PyHotKey/issues"
},
"split_keywords": [
"hotkey",
" keyboard",
" hot+key"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4ef39033d43dce32e075430a78d2c2d96fb1f81b16159f459723e3e5f818c3fb",
"md5": "28052356d42a11073a05d0aa8beadb9f",
"sha256": "9a353ac6cd8385038dcf7142df10cf113f8541bc3128e8349b08b051f79d9983"
},
"downloads": -1,
"filename": "PyHotKey-1.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "28052356d42a11073a05d0aa8beadb9f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19890,
"upload_time": "2024-08-01T05:40:23",
"upload_time_iso_8601": "2024-08-01T05:40:23.563765Z",
"url": "https://files.pythonhosted.org/packages/4e/f3/9033d43dce32e075430a78d2c2d96fb1f81b16159f459723e3e5f818c3fb/PyHotKey-1.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5d0bf61560ed6cb554b5973b1902419adf616ed678781e40d7c0de2f4600593f",
"md5": "7e5c2de9de1b8abebe98d3a6ef168062",
"sha256": "39b579c038e7850c26aa67cc1f917d5546c9d973ce60ab991fd386a1d49d1ab4"
},
"downloads": -1,
"filename": "PyHotKey-1.5.2.tar.gz",
"has_sig": false,
"md5_digest": "7e5c2de9de1b8abebe98d3a6ef168062",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17993,
"upload_time": "2024-08-01T05:40:25",
"upload_time_iso_8601": "2024-08-01T05:40:25.139434Z",
"url": "https://files.pythonhosted.org/packages/5d/0b/f61560ed6cb554b5973b1902419adf616ed678781e40d7c0de2f4600593f/PyHotKey-1.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-01 05:40:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Xpp521",
"github_project": "PyHotKey",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyhotkey"
}
JSON
