diff --git a/CHANGELOG.md b/CHANGELOG.md index 926036b48..9cbe3abe4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,21 @@ - Bug Fixes - Fixed file path completion for names containing square brackets, including bracketed working directories and home directories. + - Fixed `get_exes_in_path()` and shell command completion when executable names or `PATH` + directories contain square brackets. + - File path completion, shell command completion, and `get_exes_in_path()` now match `*` and `?` + literally instead of returning nothing when the text being completed contains one, so names + containing those characters can be completed. + - Tab completion now adds quotes when a match has a character which is special to a shell, such + as `*`, `?`, `(`, `&`, or `$`, if what is being completed is passed to one. That is the case + for the arguments of the `shell` command and for everything after a pipe. Everywhere else, + only a match with a space is quoted, as before. See the + [Special Characters in Paths](docs/features/completion.md#special-characters-in-paths) + documentation for details. + - `get_exes_in_path()`, `find_editor()`, and shell command completion no longer skip `PATH` + entries which are symbolic links to directories. + - `find_editor()` now finds the `edit` editor on Windows. It was the preferred default editor + there but could never be found because it was searched for without its `.exe` extension. - A command which prints through a `cmd2` console of its own, such as a `Cmd2GeneralConsole` showing a Rich progress bar, no longer ends with a `BrokenPipeError` message when its output is piped to something that exits early, as `head` does. `cmd2` now ends the command quietly diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index e945f5252..c0c1be687 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2385,6 +2385,10 @@ def path_complete( ) -> Completions: """Perform completion of local file system paths. + Apart from a leading ``~``, which refers to a user's home directory, every character in ``text`` is + matched literally. Glob characters like ``*``, ``?``, and ``[`` are not expanded, and they are not + escaped in the results. + :param text: the string prefix we are attempting to match (all matches must begin with it) :param line: the current input line with leading whitespace removed :param begidx: the beginning index of the prefix text @@ -2399,7 +2403,7 @@ def path_complete( if endidx == len(line) or (endidx < len(line) and line[endidx] != os.path.sep): add_trailing_sep_if_dir = True - # Used to replace cwd in the final results + # Used to replace CWD in the final results cwd = os.getcwd() cwd_added = False @@ -2407,17 +2411,11 @@ def path_complete( orig_tilde_path = "" expanded_tilde_path = "" - # If the search text is blank, then search in the CWD for * + # If the search text is blank, then complete all entries in the CWD if not text: search_str = os.path.join(os.getcwd(), "") cwd_added = True else: - # Purposely don't match any path containing wildcards - wildcards = ["*", "?"] - for wildcard in wildcards: - if wildcard in text: - return Completions() - # Start the search string search_str = text @@ -2436,7 +2434,7 @@ def path_complete( orig_tilde_path = text[:sep_index] expanded_tilde_path = os.path.expanduser(orig_tilde_path) - # If the search text does not have a directory, then use the cwd + # If the search text does not have a directory, then use the CWD elif not os.path.dirname(text): search_str = os.path.join(os.getcwd(), search_str) cwd_added = True @@ -2465,7 +2463,7 @@ def path_complete( matches[index] += os.path.sep display_matches[index] += os.path.sep - # Remove cwd if it was added to match the text prompt-toolkit expects + # Remove CWD if it was added to match the text prompt-toolkit expects if cwd_added: to_replace = cwd if cwd == os.path.sep else cwd + os.path.sep matches = [cur_path.replace(to_replace, "", 1) for cur_path in matches] @@ -2501,7 +2499,7 @@ def shell_cmd_complete( if not complete_blank and not text: return Completions() - # If there are no path characters in the search text, then do shell command completion in the user's path + # If the search text is a bare command name (no '~' or path separator), complete executables from PATH if not text.startswith("~") and os.path.sep not in text: items = [CompletionItem(exe) for exe in utils.get_exes_in_path(text)] return Completions(items=items) @@ -2536,6 +2534,9 @@ def _redirect_complete(self, text: str, line: str, begidx: int, endidx: int, com # True when command line contains any redirection tokens has_redirection = False + # True when the first redirection token is a pipe, which means everything after it is passed to a shell + piped_to_shell = False + # Keep track of state while examining tokens in_pipe = False in_file_redir = False @@ -2546,6 +2547,8 @@ def _redirect_complete(self, text: str, line: str, begidx: int, endidx: int, com for cur_token in raw_tokens: # Process redirection tokens if cur_token in constants.REDIRECTION_TOKENS: + if not has_redirection: + piped_to_shell = cur_token == constants.REDIRECTION_PIPE has_redirection = True # Check if we are at a pipe @@ -2578,11 +2581,10 @@ def _redirect_complete(self, text: str, line: str, begidx: int, endidx: int, com prior_token = cur_token - if do_shell_completion: - return self.shell_cmd_complete(text, line, begidx, endidx) - - if do_path_completion: - return self.path_complete(text, line, begidx, endidx) + if do_shell_completion or do_path_completion: + completer = self.shell_cmd_complete if do_shell_completion else self.path_complete + completions = completer(text, line, begidx, endidx) + return self._for_shell(completions) if piped_to_shell else completions # If there were redirection strings anywhere on the command line, then we # are no longer completing for the current command @@ -2729,7 +2731,13 @@ def _perform_completion( if not completion_token_quote: matches = completions.to_strings() - if any(" " in match for match in matches): + # Matches which are being passed to a shell need quotes if any of them has a character special to it + if completions._quote_for_shell: + _quote_char = utils._shell_quote_char(matches) + _add_opening_quote = bool(_quote_char) + + # Everything else only needs quotes to keep a match with a space as a single token + elif any(" " in match for match in matches): _add_opening_quote = True # Determine best quote (single vs double) based on text content @@ -5036,13 +5044,29 @@ def do_set(self, args: argparse.Namespace) -> None: @classmethod def _build_shell_parser(cls) -> Cmd2ArgumentParser: shell_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description="Execute a command as if at the OS prompt.") - shell_parser.add_argument("command", help="the command to run", completer=cls.shell_cmd_complete) + shell_parser.add_argument("command", help="the command to run", completer=cls._complete_shell_command) shell_parser.add_argument( - "command_args", nargs=argparse.REMAINDER, help="arguments to pass to command", completer=cls.path_complete + "command_args", nargs=argparse.REMAINDER, help="arguments to pass to command", completer=cls._complete_shell_arg ) return shell_parser + @staticmethod + def _for_shell(completions: Completions) -> Completions: + """Mark completions as being for part of the command line which is passed to a shell. + + This is what gets them quoted when one of them has a character which is special to that shell. + """ + return dataclasses.replace(completions, _quote_for_shell=True) + + def _complete_shell_command(self, text: str, line: str, begidx: int, endidx: int) -> Completions: + """Complete the command which do_shell passes to a shell.""" + return self._for_shell(self.shell_cmd_complete(text, line, begidx, endidx)) + + def _complete_shell_arg(self, text: str, line: str, begidx: int, endidx: int) -> Completions: + """Complete an argument of the command which do_shell passes to a shell.""" + return self._for_shell(self.path_complete(text, line, begidx, endidx)) + # Preserve quotes since we are passing these strings to the shell @with_argparser(_build_shell_parser, preserve_quotes=True) def do_shell(self, args: argparse.Namespace) -> None: diff --git a/cmd2/completion.py b/cmd2/completion.py index 460b65c12..434f72cd6 100644 --- a/cmd2/completion.py +++ b/cmd2/completion.py @@ -305,3 +305,7 @@ class Completions(CompletionResultsBase): # The quote character to use if adding an opening or closing quote to the matches. _quote_char: str = "" + + # Whether the matches are for part of the command line which is passed to a shell. If they are, + # then quotes are also added when a match has a character which is special to that shell. + _quote_for_shell: bool = field(default=False, compare=False) diff --git a/cmd2/utils.py b/cmd2/utils.py index 2d80ee5c3..bc7c20b53 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -17,6 +17,7 @@ Generator, Iterable, MutableSequence, + Sequence, ) from difflib import SequenceMatcher from typing import ( @@ -323,6 +324,36 @@ def expand_user_in_tokens(tokens: MutableSequence[str]) -> None: tokens[index] = expand_user(tokens[index]) +# Matches a character which is special to a POSIX shell. A '[' counts even when no ']' follows it since +# some shells, like zsh, reject that as a bad pattern. A '#' and a '=' only count at the start of a word. +_POSIX_SPECIAL_RE = re.compile(r"""[ \t"';|<>&()*?\[{}$`\\]|^[#=]""") + +# Matches a character which cmd.exe documents as requiring quotes. A '~' is left out because it is not +# special to cmd.exe itself, and quoting it would quote every path below a home directory. +_WINDOWS_SPECIAL_RE = re.compile(r"""[ \t&()\[\]{}^=;!'+,`]""") + + +def _shell_quote_char(matches: Sequence[str]) -> str: + """Return the quote character which completions being passed to a shell need to be wrapped in. + + :param matches: the completions being offered for part of a command line which is passed to a shell + :return: the quote character to use, or an empty string if none of the matches need quotes + """ + if sys.platform.startswith("win"): + # cmd.exe only treats double quotes as quotes, and a Windows file name can't contain one + return '"' if any(_WINDOWS_SPECIAL_RE.search(match) for match in matches) else "" + + if not any(_POSIX_SPECIAL_RE.search(match) for match in matches): + return "" + + # A quote character within a match has to be quoted with the other quote character + if any("'" in match for match in matches): + return '"' + + # Only use single quotes when a shell would still expand something within double quotes + return "'" if any(char in match for match in matches for char in '"$`\\') else '"' + + def _quote_shell_arg(arg: str) -> str: """Quote a string so the OS shell treats it as one literal argument. @@ -345,6 +376,21 @@ def _quote_shell_arg(arg: str) -> str: return shlex.quote(arg) +def _get_path_dirs() -> set[str]: + """Return the directories listed in the PATH environment variable. + + The entries are returned as they are written. Resolving them would avoid searching a directory twice + when it is listed under two names, but doing so can raise an exception for an entry which can't be reached. + + An empty entry is kept because a POSIX shell searches the current working directory for one. A PATH which + is set to an empty string is a single empty entry, so it is not the same as a PATH which is not set. + + :return: the directories, which is an empty set if PATH is not set + """ + env_path = os.getenv("PATH") + return set() if env_path is None else set(env_path.split(os.path.pathsep)) + + def find_editor() -> str | None: """Set cmd2.Cmd.DEFAULT_EDITOR. If EDITOR env variable is set, that will be used. @@ -354,15 +400,12 @@ def find_editor() -> str | None: editor = os.environ.get("EDITOR") if not editor: if sys.platform[:3] == "win": - editors = ["edit", "code.cmd", "notepad++.exe", "notepad.exe"] + editors = ["edit.exe", "code.cmd", "notepad++.exe", "notepad.exe"] else: editors = ["vim", "vi", "emacs", "nano", "pico", "joe", "code", "subl", "gedit", "kate"] - # Get a list of every directory in the PATH environment variable and ignore symbolic links - env_path = os.getenv("PATH") - paths = [] if env_path is None else [p for p in env_path.split(os.path.pathsep) if not os.path.islink(p)] - - for possible_editor, path in itertools.product(editors, paths): + # Use the most preferred editor which is in any of the PATH directories + for possible_editor, path in itertools.product(editors, _get_path_dirs()): editor_path = os.path.join(path, possible_editor) if os.path.isfile(editor_path) and os.access(editor_path, os.X_OK): if sys.platform[:3] == "win": @@ -408,26 +451,19 @@ def files_from_glob_patterns(patterns: Iterable[str], access: int = os.F_OK) -> def get_exes_in_path(starts_with: str) -> list[str]: """Return names of executables in a user's path. + Every character in ``starts_with`` is matched literally. Glob characters like ``*``, ``?``, and ``[`` + are not expanded. + :param starts_with: what the exes should start with. leave blank for all exes in path. :return: a list of matching exe names """ - # Purposely don't match any executable containing wildcards - wildcards = ["*", "?"] - for wildcard in wildcards: - if wildcard in starts_with: - return [] - - # Get a list of every directory in the PATH environment variable and ignore symbolic links - env_path = os.getenv("PATH") - paths = [] if env_path is None else [p for p in env_path.split(os.path.pathsep) if not os.path.islink(p)] - # Use a set to store exe names since there can be duplicates exes_set = set() # Find every executable file in the user's path that matches the pattern - for path in paths: + for path in _get_path_dirs(): full_path = os.path.join(path, starts_with) - matches = files_from_glob_pattern(full_path + "*", access=os.X_OK) + matches = files_from_glob_pattern(glob.escape(full_path) + "*", access=os.X_OK) for match in matches: exes_set.add(os.path.basename(match)) diff --git a/docs/features/completion.md b/docs/features/completion.md index 1def16f23..5c4f94daf 100644 --- a/docs/features/completion.md +++ b/docs/features/completion.md @@ -33,6 +33,52 @@ line of code similar to the following to your class which inherits from `cmd2.Cm complete_bar = functools.partialmethod(cmd2.Cmd.path_complete, path_filter=os.path.isdir) ``` +## Special Characters in Paths + +Path and shell command completion match the text being completed literally. Glob characters such as +`*`, `?`, and `[` are never expanded, so a file named `my*file.txt` or `notes[2026].txt` completes +like any other. The one exception is a leading `~`, which refers to a user's home directory as it +does in a shell. + +Completion results are literal names too. `cmd2` does not escape them, because most commands use a +path directly in Python, where the literal name is exactly what is wanted. The only thing `cmd2` +adds is quotes around a match which contains a space, so it stays a single argument. + +### Paths Passed to a Shell + +There are two places where `cmd2` knows that what is being completed will be passed to a shell: the +arguments of the [shell](./builtin_commands.md#shell) command, including its `!` shortcut, and +everything after a [pipe](./redirection.md). There `cmd2` also adds quotes when a match has a +character which is special to that shell, so the shell does not interpret it. For example, +completing `!ls my*` gives: + +```text +(Cmd) !ls "my*file.txt" +``` + +On POSIX systems the characters which get a match quoted are a space, a quote character, `*`, `?`, +`[`, `{`, `}`, `(`, `)`, `<`, `>`, `|`, `&`, `;`, `$`, a backtick, a backslash, and a leading `#` or +`=`. Single quotes are used when a match has a `$`, a backtick, a backslash, or a double quote in +it, since a shell still interprets those within double quotes. On Windows the characters are the +ones `cmd.exe` documents as requiring quotes, other than `~`, and the quotes are always double +quotes. + +There are limits to this: + +- One pair of quotes goes around the whole argument, and it is chosen before you pick a match. So + when several matches are offered and only one of them needs quotes, they all get them. An + executable named `[` is common, so completing a shell command which could match it quotes every + match. +- For the same reason, one quote character is used for all the matches being offered. If any of them + has a single quote in it, double quotes are used, and a `$`, a backtick, or a backslash in any of + the matches is then still interpreted by a shell. +- A `%` in a match is still interpreted by `cmd.exe` on Windows. +- A [macro](./shortcuts_aliases_macros.md#macros) which runs a shell command is not covered. Its + arguments are completed as paths, but they are only quoted for a space. An alias for the `shell` + command is covered. +- Your own commands are not covered, even if they pass their arguments to a shell. Quote or escape + those arguments in the command. + ## Included Tab Completion Functions [cmd2.Cmd][] provides the following tab completion functions diff --git a/tests/conftest.py b/tests/conftest.py index 30359d512..b2e7e091f 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -3,8 +3,12 @@ import os import subprocess import sys -from collections.abc import Callable +from collections.abc import ( + Callable, + Iterable, +) from contextlib import redirect_stderr +from pathlib import Path from typing import ( TYPE_CHECKING, ParamSpec, @@ -61,6 +65,14 @@ def normalize(block: str) -> list[str]: return [line.rstrip() for line in block.splitlines()] +def make_exes(directory: Path, names: Iterable[str]) -> None: + """Create an executable file in directory for each name.""" + for name in names: + exe = directory / name + exe.touch() + exe.chmod(0o755) + + def run_cmd(app: cmd2.Cmd, cmd: str) -> tuple[list[str], list[str]]: """Run the command in app and return what it writes to app.stdout and sys.stderr.""" diff --git a/tests/test_completion.py b/tests/test_completion.py index 39b204602..56b2db8ff 100644 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -24,6 +24,7 @@ ) from .conftest import ( + make_exes, normalize, run_cmd, ) @@ -377,7 +378,7 @@ def test_shell_command_completion_shortcut(cmd_app) -> None: assert [item.display for item in completions] == [item.display for item in expected_completions] -def test_shell_command_completion_does_not_match_wildcards(cmd_app) -> None: +def test_shell_command_completion_does_not_expand_wildcards(cmd_app) -> None: if sys.platform == "win32": text = "c*" else: @@ -387,10 +388,61 @@ def test_shell_command_completion_does_not_match_wildcards(cmd_app) -> None: endidx = len(line) begidx = endidx - len(text) + # A wildcard is matched as a literal character, so this doesn't complete to commands like calc.exe or egrep completions = cmd_app.complete(text, line, begidx, endidx) assert not completions +@pytest.mark.parametrize("prefix", ["[ab]", "[!ab]"]) +def test_shell_command_completion_literal_brackets_in_name(cmd_app, tmp_path, monkeypatch, prefix) -> None: + make_exes(tmp_path, ("[ab]-tool", "[!ab]-tool", "a-tool", "c-tool")) + monkeypatch.setenv("PATH", str(tmp_path)) + line = f"shell {prefix}" + + completions = cmd_app.shell_cmd_complete(prefix, line, len(line) - len(prefix), len(line)) + + assert completions.to_strings() == (f"{prefix}-tool",) + + +def test_shell_command_completion_literal_brackets_in_path_directory(cmd_app, tmp_path, monkeypatch) -> None: + bin_dir = tmp_path / "bin[2026]" + bin_dir.mkdir() + make_exes(bin_dir, ("mytool", "other")) + monkeypatch.setenv("PATH", str(bin_dir)) + text = "my" + line = f"shell {text}" + + completions = cmd_app.shell_cmd_complete(text, line, len(line) - len(text), len(line)) + + assert completions.to_strings() == ("mytool",) + + +def test_shell_command_completion_literal_brackets_in_given_path(cmd_app, tmp_path, monkeypatch) -> None: + # Search text containing a path separator is completed from that path instead of from PATH + bin_dir = tmp_path / "bin[2026]" + bin_dir.mkdir() + make_exes(bin_dir, ("[ab]-tool", "a-tool")) + monkeypatch.setenv("PATH", "") + text = str(bin_dir / "[ab]") + line = f"shell {text}" + + completions = cmd_app.shell_cmd_complete(text, line, len(line) - len(text), len(line)) + + assert completions.to_strings() == (str(bin_dir / "[ab]-tool"),) + + +@pytest.mark.skipif(sys.platform == "win32", reason="'*' and '?' are not legal in Windows file names") +@pytest.mark.parametrize("prefix", ["my*", "my?"]) +def test_shell_command_completion_literal_wildcards_in_name(cmd_app, tmp_path, monkeypatch, prefix) -> None: + make_exes(tmp_path, ("my*tool", "my?tool", "mytool", "myxtool")) + monkeypatch.setenv("PATH", str(tmp_path)) + line = f"shell {prefix}" + + completions = cmd_app.shell_cmd_complete(prefix, line, len(line) - len(prefix), len(line)) + + assert completions.to_strings() == (f"{prefix}tool",) + + def test_shell_command_complete(cmd_app) -> None: if sys.platform == "win32": text = "c" @@ -554,7 +606,7 @@ def test_path_completion_cwd_is_root_dir(cmd_app) -> None: os.chdir(cwd) -def test_path_completion_does_not_match_wildcards(cmd_app, request) -> None: +def test_path_completion_does_not_expand_wildcards(cmd_app, request) -> None: test_dir = os.path.dirname(request.module.__file__) text = os.path.join(test_dir, "c*") @@ -563,11 +615,40 @@ def test_path_completion_does_not_match_wildcards(cmd_app, request) -> None: endidx = len(line) begidx = endidx - len(text) - # Currently path completion doesn't accept wildcards, so will always return empty results + # A wildcard is matched as a literal character, so this doesn't complete to files like conftest.py completions = cmd_app.path_complete(text, line, begidx, endidx) assert not completions +@pytest.mark.skipif(sys.platform == "win32", reason="'*' and '?' are not legal in Windows file names") +@pytest.mark.parametrize("prefix", ["my*", "my?"]) +def test_path_completion_literal_wildcards_in_filename(cmd_app, tmp_path, monkeypatch, prefix) -> None: + for name in ("my*file.txt", "my?file.txt", "myfile.txt", "myxfile.txt"): + (tmp_path / name).touch() + monkeypatch.chdir(tmp_path) + line = f"shell cat {prefix}" + + completions = cmd_app.path_complete(prefix, line, len(line) - len(prefix), len(line)) + + assert completions.to_strings() == (f"{prefix}file.txt",) + + +@pytest.mark.skipif(sys.platform == "win32", reason="'*' and '?' are not legal in Windows file names") +@pytest.mark.parametrize("dir_name", ["project*", "project?"]) +def test_path_completion_literal_wildcards_in_directory(cmd_app, tmp_path, monkeypatch, dir_name) -> None: + # The wildcard in the directory name would also match this directory if it were expanded + for cur_dir, file_name in ((dir_name, "target.txt"), ("project2", "tardy.txt")): + (tmp_path / cur_dir).mkdir() + (tmp_path / cur_dir / file_name).touch() + monkeypatch.chdir(tmp_path) + text = os.path.join(dir_name, "tar") + line = f"shell cat {text}" + + completions = cmd_app.path_complete(text, line, len(line) - len(text), len(line)) + + assert completions.to_strings() == (os.path.join(dir_name, "target.txt"),) + + def test_path_completion_complete_user(cmd_app) -> None: import getpass @@ -831,6 +912,204 @@ def test_add_opening_quote_nothing_added(cmd_app) -> None: assert not completions._quote_char +@pytest.mark.skipif(sys.platform == "win32", reason="some of these are illegal in Windows file names or not special there") +@pytest.mark.parametrize( + ("name", "text", "quote_char"), + [ + # Glob characters + ("[ab].txt", "[ab", '"'), + ("my*file.txt", "my*", '"'), + ("my?file.txt", "my", '"'), + # Characters which are shell syntax + ("file(1).txt", "fi", '"'), + ("a&b.txt", "a", '"'), + ("semi;colon.txt", "se", '"'), + ("{x,y}.txt", "", '"'), + ("#autosave#", "", '"'), + # A quote character is quoted with the other one + ("it's.txt", "it", '"'), + ('say"hi".txt', "say", "'"), + # Characters which a shell still expands within double quotes + ("cost$5.txt", "co", "'"), + ("back`tick.txt", "ba", "'"), + ("back\\slash.txt", "ba", "'"), + ("cost[$5].txt", "", "'"), + ], +) +def test_add_opening_quote_shell_special_path(cmd_app, tmp_path, monkeypatch, name, text, quote_char) -> None: + (tmp_path / name).touch() + monkeypatch.chdir(tmp_path) + line = f"shell cat {text}" + endidx = len(line) + begidx = endidx - len(text) + + # The path has a character which is special to a shell, so quote it + completions = cmd_app.complete(text, line, begidx, endidx) + assert completions.to_strings() == (name,) + assert completions._add_opening_quote + assert completions._quote_char == quote_char + + +def test_add_opening_quote_shell_special_command(cmd_app, tmp_path, monkeypatch) -> None: + make_exes(tmp_path, ["my&tool"]) + monkeypatch.setenv("PATH", str(tmp_path)) + text = "my" + line = f"shell {text}" + endidx = len(line) + begidx = endidx - len(text) + + # Shell commands completed from PATH are quoted like paths are + completions = cmd_app.complete(text, line, begidx, endidx) + assert completions.to_strings() == ("my&tool",) + assert completions._add_opening_quote + assert completions._quote_char == '"' + + +def test_add_opening_quote_unpaired_bracket(cmd_app, tmp_path, monkeypatch) -> None: + # A '[' which isn't followed by a ']' is still a bad pattern to shells like zsh + make_exes(tmp_path, ["g[", "git"]) + monkeypatch.setenv("PATH", str(tmp_path)) + text = "g" + line = f"shell {text}" + endidx = len(line) + begidx = endidx - len(text) + + completions = cmd_app.complete(text, line, begidx, endidx) + assert sorted(completions.to_strings()) == ["g[", "git"] + assert completions._add_opening_quote + assert completions._quote_char == '"' + + +@pytest.mark.parametrize( + ("line_start", "quoted"), + [ + # Arguments to the shell command and everything after a pipe are passed to a shell + ("shell cat ", True), + ("!cat ", True), + ("help | cat ", True), + ("help | cat -n ", True), + ("help | cat > ", True), + # Nothing else is, so these are only quoted if a match has a space + ("edit ", False), + ("run_script ", False), + ("help > ", False), + ("help >> ", False), + ("raw_path ", False), + ("help > out.txt | cat ", False), + ], +) +def test_add_opening_quote_only_for_shell(tmp_path, monkeypatch, line_start, quoted) -> None: + class RawPathApp(cmd2.Cmd): + """Application with a command that receives its argument exactly as it was typed.""" + + def do_raw_path(self, line: cmd2.Statement) -> None: + self.poutput(line) + + complete_raw_path = cmd2.Cmd.path_complete + + (tmp_path / "notes[2026].txt").touch() + monkeypatch.chdir(tmp_path) + app = RawPathApp() + text = "no" + line = line_start + text + endidx = len(line) + begidx = endidx - len(text) + + completions = app.complete(text, line, begidx, endidx) + assert completions.to_strings() == ("notes[2026].txt",) + assert completions._add_opening_quote == quoted + assert completions._quote_char == ('"' if quoted else "") + + +def test_add_opening_quote_shell_command_after_pipe(cmd_app, tmp_path, monkeypatch) -> None: + make_exes(tmp_path, ["my&tool"]) + monkeypatch.setenv("PATH", str(tmp_path)) + text = "my" + line = f"help | {text}" + endidx = len(line) + begidx = endidx - len(text) + + completions = cmd_app.complete(text, line, begidx, endidx) + assert completions.to_strings() == ("my&tool",) + assert completions._add_opening_quote + assert completions._quote_char == '"' + + +def test_add_opening_quote_space_outside_shell(cmd_app, tmp_path, monkeypatch) -> None: + (tmp_path / "my notes.txt").touch() + monkeypatch.chdir(tmp_path) + text = "my" + line = f"edit {text}" + endidx = len(line) + begidx = endidx - len(text) + + # A match with a space is quoted no matter which command it is for + completions = cmd_app.complete(text, line, begidx, endidx) + assert completions.to_strings() == ("my notes.txt",) + assert completions._add_opening_quote + assert completions._quote_char == '"' + + +def test_quote_for_shell_ignored_in_comparison() -> None: + # This is an internal detail which must not make otherwise equal results differ + assert Completions.from_values(["a"]) == dataclasses.replace(Completions.from_values(["a"]), _quote_for_shell=True) + + +class GlobChoicesApp(cmd2.Cmd): + """Application with completion results containing glob characters which are not paths.""" + + choices_parser = cmd2.Cmd2ArgumentParser() + choices_parser.add_argument("item", choices=["all", "*", "pkg[extra]"]) + + @cmd2.with_argparser(choices_parser, preserve_quotes=True) + def do_pick(self, args: argparse.Namespace) -> None: + self.poutput(f"picked {args.item}") + + +@pytest.mark.parametrize(("text", "expected"), [("pk", "pkg[extra]"), ("*", "*")]) +def test_add_opening_quote_not_added_to_non_path(text, expected) -> None: + app = GlobChoicesApp() + line = f"pick {text}" + endidx = len(line) + begidx = endidx - len(text) + + # Only what is passed to a shell is quoted for one. Quoting this would break a command which preserves quotes. + completions = app.complete(text, line, begidx, endidx) + assert completions.to_strings() == (expected,) + assert not completions._add_opening_quote + + out, _err = run_cmd(app, f"pick {expected}") + assert out == [f"picked {expected}"] + + +def test_add_opening_quote_not_added_to_command_name(cmd_app) -> None: + # An alias name can have a glob character in it + run_cmd(cmd_app, "alias create zz* help") + text = "zz" + line = text + endidx = len(line) + begidx = endidx - len(text) + + completions = cmd_app.complete(text, line, begidx, endidx) + assert completions.to_strings() == ("zz*",) + assert not completions._add_opening_quote + + +def test_add_opening_quote_glob_character_already_quoted(cmd_app, tmp_path, monkeypatch) -> None: + (tmp_path / "[ab].txt").touch() + monkeypatch.chdir(tmp_path) + text = "[ab" + line = f"shell cat '{text}" + endidx = len(line) + begidx = endidx - len(text) + + # The search text already has an opening quote, so keep using it + completions = cmd_app.complete(text, line, begidx, endidx) + assert completions.to_strings() == ("[ab].txt",) + assert not completions._add_opening_quote + assert completions._quote_char == "'" + + def test_word_break_in_quote(cmd_app) -> None: """Test case where search text has a space and is in a quote.""" @@ -1112,10 +1391,10 @@ def test_redirect_complete(cmd_app, monkeypatch, line, comp_type) -> None: # Test both cases of allow_redirection cmd_app.allow_redirection = True for _ in range(2): - shell_cmd_complete_mock = mock.MagicMock(name="shell_cmd_complete") + shell_cmd_complete_mock = mock.MagicMock(name="shell_cmd_complete", return_value=Completions()) monkeypatch.setattr("cmd2.Cmd.shell_cmd_complete", shell_cmd_complete_mock) - path_complete_mock = mock.MagicMock(name="path_complete") + path_complete_mock = mock.MagicMock(name="path_complete", return_value=Completions()) monkeypatch.setattr("cmd2.Cmd.path_complete", path_complete_mock) default_complete_mock = mock.MagicMock(name="fake_completer") diff --git a/tests/test_utils.py b/tests/test_utils.py index aaedc708c..e34621f16 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -16,6 +16,8 @@ import cmd2.utils as cu +from .conftest import make_exes + HELLO_WORLD = "Hello, world!" @@ -1806,6 +1808,58 @@ def test_find_editor_not_specified() -> None: assert editor is None +@pytest.mark.skipif(sys.platform == "win32", reason="creating symbolic links requires elevated privileges on Windows") +def test_find_editor_symlinked_directory(tmp_path, monkeypatch) -> None: + real_dir = tmp_path / "real_bin" + real_dir.mkdir() + make_exes(real_dir, ["nano"]) + link_dir = tmp_path / "link_bin" + link_dir.symlink_to(real_dir, target_is_directory=True) + + # A PATH entry which is a symbolic link to a directory is searched + monkeypatch.delenv("EDITOR", raising=False) + monkeypatch.setenv("PATH", str(link_dir)) + assert cu.find_editor() == "nano" + + +def test_find_editor_prefers_earlier_editor(tmp_path, monkeypatch) -> None: + # The editors are tried in order of preference, regardless of which PATH directory they are in + first_dir = tmp_path / "first" + second_dir = tmp_path / "second" + first_dir.mkdir() + second_dir.mkdir() + if sys.platform == "win32": + make_exes(first_dir, ["notepad.exe"]) + make_exes(second_dir, ["edit.exe"]) + expected = "edit" + else: + make_exes(first_dir, ["nano"]) + make_exes(second_dir, ["emacs"]) + expected = "emacs" + + monkeypatch.delenv("EDITOR", raising=False) + monkeypatch.setenv("PATH", os.pathsep.join([str(first_dir), str(second_dir)])) + assert cu.find_editor() == expected + + +def test_find_editor_path_not_set(tmp_path, monkeypatch) -> None: + # Nothing is searched when there is no PATH, not even a default one + monkeypatch.delenv("EDITOR", raising=False) + monkeypatch.delenv("PATH", raising=False) + assert cu.find_editor() is None + + +def test_find_editor_ignores_cwd(tmp_path, monkeypatch) -> None: + # An editor in the current working directory isn't found unless that directory is in PATH + empty_dir = tmp_path / "empty" + empty_dir.mkdir() + make_exes(tmp_path, ["edit.exe", "edit.bat", "edit", "notepad.exe"] if sys.platform == "win32" else ["vim", "nano"]) + monkeypatch.chdir(tmp_path) + monkeypatch.delenv("EDITOR", raising=False) + monkeypatch.setenv("PATH", str(empty_dir)) + assert cu.find_editor() is None + + def test_similarity() -> None: suggested_command = cu.suggest_similar("comand", ["command", "UNRELATED", "NOT_SIMILAR"]) assert suggested_command == "command" @@ -1981,3 +2035,149 @@ def resume(thread_id, signum): foreground.assert_called_once_with(10, pipeline._original_group) else: foreground.assert_not_called() + + +@pytest.mark.parametrize("prefix", ["[ab]", "[!ab]"]) +def test_get_exes_in_path_literal_brackets_in_name(tmp_path, monkeypatch, prefix: str) -> None: + make_exes(tmp_path, ("[ab]-tool", "[!ab]-tool", "a-tool", "c-tool")) + monkeypatch.setenv("PATH", str(tmp_path)) + + assert cu.get_exes_in_path(prefix) == [f"{prefix}-tool"] + + +def test_get_exes_in_path_literal_brackets_in_directory(tmp_path, monkeypatch) -> None: + bin_dir = tmp_path / "bin[2026]" + bin_dir.mkdir() + make_exes(bin_dir, ("mytool", "other")) + monkeypatch.setenv("PATH", str(bin_dir)) + + assert sorted(cu.get_exes_in_path("")) == ["mytool", "other"] + assert cu.get_exes_in_path("my") == ["mytool"] + assert cu.get_exes_in_path("my*") == [] + assert cu.get_exes_in_path("my?") == [] + + +@pytest.mark.skipif(sys.platform == "win32", reason="'*' and '?' are not legal in Windows file names") +@pytest.mark.parametrize("prefix", ["my*", "my?"]) +def test_get_exes_in_path_literal_wildcards_in_name(tmp_path, monkeypatch, prefix: str) -> None: + make_exes(tmp_path, ("my*tool", "my?tool", "mytool", "myxtool")) + monkeypatch.setenv("PATH", str(tmp_path)) + + # A wildcard is matched as a literal character instead of being expanded + assert cu.get_exes_in_path(prefix) == [f"{prefix}tool"] + + +@pytest.mark.skipif(sys.platform == "win32", reason="'*' and '?' are not legal in Windows file names") +@pytest.mark.parametrize("dir_name", ["bin*", "bin?"]) +def test_get_exes_in_path_literal_wildcards_in_directory(tmp_path, monkeypatch, dir_name: str) -> None: + # The wildcard in the PATH directory would also match this directory if it were expanded + for cur_dir, exe_name in ((dir_name, "mytool"), ("bin2", "decoy")): + bin_dir = tmp_path / cur_dir + bin_dir.mkdir() + make_exes(bin_dir, [exe_name]) + monkeypatch.setenv("PATH", str(tmp_path / dir_name)) + + assert cu.get_exes_in_path("") == ["mytool"] + assert cu.get_exes_in_path("my") == ["mytool"] + assert cu.get_exes_in_path("de") == [] + + +@pytest.mark.skipif(sys.platform == "win32", reason="creating symbolic links requires elevated privileges on Windows") +def test_get_exes_in_path_symlinked_directory(tmp_path, monkeypatch) -> None: + real_dir = tmp_path / "real_bin" + real_dir.mkdir() + make_exes(real_dir, ["mytool"]) + link_dir = tmp_path / "link_bin" + link_dir.symlink_to(real_dir, target_is_directory=True) + + # A PATH entry which is a symbolic link to a directory is searched + monkeypatch.setenv("PATH", str(link_dir)) + assert cu.get_exes_in_path("my") == ["mytool"] + + # An executable reachable through more than one PATH entry is only returned once + monkeypatch.setenv("PATH", os.pathsep.join([str(real_dir), str(link_dir), str(real_dir)])) + assert cu.get_exes_in_path("my") == ["mytool"] + + +def test_get_path_dirs_does_not_resolve_entries(monkeypatch) -> None: + # Resolving an entry can raise an exception, such as for one on a network share which can't be reached + # on Windows. Since find_editor() runs when cmd2 is imported, that would keep cmd2 from being imported. + monkeypatch.setenv("PATH", os.pathsep.join(["/unreachable/bin", "relative_bin", "/unreachable/bin"])) + with mock.patch("os.path.realpath", side_effect=OSError("network path was not found")): + assert cu._get_path_dirs() == {"/unreachable/bin", "relative_bin"} + assert cu.get_exes_in_path("my") == [] + monkeypatch.delenv("EDITOR", raising=False) + assert cu.find_editor() is None + + monkeypatch.delenv("PATH") + assert cu._get_path_dirs() == set() + + +@pytest.mark.skipif(sys.platform == "win32", reason="Windows does not allow the current working directory to be removed") +@pytest.mark.parametrize("unusable_entry", ["", "relative_bin"]) +def test_get_exes_in_path_removed_cwd(tmp_path, monkeypatch, unusable_entry: str) -> None: + bin_dir = tmp_path / "bin" + bin_dir.mkdir() + make_exes(bin_dir, ["mytool"]) + cwd = tmp_path / "cwd" + cwd.mkdir() + monkeypatch.chdir(cwd) + cwd.rmdir() + + # An empty or relative PATH entry can't be searched, but that doesn't stop the others from being searched + monkeypatch.setenv("PATH", os.pathsep.join([str(bin_dir), unusable_entry])) + assert cu.get_exes_in_path("my") == ["mytool"] + + +@pytest.mark.parametrize( + ("platform", "matches", "expected"), + [ + # Nothing special + ("linux", ["file.txt", "dir/other-file_2.txt", "~/caf\u00e9.txt", "a]b", "a=b", "c#.txt"], ""), + ("win32", ["file.txt", "C:\\dir\\other-file_2.txt", "~\\file.txt", "c#.txt", "cost$5.txt"], ""), + # One special match is enough + ("linux", ["file.txt", "my file.txt"], '"'), + ("win32", ["file.txt", "my file.txt"], '"'), + # Glob patterns + ("linux", ["my*file.txt"], '"'), + ("linux", ["my?file.txt"], '"'), + ("linux", ["notes[2026].txt"], '"'), + # A '[' is a bad pattern to some shells even without a ']' + ("linux", ["g["], '"'), + # These are only special at the start + ("linux", ["#autosave#"], '"'), + ("linux", ["=equals"], '"'), + # Shell syntax + ("linux", ["a&b"], '"'), + ("linux", ["a;b"], '"'), + ("linux", ["a|b"], '"'), + ("linux", ["ab"], '"'), + ("linux", ["a(b)"], '"'), + ("linux", ["{a,b}"], '"'), + # Quote with whichever quote character the matches don't contain + ("linux", ["it's"], '"'), + ("linux", ['say"hi"'], "'"), + # Single quotes are needed for what a shell expands within double quotes + ("linux", ["cost$5"], "'"), + ("linux", ["back`tick"], "'"), + ("linux", ["back\\slash"], "'"), + ("linux", ["cost$5", "it's"], '"'), + # cmd.exe only understands double quotes, and it has different special characters + ("win32", ["a&b.txt"], '"'), + ("win32", ["a^b.txt"], '"'), + ("win32", ["file(1).txt"], '"'), + ("win32", ["notes[2026].txt"], '"'), + ("win32", ["{guid}"], '"'), + ("win32", ["a,b.txt"], '"'), + ("win32", ["a=b.txt"], '"'), + ("win32", ["a;b.txt"], '"'), + ("win32", ["a+b.txt"], '"'), + ("win32", ["wow!.txt"], '"'), + ("win32", ["back`tick.txt"], '"'), + ("win32", ["it's.txt"], '"'), + ], +) +def test_shell_quote_char(monkeypatch, platform: str, matches: list[str], expected: str) -> None: + monkeypatch.setattr(sys, "platform", platform) + assert cu._shell_quote_char(matches) == expected