Hook and simulate keyboard events on Windows and Linux
Project description
keyboard
========
Take full control of your keyboard with this small Python library. Hook
global events, register hotkeys, simulate key presses and much more.
- Global event hook on all keyboards (captures keys regardless of
focus).
- **Listen** and **sends** keyboard events.
- Works with **Windows** and **Linux** (requires sudo).
- **Pure Python**, no C modules to be compiled.
- **Zero dependencies**. Trivial to install and deploy, just copy the
files.
- **Python 2 and 3**.
- Complex hotkey support (e.g. ``Ctrl+Shift+M, Ctrl+Space``) with
controllable timeout.
- Includes **high level API** (e.g. ```record`` <#keyboard.record>`__
and ```play`` <#keyboard.play>`__,
```add_abbreviation`` <#keyboard.add_abbreviation>`__.
- Maps keys as they actually are in your layout, with **full
internationalization support** (e.g. ``Ctrl+ç``).
- Events automatically captured in separate thread, doesn't block main
program.
- Tested and documented.
- Doesn't break accented dead keys (I'm looking at you, pyHook).
- Mouse support coming soon.
Example:
::
import keyboard
# Press PAGE UP then PAGE DOWN to type "foobar".
keyboard.add_hotkey('page up, page down', lambda: keyboard.write('foobar'))
keyboard.press_and_release('shift+s, space')
# Blocks until you press esc.
keyboard.wait('esc')
This program makes no attempt to hide itself, so don't use it for
keyloggers.
API
===
Table of Contents
^^^^^^^^^^^^^^^^^
- `keyboard.\ **KEY\_DOWN** <#keyboard.KEY_DOWN>`__
- `keyboard.\ **KEY\_UP** <#keyboard.KEY_UP>`__
- `keyboard.\ **KeyboardEvent** <#keyboard.KeyboardEvent>`__
- `keyboard.\ **all\_modifiers** <#keyboard.all_modifiers>`__
- `keyboard.\ **matches** <#keyboard.matches>`__
- `keyboard.\ **is\_pressed** <#keyboard.is_pressed>`__
- `keyboard.\ **canonicalize** <#keyboard.canonicalize>`__
- `keyboard.\ **call\_later** <#keyboard.call_later>`__
- `keyboard.\ **clear\_all\_hotkeys** <#keyboard.clear_all_hotkeys>`__
- `keyboard.\ **remove\_all\_hotkeys** <#keyboard.remove_all_hotkeys>`__
*(alias)*
- `keyboard.\ **add\_hotkey** <#keyboard.add_hotkey>`__
- `keyboard.\ **register\_hotkey** <#keyboard.register_hotkey>`__
*(alias)*
- `keyboard.\ **hook** <#keyboard.hook>`__
- `keyboard.\ **unhook** <#keyboard.unhook>`__
- `keyboard.\ **unhook\_all** <#keyboard.unhook_all>`__
- `keyboard.\ **hook\_key** <#keyboard.hook_key>`__
- `keyboard.\ **on\_press** <#keyboard.on_press>`__
- `keyboard.\ **on\_release** <#keyboard.on_release>`__
- `keyboard.\ **remove\_hotkey** <#keyboard.remove_hotkey>`__
- `keyboard.\ **unhook\_key** <#keyboard.unhook_key>`__ *(alias)*
- `keyboard.\ **add\_word\_listener** <#keyboard.add_word_listener>`__
- `keyboard.\ **register\_word\_listener** <#keyboard.register_word_listener>`__
*(alias)*
- `keyboard.\ **remove\_word\_listener** <#keyboard.remove_word_listener>`__
- `keyboard.\ **remove\_abbreviation** <#keyboard.remove_abbreviation>`__
*(alias)*
- `keyboard.\ **add\_abbreviation** <#keyboard.add_abbreviation>`__
- `keyboard.\ **register\_abbreviation** <#keyboard.register_abbreviation>`__
*(alias)*
- `keyboard.\ **stash\_state** <#keyboard.stash_state>`__
- `keyboard.\ **restore\_state** <#keyboard.restore_state>`__
- `keyboard.\ **write** <#keyboard.write>`__
- `keyboard.\ **to\_scan\_code** <#keyboard.to_scan_code>`__
- `keyboard.\ **send** <#keyboard.send>`__
- `keyboard.\ **press** <#keyboard.press>`__
- `keyboard.\ **release** <#keyboard.release>`__
- `keyboard.\ **press\_and\_release** <#keyboard.press_and_release>`__
- `keyboard.\ **wait** <#keyboard.wait>`__
- `keyboard.\ **record** <#keyboard.record>`__
- `keyboard.\ **play** <#keyboard.play>`__
- `keyboard.\ **replay** <#keyboard.replay>`__ *(alias)*
- `keyboard.\ **get\_typed\_strings** <#keyboard.get_typed_strings>`__
## keyboard.\ **KEY\_DOWN** = 'down'
## keyboard.\ **KEY\_UP** = 'up'
## class keyboard.\ **KeyboardEvent**
### KeyboardEvent.\ **event\_type**
### KeyboardEvent.\ **name**
### KeyboardEvent.\ **scan\_code**
### KeyboardEvent.\ **time**
## keyboard.\ **all\_modifiers** = ('alt', 'alt gr', 'ctrl', 'shift',
'win')
## keyboard.\ **matches**\ (event, name)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L82>`__
Returns True if the given event represents the same key as the one given
in ``name``.
## keyboard.\ **is\_pressed**\ (key)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L99>`__
Returns True if the key is pressed.
::
is_pressed(57) -> True
is_pressed('space') -> True
is_pressed('ctrl+space') -> True
## keyboard.\ **canonicalize**\ (hotkey)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L121>`__
Splits a user provided hotkey into a list of steps, each one made of a
list of scan codes or names. Used to normalize input at the API
boundary. When a combo is given (e.g. 'ctrl + a, b') spaces are ignored.
::
canonicalize(57) -> [[57]]
canonicalize([[57]]) -> [[57]]
canonicalize('space') -> [['space']]
canonicalize('ctrl+space') -> [['ctrl', 'space']]
canonicalize('ctrl+space, space') -> [['ctrl', 'space'], ['space']]
Note we must not convert names into scan codes because a name may
represent more than one physical key (e.g. two 'ctrl' keys).
## keyboard.\ **call\_later**\ (fn, args=(), delay=0.001)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L155>`__
Calls the provided function in a new thread after waiting some time.
Useful for giving the system some time to process an event, without
blocking the current execution flow.
## keyboard.\ **clear\_all\_hotkeys**\ ()
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L164>`__
Removes all hotkey handlers. Note some functions such as 'wait' and
'record' internally use hotkeys and will be affected by this call.
| Abbreviations and word listeners are not hotkeys and therefore not
affected.
| To remove all hooks use ```unhook_all()`` <#keyboard.unhook_all>`__.
## keyboard.\ **remove\_all\_hotkeys**
Alias for ``clear_all_hotkeys``.
## keyboard.\ **add\_hotkey**\ (hotkey, callback, args=(),
blocking=True, timeout=1)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L179>`__
Invokes a callback every time a key combination is pressed. The hotkey
must be in the format "ctrl+shift+a, s". This would trigger when the
user holds ctrl, shift and "a" at once, releases, and then presses "s".
To represent literal commas, pluses and spaces use their names ('comma',
'plus', 'space').
- ``args`` is an optional list of arguments to passed to the callback
during each invocation.
- ``blocking`` defines if the it should block processing other hotkeys
after a match is found.
- ``timeout`` is the amount of seconds allowed to pass between key
presses
The event handler function is returned. To remove a hotkey call
```remove_hotkey(hotkey)`` <#keyboard.remove_hotkey>`__ or
```remove_hotkey(handler)`` <#keyboard.remove_hotkey>`__. before the
combination state is reset.
Note: hotkeys are activated when the last key is *pressed*, not
released. Note: the callback is executed in a separate thread,
asynchronously. For an example of how to use a callback synchronously,
see ```wait`` <#keyboard.wait>`__.
::
add_hotkey(57, print, args=['space was pressed'])
add_hotkey(' ', print, args=['space was pressed'])
add_hotkey('space', print, args=['space was pressed'])
add_hotkey('Space', print, args=['space was pressed'])
add_hotkey('ctrl+q', quit)
add_hotkey('ctrl+alt+enter, space', some_callback)
## keyboard.\ **register\_hotkey**
Alias for ``add_hotkey``.
## keyboard.\ **hook**\ (callback)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L244>`__
Installs a global listener on all available keyboards, invoking
``callback`` each time a key is pressed or released.
The event passed to the callback is of type ``keyboard.KeyboardEvent``,
with the following attributes:
- ``name``: an Unicode representation of the character (e.g. "&") or
description (e.g. "space"). The name is always lower-case.
- ``scan_code``: number representing the physical key, e.g. 55.
- ``time``: timestamp of the time the event occurred, with as much
precision as given by the OS.
Returns the given callback for easier development.
## keyboard.\ **unhook**\ (callback)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L263>`__
Removes a previously hooked callback.
## keyboard.\ **unhook\_all**\ ()
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L267>`__
Removes all keyboard hooks in use, including hotkeys, abbreviations,
word listeners, ```record`` <#keyboard.record>`__\ ers and
```wait`` <#keyboard.wait>`__\ s.
## keyboard.\ **hook\_key**\ (key, keydown\_callback=<lambda>,
keyup\_callback=<lambda>)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L276>`__
Hooks key up and key down events for a single key. Returns the event
handler created. To remove a hooked key use
```unhook_key(key)`` <#keyboard.unhook_key>`__ or
```unhook_key(handler)`` <#keyboard.unhook_key>`__.
Note: this function shares state with hotkeys, so
```clear_all_hotkeys`` <#keyboard.clear_all_hotkeys>`__ affects it
aswell.
## keyboard.\ **on\_press**\ (callback)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L297>`__
Invokes ``callback`` for every KEY\_DOWN event. For details see
```hook`` <#keyboard.hook>`__.
## keyboard.\ **on\_release**\ (callback)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L303>`__
Invokes ``callback`` for every KEY\_UP event. For details see
```hook`` <#keyboard.hook>`__.
## keyboard.\ **remove\_hotkey**\ (hotkey\_or\_handler)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L330>`__
Removes a previously registered hotkey. Accepts either the hotkey used
during registration (exact string) or the event handler returned by the
```add_hotkey`` <#keyboard.add_hotkey>`__ or
```hook_key`` <#keyboard.hook_key>`__ functions.
## keyboard.\ **unhook\_key**
Alias for ``remove_hotkey``.
## keyboard.\ **add\_word\_listener**\ (word, callback,
triggers=['space'], match\_suffix=False, timeout=2)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L342>`__
Invokes a callback every time a sequence of characters is typed (e.g.
'pet') and followed by a trigger key (e.g. space). Modifiers (e.g. alt,
ctrl, shift) are ignored.
- ``word`` the typed text to be matched. E.g. 'pet'.
- ``callback`` is an argument-less function to be invoked each time the
word is typed.
- ``triggers`` is the list of keys that will cause a match to be
checked. If the user presses some key that is not a character (len>1)
and not in triggers, the characters so far will be discarded. By
default only space bar triggers match checks.
- ``match_suffix`` defines if endings of words should also be checked
instead of only whole words. E.g. if true, typing 'carpet'+space will
trigger the listener for 'pet'. Defaults to false, only whole words
are checked.
- ``timeout`` is the maximum number of seconds between typed characters
before the current word is discarded. Defaults to 2 seconds.
Returns the event handler created. To remove a word listener use
```remove_word_listener(word)`` <#keyboard.remove_word_listener>`__ or
```remove_word_listener(handler)`` <#keyboard.remove_word_listener>`__.
Note: all actions are performed on key down. Key up events are ignored.
Note: word mathes are **case sensitive**.
## keyboard.\ **register\_word\_listener**
Alias for ``add_word_listener``.
## keyboard.\ **remove\_word\_listener**\ (word\_or\_handler)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L393>`__
Removes a previously registered word listener. Accepts either the word
used during registration (exact string) or the event handler returned by
the ```add_word_listener`` <#keyboard.add_word_listener>`__ or
```add_abbreviation`` <#keyboard.add_abbreviation>`__ functions.
## keyboard.\ **remove\_abbreviation**
Alias for ``remove_word_listener``.
## keyboard.\ **add\_abbreviation**\ (source\_text, replacement\_text,
match\_suffix=True, timeout=2)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L401>`__
Registers a hotkey that replaces one typed text with another. For
example
::
add_abbreviation('tm', u'â„¢')
Replaces every "tm" followed by a space with a â„¢ symbol (and no space).
The replacement is done by sending backspace events.
- ``match_suffix`` defines if endings of words should also be checked
instead of only whole words. E.g. if true, typing 'carpet'+space will
trigger the listener for 'pet'. Defaults to false, only whole words
are checked.
- ``timeout`` is the maximum number of seconds between typed characters
before the current word is discarded. Defaults to 2 seconds.
For more details see
```add_word_listener`` <#keyboard.add_word_listener>`__.
## keyboard.\ **register\_abbreviation**
Alias for ``add_abbreviation``.
## keyboard.\ **stash\_state**\ ()
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L427>`__
Builds a list of all currently pressed scan codes, releases them and
returns the list. Pairs well with
```restore_state`` <#keyboard.restore_state>`__.
## keyboard.\ **restore\_state**\ (scan\_codes)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L437>`__
Given a list of scan\_codes ensures these keys, and only these keys, are
pressed. Pairs well with ```stash_state`` <#keyboard.stash_state>`__.
## keyboard.\ **write**\ (text, delay=0, restore\_state\_after=True)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L449>`__
Sends artificial keyboard events to the OS, simulating the typing of a
given text. Characters not available on the keyboard are typed as
explicit unicode characters using OS-specific functionality, such as
alt+codepoint.
To ensure text integrity all currently pressed keys are released before
the text is typed.
- ``delay`` is the number of seconds to wait between keypresses,
defaults to no delay.
- ``restore_state_after`` can be used to restore the state of pressed
keys after the text is typed, i.e. presses the keys that were
released at the beginning. Defaults to True.
## keyboard.\ **to\_scan\_code**\ (key)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L492>`__
Returns the scan code for a given key name (or scan code, i.e. do
nothing). Note that a name may belong to more than one physical key, in
which case one of the scan codes will be chosen.
## keyboard.\ **send**\ (combination, do\_press=True, do\_release=True)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L504>`__
Sends OS events that perform the given hotkey combination.
- ``combination`` can be either a scan code (e.g. 57 for space), single
key (e.g. 'space') or multi-key, multi-step combination (e.g.
'alt+F4, enter').
- ``do_press`` if true then press events are sent. Defaults to True.
- ``do_release`` if true then release events are sent. Defaults to
True.
send(57) send('ctrl+alt+del') send('alt+F4, enter') send('shift+s')
Note: keys are released in the opposite order they were pressed.
## keyboard.\ **press**\ (combination)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L529>`__
Presses and holds down a key combination (see
```send`` <#keyboard.send>`__).
## keyboard.\ **release**\ (combination)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L533>`__
Releases a key combination (see ```send`` <#keyboard.send>`__).
## keyboard.\ **press\_and\_release**\ (combination)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L537>`__
Presses and releases the key combination (see
```send`` <#keyboard.send>`__).
## keyboard.\ **wait**\ (combination)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L541>`__
Blocks the program execution until the given key combination is pressed.
## keyboard.\ **record**\ (until='escape')
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L551>`__
Records all keyboard events from all keyboards until the user presses
the given key combination. Then returns the list of events recorded, of
type ``keyboard.KeyboardEvent``. Pairs well with
```play(events)`` <#keyboard.play>`__.
Note: this is a blocking function. Note: for more details on the
keyboard hook and events see ```hook`` <#keyboard.hook>`__.
## keyboard.\ **play**\ (events, speed\_factor=1.0)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L567>`__
Plays a sequence of recorded events, maintaining the relative time
intervals. If speed\_factor is <= 0 then the actions are replayed as
fast as the OS allows. Pairs well with
```record()`` <#keyboard.record>`__.
Note: the current keyboard state is cleared at the beginning and
restored at the end of the function.
## keyboard.\ **replay**
Alias for ``play``.
## keyboard.\ **get\_typed\_strings**\ (events, allow\_backspace=True)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L595>`__
Given a sequence of events, tries to deduce what strings were typed.
Strings are separated when a non-textual key is pressed (such as tab or
enter). Characters are converted to uppercase according to shift and
capslock status. If ``allow_backspace`` is True, backspaces remove the
last character typed.
::
get_type_strings(record()) -> ['This is what', 'I recorded', '']
========
Take full control of your keyboard with this small Python library. Hook
global events, register hotkeys, simulate key presses and much more.
- Global event hook on all keyboards (captures keys regardless of
focus).
- **Listen** and **sends** keyboard events.
- Works with **Windows** and **Linux** (requires sudo).
- **Pure Python**, no C modules to be compiled.
- **Zero dependencies**. Trivial to install and deploy, just copy the
files.
- **Python 2 and 3**.
- Complex hotkey support (e.g. ``Ctrl+Shift+M, Ctrl+Space``) with
controllable timeout.
- Includes **high level API** (e.g. ```record`` <#keyboard.record>`__
and ```play`` <#keyboard.play>`__,
```add_abbreviation`` <#keyboard.add_abbreviation>`__.
- Maps keys as they actually are in your layout, with **full
internationalization support** (e.g. ``Ctrl+ç``).
- Events automatically captured in separate thread, doesn't block main
program.
- Tested and documented.
- Doesn't break accented dead keys (I'm looking at you, pyHook).
- Mouse support coming soon.
Example:
::
import keyboard
# Press PAGE UP then PAGE DOWN to type "foobar".
keyboard.add_hotkey('page up, page down', lambda: keyboard.write('foobar'))
keyboard.press_and_release('shift+s, space')
# Blocks until you press esc.
keyboard.wait('esc')
This program makes no attempt to hide itself, so don't use it for
keyloggers.
API
===
Table of Contents
^^^^^^^^^^^^^^^^^
- `keyboard.\ **KEY\_DOWN** <#keyboard.KEY_DOWN>`__
- `keyboard.\ **KEY\_UP** <#keyboard.KEY_UP>`__
- `keyboard.\ **KeyboardEvent** <#keyboard.KeyboardEvent>`__
- `keyboard.\ **all\_modifiers** <#keyboard.all_modifiers>`__
- `keyboard.\ **matches** <#keyboard.matches>`__
- `keyboard.\ **is\_pressed** <#keyboard.is_pressed>`__
- `keyboard.\ **canonicalize** <#keyboard.canonicalize>`__
- `keyboard.\ **call\_later** <#keyboard.call_later>`__
- `keyboard.\ **clear\_all\_hotkeys** <#keyboard.clear_all_hotkeys>`__
- `keyboard.\ **remove\_all\_hotkeys** <#keyboard.remove_all_hotkeys>`__
*(alias)*
- `keyboard.\ **add\_hotkey** <#keyboard.add_hotkey>`__
- `keyboard.\ **register\_hotkey** <#keyboard.register_hotkey>`__
*(alias)*
- `keyboard.\ **hook** <#keyboard.hook>`__
- `keyboard.\ **unhook** <#keyboard.unhook>`__
- `keyboard.\ **unhook\_all** <#keyboard.unhook_all>`__
- `keyboard.\ **hook\_key** <#keyboard.hook_key>`__
- `keyboard.\ **on\_press** <#keyboard.on_press>`__
- `keyboard.\ **on\_release** <#keyboard.on_release>`__
- `keyboard.\ **remove\_hotkey** <#keyboard.remove_hotkey>`__
- `keyboard.\ **unhook\_key** <#keyboard.unhook_key>`__ *(alias)*
- `keyboard.\ **add\_word\_listener** <#keyboard.add_word_listener>`__
- `keyboard.\ **register\_word\_listener** <#keyboard.register_word_listener>`__
*(alias)*
- `keyboard.\ **remove\_word\_listener** <#keyboard.remove_word_listener>`__
- `keyboard.\ **remove\_abbreviation** <#keyboard.remove_abbreviation>`__
*(alias)*
- `keyboard.\ **add\_abbreviation** <#keyboard.add_abbreviation>`__
- `keyboard.\ **register\_abbreviation** <#keyboard.register_abbreviation>`__
*(alias)*
- `keyboard.\ **stash\_state** <#keyboard.stash_state>`__
- `keyboard.\ **restore\_state** <#keyboard.restore_state>`__
- `keyboard.\ **write** <#keyboard.write>`__
- `keyboard.\ **to\_scan\_code** <#keyboard.to_scan_code>`__
- `keyboard.\ **send** <#keyboard.send>`__
- `keyboard.\ **press** <#keyboard.press>`__
- `keyboard.\ **release** <#keyboard.release>`__
- `keyboard.\ **press\_and\_release** <#keyboard.press_and_release>`__
- `keyboard.\ **wait** <#keyboard.wait>`__
- `keyboard.\ **record** <#keyboard.record>`__
- `keyboard.\ **play** <#keyboard.play>`__
- `keyboard.\ **replay** <#keyboard.replay>`__ *(alias)*
- `keyboard.\ **get\_typed\_strings** <#keyboard.get_typed_strings>`__
## keyboard.\ **KEY\_DOWN** = 'down'
## keyboard.\ **KEY\_UP** = 'up'
## class keyboard.\ **KeyboardEvent**
### KeyboardEvent.\ **event\_type**
### KeyboardEvent.\ **name**
### KeyboardEvent.\ **scan\_code**
### KeyboardEvent.\ **time**
## keyboard.\ **all\_modifiers** = ('alt', 'alt gr', 'ctrl', 'shift',
'win')
## keyboard.\ **matches**\ (event, name)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L82>`__
Returns True if the given event represents the same key as the one given
in ``name``.
## keyboard.\ **is\_pressed**\ (key)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L99>`__
Returns True if the key is pressed.
::
is_pressed(57) -> True
is_pressed('space') -> True
is_pressed('ctrl+space') -> True
## keyboard.\ **canonicalize**\ (hotkey)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L121>`__
Splits a user provided hotkey into a list of steps, each one made of a
list of scan codes or names. Used to normalize input at the API
boundary. When a combo is given (e.g. 'ctrl + a, b') spaces are ignored.
::
canonicalize(57) -> [[57]]
canonicalize([[57]]) -> [[57]]
canonicalize('space') -> [['space']]
canonicalize('ctrl+space') -> [['ctrl', 'space']]
canonicalize('ctrl+space, space') -> [['ctrl', 'space'], ['space']]
Note we must not convert names into scan codes because a name may
represent more than one physical key (e.g. two 'ctrl' keys).
## keyboard.\ **call\_later**\ (fn, args=(), delay=0.001)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L155>`__
Calls the provided function in a new thread after waiting some time.
Useful for giving the system some time to process an event, without
blocking the current execution flow.
## keyboard.\ **clear\_all\_hotkeys**\ ()
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L164>`__
Removes all hotkey handlers. Note some functions such as 'wait' and
'record' internally use hotkeys and will be affected by this call.
| Abbreviations and word listeners are not hotkeys and therefore not
affected.
| To remove all hooks use ```unhook_all()`` <#keyboard.unhook_all>`__.
## keyboard.\ **remove\_all\_hotkeys**
Alias for ``clear_all_hotkeys``.
## keyboard.\ **add\_hotkey**\ (hotkey, callback, args=(),
blocking=True, timeout=1)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L179>`__
Invokes a callback every time a key combination is pressed. The hotkey
must be in the format "ctrl+shift+a, s". This would trigger when the
user holds ctrl, shift and "a" at once, releases, and then presses "s".
To represent literal commas, pluses and spaces use their names ('comma',
'plus', 'space').
- ``args`` is an optional list of arguments to passed to the callback
during each invocation.
- ``blocking`` defines if the it should block processing other hotkeys
after a match is found.
- ``timeout`` is the amount of seconds allowed to pass between key
presses
The event handler function is returned. To remove a hotkey call
```remove_hotkey(hotkey)`` <#keyboard.remove_hotkey>`__ or
```remove_hotkey(handler)`` <#keyboard.remove_hotkey>`__. before the
combination state is reset.
Note: hotkeys are activated when the last key is *pressed*, not
released. Note: the callback is executed in a separate thread,
asynchronously. For an example of how to use a callback synchronously,
see ```wait`` <#keyboard.wait>`__.
::
add_hotkey(57, print, args=['space was pressed'])
add_hotkey(' ', print, args=['space was pressed'])
add_hotkey('space', print, args=['space was pressed'])
add_hotkey('Space', print, args=['space was pressed'])
add_hotkey('ctrl+q', quit)
add_hotkey('ctrl+alt+enter, space', some_callback)
## keyboard.\ **register\_hotkey**
Alias for ``add_hotkey``.
## keyboard.\ **hook**\ (callback)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L244>`__
Installs a global listener on all available keyboards, invoking
``callback`` each time a key is pressed or released.
The event passed to the callback is of type ``keyboard.KeyboardEvent``,
with the following attributes:
- ``name``: an Unicode representation of the character (e.g. "&") or
description (e.g. "space"). The name is always lower-case.
- ``scan_code``: number representing the physical key, e.g. 55.
- ``time``: timestamp of the time the event occurred, with as much
precision as given by the OS.
Returns the given callback for easier development.
## keyboard.\ **unhook**\ (callback)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L263>`__
Removes a previously hooked callback.
## keyboard.\ **unhook\_all**\ ()
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L267>`__
Removes all keyboard hooks in use, including hotkeys, abbreviations,
word listeners, ```record`` <#keyboard.record>`__\ ers and
```wait`` <#keyboard.wait>`__\ s.
## keyboard.\ **hook\_key**\ (key, keydown\_callback=<lambda>,
keyup\_callback=<lambda>)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L276>`__
Hooks key up and key down events for a single key. Returns the event
handler created. To remove a hooked key use
```unhook_key(key)`` <#keyboard.unhook_key>`__ or
```unhook_key(handler)`` <#keyboard.unhook_key>`__.
Note: this function shares state with hotkeys, so
```clear_all_hotkeys`` <#keyboard.clear_all_hotkeys>`__ affects it
aswell.
## keyboard.\ **on\_press**\ (callback)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L297>`__
Invokes ``callback`` for every KEY\_DOWN event. For details see
```hook`` <#keyboard.hook>`__.
## keyboard.\ **on\_release**\ (callback)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L303>`__
Invokes ``callback`` for every KEY\_UP event. For details see
```hook`` <#keyboard.hook>`__.
## keyboard.\ **remove\_hotkey**\ (hotkey\_or\_handler)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L330>`__
Removes a previously registered hotkey. Accepts either the hotkey used
during registration (exact string) or the event handler returned by the
```add_hotkey`` <#keyboard.add_hotkey>`__ or
```hook_key`` <#keyboard.hook_key>`__ functions.
## keyboard.\ **unhook\_key**
Alias for ``remove_hotkey``.
## keyboard.\ **add\_word\_listener**\ (word, callback,
triggers=['space'], match\_suffix=False, timeout=2)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L342>`__
Invokes a callback every time a sequence of characters is typed (e.g.
'pet') and followed by a trigger key (e.g. space). Modifiers (e.g. alt,
ctrl, shift) are ignored.
- ``word`` the typed text to be matched. E.g. 'pet'.
- ``callback`` is an argument-less function to be invoked each time the
word is typed.
- ``triggers`` is the list of keys that will cause a match to be
checked. If the user presses some key that is not a character (len>1)
and not in triggers, the characters so far will be discarded. By
default only space bar triggers match checks.
- ``match_suffix`` defines if endings of words should also be checked
instead of only whole words. E.g. if true, typing 'carpet'+space will
trigger the listener for 'pet'. Defaults to false, only whole words
are checked.
- ``timeout`` is the maximum number of seconds between typed characters
before the current word is discarded. Defaults to 2 seconds.
Returns the event handler created. To remove a word listener use
```remove_word_listener(word)`` <#keyboard.remove_word_listener>`__ or
```remove_word_listener(handler)`` <#keyboard.remove_word_listener>`__.
Note: all actions are performed on key down. Key up events are ignored.
Note: word mathes are **case sensitive**.
## keyboard.\ **register\_word\_listener**
Alias for ``add_word_listener``.
## keyboard.\ **remove\_word\_listener**\ (word\_or\_handler)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L393>`__
Removes a previously registered word listener. Accepts either the word
used during registration (exact string) or the event handler returned by
the ```add_word_listener`` <#keyboard.add_word_listener>`__ or
```add_abbreviation`` <#keyboard.add_abbreviation>`__ functions.
## keyboard.\ **remove\_abbreviation**
Alias for ``remove_word_listener``.
## keyboard.\ **add\_abbreviation**\ (source\_text, replacement\_text,
match\_suffix=True, timeout=2)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L401>`__
Registers a hotkey that replaces one typed text with another. For
example
::
add_abbreviation('tm', u'â„¢')
Replaces every "tm" followed by a space with a â„¢ symbol (and no space).
The replacement is done by sending backspace events.
- ``match_suffix`` defines if endings of words should also be checked
instead of only whole words. E.g. if true, typing 'carpet'+space will
trigger the listener for 'pet'. Defaults to false, only whole words
are checked.
- ``timeout`` is the maximum number of seconds between typed characters
before the current word is discarded. Defaults to 2 seconds.
For more details see
```add_word_listener`` <#keyboard.add_word_listener>`__.
## keyboard.\ **register\_abbreviation**
Alias for ``add_abbreviation``.
## keyboard.\ **stash\_state**\ ()
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L427>`__
Builds a list of all currently pressed scan codes, releases them and
returns the list. Pairs well with
```restore_state`` <#keyboard.restore_state>`__.
## keyboard.\ **restore\_state**\ (scan\_codes)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L437>`__
Given a list of scan\_codes ensures these keys, and only these keys, are
pressed. Pairs well with ```stash_state`` <#keyboard.stash_state>`__.
## keyboard.\ **write**\ (text, delay=0, restore\_state\_after=True)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L449>`__
Sends artificial keyboard events to the OS, simulating the typing of a
given text. Characters not available on the keyboard are typed as
explicit unicode characters using OS-specific functionality, such as
alt+codepoint.
To ensure text integrity all currently pressed keys are released before
the text is typed.
- ``delay`` is the number of seconds to wait between keypresses,
defaults to no delay.
- ``restore_state_after`` can be used to restore the state of pressed
keys after the text is typed, i.e. presses the keys that were
released at the beginning. Defaults to True.
## keyboard.\ **to\_scan\_code**\ (key)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L492>`__
Returns the scan code for a given key name (or scan code, i.e. do
nothing). Note that a name may belong to more than one physical key, in
which case one of the scan codes will be chosen.
## keyboard.\ **send**\ (combination, do\_press=True, do\_release=True)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L504>`__
Sends OS events that perform the given hotkey combination.
- ``combination`` can be either a scan code (e.g. 57 for space), single
key (e.g. 'space') or multi-key, multi-step combination (e.g.
'alt+F4, enter').
- ``do_press`` if true then press events are sent. Defaults to True.
- ``do_release`` if true then release events are sent. Defaults to
True.
send(57) send('ctrl+alt+del') send('alt+F4, enter') send('shift+s')
Note: keys are released in the opposite order they were pressed.
## keyboard.\ **press**\ (combination)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L529>`__
Presses and holds down a key combination (see
```send`` <#keyboard.send>`__).
## keyboard.\ **release**\ (combination)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L533>`__
Releases a key combination (see ```send`` <#keyboard.send>`__).
## keyboard.\ **press\_and\_release**\ (combination)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L537>`__
Presses and releases the key combination (see
```send`` <#keyboard.send>`__).
## keyboard.\ **wait**\ (combination)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L541>`__
Blocks the program execution until the given key combination is pressed.
## keyboard.\ **record**\ (until='escape')
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L551>`__
Records all keyboard events from all keyboards until the user presses
the given key combination. Then returns the list of events recorded, of
type ``keyboard.KeyboardEvent``. Pairs well with
```play(events)`` <#keyboard.play>`__.
Note: this is a blocking function. Note: for more details on the
keyboard hook and events see ```hook`` <#keyboard.hook>`__.
## keyboard.\ **play**\ (events, speed\_factor=1.0)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L567>`__
Plays a sequence of recorded events, maintaining the relative time
intervals. If speed\_factor is <= 0 then the actions are replayed as
fast as the OS allows. Pairs well with
```record()`` <#keyboard.record>`__.
Note: the current keyboard state is cleared at the beginning and
restored at the end of the function.
## keyboard.\ **replay**
Alias for ``play``.
## keyboard.\ **get\_typed\_strings**\ (events, allow\_backspace=True)
`[source] <https://github.com/boppreh/keyboard/blob/master/keyboard/__init__.py#L595>`__
Given a sequence of events, tries to deduce what strings were typed.
Strings are separated when a non-textual key is pressed (such as tab or
enter). Characters are converted to uppercase according to shift and
capslock status. If ``allow_backspace`` is True, backspaces remove the
last character typed.
::
get_type_strings(record()) -> ['This is what', 'I recorded', '']
