Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/face/parser.py: 58%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1import sys
2import shlex
3import codecs
4import os.path
5from collections import OrderedDict
6from typing import Optional
8from boltons.iterutils import split, unique
9from boltons.dictutils import OrderedMultiDict as OMD
10from boltons.funcutils import format_exp_repr, format_nonexp_repr
12from face.utils import (ERROR,
13 get_type_desc,
14 flag_to_identifier,
15 normalize_flag_name,
16 process_command_name,
17 get_minimal_executable)
18from face.errors import (FaceException,
19 ArgumentParseError,
20 ArgumentArityError,
21 InvalidSubcommand,
22 UnknownFlag,
23 DuplicateFlag,
24 InvalidFlagArgument,
25 InvalidPositionalArgument,
26 MissingRequiredFlags)
29def _arg_to_subcmd(arg):
30 return arg.lower().replace('-', '_')
33def _multi_error(flag, arg_val_list):
34 "Raise a DuplicateFlag if more than one value is specified for an argument"
35 if len(arg_val_list) > 1:
36 raise DuplicateFlag.from_parse(flag, arg_val_list)
37 return arg_val_list[0]
40def _multi_extend(flag, arg_val_list):
41 "Return a list of all arguments specified for a flag"
42 ret = [v for v in arg_val_list if v is not flag.missing]
43 return ret
46def _multi_override(flag, arg_val_list):
47 "Return only the last argument specified for a flag"
48 return arg_val_list[-1]
50# TODO: _multi_ignore?
52_MULTI_SHORTCUTS = {'error': _multi_error,
53 False: _multi_error,
54 'extend': _multi_extend,
55 True: _multi_extend,
56 'override': _multi_override}
59_VALID_CHARS = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!*+./?@_'
60def _validate_char(char):
61 orig_char = char
62 if char[0] == '-' and len(char) > 1:
63 char = char[1:]
64 if len(char) > 1:
65 raise ValueError('char flags must be exactly one character, optionally'
66 ' prefixed by a dash, not: %r' % orig_char)
67 if char not in _VALID_CHARS:
68 raise ValueError('expected valid flag character (ASCII letters, numbers,'
69 ' or shell-compatible punctuation), not: %r' % orig_char)
70 return char
73def _posargs_to_provides(posargspec, posargs):
74 '''Automatically unwrap injectable posargs into a more intuitive
75 format, similar to an API a human might design. For instance, a
76 function which takes exactly one argument would not take a list of
77 exactly one argument.
79 Cases as follows:
81 1. min_count > 1 or max_count > 1, pass through posargs as a list
82 2. max_count == 1 -> single argument or None
84 Even if min_count == 1, you can get a None back. This compromise
85 was made necessary to keep "to_cmd_scope" robust enough to pass to
86 help/error handler funcs when validation fails.
87 '''
88 # all of the following assumes a valid posargspec, with min_count
89 # <= max_count, etc.
90 pas = posargspec
91 if pas.max_count is None or pas.min_count > 1 or pas.max_count > 1:
92 return posargs
93 if pas.max_count == 1:
94 # None is considered sufficiently unambiguous, even for cases when pas.min_count==1
95 return posargs[0] if posargs else None
96 raise RuntimeError('invalid posargspec/posargs configuration %r -- %r'
97 % (posargspec, posargs)) # pragma: no cover (shouldn't get here)
100class CommandParseResult:
101 """The result of :meth:`Parser.parse`, instances of this type
102 semantically store all that a command line can contain. Each
103 argument corresponds 1:1 with an attribute.
105 Args:
106 name (str): Top-level program name, typically the first
107 argument on the command line, i.e., ``sys.argv[0]``.
108 subcmds (tuple): Sequence of subcommand names.
109 flags (OrderedDict): Mapping of canonical flag names to matched values.
110 posargs (tuple): Sequence of parsed positional arguments.
111 post_posargs (tuple): Sequence of parsed post-positional
112 arguments (args following ``--``)
113 parser (Parser): The Parser instance that parsed this
114 result. Defaults to None.
115 argv (tuple): The sequence of strings parsed by the Parser to
116 yield this result. Defaults to ``()``.
118 Instances of this class can be injected by accepting the ``args_``
119 builtin in their Command handler function.
121 """
122 def __init__(self, parser, argv=()):
123 self.parser = parser
124 self.argv = tuple(argv)
126 self.name = None # str
127 self.subcmds = None # tuple
128 self.flags = None # OrderedDict
129 self.posargs = None # tuple
130 self.post_posargs = None # tuple
132 def to_cmd_scope(self):
133 "returns a dict which can be used as kwargs in an inject call"
134 _subparser = self.parser.subprs_map[self.subcmds] if self.subcmds else self.parser
136 if not self.argv:
137 cmd_ = self.parser.name
138 else:
139 cmd_ = self.argv[0]
140 path, basename = os.path.split(cmd_)
141 if basename == '__main__.py':
142 pkg_name = os.path.basename(path)
143 executable_path = get_minimal_executable()
144 cmd_ = f'{executable_path} -m {pkg_name}'
145 else:
146 cmd_ = get_minimal_executable(cmd_)
148 ret = {'args_': self,
149 'cmd_': cmd_,
150 'subcmds_': self.subcmds,
151 'flags_': self.flags,
152 'posargs_': self.posargs,
153 'post_posargs_': self.post_posargs,
154 'subcommand_': _subparser,
155 'command_': self.parser}
156 if self.flags:
157 ret.update(self.flags)
159 prs = self.parser if not self.subcmds else self.parser.subprs_map[self.subcmds]
160 if prs.posargs.provides:
161 posargs_provides = _posargs_to_provides(prs.posargs, self.posargs)
162 ret[prs.posargs.provides] = posargs_provides
163 if prs.post_posargs.provides:
164 posargs_provides = _posargs_to_provides(prs.posargs, self.post_posargs)
165 ret[prs.post_posargs.provides] = posargs_provides
167 return ret
169 def __repr__(self):
170 return format_nonexp_repr(self, ['name', 'argv', 'parser'])
173# TODO: allow name="--flag / -F" and do the split for automatic
174# char form?
175class Flag:
176 """The Flag object represents all there is to know about a resource
177 that can be parsed from argv and consumed by a Command
178 function. It also references a FlagDisplay, used by HelpHandlers
179 to control formatting of the flag during --help output
181 Args:
182 name (str): A string name for the flag, starting with a letter,
183 and consisting of only ASCII letters, numbers, '-', and '_'.
184 parse_as: How to interpret the flag. If *parse_as* is a
185 callable, it will be called with the argument to the flag,
186 the return value of which is stored in the parse result. If
187 *parse_as* is not a callable, then the flag takes no
188 argument, and the presence of the flag will produce this
189 value in the parse result. Defaults to ``str``, meaning a
190 default flag will take one string argument.
191 missing: How to interpret the absence of the flag. Can be any
192 value, which will be in the parse result when the flag is not
193 present. Can also be the special value ``face.ERROR``, which
194 will make the flag required. Defaults to ``None``.
195 multi (str): How to handle multiple instances of the same
196 flag. Pass 'overwrite' to accept the last flag's value. Pass
197 'extend' to collect all values into a list. Pass 'error' to
198 get the default behavior, which raises a DuplicateFlag
199 exception. *multi* can also take a callable, which accepts a
200 list of flag values and returns the value to be stored in the
201 :class:`CommandParseResult`.
202 char (str): A single-character short form for the flag. Can be
203 user-friendly for commonly-used flags. Defaults to ``None``.
204 doc (str): A summary of the flag's behavior, used in automatic
205 help generation.
206 display: Controls how the flag is displayed in automatic help
207 generation. Pass False to hide the flag, pass a string to
208 customize the label, and pass a FlagDisplay instance for full
209 customizability.
210 """
211 def __init__(self, name, parse_as=str, missing=None, multi='error',
212 char=None, doc=None, display=None):
213 self.name = flag_to_identifier(name)
214 self.doc = doc
215 self.parse_as = parse_as
216 self.missing = missing
217 if missing is ERROR and not callable(parse_as):
218 raise ValueError('cannot make an argument-less flag required.'
219 ' expected non-ERROR for missing, or a callable'
220 ' for parse_as, not: %r' % parse_as)
221 self.char = _validate_char(char) if char else None
223 if callable(multi):
224 self.multi = multi
225 elif multi in _MULTI_SHORTCUTS:
226 self.multi = _MULTI_SHORTCUTS[multi]
227 else:
228 raise ValueError('multi expected callable, bool, or one of %r, not: %r'
229 % (list(_MULTI_SHORTCUTS.keys()), multi))
231 self.set_display(display)
233 def set_display(self, display):
234 """Controls how the flag is displayed in automatic help
235 generation. Pass False to hide the flag, pass a string to
236 customize the label, and pass a FlagDisplay instance for full
237 customizability.
238 """
239 if display is None:
240 display = {}
241 elif isinstance(display, bool):
242 display = {'hidden': not display}
243 elif isinstance(display, str):
244 display = {'label': display}
245 if isinstance(display, dict):
246 display = FlagDisplay(self, **display)
247 if not isinstance(display, FlagDisplay):
248 raise TypeError('expected bool, text name, dict of display'
249 ' options, or FlagDisplay instance, not: %r'
250 % display)
251 self.display = display
253 def __repr__(self):
254 return format_nonexp_repr(self, ['name', 'parse_as'], ['missing', 'multi'],
255 opt_key=lambda v: v not in (None, _multi_error))
258class FlagDisplay:
259 """Provides individual overrides for most of a given flag's display
260 settings, as used by HelpFormatter instances attached to Parser
261 and Command objects. Pass an instance of this to
262 Flag.set_display() for full control of help output.
264 FlagDisplay instances are meant to be used 1:1 with Flag
265 instances, as they maintain a reference back to their associated
266 Flag. They are generally automatically created by a Flag
267 constructor, based on the "display" argument.
269 Args:
270 flag (Flag): The Flag instance to which this FlagDisplay applies.
271 label (str): The formatted version of the string used to
272 represent the flag in help and error messages. Defaults to
273 None, which allows the label to be autogenerated by the
274 HelpFormatter.
275 post_doc (str): An addendum string added to the Flag's own
276 doc. Defaults to a parenthetical describing whether the flag
277 takes an argument, and whether the argument is required.
278 full_doc (str): A string of the whole flag's doc, overriding
279 the doc + post_doc default.
280 value_name (str): For flags which take an argument, the string
281 to use as the placeholder of the flag argument in help and
282 error labels.
283 hidden (bool): Pass True to hide this flag in general help and
284 error messages. Defaults to False.
285 group: An integer or string indicating how this flag should be
286 grouped in help messages, improving readability. Integers are
287 unnamed groups, strings are for named groups. Defaults to 0.
288 sort_key: Flags are sorted in help output, pass an integer or
289 string to override the sort order.
291 """
292 # value_name -> arg_name?
293 def __init__(self, flag, *,
294 label: Optional[str] = None,
295 post_doc: Optional[str] = None,
296 full_doc: Optional[str] = None,
297 value_name: Optional[str] = None,
298 group: int = 0,
299 hidden: bool = False,
300 sort_key: int = 0):
301 self.flag = flag
303 self.doc = flag.doc
304 if self.doc is None and callable(flag.parse_as):
305 _prep, desc = get_type_desc(flag.parse_as)
306 self.doc = 'Parsed with ' + desc
307 if _prep == 'as':
308 self.doc = desc
310 self.post_doc = post_doc
311 self.full_doc = full_doc
313 self.value_name = ''
314 if callable(flag.parse_as):
315 # TODO: use default when it's set and it's a basic renderable type
316 self.value_name = value_name or self.flag.name.upper()
318 self.group = group
319 self._hide = hidden
320 self.label = label # see hidden property below for more info
321 self.sort_key = sort_key
322 # TODO: sort_key is gonna need to be partitioned on type for py3
323 # TODO: maybe sort_key should be a counter so that flags sort
324 # in the order they are created
325 return
327 @property
328 def hidden(self):
329 return self._hide or self.label == ''
331 def __repr__(self):
332 return format_nonexp_repr(self, ['label', 'doc'], ['group', 'hidden'], opt_key=bool)
335class PosArgDisplay:
336 """Provides individual overrides for PosArgSpec display in automated
337 help formatting. Pass to a PosArgSpec constructor, which is in
338 turn passed to a Command/Parser.
340 Args:
341 spec (PosArgSpec): The associated PosArgSpec.
342 name (str): The string name of an individual positional
343 argument. Automatically pluralized in the label according to
344 PosArgSpec values. Defaults to 'arg'.
345 label (str): The full display label for positional arguments,
346 bypassing the automatic formatting of the *name* parameter.
347 doc (str): A summary description of the positional arguments.
348 post_doc (str): An informational addendum about the arguments,
349 often describes default behavior.
351 """
352 def __init__(self, *,
353 name: Optional[str] = None,
354 doc: str = '',
355 post_doc: Optional[str] = None,
356 hidden: bool = False,
357 label: Optional[str] = None) -> None:
358 self.name = name or 'arg'
359 self.doc = doc
360 self.post_doc = post_doc
361 self._hide = hidden
362 self.label = label
364 @property
365 def hidden(self):
366 return self._hide or self.label == ''
368 def __repr__(self):
369 return format_nonexp_repr(self, ['name', 'label'])
372class PosArgSpec:
373 """Passed to Command/Parser as posargs and post_posargs parameters to
374 configure the number and type of positional arguments.
376 Args:
377 parse_as (callable): A function to call on each of the passed
378 arguments. Also accepts special argument ERROR, which will raise
379 an exception if positional arguments are passed. Defaults to str.
380 min_count (int): A minimimum number of positional
381 arguments. Defaults to 0.
382 max_count (int): A maximum number of positional arguments. Also
383 accepts None, meaning no maximum. Defaults to None.
384 display: Pass a string to customize the name in help output, or
385 False to hide it completely. Also accepts a PosArgDisplay
386 instance, or a dict of the respective arguments.
387 provides (str): name of an argument to be passed to a receptive
388 handler function.
389 name (str): A shortcut to set *display* name and *provides*
390 count (int): A shortcut to set min_count and max_count to a single value
391 when an exact number of arguments should be specified.
393 PosArgSpec instances are stateless and safe to be used multiple
394 times around the application.
396 """
397 def __init__(self, parse_as=str, min_count=None, max_count=None, display=None, provides=None,
398 *, name: Optional[str] = None, count: Optional[int] = None):
399 if not callable(parse_as) and parse_as is not ERROR:
400 raise TypeError(f'expected callable or ERROR for parse_as, not {parse_as!r}')
402 self.parse_as = parse_as
404 # count convenience alias
405 min_count = count if min_count is None else min_count
406 max_count = count if max_count is None else max_count
408 self.min_count = int(min_count) if min_count else 0
409 self.max_count = int(max_count) if max_count is not None else None
411 if self.min_count < 0:
412 raise ValueError(f'expected min_count >= 0, not: {self.min_count!r}')
413 if self.max_count is not None and self.max_count <= 0:
414 raise ValueError(f'expected max_count > 0, not: {self.max_count!r}')
415 if self.max_count and self.min_count > self.max_count:
416 raise ValueError('expected min_count > max_count, not: %r > %r'
417 % (self.min_count, self.max_count))
419 provides = name if provides is None else provides
420 self.provides = provides
422 if display is None:
423 display = {}
424 elif isinstance(display, bool):
425 display = {'hidden': not display}
426 elif isinstance(display, str):
427 display = {'name': display}
428 if isinstance(display, dict):
429 display.setdefault('name', name)
430 display = PosArgDisplay(**display)
431 if not isinstance(display, PosArgDisplay):
432 raise TypeError('expected bool, text name, dict of display'
433 ' options, or PosArgDisplay instance, not: %r'
434 % display)
436 self.display = display
438 # TODO: default? type check that it's a sequence matching min/max reqs
440 def __repr__(self):
441 return format_nonexp_repr(self, ['parse_as', 'min_count', 'max_count', 'display'])
443 @property
444 def accepts_args(self):
445 """True if this PosArgSpec is configured to accept one or
446 more arguments.
447 """
448 return self.parse_as is not ERROR
450 def parse(self, posargs):
451 """Parse a list of strings as positional arguments.
453 Args:
454 posargs (list): List of strings, likely parsed by a Parser
455 instance from sys.argv.
457 Raises an ArgumentArityError if there are too many or too few
458 arguments.
460 Raises InvalidPositionalArgument if the argument doesn't match
461 the configured *parse_as*. See PosArgSpec for more info.
463 Returns a list of arguments, parsed with *parse_as*.
464 """
465 len_posargs = len(posargs)
466 if posargs and not self.accepts_args:
467 # TODO: check for likely subcommands
468 raise ArgumentArityError(f'unexpected positional arguments: {posargs!r}')
469 min_count, max_count = self.min_count, self.max_count
470 if min_count == max_count:
471 # min_count must be >0 because max_count cannot be 0
472 arg_range_text = f'{min_count} argument'
473 if min_count > 1:
474 arg_range_text += 's'
475 else:
476 if min_count == 0:
477 arg_range_text = f'up to {max_count} argument'
478 arg_range_text += 's' if (max_count and max_count > 1) else ''
479 elif max_count is None:
480 arg_range_text = f'at least {min_count} argument'
481 arg_range_text += 's' if min_count > 1 else ''
482 else:
483 arg_range_text = f'{min_count} - {max_count} arguments'
485 if len_posargs < min_count:
486 raise ArgumentArityError('too few arguments, expected %s, got %s'
487 % (arg_range_text, len_posargs))
488 if max_count is not None and len_posargs > max_count:
489 raise ArgumentArityError('too many arguments, expected %s, got %s'
490 % (arg_range_text, len_posargs))
491 ret = []
492 for pa in posargs:
493 try:
494 val = self.parse_as(pa)
495 except Exception as exc:
496 raise InvalidPositionalArgument.from_parse(self, pa, exc)
497 else:
498 ret.append(val)
499 return ret
502FLAGFILE_ENABLED = Flag('--flagfile', parse_as=str, multi='extend', missing=None, display=False, doc='')
505def _ensure_posargspec(posargs, posargs_name):
506 if not posargs:
507 # take no posargs
508 posargs = PosArgSpec(parse_as=ERROR)
509 elif posargs is True:
510 # take any number of posargs
511 posargs = PosArgSpec()
512 elif isinstance(posargs, int):
513 # take an exact number of posargs
514 # (True and False are handled above, so only real nonzero ints get here)
515 posargs = PosArgSpec(min_count=posargs, max_count=posargs)
516 elif isinstance(posargs, str):
517 posargs = PosArgSpec(display=posargs, provides=posargs)
518 elif isinstance(posargs, dict):
519 posargs = PosArgSpec(**posargs)
520 elif callable(posargs):
521 # take any number of posargs of a given format
522 posargs = PosArgSpec(parse_as=posargs)
524 if not isinstance(posargs, PosArgSpec):
525 raise TypeError('expected %s as True, False, number of args, text name of args,'
526 ' dict of PosArgSpec options, or instance of PosArgSpec, not: %r'
527 % (posargs_name, posargs))
529 return posargs
532class Parser:
533 """The Parser lies at the center of face, primarily providing a
534 configurable validation logic on top of the conventional grammar
535 for CLI argument parsing.
537 Args:
538 name (str): A name used to identify this command. Important
539 when the command is embedded as a subcommand of another
540 command.
541 doc (str): An optional summary description of the command, used
542 to generate help and usage information.
543 flags (list): A list of Flag instances. Optional, as flags can
544 be added with :meth:`~Parser.add()`.
545 posargs (bool): Defaults to disabled, pass ``True`` to enable
546 the Parser to accept positional arguments. Pass a callable
547 to parse the positional arguments using that
548 function/type. Pass a :class:`PosArgSpec` for full
549 customizability.
550 post_posargs (bool): Same as *posargs*, but refers to the list
551 of arguments following the ``--`` conventional marker. See
552 ``git`` and ``tox`` for examples of commands using this
553 style of positional argument.
554 flagfile (bool): Defaults to enabled, pass ``False`` to disable
555 flagfile support. Pass a :class:`Flag` instance to use a
556 custom flag instead of ``--flagfile``. Read more about
557 Flagfiles below.
559 Once initialized, parsing is performed by calling
560 :meth:`Parser.parse()` with ``sys.argv`` or any other list of strings.
561 """
562 def __init__(self, name, doc=None, flags=None, posargs=None,
563 post_posargs=None, flagfile=True):
564 self.name = process_command_name(name)
565 self.doc = doc
566 flags = list(flags or [])
568 self.posargs = _ensure_posargspec(posargs, 'posargs')
569 self.post_posargs = _ensure_posargspec(post_posargs, 'post_posargs')
571 if flagfile is True:
572 self.flagfile_flag = FLAGFILE_ENABLED
573 elif isinstance(flagfile, Flag):
574 self.flagfile_flag = flagfile
575 elif not flagfile:
576 self.flagfile_flag = None
577 else:
578 raise TypeError('expected True, False, or Flag instance for'
579 ' flagfile, not: %r' % flagfile)
581 self.subprs_map = OrderedDict()
582 self._path_flag_map = OrderedDict()
583 self._path_flag_map[()] = OrderedDict()
585 for flag in flags:
586 self.add(flag)
587 if self.flagfile_flag:
588 self.add(self.flagfile_flag)
589 return
591 def get_flag_map(self, path, with_hidden=True):
592 flag_map = self._path_flag_map[path]
593 return OrderedDict([(k, f) for k, f in flag_map.items()
594 if with_hidden or not f.display.hidden])
596 def get_flags(self, path=(), with_hidden=True):
597 flag_map = self.get_flag_map(path=path, with_hidden=with_hidden)
599 return unique(flag_map.values())
601 def __repr__(self):
602 cn = self.__class__.__name__
603 return ('<%s name=%r subcmd_count=%r flag_count=%r posargs=%r>'
604 % (cn, self.name, len(self.subprs_map), len(self.get_flags()), self.posargs))
606 def _add_subparser(self, subprs):
607 """Process subcommand name, check for subcommand conflicts, check for
608 subcommand flag conflicts, then finally add subcommand.
610 To add a command under a different name, simply make a copy of
611 that parser or command with a different name.
612 """
613 if self.posargs.accepts_args:
614 raise ValueError('commands accepting positional arguments'
615 ' cannot take subcommands')
617 # validate that the subparser's name can be used as a subcommand
618 subprs_name = process_command_name(subprs.name)
620 # then, check for conflicts with existing subcommands and flags
621 for prs_path in self.subprs_map:
622 if prs_path[0] == subprs_name:
623 raise ValueError(f'conflicting subcommand name: {subprs_name!r}')
624 parent_flag_map = self._path_flag_map[()]
626 check_no_conflicts = lambda parent_flag_map, subcmd_path, subcmd_flags: True
627 for path, flags in subprs._path_flag_map.items():
628 if not check_no_conflicts(parent_flag_map, path, flags):
629 # TODO
630 raise ValueError(f'subcommand flags conflict with parent command: {flags!r}')
632 # with checks complete, add parser and all subparsers
633 self.subprs_map[(subprs_name,)] = subprs
634 for path, cur_subprs in list(subprs.subprs_map.items()):
635 new_path = (subprs_name,) + path
636 self.subprs_map[new_path] = cur_subprs
638 # Flags inherit down (a parent's flags are usable by the child)
639 for path, flags in subprs._path_flag_map.items():
640 new_flags = parent_flag_map.copy()
641 new_flags.update(flags)
642 self._path_flag_map[(subprs_name,) + path] = new_flags
644 # If two flags have the same name, as long as the "parse_as"
645 # is the same, things should be ok. Need to watch for
646 # overlapping aliases, too. This may allow subcommands to
647 # further document help strings. Should the same be allowed
648 # for defaults?
650 def add(self, *a, **kw):
651 """Add a flag or subparser.
653 Unless the first argument is a Parser or Flag object, the
654 arguments are the same as the Flag constructor, and will be
655 used to create a new Flag instance to be added.
657 May raise ValueError if arguments are not recognized as
658 Parser, Flag, or Flag parameters. ValueError may also be
659 raised on duplicate definitions and other conflicts.
660 """
661 if isinstance(a[0], Parser):
662 subprs = a[0]
663 self._add_subparser(subprs)
664 return
666 if isinstance(a[0], Flag):
667 flag = a[0]
668 else:
669 try:
670 flag = Flag(*a, **kw)
671 except TypeError as te:
672 raise ValueError('expected Parser, Flag, or Flag parameters,'
673 ' not: %r, %r (got %r)' % (a, kw, te))
674 return self._add_flag(flag)
676 def _add_flag(self, flag):
677 # first check there are no conflicts...
678 for subcmds, flag_map in self._path_flag_map.items():
679 conflict_flag = flag_map.get(flag.name) or (flag.char and flag_map.get(flag.char))
680 if conflict_flag is None:
681 continue
682 if flag.name in (conflict_flag.name, conflict_flag.char):
683 raise ValueError('pre-existing flag %r conflicts with name of new flag %r'
684 % (conflict_flag, flag.name))
685 if flag.char and flag.char in (conflict_flag.name, conflict_flag.char):
686 raise ValueError('pre-existing flag %r conflicts with short form for new flag %r'
687 % (conflict_flag, flag))
689 # ... then we add the flags
690 for flag_map in self._path_flag_map.values():
691 flag_map[flag.name] = flag
692 if flag.char:
693 flag_map[flag.char] = flag
694 return
696 def parse(self, argv):
697 """This method takes a list of strings and converts them into a
698 validated :class:`CommandParseResult` according to the flags,
699 subparsers, and other options configured.
701 Args:
702 argv (list): A required list of strings. Pass ``None`` to
703 use ``sys.argv``.
705 This method may raise ArgumentParseError (or one of its
706 subtypes) if the list of strings fails to parse.
708 .. note:: The *argv* parameter does not automatically default
709 to using ``sys.argv`` because it's best practice for
710 implementing codebases to perform that sort of
711 defaulting in their ``main()``, which should accept
712 an ``argv=None`` parameter. This simple step ensures
713 that the Python CLI application has some sort of
714 programmatic interface that doesn't require
715 subprocessing. See here for an example.
717 """
718 if argv is None:
719 argv = sys.argv
720 cpr = CommandParseResult(parser=self, argv=argv)
721 if not argv:
722 ape = ArgumentParseError(f'expected non-empty sequence of arguments, not: {argv!r}')
723 ape.prs_res = cpr
724 raise ape
725 for arg in argv:
726 if not isinstance(arg, str):
727 raise TypeError(f'parse expected all args as strings, not: {arg!r} ({type(arg).__name__})')
728 '''
729 for subprs_path, subprs in self.subprs_map.items():
730 if len(subprs_path) == 1:
731 # _add_subparser takes care of recurring so we only
732 # need direct subparser descendants
733 self._add_subparser(subprs, overwrite=True)
734 '''
735 flag_map = None
736 # first snip off the first argument, the command itself
737 cmd_name, args = argv[0], list(argv)[1:]
738 cpr.name = cmd_name
740 # we record our progress as we parse to provide the most
741 # up-to-date info possible to the error and help handlers
743 try:
744 # then figure out the subcommand path
745 subcmds, args = self._parse_subcmds(args)
746 cpr.subcmds = tuple(subcmds)
748 prs = self.subprs_map[tuple(subcmds)] if subcmds else self
750 # then look up the subcommand's supported flags
751 # NOTE: get_flag_map() is used so that inheritors, like Command,
752 # can filter by actually-used arguments, not just
753 # available arguments.
754 cmd_flag_map = self.get_flag_map(path=tuple(subcmds))
756 # parse supported flags and validate their arguments
757 flag_map, flagfile_map, posargs = self._parse_flags(cmd_flag_map, args)
758 cpr.flags = OrderedDict(flag_map)
759 cpr.posargs = tuple(posargs)
761 # take care of dupes and check required flags
762 resolved_flag_map = self._resolve_flags(cmd_flag_map, flag_map, flagfile_map)
763 cpr.flags = OrderedDict(resolved_flag_map)
765 # separate out any trailing arguments from normal positional arguments
766 post_posargs = None # TODO: default to empty list?
767 parsed_post_posargs = None
768 if '--' in posargs:
769 posargs, post_posargs = split(posargs, '--', 1)
770 cpr.posargs, cpr.post_posargs = posargs, post_posargs
772 parsed_post_posargs = prs.post_posargs.parse(post_posargs)
773 cpr.post_posargs = tuple(parsed_post_posargs)
775 parsed_posargs = prs.posargs.parse(posargs)
776 cpr.posargs = tuple(parsed_posargs)
777 except ArgumentParseError as ape:
778 ape.prs_res = cpr
779 raise
781 return cpr
783 def _parse_subcmds(self, args):
784 """Expects arguments after the initial command (i.e., argv[1:])
786 Returns a tuple of (list_of_subcmds, remaining_args).
788 Raises on unknown subcommands."""
789 ret = []
791 for arg in args:
792 if arg.startswith('-'):
793 break # subcmd parsing complete
795 arg = _arg_to_subcmd(arg)
796 if tuple(ret + [arg]) not in self.subprs_map:
797 prs = self.subprs_map[tuple(ret)] if ret else self
798 if prs.posargs.parse_as is not ERROR or not prs.subprs_map:
799 # we actually have posargs from here
800 break
801 raise InvalidSubcommand.from_parse(prs, arg)
802 ret.append(arg)
803 return ret, args[len(ret):]
805 def _parse_single_flag(self, cmd_flag_map, args):
806 advance = 1
807 arg = args[0]
808 arg_text = None
809 try:
810 arg, arg_text = arg.split('=', maxsplit=1)
811 except ValueError:
812 pass
813 flag = cmd_flag_map.get(normalize_flag_name(arg))
814 if flag is None:
815 raise UnknownFlag.from_parse(cmd_flag_map, arg)
816 parse_as = flag.parse_as
817 if not callable(parse_as):
818 if arg_text:
819 raise InvalidFlagArgument.from_parse(cmd_flag_map, flag, arg_text)
820 # e.g., True is effectively store_true, False is effectively store_false
821 return flag, parse_as, args[1:]
823 try:
824 if arg_text is None:
825 arg_text = args[1]
826 advance = 2
827 except IndexError:
828 raise InvalidFlagArgument.from_parse(cmd_flag_map, flag, arg=None)
829 try:
830 arg_val = parse_as(arg_text)
831 except Exception as e:
832 raise InvalidFlagArgument.from_parse(cmd_flag_map, flag, arg_text, exc=e)
834 return flag, arg_val, args[advance:]
836 def _parse_flags(self, cmd_flag_map, args):
837 """Expects arguments after the initial command and subcommands (i.e.,
838 the second item returned from _parse_subcmds)
840 Returns a tuple of (multidict of flag names to parsed and validated values, remaining_args).
842 Raises on unknown subcommands.
843 """
844 flag_value_map = OMD()
845 ff_path_res_map = OrderedDict()
846 ff_path_seen = set()
848 orig_args = args
849 while args:
850 arg = args[0]
851 if not arg or arg[0] != '-' or arg == '-' or arg == '--':
852 # posargs or post_posargs beginning ('-' is a conventional pos arg for stdin)
853 break
854 flag, value, args = self._parse_single_flag(cmd_flag_map, args)
855 flag_value_map.add(flag.name, value)
857 if flag is self.flagfile_flag:
858 self._parse_flagfile(cmd_flag_map, value, res_map=ff_path_res_map)
859 for path, ff_flag_value_map in ff_path_res_map.items():
860 if path in ff_path_seen:
861 continue
862 flag_value_map.update_extend(ff_flag_value_map)
863 ff_path_seen.add(path)
865 return flag_value_map, ff_path_res_map, args
867 def _parse_flagfile(self, cmd_flag_map, path_or_file, res_map=None):
868 ret = res_map if res_map is not None else OrderedDict()
869 if callable(getattr(path_or_file, 'read', None)):
870 # enable StringIO and custom flagfile opening
871 f_name = getattr(path_or_file, 'name', None)
872 path = os.path.abspath(f_name) if f_name else repr(path_or_file)
873 ff_text = path_or_file.read()
874 else:
875 path = os.path.abspath(path_or_file)
876 try:
877 with codecs.open(path_or_file, 'r', 'utf-8') as f:
878 ff_text = f.read()
879 except (UnicodeError, OSError) as ee:
880 raise ArgumentParseError(f'failed to load flagfile "{path}", got: {ee!r}')
881 if path in res_map:
882 # we've already seen this file
883 return res_map
884 ret[path] = cur_file_res = OMD()
885 lines = ff_text.splitlines()
886 for lineno, line in enumerate(lines, 1):
887 try:
888 args = shlex.split(line, comments=True)
889 if not args:
890 continue # comment or empty line
891 flag, value, leftover_args = self._parse_single_flag(cmd_flag_map, args)
893 if leftover_args:
894 raise ArgumentParseError('excessive flags or arguments for flag "%s",'
895 ' expected one flag per line' % flag.name)
897 cur_file_res.add(flag.name, value)
898 if flag is self.flagfile_flag:
899 self._parse_flagfile(cmd_flag_map, value, res_map=ret)
901 except FaceException as fe:
902 fe.args = (fe.args[0] + f' (on line {lineno} of flagfile "{path}")',)
903 raise
905 return ret
907 def _resolve_flags(self, cmd_flag_map, parsed_flag_map, flagfile_map=None):
908 ret = OrderedDict()
909 cfm, pfm = cmd_flag_map, parsed_flag_map
910 flagfile_map = flagfile_map or {}
912 # check requireds and set defaults and then...
913 missing_flags = []
914 for flag_name, flag in cfm.items():
915 if flag.name in pfm:
916 continue
917 if flag.missing is ERROR:
918 missing_flags.append(flag.name)
919 else:
920 pfm[flag.name] = flag.missing
921 if missing_flags:
922 raise MissingRequiredFlags.from_parse(cfm, pfm, missing_flags)
924 # ... resolve dupes
925 for flag_name in pfm:
926 flag = cfm[flag_name]
927 arg_val_list = pfm.getlist(flag_name)
928 try:
929 ret[flag_name] = flag.multi(flag, arg_val_list)
930 except FaceException as fe:
931 ff_paths = []
932 for ff_path, ff_value_map in flagfile_map.items():
933 if flag_name in ff_value_map:
934 ff_paths.append(ff_path)
935 if ff_paths:
936 ff_label = 'flagfiles' if len(ff_paths) > 1 else 'flagfile'
937 msg = ('\n\t(check %s with definitions for flag "%s": %s)'
938 % (ff_label, flag_name, ', '.join(ff_paths)))
939 fe.args = (fe.args[0] + msg,)
940 raise
941 return ret
944def parse_sv_line(line, sep=','):
945 """Parse a single line of values, separated by the delimiter
946 *sep*. Supports quoting.
948 """
949 # TODO: this doesn't support unicode, which is intended to be
950 # handled at the layer above.
951 from csv import reader, Dialect, QUOTE_MINIMAL
953 class _face_dialect(Dialect):
954 delimiter = sep
955 escapechar = '\\'
956 quotechar = '"'
957 doublequote = True
958 skipinitialspace = False
959 lineterminator = '\n'
960 quoting = QUOTE_MINIMAL
962 parsed = list(reader([line], dialect=_face_dialect))
963 return parsed[0]
966class ListParam:
967 """The ListParam takes an argument as a character-separated list, and
968 produces a Python list of parsed values. Basically, the argument
969 equivalent of CSV (Comma-Separated Values)::
971 --flag a1,b2,c3
973 By default, this yields a ``['a1', 'b2', 'c3']`` as the value for
974 ``flag``. The format is also similar to CSV in that it supports
975 quoting when values themselves contain the separator::
977 --flag 'a1,"b,2",c3'
979 Args:
980 parse_one_as (callable): Turns a single value's text into its
981 parsed value.
982 sep (str): A single-character string representing the list
983 value separator. Defaults to ``,``.
984 strip (bool): Whether or not each value in the list should have
985 whitespace stripped before being passed to
986 *parse_one_as*. Defaults to False.
988 .. note:: Aside from using ListParam, an alternative method for
989 accepting multiple arguments is to use the
990 ``multi=True`` on the :class:`Flag` constructor. The
991 approach tends to be more verbose and can be confusing
992 because arguments can get spread across the command
993 line.
995 """
996 def __init__(self, parse_one_as=str, sep=',', strip=False):
997 # TODO: min/max limits?
998 self.parse_one_as = parse_one_as
999 self.sep = sep
1000 self.strip = strip
1002 def parse(self, list_text):
1003 "Parse a single string argument into a list of arguments."
1004 split_vals = parse_sv_line(list_text, self.sep)
1005 if self.strip:
1006 split_vals = [v.strip() for v in split_vals]
1007 return [self.parse_one_as(v) for v in split_vals]
1009 __call__ = parse
1011 def __repr__(self):
1012 return format_exp_repr(self, ['parse_one_as'], ['sep', 'strip'])
1015class ChoicesParam:
1016 """Parses a single value, limited to a set of *choices*. The actual
1017 converter used to parse is inferred from *choices* by default, but
1018 an explicit one can be set *parse_as*.
1019 """
1020 def __init__(self, choices, parse_as=None):
1021 if not choices:
1022 raise ValueError(f'expected at least one choice, not: {choices!r}')
1023 try:
1024 self.choices = sorted(choices)
1025 except Exception:
1026 # in case choices aren't sortable
1027 self.choices = list(choices)
1028 if parse_as is None:
1029 parse_as = type(self.choices[0])
1030 # TODO: check for builtins, raise if not a supported type
1031 self.parse_as = parse_as
1033 def parse(self, text):
1034 choice = self.parse_as(text)
1035 if choice not in self.choices:
1036 raise ArgumentParseError(f'expected one of {self.choices!r}, not: {text!r}')
1037 return choice
1039 __call__ = parse
1041 def __repr__(self):
1042 return format_exp_repr(self, ['choices'], ['parse_as'])
1045class FilePathParam:
1046 """TODO
1048 ideas: exists, minimum permissions, can create, abspath, type=d/f
1049 (technically could also support socket, named pipe, and symlink)
1051 could do missing=TEMP, but that might be getting too fancy tbh.
1052 """
1054class FileValueParam:
1055 """
1056 TODO: file with a single value in it, like a pidfile
1057 or a password file mounted in. Read in and treated like it
1058 was on the argv.
1059 """