# -*- coding: utf-8 -*- """ keyboard ======== Take full control of your keyboard with this small Python library. Hook global events, register hotkeys, simulate key presses and much more. ## Features - **Global event hook** on all keyboards (captures keys regardless of focus). - **Listen** and **send** keyboard events. - Works with **Windows** and **Linux** (requires sudo), with experimental **OS X** support (thanks @glitchassassin!). - **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 available via project [mouse](https://github.com/boppreh/mouse) (`pip install mouse`). ## Usage Install the [PyPI package](https://pypi.python.org/pypi/keyboard/): pip install keyboard or clone the repository (no installation required, source files are sufficient): git clone https://github.com/boppreh/keyboard or [download and extract the zip](https://github.com/boppreh/keyboard/archive/master.zip) into your project folder. Then check the [API docs below](https://github.com/boppreh/keyboard#api) to see what features are available. ## Example ```py import keyboard keyboard.press_and_release('shift+s, space') keyboard.write('The quick brown fox jumps over the lazy dog.') keyboard.add_hotkey('ctrl+shift+a', print, args=('triggered', 'hotkey')) # Press PAGE UP then PAGE DOWN to type "foobar". keyboard.add_hotkey('page up, page down', lambda: keyboard.write('foobar')) # Blocks until you press esc. keyboard.wait('esc') # Record events until 'esc' is pressed. recorded = keyboard.record(until='esc') # Then replay back at three times the speed. keyboard.play(recorded, speed_factor=3) # Type @@ then press space to replace with abbreviation. keyboard.add_abbreviation('@@', 'my.long.email@example.com') # Block forever, like `while True`. keyboard.wait() ``` ## Known limitations: - Events generated under Windows don't report device id (`event.device == None`). [#21](https://github.com/boppreh/keyboard/issues/21) - Media keys on Linux may appear nameless (scan-code only) or not at all. [#20](https://github.com/boppreh/keyboard/issues/20) - Key suppression/blocking only available on Windows. [#22](https://github.com/boppreh/keyboard/issues/22) - To avoid depending on X, the Linux parts reads raw device files (`/dev/input/input*`) but this requries root. - Other applications, such as some games, may register hooks that swallow all key events. In this case `keyboard` will be unable to report events. - This program makes no attempt to hide itself, so don't use it for keyloggers or online gaming bots. Be responsible. """ from __future__ import print_function as _print_function version = '0.13.4' import re as _re import itertools as _itertools import collections as _collections from threading import Thread as _Thread, Lock as _Lock import time as _time # Python2... Buggy on time changes and leap seconds, but no other good option (https://stackoverflow.com/questions/1205722/how-do-i-get-monotonic-time-durations-in-python). _time.monotonic = getattr(_time, 'monotonic', None) or _time.time try: # Python2 long, basestring _is_str = lambda x: isinstance(x, basestring) _is_number = lambda x: isinstance(x, (int, long)) import Queue as _queue # threading.Event is a function in Python2 wrappin _Event (?!). from threading import _Event as _UninterruptibleEvent except NameError: # Python3 _is_str = lambda x: isinstance(x, str) _is_number = lambda x: isinstance(x, int) import queue as _queue from threading import Event as _UninterruptibleEvent _is_list = lambda x: isinstance(x, (list, tuple)) # Just a dynamic object to store attributes for the closures. class _State(object): pass # The "Event" class from `threading` ignores signals when waiting and is # impossible to interrupt with Ctrl+C. So we rewrite `wait` to wait in small, # interruptible intervals. class _Event(_UninterruptibleEvent): def wait(self): while True: if _UninterruptibleEvent.wait(self, 0.5): break import platform as _platform if _platform.system() == 'Windows': from. import _winkeyboard as _os_keyboard elif _platform.system() == 'Linux': from. import _nixkeyboard as _os_keyboard elif _platform.system() == 'Darwin': from. import _darwinkeyboard as _os_keyboard else: raise OSError("Unsupported platform '{}'".format(_platform.system())) from ._keyboard_event import KEY_DOWN, KEY_UP, KeyboardEvent from ._generic import GenericListener as _GenericListener from ._canonical_names import all_modifiers, sided_modifiers, normalize_name _modifier_scan_codes = set() def is_modifier(key): """ Returns True if `key` is a scan code or name of a modifier key. """ if _is_str(key): return key in all_modifiers else: if not _modifier_scan_codes: scan_codes = (key_to_scan_codes(name, False) for name in all_modifiers) _modifier_scan_codes.update(*scan_codes) return key in _modifier_scan_codes _pressed_events_lock = _Lock() _pressed_events = {} _physically_pressed_keys = _pressed_events _logically_pressed_keys = {} class _KeyboardListener(_GenericListener): transition_table = { #Current state of the modifier, per `modifier_states`. #| #| Type of event that triggered this modifier update. #| | #| | Type of key that triggered this modiier update. #| | | #| | | Should we send a fake key press? #| | | | #| | | => | Accept the event? #| | | | | #| | | | | Next state. #v v v v v v ('free', KEY_UP, 'modifier'): (False, True, 'free'), ('free', KEY_DOWN, 'modifier'): (False, False, 'pending'), ('pending', KEY_UP, 'modifier'): (True, True, 'free'), ('pending', KEY_DOWN, 'modifier'): (False, True, 'allowed'), ('suppressed', KEY_UP, 'modifier'): (False, False, 'free'), ('suppressed', KEY_DOWN, 'modifier'): (False, False, 'suppressed'), ('allowed', KEY_UP, 'modifier'): (False, True, 'free'), ('allowed', KEY_DOWN, 'modifier'): (False, True, 'allowed'), ('free', KEY_UP, 'hotkey'): (False, None, 'free'), ('free', KEY_DOWN, 'hotkey'): (False, None, 'free'), ('pending', KEY_UP, 'hotkey'): (False, None, 'suppressed'), ('pending', KEY_DOWN, 'hotkey'): (False, None, 'suppressed'), ('suppressed', KEY_UP, 'hotkey'): (False, None, 'suppressed'), ('suppressed', KEY_DOWN, 'hotkey'): (False, None, 'suppressed'), ('allowed', KEY_UP, 'hotkey'): (False, None, 'allowed'), ('allowed', KEY_DOWN, 'hotkey'): (False, None, 'allowed'), ('free', KEY_UP, 'other'): (False, True, 'free'), ('free', KEY_DOWN, 'other'): (False, True, 'free'), ('pending', KEY_UP, 'other'): (True, True, 'allowed'), ('pending', KEY_DOWN, 'other'): (True, True, 'allowed'), # Necessary when hotkeys are removed after beign triggered, such as # TestKeyboard.test_add_hotkey_multistep_suppress_modifier. ('suppressed', KEY_UP, 'other'): (False, False, 'allowed'), ('suppressed', KEY_DOWN, 'other'): (True, True, 'allowed'), ('allowed', KEY_UP, 'other'): (False, True, 'allowed'), ('allowed', KEY_DOWN, 'other'): (False, True, 'allowed'), } def init(self): _os_keyboard.init() self.active_modifiers = set() self.blocking_hooks = [] self.blocking_keys = _collections.defaultdict(list) self.nonblocking_keys = _collections.defaultdict(list) self.blocking_hotkeys = _collections.defaultdict(list) self.nonblocking_hotkeys = _collections.defaultdict(list) self.filtered_modifiers = _collections.Counter() self.is_replaying = False # Supporting hotkey suppression is harder than it looks. See # https://github.com/boppreh/keyboard/issues/22 self.modifier_states = {} # "alt" -> "allowed" def pre_process_event(self, event): for key_hook in self.nonblocking_keys[event.scan_code]: key_hook(event) with _pressed_events_lock: hotkey = tuple(sorted(_pressed_events)) for callback in self.nonblocking_hotkeys[hotkey]: callback(event) return event.scan_code or (event.name and event.name != 'unknown') def direct_callback(self, event): """ This function is called for every OS keyboard event and decides if the event should be blocked or not, and passes a copy of the event to other, non-blocking, listeners. There are two ways to block events: remapped keys, which translate events by suppressing and re-emitting; and blocked hotkeys, which suppress specific hotkeys. """ # Pass through all fake key events, don't even report to other handlers. if self.is_replaying: return True if not all(hook(event) for hook in self.blocking_hooks): return False event_type = event.event_type scan_code = event.scan_code # Update tables of currently pressed keys and modifiers. with _pressed_events_lock: if event_type == KEY_DOWN: if is_modifier(scan_code): self.active_modifiers.add(scan_code) _pressed_events[scan_code] = event hotkey = tuple(sorted(_pressed_events)) if event_type == KEY_UP: self.active_modifiers.discard(scan_code) if scan_code in _pressed_events: del _pressed_events[scan_code] # Mappings based on individual keys instead of hotkeys. for key_hook in self.blocking_keys[scan_code]: if not key_hook(event): return False # Default accept. accept = True if self.blocking_hotkeys: if self.filtered_modifiers[scan_code]: origin = 'modifier' modifiers_to_update = set([scan_code]) else: modifiers_to_update = self.active_modifiers if is_modifier(scan_code): modifiers_to_update = modifiers_to_update | {scan_code} callback_results = [callback(event) for callback in self.blocking_hotkeys[hotkey]] if callback_results: accept = all(callback_results) origin = 'hotkey' else: origin = 'other' for key in sorted(modifiers_to_update): transition_tuple = (self.modifier_states.get(key, 'free'), event_type, origin) should_press, new_accept, new_state = self.transition_table[transition_tuple] if should_press: press(key) if new_accept is not None: accept = new_accept self.modifier_states[key] = new_state if accept: if event_type == KEY_DOWN: _logically_pressed_keys[scan_code] = event elif event_type == KEY_UP and scan_code in _logically_pressed_keys: del _logically_pressed_keys[scan_code] # Queue for handlers that won't block the event. self.queue.put(event) return accept def listen(self): _os_keyboard.listen(self.direct_callback) _listener = _KeyboardListener() def key_to_scan_codes(key, error_if_missing=True): """ Returns a list of scan codes associated with this key (name or scan code). """ if _is_number(key): return (key,) elif _is_list(key): return sum((key_to_scan_codes(i) for i in key), ()) elif not _is_str(key): raise ValueError('Unexpected key type ' + str(type(key)) + ', value (' + repr(key) + ')') normalized = normalize_name(key) if normalized in sided_modifiers: left_scan_codes = key_to_scan_codes('left ' + normalized, False) right_scan_codes = key_to_scan_codes('right ' + normalized, False) return left_scan_codes + tuple(c for c in right_scan_codes if c not in left_scan_codes) try: # Put items in ordered dict to remove duplicates. t = tuple(_collections.OrderedDict((scan_code, True) for scan_code, modifier in _os_keyboard.map_name(normalized))) e = None except (KeyError, ValueError) as exception: t = () e = exception if not t and error_if_missing: raise ValueError('Key {} is not mapped to any known key.'.format(repr(key)), e) else: return t def parse_hotkey(hotkey): """ Parses a user-provided hotkey into nested tuples representing the parsed structure, with the bottom values being lists of scan codes. Also accepts raw scan codes, which are then wrapped in the required number of nestings. Example: parse_hotkey("alt+shift+a, alt+b, c") # Keys: ^~^ ^~~~^ ^ ^~^ ^ ^ # Steps: ^~~~~~~~~~^ ^~~~^ ^ # ((alt_codes, shift_codes, a_codes), (alt_codes, b_codes), (c_codes,)) """ if _is_number(hotkey) or len(hotkey) == 1: scan_codes = key_to_scan_codes(hotkey) step = (scan_codes,) steps = (step,) return steps elif _is_list(hotkey): if not any(map(_is_list, hotkey)): step = tuple(key_to_scan_codes(k) for k in hotkey) steps = (step,) return steps return hotkey steps = [] for step in _re.split(r',\s?', hotkey): keys = _re.split(r'\s?\+\s?', step) steps.append(tuple(key_to_scan_codes(key) for key in keys)) return tuple(steps) def send(hotkey, do_press=True, do_release=True): """ Sends OS events that perform the given *hotkey* hotkey. - `hotkey` can be either a scan code (e.g. 57 for space), single key (e.g. 'space') or multi-key, multi-step hotkey (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. """ _listener.is_replaying = True parsed = parse_hotkey(hotkey) for step in parsed: if do_press: for scan_codes in step: _os_keyboard.press(scan_codes[0]) if do_release: for scan_codes in reversed(step): _os_keyboard.release(scan_codes[0]) _listener.is_replaying = False # Alias. press_and_release = send def press(hotkey): """ Presses and holds down a hotkey (see `send`). """ send(hotkey, True, False) def release(hotkey): """ Releases a hotkey (see `send`). """ send(hotkey, False, True) def is_pressed(hotkey): """ Returns True if the key is pressed. is_pressed(57) #-> True is_pressed('space') #-> True is_pressed('ctrl+space') #-> True """ _listener.start_if_necessary() if _is_number(hotkey): # Shortcut. with _pressed_events_lock: return hotkey in _pressed_events steps = parse_hotkey(hotkey) if len(steps) > 1: raise ValueError("Impossible to check if multi-step hotkeys are pressed (`a+b` is ok, `a, b` isn't).") # Convert _pressed_events into a set with _pressed_events_lock: pressed_scan_codes = set(_pressed_events) for scan_codes in steps[0]: if not any(scan_code in pressed_scan_codes for scan_code in scan_codes): return False return True def call_later(fn, args=(), delay=0.001): """ 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. """ thread = _Thread(target=lambda: (_time.sleep(delay), fn(*args))) thread.start() _hooks = {} def hook(callback, suppress=False, on_remove=lambda: None): """ 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. """ if suppress: _listener.start_if_necessary() append, remove = _listener.blocking_hooks.append, _listener.blocking_hooks.remove else: append, remove = _listener.add_handler, _listener.remove_handler append(callback) def remove_(): del _hooks[callback] del _hooks[remove_] remove(callback) on_remove() _hooks[callback] = _hooks[remove_] = remove_ return remove_ def on_press(callback, suppress=False): """ Invokes `callback` for every KEY_DOWN event. For details see `hook`. """ return hook(lambda e: e.event_type == KEY_UP or callback(e), suppress=suppress) def on_release(callback, suppress=False): """ Invokes `callback` for every KEY_UP event. For details see `hook`. """ return hook(lambda e: e.event_type == KEY_DOWN or callback(e), suppress=suppress) def hook_key(key, callback, suppress=False): """ 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)` or `unhook_key(handler)`. Note: this function shares state with hotkeys, so `clear_all_hotkeys` affects it aswell. """ _listener.start_if_necessary() store = _listener.blocking_keys if suppress else _listener.nonblocking_keys scan_codes = key_to_scan_codes(key) for scan_code in scan_codes: store[scan_code].append(callback) def remove_(): del _hooks[callback] del _hooks[key] del _hooks[remove_] for scan_code in scan_codes: store[scan_code].remove(callback) _hooks[callback] = _hooks[key] = _hooks[remove_] = remove_ return remove_ def on_press_key(key, callback, suppress=False): """ Invokes `callback` for KEY_DOWN event related to the given key. For details see `hook`. """ return hook_key(key, lambda e: e.event_type == KEY_UP or callback(e), suppress=suppress) def on_release_key(key, callback, suppress=False): """ Invokes `callback` for KEY_UP event related to the given key. For details see `hook`. """ return hook_key(key, lambda e: e.event_type == KEY_DOWN or callback(e), suppress=suppress) def unhook(remove): """ Removes a previously added hook, either by callback or by the return value of `hook`. """ _hooks[remove]() unhook_key = unhook def unhook_all(): """ Removes all keyboard hooks in use, including hotkeys, abbreviations, word listeners, `record`ers and `wait`s. """ _listener.start_if_necessary() _listener.blocking_keys.clear() _listener.nonblocking_keys.clear() del _listener.blocking_hooks[:] del _listener.handlers[:] unhook_all_hotkeys() def block_key(key): """ Suppresses all key events of the given key, regardless of modifiers. """ return hook_key(key, lambda e: False, suppress=True) unblock_key = unhook_key def remap_key(src, dst): """ Whenever the key `src` is pressed or released, regardless of modifiers, press or release the hotkey `dst` instead. """ def handler(event): if event.event_type == KEY_DOWN: press(dst) else: release(dst) return False return hook_key(src, handler, suppress=True) unremap_key = unhook_key def parse_hotkey_combinations(hotkey): """ Parses a user-provided hotkey. Differently from `parse_hotkey`, instead of each step being a list of the different scan codes for each key, each step is a list of all possible combinations of those scan codes. """ def combine_step(step): # A single step may be composed of many keys, and each key can have # multiple scan codes. To speed up hotkey matching and avoid introducing # event delays, we list all possible combinations of scan codes for these # keys. Hotkeys are usually small, and there are not many combinations, so # this is not as insane as it sounds. return (tuple(sorted(scan_codes)) for scan_codes in _itertools.product(*step)) return tuple(tuple(combine_step(step)) for step in parse_hotkey(hotkey)) def _add_hotkey_step(handler, combinations, suppress): """ Hooks a single-step hotkey (e.g. 'shift+a'). """ container = _listener.blocking_hotkeys if suppress else _listener.nonblocking_hotkeys # Register the scan codes of every possible combination of # modfiier + main key. Modifiers have to be registered in # filtered_modifiers too, so suppression and replaying can work. for scan_codes in combinations: for scan_code in scan_codes: if is_modifier(scan_code): _listener.filtered_modifiers[scan_code] += 1 container[scan_codes].append(handler) def remove(): for scan_codes in combinations: for scan_code in scan_codes: if is_modifier(scan_code): _listener.filtered_modifiers[scan_code] -= 1 container[scan_codes].remove(handler) return remove _hotkeys = {} def add_hotkey(hotkey, callback, args=(), suppress=False, timeout=1, trigger_on_release=False): """ Invokes a callback every time a hotkey 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. - `suppress` defines if successful triggers should block the keys from being sent to other programs. - `timeout` is the amount of seconds allowed to pass between key presses. - `trigger_on_release` if true, the callback is invoked on key release instead of key press. The event handler function is returned. To remove a hotkey call `remove_hotkey(hotkey)` or `remove_hotkey(handler)`. before the hotkey 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`. Examples: # Different but equivalent ways to listen for a spacebar key press. add_hotkey(' ', print, args=['space was pressed']) add_hotkey('space', print, args=['space was pressed']) add_hotkey('Space', print, args=['space was pressed']) # Here 57 represents the keyboard code for spacebar; so you will be # pressing 'spacebar', not '57' to activate the print function. add_hotkey(57, print, args=['space was pressed']) add_hotkey('ctrl+q', quit) add_hotkey('ctrl+alt+enter, space', some_callback) """ if args: callback = lambda callback=callback: callback(*args) _listener.start_if_necessary() steps = parse_hotkey_combinations(hotkey) event_type = KEY_UP if trigger_on_release else KEY_DOWN if len(steps) == 1: # Deciding when to allow a KEY_UP event is far harder than I thought, # and any mistake will make that key "sticky". Therefore just let all # KEY_UP events go through as long as that's not what we are listening # for. handler = lambda e: (event_type == KEY_DOWN and e.event_type == KEY_UP and e.scan_code in _logically_pressed_keys) or (event_type == e.event_type and callback()) remove_step = _add_hotkey_step(handler, steps[0], suppress) def remove_(): remove_step() del _hotkeys[hotkey] del _hotkeys[remove_] del _hotkeys[callback] # TODO: allow multiple callbacks for each hotkey without overwriting the # remover. _hotkeys[hotkey] = _hotkeys[remove_] = _hotkeys[callback] = remove_ return remove_ state = _State() state.remove_catch_misses = None state.remove_last_step = None state.suppressed_events = [] state.last_update = float('-inf') def catch_misses(event, force_fail=False): if ( event.event_type == event_type and state.index and event.scan_code not in allowed_keys_by_step[state.index] ) or ( timeout and _time.monotonic() - state.last_update >= timeout ) or force_fail: # Weird formatting to ensure short-circuit. state.remove_last_step() for event in state.suppressed_events: if event.event_type == KEY_DOWN: press(event.scan_code) else: release(event.scan_code) del state.suppressed_events[:] index = 0 set_index(0) return True def set_index(new_index): state.index = new_index if new_index == 0: # This is done for performance reasons, avoiding a global key hook # that is always on. state.remove_catch_misses = lambda: None elif new_index == 1: state.remove_catch_misses() # Must be `suppress=True` to ensure `send` has priority. state.remove_catch_misses = hook(catch_misses, suppress=True) if new_index == len(steps) - 1: def handler(event): if event.event_type == KEY_UP: remove() set_index(0) accept = event.event_type == event_type and callback() if accept: return catch_misses(event, force_fail=True) else: state.suppressed_events[:] = [event] return False remove = _add_hotkey_step(handler, steps[state.index], suppress) else: # Fix value of next_index. def handler(event, new_index=state.index+1): if event.event_type == KEY_UP: remove() set_index(new_index) state.suppressed_events.append(event) return False remove = _add_hotkey_step(handler, steps[state.index], suppress) state.remove_last_step = remove state.last_update = _time.monotonic() return False set_index(0) allowed_keys_by_step = [ set().union(*step) for step in steps ] def remove_(): state.remove_catch_misses() state.remove_last_step() del _hotkeys[hotkey] del _hotkeys[remove_] del _hotkeys[callback] # TODO: allow multiple callbacks for each hotkey without overwriting the # remover. _hotkeys[hotkey] = _hotkeys[remove_] = _hotkeys[callback] = remove_ return remove_ register_hotkey = add_hotkey def remove_hotkey(hotkey_or_callback): """ Removes a previously hooked hotkey. Must be called wtih the value returned by `add_hotkey`. """ _hotkeys[hotkey_or_callback]() unregister_hotkey = clear_hotkey = remove_hotkey def unhook_all_hotkeys(): """ Removes all keyboard hotkeys in use, including abbreviations, word listeners, `record`ers and `wait`s. """ # Because of "alises" some hooks may have more than one entry, all of which # are removed together. _listener.blocking_hotkeys.clear() _listener.nonblocking_hotkeys.clear() unregister_all_hotkeys = remove_all_hotkeys = clear_all_hotkeys = unhook_all_hotkeys def remap_hotkey(src, dst, suppress=True, trigger_on_release=False): """ Whenever the hotkey `src` is pressed, suppress it and send `dst` instead. Example: remap('alt+w', 'ctrl+up') """ def handler(): active_modifiers = sorted(modifier for modifier, state in _listener.modifier_states.items() if state == 'allowed') for modifier in active_modifiers: release(modifier) send(dst) for modifier in reversed(active_modifiers): press(modifier) return False return add_hotkey(src, handler, suppress=suppress, trigger_on_release=trigger_on_release) unremap_hotkey = remove_hotkey def stash_state(): """ Builds a list of all currently pressed scan codes, releases them and returns the list. Pairs well with `restore_state` and `restore_modifiers`. """ # TODO: stash caps lock / numlock /scrollock state. with _pressed_events_lock: state = sorted(_pressed_events) for scan_code in state: _os_keyboard.release(scan_code) return state def restore_state(scan_codes): """ Given a list of scan_codes ensures these keys, and only these keys, are pressed. Pairs well with `stash_state`, alternative to `restore_modifiers`. """ _listener.is_replaying = True with _pressed_events_lock: current = set(_pressed_events) target = set(scan_codes) for scan_code in current - target: _os_keyboard.release(scan_code) for scan_code in target - current: _os_keyboard.press(scan_code) _listener.is_replaying = False def restore_modifiers(scan_codes): """ Like `restore_state`, but only restores modifier keys. """ restore_state((scan_code for scan_code in scan_codes if is_modifier(scan_code))) def write(text, delay=0, restore_state_after=True, exact=None): """ 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, and modifiers are restored afterwards. - `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. - `exact` forces typing all characters as explicit unicode (e.g. alt+codepoint or special events). If None, uses platform-specific suggested value. """ if exact is None: exact = _platform.system() == 'Windows' state = stash_state() # Window's typing of unicode characters is quite efficient and should be preferred. if exact: for letter in text: if letter in '\n\b': send(letter) else: _os_keyboard.type_unicode(letter) if delay: _time.sleep(delay) else: for letter in text: try: entries = _os_keyboard.map_name(normalize_name(letter)) scan_code, modifiers = next(iter(entries)) except (KeyError, ValueError): _os_keyboard.type_unicode(letter) continue for modifier in modifiers: press(modifier) _os_keyboard.press(scan_code) _os_keyboard.release(scan_code) for modifier in modifiers: release(modifier) if delay: _time.sleep(delay) if restore_state_after: restore_modifiers(state) def wait(hotkey=None, suppress=False, trigger_on_release=False): """ Blocks the program execution until the given hotkey is pressed or, if given no parameters, blocks forever. """ if hotkey: lock = _Event() remove = add_hotkey(hotkey, lambda: lock.set(), suppress=suppress, trigger_on_release=trigger_on_release) lock.wait() remove_hotkey(remove) else: while True: _time.sleep(1e6) def get_hotkey_name(names=None): """ Returns a string representation of hotkey from the given key names, or the currently pressed keys if not given. This function: - normalizes names; - removes "left" and "right" prefixes; - replaces the "+" key name with "plus" to avoid ambiguity; - puts modifier keys first, in a standardized order; - sort remaining keys; - finally, joins everything with "+". Example: get_hotkey_name(['+', 'left ctrl', 'shift']) # "ctrl+shift+plus" """ if names is None: _listener.start_if_necessary() with _pressed_events_lock: names = [e.name for e in _pressed_events.values()] else: names = [normalize_name(name) for name in names] clean_names = set(e.replace('left ', '').replace('right ', '').replace('+', 'plus') for e in names) # https://developer.apple.com/macos/human-interface-guidelines/input-and-output/keyboard/ # > List modifier keys in the correct order. If you use more than one modifier key in a # > hotkey, always list them in this order: Control, Option, Shift, Command. modifiers = ['ctrl', 'alt', 'shift', 'windows'] sorting_key = lambda k: (modifiers.index(k) if k in modifiers else 5, str(k)) return '+'.join(sorted(clean_names, key=sorting_key)) def read_event(suppress=False): """ Blocks until a keyboard event happens, then returns that event. """ queue = _queue.Queue(maxsize=1) hooked = hook(queue.put, suppress=suppress) while True: event = queue.get() unhook(hooked) return event def read_key(suppress=False): """ Blocks until a keyboard event happens, then returns that event's name or, if missing, its scan code. """ event = read_event(suppress) return event.name or event.scan_code def read_hotkey(suppress=True): """ Similar to `read_key()`, but blocks until the user presses and releases a hotkey (or single key), then returns a string representing the hotkey pressed. Example: read_hotkey() # "ctrl+shift+p" """ queue = _queue.Queue() fn = lambda e: queue.put(e) or e.event_type == KEY_DOWN hooked = hook(fn, suppress=suppress) while True: event = queue.get() if event.event_type == KEY_UP: unhook(hooked) with _pressed_events_lock: names = [e.name for e in _pressed_events.values()] + [event.name] return get_hotkey_name(names) def get_typed_strings(events, allow_backspace=True): """ 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. This function is a generator, so you can pass an infinite stream of events and convert them to strings in real time. Note this functions is merely an heuristic. Windows for example keeps per- process keyboard state such as keyboard layout, and this information is not available for our hooks. get_type_strings(record()) #-> ['This is what', 'I recorded', ''] """ backspace_name = 'delete' if _platform.system() == 'Darwin' else 'backspace' shift_pressed = False capslock_pressed = False string = '' for event in events: name = event.name # Space is the only key that we _parse_hotkey to the spelled out name # because of legibility. Now we have to undo that. if event.name == 'space': name = ' ' if 'shift' in event.name: shift_pressed = event.event_type == 'down' elif event.name == 'caps lock' and event.event_type == 'down': capslock_pressed = not capslock_pressed elif allow_backspace and event.name == backspace_name and event.event_type == 'down': string = string[:-1] elif event.event_type == 'down': if len(name) == 1: if shift_pressed ^ capslock_pressed: name = name.upper() string = string + name else: yield string string = '' yield string _recording = None def start_recording(recorded_events_queue=None): """ Starts recording all keyboard events into a global variable, or the given queue if any. Returns the queue of events and the hooked function. Use `stop_recording()` or `unhook(hooked_function)` to stop. """ recorded_events_queue = recorded_events_queue or _queue.Queue() global _recording _recording = (recorded_events_queue, hook(recorded_events_queue.put)) return _recording def stop_recording(): """ Stops the global recording of events and returns a list of the events captured. """ global _recording if not _recording: raise ValueError('Must call "start_recording" before.') recorded_events_queue, hooked = _recording unhook(hooked) return list(recorded_events_queue.queue) def record(until='escape', suppress=False, trigger_on_release=False): """ Records all keyboard events from all keyboards until the user presses the given hotkey. Then returns the list of events recorded, of type `keyboard.KeyboardEvent`. Pairs well with `play(events)`. Note: this is a blocking function. Note: for more details on the keyboard hook and events see `hook`. """ start_recording() wait(until, suppress=suppress, trigger_on_release=trigger_on_release) return stop_recording() def play(events, speed_factor=1.0): """ 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()`. Note: the current keyboard state is cleared at the beginning and restored at the end of the function. """ state = stash_state() last_time = None for event in events: if speed_factor > 0 and last_time is not None: _time.sleep((event.time - last_time) / speed_factor) last_time = event.time key = event.scan_code or event.name press(key) if event.event_type == KEY_DOWN else release(key) restore_modifiers(state) replay = play _word_listeners = {} def add_word_listener(word, callback, triggers=['space'], match_suffix=False, timeout=2): """ 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 the trigger is only `space`. - `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)` or `remove_word_listener(handler)`. Note: all actions are performed on key down. Key up events are ignored. Note: word mathes are **case sensitive**. """ state = _State() state.current = '' state.time = -1 def handler(event): name = event.name if event.event_type == KEY_UP or name in all_modifiers: return if timeout and event.time - state.time > timeout: state.current = '' state.time = event.time matched = state.current == word or (match_suffix and state.current.endswith(word)) if name in triggers and matched: callback() state.current = '' elif len(name) > 1: state.current = '' else: state.current += name hooked = hook(handler) def remove(): hooked() del _word_listeners[word] del _word_listeners[handler] del _word_listeners[remove] _word_listeners[word] = _word_listeners[handler] = _word_listeners[remove] = remove # TODO: allow multiple word listeners and removing them correctly. return remove def remove_word_listener(word_or_handler): """ 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` or `add_abbreviation` functions. """ _word_listeners[word_or_handler]() def add_abbreviation(source_text, replacement_text, match_suffix=False, timeout=2): """ 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`. """ replacement = '\b'*(len(source_text)+1) + replacement_text callback = lambda: write(replacement) return add_word_listener(source_text, callback, match_suffix=match_suffix, timeout=timeout) # Aliases. register_word_listener = add_word_listener register_abbreviation = add_abbreviation remove_abbreviation = remove_word_listener