0
# Shell Integration
1

2
Functions for generating shell-specific completion code that integrates argcomplete with various shell environments. The shell integration system generates the necessary shell code to bridge between the shell's completion system and Python-based completion logic.
3

4
## Capabilities
5

6
### Shell Code Generation
7

8
Generate shell-specific completion code for different shell environments.
9

10
```python { .api }
11
def shellcode(
12
    executables: List[str], 
13
    use_defaults: bool = True, 
14
    shell: str = "bash", 
15
    complete_arguments: Optional[List[str]] = None, 
16
    argcomplete_script: Optional[str] = None
17
) -> str
18
```
19

20
**Parameters:**
21
- `executables`: List of executable names to enable completion for
22
- `use_defaults`: Whether to fallback to readline's default completion (bash only)
23
- `shell`: Target shell ("bash", "zsh", "fish", "tcsh", "powershell")
24
- `complete_arguments`: Custom arguments for the complete command (bash only)
25
- `argcomplete_script`: Alternative script to call for completion
26

27
**Returns:**
28
- String containing shell code ready to be sourced or evaluated
29

30
**Usage:**
31

32
```python
33
from argcomplete import shellcode
34

35
# Generate bash completion code
36
bash_code = shellcode(['my-script', 'my-other-script'], shell='bash')
37
print(bash_code)
38

39
# Generate zsh completion code
40
zsh_code = shellcode(['my-script'], shell='zsh')
41

42
# Generate fish completion code
43
fish_code = shellcode(['my-script'], shell='fish')
44

45
# Disable default completions
46
code = shellcode(['my-script'], use_defaults=False)
47

48
# Custom complete arguments
49
code = shellcode(['my-script'], complete_arguments=['-o', 'nospace'])
50
```
51

52
## Shell-Specific Features
53

54
### Bash Integration
55

56
Generates bash completion code that integrates with the bash completion system:
57

58
```bash
59
# Example generated bash code
60
_python_argcomplete_my_script() {
61
    local IFS=$'\013'
62
    COMPREPLY=($(IFS="$IFS" \
63
        COMP_LINE="$COMP_LINE" \
64
        COMP_POINT="$COMP_POINT" \
65
        _ARGCOMPLETE=1 \
66
        _ARGCOMPLETE_SHELL="bash" \
67
        __python_argcomplete_run my-script))
68
}
69
complete -o nospace -o default -o bashdefault -F _python_argcomplete_my_script my-script
70
```
71

72
**Features:**
73
- Supports `COMP_WORDBREAKS` customization
74
- Handles space suppression for continuation characters
75
- Integrates with bash-completion system
76

77
### Zsh Integration
78

79
Generates zsh completion code using the `_describe` function:
80

81
```zsh
82
# Example generated zsh code
83
_python_argcomplete_my_script() {
84
    local completions
85
    completions=($(IFS="$IFS" \
86
        COMP_LINE="$BUFFER" \
87
        COMP_POINT="$CURSOR" \
88
        _ARGCOMPLETE=1 \
89
        _ARGCOMPLETE_SHELL="zsh" \
90
        __python_argcomplete_run my-script))
91
    _describe "my-script" completions
92
}
93
compdef _python_argcomplete_my_script my-script
94
```
95

96
**Features:**
97
- Uses zsh's `_describe` for rich completions with descriptions
98
- Handles cursor position mapping
99
- Supports zsh-specific completion features
100

101
### Fish Integration
102

103
Generates fish shell completion code:
104

105
```fish
106
# Example generated fish code
107
function __fish_my_script_complete
108
    set -x _ARGCOMPLETE 1
109
    set -x _ARGCOMPLETE_SHELL fish
110
    set -x COMP_LINE (commandline -p)
111
    set -x COMP_POINT (string length (commandline -cp))
112
    my-script 8>&1 9>&2 1>/dev/null 2>&1
113
end
114
complete --command my-script -f -a '(__fish_my_script_complete)'
115
```
116

117
**Features:**
118
- Uses fish's command line utilities
119
- Supports tab-separated descriptions
120
- Integrates with fish completion system
121

122
### PowerShell Integration
123

124
Generates PowerShell completion code using `Register-ArgumentCompleter`:
125

126
```powershell
127
# Example generated PowerShell code
128
Register-ArgumentCompleter -Native -CommandName my-script -ScriptBlock {
129
    param($commandName, $wordToComplete, $cursorPosition)
130
    $env:_ARGCOMPLETE = 1
131
    $env:_ARGCOMPLETE_SHELL = "powershell"
132
    $env:COMP_LINE = $wordToComplete
133
    $env:COMP_POINT = $cursorPosition
134
    my-script 2>&1 | Out-Null | ForEach-Object {
135
        [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
136
    }
137
}
138
```
139

140
### Tcsh Integration
141

142
Generates tcsh completion code:
143

144
```tcsh
145
# Example generated tcsh code
146
complete "my-script" 'p@*@`python-argcomplete-tcsh "my-script"`@' ;
147
```
148

149
## Advanced Usage
150

151
### Multiple Executables
152

153
Generate completion for multiple related scripts:
154

155
```python
156
code = shellcode([
157
    'my-tool',
158
    'my-tool-admin', 
159
    'my-tool-dev'
160
], shell='bash')
161
```
162

163
### Custom Completion Script
164

165
Use a different script for completion than the executable being completed:
166

167
```python
168
# All executables use the same completion script
169
code = shellcode(
170
    ['my-tool', 'my-tool-legacy'],
171
    argcomplete_script='my-tool-completion'
172
)
173
```
174

175
### Integration Examples
176

177
#### Register with Shell
178

179
```bash
180
# Bash
181
eval "$(python -c "from argcomplete import shellcode; print(shellcode(['my-script']))")"
182

183
# Or save to file
184
python -c "from argcomplete import shellcode; print(shellcode(['my-script']))" > my-script-completion.bash
185
source my-script-completion.bash
186
```
187

188
#### Zsh Setup
189

190
```zsh
191
# Add to .zshrc
192
eval "$(python -c "from argcomplete import shellcode; print(shellcode(['my-script'], shell='zsh'))")"
193
```
194

195
#### Fish Setup
196

197
```fish
198
# Save to completion file
199
python -c "from argcomplete import shellcode; print(shellcode(['my-script'], shell='fish'))" > ~/.config/fish/completions/my-script.fish
200
```
201

202
## Environment Variables
203

204
The shell integration relies on specific environment variables during completion:
205

206
### Core Variables
207
- `_ARGCOMPLETE`: Set to indicate completion mode
208
- `_ARGCOMPLETE_SHELL`: Target shell type
209
- `COMP_LINE`: Full command line being completed
210
- `COMP_POINT`: Cursor position in the command line
211

212
### Control Variables
213
- `_ARGCOMPLETE_SUPPRESS_SPACE`: Control space appending
214
- `_ARGCOMPLETE_IFS`: Internal field separator for completion output
215
- `_ARGCOMPLETE_DFS`: Description field separator
216
- `_ARGCOMPLETE_COMP_WORDBREAKS`: Word break characters
217
- `_ARC_DEBUG`: Enable debug output
218

219
### File Output Variables
220
- `_ARGCOMPLETE_STDOUT_FILENAME`: Redirect completion output to file
221
- `ARGCOMPLETE_USE_TEMPFILES`: Use temporary files for IPC
222

223
## Debugging Shell Integration
224

225
Enable debug output to troubleshoot completion issues:
226

227
```bash
228
export _ARC_DEBUG=1
229
my-script <TAB>  # Debug output will show in terminal
230
```
231

232
The debug output includes:
233
- Parsed command line components
234
- Active parsers and actions
235
- Generated completions
236
- Shell-specific processing steps