0
# Command Line Scripts
1
2
Command-line utilities for registering and activating argcomplete completion for Python scripts. These tools help set up completion for individual scripts or enable global completion support.
3
4
## Entry Points
5
6
After installing argcomplete, the following command-line utilities are available:
7
8
### register-python-argcomplete
9
10
Register individual Python scripts for tab completion.
11
12
**Usage:**
13
```bash
14
register-python-argcomplete [options] executable [executable ...]
15
```
16
17
**Options:**
18
- `--shell SHELL`: Target shell (bash, zsh, fish, tcsh, powershell)
19
- `--complete-arguments ARGS`: Custom completion arguments
20
- `--no-defaults`: Disable default completion fallback
21
- `--external-argcomplete-script SCRIPT`: Use external completion script
22
23
**Examples:**
24
25
```bash
26
# Basic registration (bash)
27
eval "$(register-python-argcomplete my-script.py)"
28
29
# Register for zsh
30
eval "$(register-python-argcomplete --shell zsh my-script.py)"
31
32
# Register for fish (save to file)
33
register-python-argcomplete --shell fish my-script.py > ~/.config/fish/completions/my-script.py.fish
34
35
# Register multiple scripts
36
eval "$(register-python-argcomplete my-script.py my-other-script.py)"
37
38
# Custom completion arguments
39
eval "$(register-python-argcomplete --complete-arguments '-o nospace' my-script.py)"
40
```
41
42
**Advanced Usage:**
43
44
```bash
45
# Use external completion script
46
eval "$(register-python-argcomplete --external-argcomplete-script my-completion-handler my-script.py)"
47
48
# PowerShell registration
49
register-python-argcomplete --shell powershell my-script.py | Out-String | Invoke-Expression
50
```
51
52
### activate-global-python-argcomplete
53
54
Enable global completion for all Python scripts that support argcomplete.
55
56
**Usage:**
57
```bash
58
activate-global-python-argcomplete [options]
59
```
60
61
**Options:**
62
- `--dest DEST`: Destination directory for completion files
63
- `--shell SHELL`: Target shell (bash, zsh)
64
- `--user`: Install for current user only
65
- `--complete-arguments ARGS`: Custom completion arguments
66
67
**Examples:**
68
69
```bash
70
# Enable global completion (requires sudo for system-wide)
71
sudo activate-global-python-argcomplete
72
73
# Enable for current user only
74
activate-global-python-argcomplete --user
75
76
# Enable for zsh
77
activate-global-python-argcomplete --shell zsh --user
78
79
# Custom destination
80
activate-global-python-argcomplete --dest ~/.bash_completion.d --user
81
```
82
83
**What it does:**
84
- Installs completion files to standard locations
85
- Modifies shell configuration files to source completion
86
- Enables completion for any script with `# PYTHON_ARGCOMPLETE_OK` comment
87
88
### python-argcomplete-check-easy-install-script
89
90
Verify that easy_install scripts are properly set up for argcomplete.
91
92
**Usage:**
93
```bash
94
python-argcomplete-check-easy-install-script script-name
95
```
96
97
**Purpose:**
98
- Checks if scripts installed via easy_install have proper argcomplete headers
99
- Verifies that the `# PYTHON_ARGCOMPLETE_OK` marker is present
100
- Helps diagnose completion issues with installed packages
101
102
**Example:**
103
```bash
104
python-argcomplete-check-easy-install-script my-installed-tool
105
```
106
107
## Script Requirements
108
109
### Python Script Setup
110
111
For scripts to work with argcomplete, they need:
112
113
1. **Argcomplete marker comment** (first or second line):
114
```python
115
#!/usr/bin/env python
116
# PYTHON_ARGCOMPLETE_OK
117
118
import argparse
119
import argcomplete
120
```
121
122
2. **Argcomplete integration**:
123
```python
124
parser = argparse.ArgumentParser()
125
# Add arguments...
126
127
argcomplete.autocomplete(parser) # Must be before parse_args()
128
args = parser.parse_args()
129
```
130
131
### Installation Verification
132
133
Check if completion is working:
134
135
```bash
136
# Test completion (should show available options)
137
my-script --<TAB><TAB>
138
139
# Debug completion
140
_ARC_DEBUG=1 my-script --<TAB>
141
```
142
143
## Integration Examples
144
145
### Bash Integration
146
147
#### Individual Script Registration
148
149
```bash
150
# Add to ~/.bashrc or ~/.bash_profile
151
eval "$(register-python-argcomplete my-project-cli)"
152
```
153
154
#### Global Registration
155
156
```bash
157
# System-wide (requires sudo)
158
sudo activate-global-python-argcomplete
159
160
# User-specific
161
activate-global-python-argcomplete --user
162
```
163
164
### Zsh Integration
165
166
#### Individual Script
167
168
```zsh
169
# Add to ~/.zshrc
170
eval "$(register-python-argcomplete --shell zsh my-script)"
171
```
172
173
#### Global Setup
174
175
```zsh
176
# Enable global completion
177
activate-global-python-argcomplete --shell zsh --user
178
179
# Add to ~/.zshrc if not done automatically
180
fpath=(~/.local/share/zsh/site-functions $fpath)
181
autoload -U compinit && compinit
182
```
183
184
### Fish Integration
185
186
```fish
187
# Save completion to fish config
188
register-python-argcomplete --shell fish my-script > ~/.config/fish/completions/my-script.fish
189
190
# Reload fish completions
191
fish -c "complete --erase; complete --reload"
192
```
193
194
### Package Integration
195
196
For distributable packages, include completion setup in installation:
197
198
**setup.py example:**
199
```python
200
from setuptools import setup
201
202
setup(
203
name="my-package",
204
entry_points={
205
'console_scripts': [
206
'my-tool=my_package.cli:main',
207
],
208
},
209
# Optional: Include completion setup in post-install
210
)
211
```
212
213
**Post-install message:**
214
```python
215
print("""
216
To enable tab completion, run:
217
eval "$(register-python-argcomplete my-tool)"
218
219
Or add this line to your ~/.bashrc
220
""")
221
```
222
223
### Docker Integration
224
225
For containerized applications:
226
227
```dockerfile
228
# Install argcomplete
229
RUN pip install argcomplete
230
231
# Enable completion in container
232
RUN activate-global-python-argcomplete --user
233
234
# Set up environment
235
ENV PYTHONPATH=/app
236
ENV _ARC_DEBUG=1 # Optional: for debugging
237
```
238
239
## Troubleshooting
240
241
### Common Issues
242
243
1. **Completion not working:**
244
```bash
245
# Check if script has proper marker
246
head -n 5 my-script.py | grep -i argcomplete
247
248
# Verify registration
249
type _python_argcomplete_my_script
250
```
251
252
2. **Debug completion issues:**
253
```bash
254
# Enable debug output
255
_ARC_DEBUG=1 my-script --<TAB>
256
257
# Check environment variables
258
env | grep -i comp
259
env | grep -i argcomplete
260
```
261
262
3. **Shell-specific issues:**
263
```bash
264
# Bash: Check completion loading
265
complete -p my-script
266
267
# Zsh: Check function definition
268
which _python_argcomplete_my_script
269
270
# Fish: List completions
271
complete -C my-script
272
```
273
274
### Performance Issues
275
276
For slow completion:
277
278
```bash
279
# Profile completion time
280
time (my-script --<TAB> 2>/dev/null)
281
282
# Enable debug to see what's slow
283
_ARC_DEBUG=1 my-script --<TAB>
284
```
285
286
### Permission Issues
287
288
For global installation issues:
289
290
```bash
291
# Use user installation instead
292
activate-global-python-argcomplete --user
293
294
# Check destination permissions
295
ls -la /etc/bash_completion.d/
296
ls -la ~/.bash_completion.d/
297
```