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:
(1) Event original: "self._options[option]" looks like the original copy.
Also see events: [copy_paste_error][remediation]
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