0
# Keyboard Input
1
2
Comprehensive keyboard automation including key presses, text typing, and keyboard shortcuts with support for all standard keys, modifiers, and special characters. Provides precise control over key timing and supports both individual key operations and complex keyboard combinations.
3
4
## Capabilities
5
6
### Key Pressing
7
8
Press and release individual keys or key combinations with configurable timing and repetition.
9
10
```python { .api }
11
def press(keys, presses=1, interval=0.0, logScreenshot=None, _pause=True):
12
"""
13
Press and release key(s) one or more times.
14
15
Parameters:
16
- keys (str or list): Key name(s) to press. Can be single key or list of keys
17
- presses (int): Number of times to press the key(s) (default: 1)
18
- interval (float): Seconds to wait between key presses (default: 0.0)
19
- logScreenshot (bool): Log screenshot for debugging (default: None)
20
- _pause (bool): Apply global PAUSE after operation (default: True)
21
22
Returns:
23
None
24
25
Examples:
26
press('enter')
27
press(['ctrl', 'c'])
28
press('a', presses=3, interval=0.1)
29
"""
30
31
def keyDown(key, logScreenshot=None, _pause=True):
32
"""
33
Press key down without releasing.
34
35
Parameters:
36
- key (str): Key name to press down
37
- logScreenshot (bool): Log screenshot for debugging (default: None)
38
- _pause (bool): Apply global PAUSE after operation (default: True)
39
40
Returns:
41
None
42
"""
43
44
def keyUp(key, logScreenshot=None, _pause=True):
45
"""
46
Release key without pressing.
47
48
Parameters:
49
- key (str): Key name to release
50
- logScreenshot (bool): Log screenshot for debugging (default: None)
51
- _pause (bool): Apply global PAUSE after operation (default: True)
52
53
Returns:
54
None
55
"""
56
```
57
58
### Text Typing
59
60
Type text strings character by character with configurable timing between characters.
61
62
```python { .api }
63
def typewrite(message, interval=0.0, logScreenshot=None, _pause=True):
64
"""
65
Type text message character by character.
66
67
Parameters:
68
- message (str): Text to type
69
- interval (float): Seconds to wait between each character (default: 0.0)
70
- logScreenshot (bool): Log screenshot for debugging (default: None)
71
- _pause (bool): Apply global PAUSE after operation (default: True)
72
73
Returns:
74
None
75
76
Note: Only types printable characters. Use press() for special keys.
77
"""
78
79
def write(message, interval=0.0, logScreenshot=None, _pause=True):
80
"""Alias for typewrite() - type text message character by character."""
81
```
82
83
### Keyboard Shortcuts
84
85
Execute keyboard shortcuts by pressing multiple keys in sequence and releasing them in reverse order.
86
87
```python { .api }
88
def hotkey(*args, **kwargs):
89
"""
90
Perform keyboard shortcut by pressing keys in sequence, then releasing in reverse.
91
92
Parameters:
93
- *args: Key names to press in order (e.g., 'ctrl', 'c')
94
- **kwargs: Same parameters as press() (logScreenshot, _pause)
95
96
Returns:
97
None
98
99
Examples:
100
hotkey('ctrl', 'c') # Copy
101
hotkey('ctrl', 'shift', 's') # Save As
102
hotkey('alt', 'tab') # Switch windows
103
"""
104
105
def shortcut(*args, **kwargs):
106
"""Alias for hotkey() - perform keyboard shortcut."""
107
```
108
109
### Key State Management
110
111
Advanced key state control using context managers for holding keys during other operations.
112
113
```python { .api }
114
def hold(keys, logScreenshot=None, _pause=True):
115
"""
116
Context manager for holding key(s) down during other operations.
117
118
Parameters:
119
- keys (str or list): Key name(s) to hold down
120
- logScreenshot (bool): Log screenshot for debugging (default: None)
121
- _pause (bool): Apply global PAUSE after operation (default: True)
122
123
Returns:
124
Context manager
125
126
Example:
127
with pyautogui.hold('shift'):
128
pyautogui.press(['right', 'right', 'right']) # Select text
129
"""
130
```
131
132
### Key Validation
133
134
Utility functions to validate key names and check character requirements.
135
136
```python { .api }
137
def isValidKey(key):
138
"""
139
Check if key name is valid for the current platform.
140
141
Parameters:
142
- key (str): Key name to validate
143
144
Returns:
145
bool: True if key is valid, False otherwise
146
"""
147
148
def isShiftCharacter(character):
149
"""
150
Check if character requires shift key to type.
151
152
Parameters:
153
- character (str): Single character to check
154
155
Returns:
156
bool: True if character requires shift, False otherwise
157
"""
158
```
159
160
## Key Names
161
162
PyAutoGUI supports the following key names (case-insensitive):
163
164
### Letter Keys
165
```python { .api }
166
# All letters a-z (case insensitive)
167
KEY_LETTERS = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
168
'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z']
169
```
170
171
### Number Keys
172
```python { .api }
173
# Number keys 0-9
174
KEY_NUMBERS = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
175
```
176
177
### Function Keys
178
```python { .api }
179
# Function keys F1-F24
180
FUNCTION_KEYS = ['f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
181
'f11', 'f12', 'f13', 'f14', 'f15', 'f16', 'f17', 'f18', 'f19',
182
'f20', 'f21', 'f22', 'f23', 'f24']
183
```
184
185
### Modifier Keys
186
```python { .api }
187
MODIFIER_KEYS = [
188
'shift', 'shiftleft', 'shiftright',
189
'ctrl', 'ctrlleft', 'ctrlright', 'control',
190
'alt', 'altleft', 'altright', 'option',
191
'cmd', 'command', 'win', 'winleft', 'winright'
192
]
193
```
194
195
### Navigation Keys
196
```python { .api }
197
NAVIGATION_KEYS = [
198
'up', 'down', 'left', 'right', # Arrow keys
199
'home', 'end', 'pageup', 'pagedown', # Page navigation
200
'tab', 'enter', 'return', 'space', # Common navigation
201
'backspace', 'delete', 'insert' # Editing keys
202
]
203
```
204
205
### Special Keys
206
```python { .api }
207
SPECIAL_KEYS = [
208
'escape', 'esc', # Escape
209
'capslock', 'numlock', 'scrolllock', # Lock keys
210
'printscreen', 'pause', 'break', # System keys
211
'menu', 'apps', # Context menu keys
212
'select', 'execute', 'sleep' # Additional special keys
213
]
214
```
215
216
### Numpad Keys
217
```python { .api }
218
NUMPAD_KEYS = [
219
'num0', 'num1', 'num2', 'num3', 'num4', # Numpad numbers
220
'num5', 'num6', 'num7', 'num8', 'num9',
221
'multiply', 'add', 'separator', # Numpad operators
222
'subtract', 'decimal', 'divide'
223
]
224
```
225
226
### Complete Key List
227
```python { .api }
228
# All valid key names are available in:
229
KEY_NAMES: List[str] # Complete list of all valid key names
230
KEYBOARD_KEYS: List[str] # Alias for KEY_NAMES (backwards compatibility)
231
```
232
233
## Keyboard Layout Support
234
235
```python { .api }
236
# Keyboard layout mappings for international support
237
QWERTY: str # QWERTY keyboard layout character mapping
238
QWERTZ: str # QWERTZ keyboard layout character mapping
239
```
240
241
## Usage Examples
242
243
```python
244
import pyautogui
245
246
# Basic key pressing
247
pyautogui.press('enter') # Press Enter key
248
pyautogui.press('f1') # Press F1 function key
249
pyautogui.press('space', presses=3) # Press space 3 times
250
251
# Text typing
252
pyautogui.typewrite('Hello, World!') # Type text
253
pyautogui.typewrite('Slow typing', interval=0.1) # Type with delay
254
255
# Keyboard shortcuts
256
pyautogui.hotkey('ctrl', 'c') # Copy
257
pyautogui.hotkey('ctrl', 'v') # Paste
258
pyautogui.hotkey('alt', 'f4') # Close window
259
pyautogui.hotkey('ctrl', 'shift', 's') # Save As
260
261
# Advanced key control
262
pyautogui.keyDown('shift') # Hold shift
263
pyautogui.press(['right', 'right']) # Select text while holding
264
pyautogui.keyUp('shift') # Release shift
265
266
# Using context manager
267
with pyautogui.hold('ctrl'):
268
pyautogui.press('a') # Select all (Ctrl+A)
269
270
# Key validation
271
if pyautogui.isValidKey('f15'):
272
pyautogui.press('f15')
273
274
# Check if character needs shift
275
if pyautogui.isShiftCharacter('A'):
276
print("Capital A requires shift key")
277
278
# Complex typing with special keys
279
pyautogui.typewrite('Username: ')
280
pyautogui.typewrite('john_doe')
281
pyautogui.press('tab') # Move to next field
282
pyautogui.typewrite('password123')
283
pyautogui.press('enter') # Submit form
284
```
285
286
## Platform-Specific Notes
287
288
### Windows
289
- All standard keys supported
290
- Windows key available as 'win', 'winleft', 'winright'
291
- Context menu key available as 'menu' or 'apps'
292
293
### macOS
294
- Command key available as 'cmd' or 'command'
295
- Option key available as 'option' or 'alt'
296
- Some function keys may be intercepted by system
297
298
### Linux
299
- Key support depends on X11 implementation
300
- Some special keys may not be available
301
- Function key behavior varies by desktop environment