0
# Completers
1

2
Built-in completer classes that provide different completion strategies for various argument types. Completers can be assigned to specific arguments to customize their completion behavior.
3

4
## Capabilities
5

6
### Base Completer
7

8
Abstract base class that all argcomplete completers should inherit from.
9

10
```python { .api }
11
class BaseCompleter:
12
    def __call__(
13
        self, 
14
        *, 
15
        prefix: str, 
16
        action: argparse.Action, 
17
        parser: argparse.ArgumentParser, 
18
        parsed_args: argparse.Namespace
19
    ) -> None:
20
        """
21
        Generate completions for the given prefix.
22
        
23
        Parameters:
24
        - prefix: The partial string being completed
25
        - action: The argparse action being completed
26
        - parser: The argument parser instance
27
        - parsed_args: Already parsed arguments
28
        
29
        Returns:
30
        - Iterator or list of completion strings
31
        """
32
```
33

34
### Choice Completion
35

36
Completer for predefined choices, useful for arguments with a fixed set of valid values.
37

38
```python { .api }
39
class ChoicesCompleter(BaseCompleter):
40
    def __init__(self, choices):
41
        """
42
        Create completer for predefined choices.
43
        
44
        Parameters:
45
        - choices: Iterable of valid choices
46
        """
47
    
48
    def __call__(self, **kwargs):
49
        """Returns completions matching the choices."""
50
```
51

52
**Usage:**
53

54
```python
55
import argparse
56
import argcomplete
57
from argcomplete import ChoicesCompleter
58

59
parser = argparse.ArgumentParser()
60
parser.add_argument('--format', choices=['json', 'xml', 'yaml'])
61

62
# Use built-in choices completion (automatic)
63
# or explicitly assign:
64
parser.add_argument('--level').completer = ChoicesCompleter(['debug', 'info', 'warning', 'error'])
65

66
argcomplete.autocomplete(parser)
67
```
68

69
### File Completion
70

71
Completer for file and directory paths with optional filtering by file extensions.
72

73
```python { .api }
74
class FilesCompleter(BaseCompleter):
75
    def __init__(self, allowednames=(), directories=True):
76
        """
77
        Create file completer with optional filtering.
78
        
79
        Parameters:
80
        - allowednames: Tuple/list of allowed file extensions (without dots)
81
        - directories: Whether to include directories in completion
82
        """
83
    
84
    def __call__(self, prefix, **kwargs):
85
        """Returns file and directory completions matching the prefix."""
86
```
87

88
**Usage:**
89

90
```python
91
from argcomplete import FilesCompleter
92

93
# Complete any files and directories
94
parser.add_argument('--input').completer = FilesCompleter()
95

96
# Complete only Python files and directories
97
parser.add_argument('--script').completer = FilesCompleter(
98
    allowednames=('py', 'pyw'), 
99
    directories=True
100
)
101

102
# Complete only files, no directories
103
parser.add_argument('--data').completer = FilesCompleter(directories=False)
104

105
# Complete multiple file types
106
parser.add_argument('--config').completer = FilesCompleter(
107
    allowednames=('json', 'yaml', 'yml', 'toml')
108
)
109
```
110

111
### Directory Completion
112

113
Specialized completer that only completes directories, not files.
114

115
```python { .api }
116
class DirectoriesCompleter(BaseCompleter):
117
    def __init__(self):
118
        """Create directory-only completer."""
119
```
120

121
**Usage:**
122

123
```python
124
from argcomplete import DirectoriesCompleter
125

126
parser.add_argument('--output-dir').completer = DirectoriesCompleter()
127
parser.add_argument('--workdir').completer = DirectoriesCompleter()
128
```
129

130
### Environment Variable Completion
131

132
Pre-configured completer for environment variable names.
133

134
```python { .api }
135
EnvironCompleter: ChoicesCompleter  # Pre-instantiated with os.environ keys
136
```
137

138
**Usage:**
139

140
```python
141
from argcomplete import EnvironCompleter
142

143
parser.add_argument('--env-var').completer = EnvironCompleter
144
```
145

146
### Suppress Completion
147

148
Completer that suppresses completion for specific arguments.
149

150
```python { .api }
151
class SuppressCompleter(BaseCompleter):
152
    def __init__(self):
153
        """Create completer that suppresses completion."""
154
    
155
    def suppress(self) -> bool:
156
        """Returns True to indicate completion should be suppressed."""
157
```
158

159
**Usage:**
160

161
```python
162
from argcomplete import SuppressCompleter
163

164
# Disable completion for sensitive arguments
165
parser.add_argument('--password').completer = SuppressCompleter()
166
parser.add_argument('--secret-key').completer = SuppressCompleter()
167
```
168

169
## Custom Completers
170

171
### Creating Custom Completers
172

173
You can create custom completers by inheriting from BaseCompleter:
174

175
```python
176
import subprocess
177
from argcomplete import BaseCompleter
178

179
class GitBranchCompleter(BaseCompleter):
180
    def __call__(self, prefix, **kwargs):
181
        try:
182
            output = subprocess.check_output(
183
                ['git', 'branch', '--format=%(refname:short)'], 
184
                universal_newlines=True
185
            )
186
            branches = output.strip().split('\n')
187
            return [branch for branch in branches if branch.startswith(prefix)]
188
        except subprocess.CalledProcessError:
189
            return []
190

191
# Use the custom completer
192
parser.add_argument('--branch').completer = GitBranchCompleter()
193
```
194

195
### Dynamic Completers
196

197
Completers can use parsed arguments to provide context-sensitive completion:
198

199
```python
200
class ContextCompleter(BaseCompleter):
201
    def __call__(self, prefix, action, parser, parsed_args, **kwargs):
202
        if parsed_args.mode == 'development':
203
            return ['debug', 'trace', 'verbose']
204
        elif parsed_args.mode == 'production':
205
            return ['error', 'warning', 'info']
206
        return []
207

208
parser.add_argument('--mode', choices=['development', 'production'])
209
parser.add_argument('--log-level').completer = ContextCompleter()
210
```
211

212
### Completer with Descriptions
213

214
Completers can return dictionaries to provide descriptions for completions:
215

216
```python
217
class DocumentedCompleter(BaseCompleter):
218
    def __call__(self, prefix, **kwargs):
219
        options = {
220
            'fast': 'Quick processing with basic features',
221
            'thorough': 'Complete processing with all features',
222
            'balanced': 'Good balance of speed and features'
223
        }
224
        return {k: v for k, v in options.items() if k.startswith(prefix)}
225

226
parser.add_argument('--mode').completer = DocumentedCompleter()
227
```
228

229
## Best Practices
230

231
### Performance Considerations
232

233
- Keep completion fast (< 100ms) to maintain responsiveness
234
- Cache expensive operations when possible
235
- Handle exceptions gracefully to prevent completion failures
236

237
```python
238
class CachedCompleter(BaseCompleter):
239
    def __init__(self):
240
        self._cache = None
241
        self._cache_time = 0
242
    
243
    def __call__(self, prefix, **kwargs):
244
        import time
245
        now = time.time()
246
        
247
        if self._cache is None or now - self._cache_time > 60:
248
            self._cache = self._fetch_completions()
249
            self._cache_time = now
250
        
251
        return [item for item in self._cache if item.startswith(prefix)]
252
```
253

254
### Error Handling
255

256
```python
257
class RobustCompleter(BaseCompleter):
258
    def __call__(self, prefix, **kwargs):
259
        try:
260
            return self._get_completions(prefix)
261
        except Exception:
262
            # Fall back to no completions rather than breaking completion
263
            return []
264
```