1 from collections import Counter
2 from collections.abc import Mapping
3 from functools import partial
4 from typing import Final
5
6 from pcs.cli.common.errors import SEE_MAN_CHANGES, CmdLineInputError
7 from pcs.common.str_tools import (
8 format_list,
9 format_list_custom_last_separator,
10 format_plural,
11 )
12 from pcs.common.tools import timeout_to_seconds
13 from pcs.common.types import StringCollection, StringIterable, StringSequence
14
15 # sys.argv always returns a list, we don't need StringSequence in here
16 Argv = list[str]
17 ModifierValueType = None | bool | str
18
19 _FUTURE_OPTION_STR: Final = "future"
20 FUTURE_OPTION: Final = f"--{_FUTURE_OPTION_STR}"
21 FUTURE_OPTION_DEPRECATION_WARNING: Final = (
22 "Option '--future' is deprecated and no longer has any effect, "
23 "since the behavior it enabled is now the default. It will be "
24 "removed in a future release."
25 )
26 _OUTPUT_FORMAT_OPTION_STR: Final = "output-format"
27 OUTPUT_FORMAT_OPTION: Final = f"--{_OUTPUT_FORMAT_OPTION_STR}"
28 OUTPUT_FORMAT_VALUE_CMD: Final = "cmd"
29 OUTPUT_FORMAT_VALUE_JSON: Final = "json"
30 OUTPUT_FORMAT_VALUE_TEXT: Final = "text"
31 OUTPUT_FORMAT_VALUES: Final = frozenset(
32 (
33 OUTPUT_FORMAT_VALUE_CMD,
34 OUTPUT_FORMAT_VALUE_JSON,
35 OUTPUT_FORMAT_VALUE_TEXT,
36 )
37 )
38
39 MODIFIER_OPTIONS_BOOL: Final[frozenset[str]] = frozenset(
40 (
41 "--all",
42 "--agent-validation",
43 # TODO remove
44 # used only in acl commands and it is deprecated there
45 "--autodelete",
46 "--brief",
47 "--config",
48 "--corosync",
49 "--debug",
50 "--defaults",
51 "--disabled",
52 "--enable",
53 "--expired",
54 "--force",
55 "--full",
56 "--quiet",
57 FUTURE_OPTION,
58 "--hide-inactive",
59 "--local",
60 "--monitor",
61 "--no-default-ops",
62 "--nodesc",
63 "--no-expire-check",
64 "--no-cluster-uuid",
65 "--no-keys-sync",
66 "--no-stop",
67 "--no-strict",
68 "--no-watchdog-validation",
69 "--off",
70 "--overwrite",
71 "--pacemaker",
72 "--promoted",
73 "--safe",
74 "--show-secrets",
75 "--simulate",
76 "--skip-offline",
77 "--start",
78 "--strict",
79 "--yes",
80 )
81 )
82
83 MODIFIER_OPTIONS_VAL: Final[frozenset[str]] = frozenset(
84 (
85 "--after",
86 "--before",
87 "--corosync_conf",
88 "--from",
89 # TODO: remove in the next major version, added in the first version of
90 # 1.x
91 # No longer used by any command. It is kept only so that pcs recognizes
92 # it and 'pcs resource create' can print a helpful "syntax has changed"
93 # error instead of a generic unknown-option error.
94 # deprecated in the 0.11.7 version
95 "--group",
96 "--name",
97 "--node",
98 "--request-timeout",
99 "--to",
100 "--token",
101 "-f",
102 "-p",
103 "-u",
104 )
105 )
106
107 ARG_TYPE_DELIMITER: Final = "%"
108
109 # h = help, f = file,
110 # p = password (cluster auth), u = user (cluster auth),
111 PCS_SHORT_OPTIONS: Final = "hf:p:u:"
112 PCS_LONG_OPTIONS: Final = [
113 "debug",
114 "version",
115 "help",
116 "fullhelp",
117 "force",
118 "skip-offline",
119 "autodelete",
120 "simulate",
121 "all",
122 "full",
123 "local",
124 "wait",
125 "config",
126 "start",
127 "enable",
128 "disabled",
129 "off",
130 "request-timeout=",
131 "brief",
132 _FUTURE_OPTION_STR,
133 # resource (safe-)disable
134 "safe",
135 "no-strict",
136 # resource cleanup | refresh
137 "strict",
138 "pacemaker",
139 "corosync",
140 "no-default-ops",
141 "defaults",
142 "nodesc",
143 "promoted",
144 "name=",
145 # TODO: remove in the next major version, added in the first version of 1.x
146 # kept only so 'pcs resource create' can print a "syntax has changed" error
147 # deprecated in the 0.11.7 version
148 "group=",
149 "node=",
150 "from=",
151 "to=",
152 "after=",
153 "before=",
154 "corosync_conf=",
155 # do not stop resources in resource delete command
156 "no-stop",
157 "no-watchdog-validation",
158 # pcs cluster setup
159 "no-cluster-uuid",
160 "no-keys-sync",
161 # in pcs status - do not display resource status on inactive node
162 "hide-inactive",
163 # pcs resource (un)manage - enable or disable monitor operations
164 "monitor",
165 # "pcs resource clear --expired" - only clear expired moves and bans
166 "expired",
167 # disable evaluating whether rules are expired
168 "no-expire-check",
169 # allow overwriting existing files, currently meant for / used in CLI only
170 "overwrite",
171 # output format of commands, e.g: json, cmd, text, ...
172 f"{_OUTPUT_FORMAT_OPTION_STR}=",
173 # auth token
174 "token=",
175 # enable agent self validation
176 "agent-validation",
177 # disable text output in query commands
178 "quiet",
179 # proceed with dangerous actions, meant for / used in CLI only
180 "yes",
181 # retrieve and display cibsecret values / used in CLI only
182 "show-secrets",
183 ]
184
185
186 def split_list(arg_list: Argv, separator: str) -> list[Argv]:
187 """
188 split a list of arguments to several lists using separator as a delimiter
189
190 arg_list -- list of command line arguments to split
191 separator -- delimiter
192 """
193 separator_indexes = [i for i, x in enumerate(arg_list) if x == separator]
194 bounds = zip(
195 [0] + [i + 1 for i in separator_indexes],
196 separator_indexes + [None],
197 strict=False,
198 )
199 return [arg_list[i:j] for i, j in bounds]
200
201
202 def split_list_by_any_keywords(
203 arg_list: Argv, keyword_label: str
204 ) -> dict[str, Argv]:
205 """
206 split a list of arguments using any argument not containing = as a delimiter
207
208 arg_list -- list of command line arguments to split
209 keyword_label -- description of all keywords
210 """
211 groups: dict[str, Argv] = {}
212 if not arg_list:
213 return groups
214
215 if "=" in arg_list[0]:
216 raise CmdLineInputError(
217 f"Invalid character '=' in {keyword_label} '{arg_list[0]}'"
218 )
219
220 current_keyword = arg_list[0]
221 groups[current_keyword] = []
222 for arg in arg_list[1:]:
223 if "=" in arg:
224 groups[current_keyword].append(arg)
225 else:
226 current_keyword = arg
227 if current_keyword in groups:
228 raise CmdLineInputError(
229 "{} '{}' defined multiple times".format(
230 keyword_label.capitalize(), current_keyword
231 )
232 )
233 groups[current_keyword] = []
234 return groups
235
236
237 def split_option(arg: str, allow_empty_value: bool = True) -> tuple[str, str]:
238 """
239 Get (key, value) from a key=value commandline argument.
240
241 Split the argument by the first = and return resulting parts. Raise
242 CmdLineInputError if the argument cannot be split.
243
244 arg -- commandline argument to split
245 allow_empty_value -- if False, raise CmdLineInputError on empty value
246 """
247 if "=" not in arg:
248 raise CmdLineInputError(f"missing value of '{arg}' option")
249 if arg.startswith("="):
250 raise CmdLineInputError(f"missing key in '{arg}' option")
251 key, value = arg.split("=", 1)
252 if not (value or allow_empty_value):
253 raise CmdLineInputError(f"value of '{key}' option is empty")
254 return key, value
255
256
257 def ensure_unique_args(cmdline_args: Argv) -> None:
258 """
259 Raises in case there are duplicate args
260 """
261 duplicities = [
262 item for item, count in Counter(cmdline_args).items() if count > 1
263 ]
264 if duplicities:
265 argument_pl = format_plural(duplicities, "argument")
266 duplicities_list = format_list(duplicities)
267 raise CmdLineInputError(f"duplicate {argument_pl}: {duplicities_list}")
268
269
270 class KeyValueParser:
271 """
272 Parse and check key=value options
273 """
274
275 def __init__(self, arg_list: Argv, repeatable: StringCollection = ()):
276 """
277 arg_list -- commandline arguments to be parsed
278 repeatable -- keys that are allowed to be specified several times
279 """
280 self._repeatable_keys = repeatable
281 self._key_value_map: dict[str, list[str]] = {}
282 for arg in arg_list:
283 name, value = split_option(arg)
284 if name not in self._key_value_map:
285 self._key_value_map[name] = [value]
286 else:
287 self._key_value_map[name].append(value)
288
289 def check_allowed_keys(self, allowed_keys: StringCollection) -> None:
290 """
291 Check that only allowed keys were specified
292
293 allowed_keys -- list of allowed keys
294 """
295 unknown_options = set(self._key_value_map.keys()) - set(allowed_keys)
296 if unknown_options:
297 raise CmdLineInputError(
298 "Unknown option{s} '{options}'".format(
299 s=("s" if len(unknown_options) > 1 else ""),
300 options="', '".join(sorted(unknown_options)),
301 )
302 )
303
304 def get_unique(self) -> dict[str, str]:
305 """
306 Get all non-repeatable keys and their values; raise if a key has more values
307 """
308 result: dict[str, str] = {}
309 for key, values in self._key_value_map.items():
310 if key in self._repeatable_keys:
311 continue
312 values_uniq = set(values)
313 if len(values_uniq) > 1:
314 raise CmdLineInputError(
315 f"duplicate option '{key}' with different values "
316 f"{format_list_custom_last_separator(values_uniq, ' and ')}"
317 )
318 result[key] = values[0]
319 return result
320
321 def get_repeatable(self) -> dict[str, list[str]]:
322 """
323 Get all repeatable keys and their values
324 """
325 return {
326 key: self._key_value_map[key]
327 for key in self._repeatable_keys
328 if key in self._key_value_map
329 }
330
331
332 class ArgsByKeywords:
333 def __init__(self, groups: Mapping[str, list[Argv]]):
334 self._groups = groups
335 self._flat_cache: dict[str, Argv] = {}
336
337 def allow_repetition_only_for(self, keyword_set: StringCollection) -> None:
338 """
339 Raise CmdLineInputError if a keyword has been repeated when not allowed
340
341 keyword_set -- repetition is allowed for these keywords
342 """
343 for keyword, arg_groups in self._groups.items():
344 if len(arg_groups) > 1 and keyword not in keyword_set:
345 raise CmdLineInputError(
346 f"'{keyword}' cannot be used more than once"
347 )
348
349 def ensure_unique_keywords(self) -> None:
350 """
351 Raise CmdLineInputError if any keyword has been repeated
352 """
353 return self.allow_repetition_only_for(set())
354
355 def is_empty(self) -> bool:
356 """
357 Check if any args have been specified
358 """
359 return not self._groups
360
361 def has_keyword(self, keyword: str) -> bool:
362 """
363 Check if a keyword has been specified
364
365 keyword -- a keyword to check
366 """
367 return keyword in self._groups
368
369 def has_empty_keyword(self, keyword: str) -> bool:
370 """
371 Check if a keyword has been specified without any following args
372
373 keyword -- a keyword to check
374 """
375 return self.has_keyword(keyword) and not self.get_args_flat(keyword)
376
377 def get_args_flat(self, keyword: str) -> Argv:
378 """
379 Get arguments of a keyword in one sequence
380 """
381 if keyword in self._groups:
382 if keyword not in self._flat_cache:
383 self._flat_cache[keyword] = [
384 arg
385 for one_group in self._groups[keyword]
386 for arg in one_group
387 ]
388 return self._flat_cache[keyword]
389 return []
390
391 def get_args_groups(self, keyword: str) -> list[Argv]:
392 """
393 Get arguments of a keyword, one group for each keyword occurrence
394 """
395 if keyword in self._groups:
396 return self._groups[keyword]
397 return []
398
399
400 def group_by_keywords(
401 arg_list: Argv,
402 keyword_set: StringCollection,
403 implicit_first_keyword: str | None = None,
404 ) -> ArgsByKeywords:
405 """
406 Separate argv into groups delimited by specified keywords
407
408 arg_list -- commandline arguments containing keywords
409 keyword_set -- all expected keywords
410 implicit_first_keyword -- key for capturing args before the first keyword
411 """
412 args_by_keywords: dict[str, list[Argv]] = {}
413
414 def new_keyword(keyword: str) -> None:
415 if keyword not in args_by_keywords:
416 args_by_keywords[keyword] = []
417 args_by_keywords[keyword].append([])
418
419 if arg_list:
420 if arg_list[0] not in keyword_set:
421 if not implicit_first_keyword:
422 raise CmdLineInputError()
423 current_keyword = implicit_first_keyword
424 new_keyword(current_keyword)
425
426 for arg in arg_list:
427 if arg in keyword_set:
428 current_keyword = arg
429 new_keyword(current_keyword)
430 else:
431 args_by_keywords[current_keyword][-1].append(arg)
432
433 return ArgsByKeywords(args_by_keywords)
434
435
436 def parse_typed_arg(
437 arg: str, allowed_types: StringSequence, default_type: str
438 ) -> tuple[str, str]:
439 """
440 Get (type, value) from a typed commandline argument.
441
442 Split the argument by the type separator and return the type and the value.
443 Raise CmdLineInputError in the argument format or type is not valid.
444 string arg -- commandline argument
445 Iterable allowed_types -- list of allowed argument types
446 string default_type -- type to return if the argument doesn't specify a type
447 """
448 if ARG_TYPE_DELIMITER not in arg:
449 return default_type, arg
450 arg_type, arg_value = arg.split(ARG_TYPE_DELIMITER, 1)
451 if not arg_type:
452 return default_type, arg_value
453 if arg_type not in allowed_types:
454 raise CmdLineInputError(
455 (
456 "'{arg_type}' is not an allowed type for '{arg_full}', use "
457 "{hint}"
458 ).format(
459 arg_type=arg_type,
460 arg_full=arg,
461 hint=", ".join(sorted(allowed_types)),
462 )
463 )
464 return arg_type, arg_value
465
466
467 def is_short_option_expecting_value(arg: str) -> bool:
468 return len(arg) == 2 and arg[0] == "-" and f"{arg[1]}:" in PCS_SHORT_OPTIONS
469
470
471 def is_long_option_expecting_value(arg: str) -> bool:
472 return (
473 len(arg) > 2 and arg[0:2] == "--" and f"{arg[2:]}=" in PCS_LONG_OPTIONS
474 )
475
476
477 def is_option_expecting_value(arg: str) -> bool:
478 return is_short_option_expecting_value(
479 arg
480 ) or is_long_option_expecting_value(arg)
481
482
483 def wait_to_timeout(wait: bool | str | None) -> int:
484 if wait is False:
485 return -1
486 if wait is None:
487 return 0
488 timeout = timeout_to_seconds(wait)
489 if timeout is None:
490 raise CmdLineInputError(f"'{wait}' is not a valid interval value")
491 return timeout
492
493
494 class InputModifiers:
495 def __init__(self, options: Mapping[str, ModifierValueType]):
496 self._defined_options = set(options.keys())
497 self._options = dict(options)
498 self._options.update(
499 {opt: opt in options for opt in MODIFIER_OPTIONS_BOOL}
500 )
501 self._options.update(
502 {opt: options.get(opt, None) for opt in MODIFIER_OPTIONS_VAL}
503 )
504 self._options.update(
505 {
506 OUTPUT_FORMAT_OPTION: options.get(
507 OUTPUT_FORMAT_OPTION, OUTPUT_FORMAT_VALUE_TEXT
508 ),
509 "--wait": options.get("--wait", False),
510 }
511 )
512
513 def get_subset(
514 self, *options: str, **custom_options: ModifierValueType
515 ) -> "InputModifiers":
516 opt_dict = {
517 opt: self.get(opt) for opt in options if self.is_specified(opt)
518 }
519 opt_dict.update(custom_options)
520 return InputModifiers(opt_dict)
521
522 def ensure_only_supported(
523 self,
524 *supported_options: str,
525 hint_syntax_changed: str | None = None,
526 output_format_supported: bool = False,
527 ) -> None:
528 # --debug is supported in all commands
529 supported_options_set = set(supported_options) | {"--debug"}
530 if output_format_supported:
531 supported_options_set.add(OUTPUT_FORMAT_OPTION)
532 unsupported_options = self._defined_options - supported_options_set
533 if unsupported_options:
534 pluralize = partial(format_plural, unsupported_options)
535 raise CmdLineInputError(
536 "Specified {option} {option_list} {_is} not supported in this "
537 "command".format(
538 option=pluralize("option"),
539 option_list=format_list(sorted(unsupported_options)),
540 _is=pluralize("is"),
541 ),
542 hint=(
543 "Syntax has changed from previous version. {}".format(
544 SEE_MAN_CHANGES.format(hint_syntax_changed)
545 )
546 if hint_syntax_changed
547 else None
548 ),
549 )
550
551 def ensure_not_mutually_exclusive(self, *mutually_exclusive: str) -> None:
552 """
553 Raise CmdLineInputError if several exclusive options were specified
554
555 mutually_exclusive -- mutually exclusive options
556 """
557 options_to_report = self._defined_options & set(mutually_exclusive)
558 if len(options_to_report) > 1:
559 raise CmdLineInputError(
560 "Only one of {} can be used".format(
561 format_list(sorted(options_to_report))
562 )
563 )
564
565 def ensure_not_incompatible(
566 self, checked: str, incompatible: StringCollection
567 ) -> None:
568 """
569 Raise CmdLineInputError if both the checked and an incompatible option
570 were specified
571
572 checked -- option incompatible with any of incompatible options
573 incompatible -- set of options incompatible with checked
574 """
575 if checked not in self._defined_options:
576 return
577 disallowed = self._defined_options & set(incompatible)
578 if disallowed:
579 raise CmdLineInputError(
580 "'{}' cannot be used with {}".format(
581 checked, format_list(sorted(disallowed))
582 )
583 )
584
585 def ensure_dependency_satisfied(
586 self, main_option: str, dependent_options: StringCollection
587 ) -> None:
588 """
589 Raise CmdLineInputError if any of dependent_options is present and
590 main_option is not present.
591
592 main_option -- option on which dependent_options depend
593 dependent_options -- none of these options can be specified if
594 main_option is not specified
595 """
596 if main_option in self._defined_options:
597 return
598 disallowed = self._defined_options & set(dependent_options)
599 if disallowed:
600 raise CmdLineInputError(
601 "{} cannot be used without '{}'".format(
602 format_list(sorted(disallowed)), main_option
603 )
604 )
605
606 def is_specified(self, option: str) -> bool:
607 return option in self._defined_options
608
609 def is_specified_any(self, option_list: StringIterable) -> bool:
610 return any(self.is_specified(option) for option in option_list)
611
612 def get(
613 self, option: str, default: ModifierValueType = None
614 ) -> ModifierValueType:
615 if option in self._defined_options:
|
CID (unavailable; MK=489eaaa87afbb746a3d63c1bcfb03702) (#1 of 1): Copy-paste error (COPY_PASTE_ERROR): |
|
(2) Event copy_paste_error: |
"_options" in "self._options[option]" looks like a copy-paste error. |
|
(3) Event remediation: |
Should it say "_defined_options" instead? |
| Also see events: |
[original] |
616 return self._options[option]
617 if default is not None:
618 return default
619 if option in self._options:
620 return self._options[option]
621 raise AssertionError(f"Non existing default value for '{option}'")
622
623 def get_output_format(
624 self,
625 supported_formats: StringCollection = OUTPUT_FORMAT_VALUES,
626 ) -> str:
627 output_format = self.get(OUTPUT_FORMAT_OPTION)
628 if output_format in supported_formats:
629 return str(output_format)
630 raise CmdLineInputError(
631 (
632 "Unknown value '{value}' for '{option}' option. Supported "
633 "{value_pl} {is_pl}: {supported}"
634 ).format(
635 value=output_format,
636 option=OUTPUT_FORMAT_OPTION,
637 value_pl=format_plural(supported_formats, "value"),
638 is_pl=format_plural(supported_formats, "is"),
639 supported=format_list(list(supported_formats)),
640 )
641 )
642
643
644 def get_rule_str(argv: Argv) -> str | None:
645 if argv:
646 if len(argv) > 1:
647 raise CmdLineInputError()
648 return argv[0]
649 return None
650