0
# Command Line Arguments
1
2
Comprehensive command-line argument parsing with filtering, grouping, and file/flag detection. The Args class provides chainable methods for finding, filtering, and extracting arguments with support for complex argument patterns and intelligent file/flag separation.
3
4
## Capabilities
5
6
### Basic Argument Access
7
8
Access arguments by index, check for existence, and retrieve argument values with safe fallbacks to None for missing arguments.
9
10
```python { .api }
11
class Args:
12
def __init__(self, args=None, no_argv=False):
13
"""
14
Initialize Args object.
15
16
Parameters:
17
- args: list, optional custom argument list (defaults to sys.argv[1:])
18
- no_argv: bool, if True creates empty Args object
19
"""
20
21
def get(self, x):
22
"""
23
Returns argument at given index, else None.
24
25
Parameters:
26
- x: int, index of argument to retrieve
27
28
Returns:
29
str or None: argument at index or None if not found
30
"""
31
32
def __getitem__(self, i):
33
"""Get argument by index, returns None if not found."""
34
35
def __len__(self):
36
"""Return number of arguments."""
37
38
def __contains__(self, x):
39
"""Check if argument exists in argument list."""
40
41
def __repr__(self):
42
"""Return string representation of Args object."""
43
```
44
45
### Argument Search and Filtering
46
47
Find arguments by value, search for arguments containing specific strings, and filter arguments based on various criteria.
48
49
```python { .api }
50
def contains(self, x):
51
"""
52
Tests if given object is in arguments list.
53
54
Parameters:
55
- x: str or list, value(s) to search for
56
57
Returns:
58
bool: True if found
59
"""
60
61
def first(self, x):
62
"""
63
Returns first found index of given value (or list of values).
64
65
Parameters:
66
- x: str or list, value(s) to find
67
68
Returns:
69
int or None: index of first match or None
70
"""
71
72
def first_with(self, x):
73
"""
74
Returns first found index containing value (or list of values).
75
76
Parameters:
77
- x: str or list, substring(s) to search for
78
79
Returns:
80
int or None: index of first containing match or None
81
"""
82
83
def first_without(self, x):
84
"""
85
Returns first found index not containing value (or list of values).
86
87
Parameters:
88
- x: str or list, substring(s) to exclude
89
90
Returns:
91
int or None: index of first non-matching argument or None
92
"""
93
94
def any_contain(self, x):
95
"""
96
Tests if given string is contained in any stored argument.
97
98
Parameters:
99
- x: str, substring to search for
100
101
Returns:
102
bool: True if substring found in any argument
103
"""
104
```
105
106
### Argument Retrieval and Collection
107
108
Retrieve multiple arguments based on search criteria and get related argument values.
109
110
```python { .api }
111
def get_with(self, x):
112
"""
113
Returns first argument that contains given string.
114
115
Parameters:
116
- x: str, substring to search for
117
118
Returns:
119
str: first argument containing substring
120
"""
121
122
def all_with(self, x):
123
"""
124
Returns all arguments containing given string (or list thereof).
125
126
Parameters:
127
- x: str or list, substring(s) to search for
128
129
Returns:
130
Args: new Args object with matching arguments
131
"""
132
133
def all_without(self, x):
134
"""
135
Returns all arguments not containing given string (or list thereof).
136
137
Parameters:
138
- x: str or list, substring(s) to exclude
139
140
Returns:
141
Args: new Args object with non-matching arguments
142
"""
143
144
def start_with(self, x):
145
"""
146
Returns all arguments beginning with given string (or list thereof).
147
148
Parameters:
149
- x: str or list, prefix(es) to match
150
151
Returns:
152
Args: new Args object with matching arguments
153
"""
154
155
def value_after(self, x):
156
"""
157
Returns value of argument after given found argument (or list thereof).
158
159
Parameters:
160
- x: str, argument to find
161
162
Returns:
163
str or None: argument following the found argument or None
164
"""
165
```
166
167
### Argument Modification
168
169
Remove arguments from the Args object and manipulate the argument list.
170
171
```python { .api }
172
def remove(self, x):
173
"""
174
Removes given arg (or list thereof) from Args object.
175
176
Parameters:
177
- x: str or list, argument(s) to remove
178
"""
179
180
def pop(self, x):
181
"""
182
Removes and returns value at given index, else None.
183
184
Parameters:
185
- x: int, index of argument to remove
186
187
Returns:
188
str or None: removed argument or None
189
"""
190
```
191
192
### Argument Properties and Grouping
193
194
Access collections of arguments with special properties and group arguments by flags.
195
196
```python { .api }
197
@property
198
def all(self):
199
"""
200
Returns all arguments.
201
202
Returns:
203
list: all arguments as list
204
"""
205
206
@property
207
def last(self):
208
"""
209
Returns last argument.
210
211
Returns:
212
str or None: last argument or None if empty
213
"""
214
215
@property
216
def flags(self):
217
"""
218
Returns Args object including only flagged arguments (starting with '-').
219
220
Returns:
221
Args: new Args object with only flag arguments
222
"""
223
224
@property
225
def not_flags(self):
226
"""
227
Returns Args object excluding flagged arguments.
228
229
Returns:
230
Args: new Args object without flag arguments
231
"""
232
233
@property
234
def grouped(self):
235
"""
236
Extracts --flag groups from argument list.
237
238
Returns:
239
OrderedDict: {flag: Args, '_': Args} mapping flags to their arguments
240
"""
241
```
242
243
### File and Path Handling
244
245
Intelligent file path detection and expansion with glob pattern support.
246
247
```python { .api }
248
@property
249
def files(self):
250
"""
251
Returns an expanded list of all valid paths that were passed in.
252
253
Returns:
254
list: list of valid file paths (relative paths as provided)
255
"""
256
257
@property
258
def not_files(self):
259
"""
260
Returns a list of all arguments that aren't files/globs.
261
262
Returns:
263
Args: new Args object with non-file arguments
264
"""
265
```
266
267
### Position and Context Testing
268
269
Test arguments at specific positions and check for contextual relationships.
270
271
```python { .api }
272
def contains_at(self, x, index):
273
"""
274
Tests if given [list of] string is at given index.
275
276
Parameters:
277
- x: str or list, value(s) to test
278
- index: int, position to check
279
280
Returns:
281
bool: True if value found at index
282
"""
283
284
def has(self, x):
285
"""
286
Returns true if argument exists at given index.
287
288
Parameters:
289
- x: int, index to check
290
291
Returns:
292
bool: True if argument exists at index
293
"""
294
295
@property
296
def copy(self):
297
"""
298
Returns a copy of Args object for temporary manipulation.
299
300
Returns:
301
Args: independent copy of current Args object
302
"""
303
```
304
305
## Usage Examples
306
307
```python
308
from clint.arguments import Args
309
310
# Basic usage
311
args = Args()
312
first_arg = args.get(0)
313
if first_arg:
314
print(f"First argument: {first_arg}")
315
316
# Check for flags
317
if '--verbose' in args:
318
print("Verbose mode enabled")
319
320
# Get all Python files
321
python_files = args.all_with('.py').files
322
print(f"Python files: {python_files}")
323
324
# Group arguments by flags
325
grouped = args.grouped
326
for flag, flag_args in grouped.items():
327
if flag != '_':
328
print(f"Flag {flag}: {flag_args.all}")
329
330
# Get value after a flag
331
output_file = args.value_after('--output')
332
if output_file:
333
print(f"Output file: {output_file}")
334
335
# Work with file arguments only
336
file_args = args.files
337
non_file_args = args.not_files.all
338
print(f"Files: {file_args}")
339
print(f"Other args: {non_file_args}")
340
```