From f2b579beba5b019d43081cc2288a60a0e734de10 Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Sat, 14 Nov 2026 08:37:59 -0500 Subject: [PATCH 1/8] Fixed get_exes_in_path() when files or dirs contain brackets --- CHANGELOG.md | 4 ++-- cmd2/cmd2.py | 10 +++++----- cmd2/utils.py | 2 +- tests/test_utils.py | 26 ++++++++++++++++++++++++++ 4 files changed, 34 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84cf989e2..aa48851fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,8 @@ ## Unreleased - Bug Fixes - - Fixed file path completion for names containing square brackets, including bracketed working - directories and home directories. + - Fixed file path and `PATH` executable completion (`path_complete()` and `get_exes_in_path()`) + for names and directories containing literal glob metacharacters such as square brackets. ## 4.4.2 (November 11, 2026) diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 4107fbfc6..7845009e9 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2364,7 +2364,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 @@ -2372,7 +2372,7 @@ 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 @@ -2401,7 +2401,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 @@ -2430,7 +2430,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] @@ -2466,7 +2466,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) diff --git a/cmd2/utils.py b/cmd2/utils.py index 2d80ee5c3..685612e64 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -427,7 +427,7 @@ def get_exes_in_path(starts_with: str) -> list[str]: # Find every executable file in the user's path that matches the pattern for path in paths: 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/tests/test_utils.py b/tests/test_utils.py index aaedc708c..0422dd06f 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -1981,3 +1981,29 @@ 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: + for name in ("[ab]-tool", "[!ab]-tool", "a-tool", "c-tool"): + exe = tmp_path / name + exe.touch() + exe.chmod(0o755) + 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() + for name in ("mytool", "other"): + exe = bin_dir / name + exe.touch() + exe.chmod(0o755) + 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?") == [] From fad2e6706423aa26cc93d8e8536022ba45fd13a9 Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Sun, 15 Nov 2026 00:23:17 -0500 Subject: [PATCH 2/8] Updated CHANGELOG. --- CHANGELOG.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aa48851fb..8e0dd0de8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,10 @@ ## Unreleased - Bug Fixes - - Fixed file path and `PATH` executable completion (`path_complete()` and `get_exes_in_path()`) - for names and directories containing literal glob metacharacters such as square brackets. + - Fixed file path completion for names containing square brackets, including bracketed working + directories and home directories. + - Fixed `get_exes_in_path()` when executable names or `PATH` directories contain square + brackets. ## 4.4.2 (November 11, 2026) From c298a9eb4c686ee6b4ccdf054ea84c0444c19893 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:56:04 -0500 Subject: [PATCH 3/8] Match glob characters literally in completion and search symlinked PATH entries Removed the guard which made path_complete() and get_exes_in_path() return nothing when the search text contained '*' or '?'. Since the search text now goes through glob.escape(), those characters are matched literally like any other, so names containing them can be completed. get_exes_in_path() and find_editor() no longer skip PATH entries which are symbolic links to directories. get_exes_in_path() resolves each entry so a directory reachable through more than one entry is only searched once. Documented that completion results are literal names which are not escaped for a shell, and added tests for shell_cmd_complete() with bracketed names and for PATH directories containing glob characters. --- CHANGELOG.md | 11 ++++- cmd2/cmd2.py | 9 ++-- cmd2/utils.py | 18 ++++--- docs/features/completion.md | 17 +++++++ tests/test_completion.py | 94 +++++++++++++++++++++++++++++++++++-- tests/test_utils.py | 67 ++++++++++++++++++++++++++ 6 files changed, 195 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 362b99ae1..f713aae19 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,8 +3,15 @@ - Bug Fixes - Fixed file path completion for names containing square brackets, including bracketed working directories and home directories. - - Fixed `get_exes_in_path()` when executable names or `PATH` directories contain square - brackets. + - 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. Completion results are not escaped for a shell. + 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. - 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 275a02779..283661333 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2385,6 +2385,9 @@ def path_complete( ) -> Completions: """Perform completion of local file system paths. + 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 @@ -2412,12 +2415,6 @@ def path_complete( 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 diff --git a/cmd2/utils.py b/cmd2/utils.py index 685612e64..ed9a499e4 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -358,9 +358,9 @@ def find_editor() -> str | None: 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 + # Get a list of every directory in the PATH environment variable 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)] + paths = [] if env_path is None else env_path.split(os.path.pathsep) for possible_editor, path in itertools.product(editors, paths): editor_path = os.path.join(path, possible_editor) @@ -408,18 +408,16 @@ 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 + # Get every directory in the PATH environment variable. Resolve symbolic links so + # a directory which is reachable through more than one entry is only searched once. 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)] + paths = [] if env_path is None else list(dict.fromkeys(os.path.realpath(p) for p in env_path.split(os.path.pathsep))) # Use a set to store exe names since there can be duplicates exes_set = set() diff --git a/docs/features/completion.md b/docs/features/completion.md index 1def16f23..3d32eeb65 100644 --- a/docs/features/completion.md +++ b/docs/features/completion.md @@ -33,6 +33,23 @@ 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. + +Completion results are literal names too. `cmd2` adds an opening quote when a match contains a +space, but it does not escape characters which are special to a shell, because it has no way of +knowing how a command will use the path. Most commands use a path directly in Python, where the +literal name is exactly what is wanted. If a completed path is going to be passed to a shell, as the +[shell](./builtin_commands.md#shell) command does with its arguments, then quote or escape it +yourself: + +```text +(Cmd) !ls 'my*file.txt' +``` + ## Included Tab Completion Functions [cmd2.Cmd][] provides the following tab completion functions diff --git a/tests/test_completion.py b/tests/test_completion.py index 39b204602..52cad1738 100644 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -377,7 +377,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 +387,69 @@ 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 +def _make_exes(directory, names) -> None: + """Create an executable file in directory for each name.""" + for name in names: + exe = directory / name + exe.touch() + exe.chmod(0o755) + + +@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 +613,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 +622,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 diff --git a/tests/test_utils.py b/tests/test_utils.py index 0422dd06f..67b6969b0 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -1806,6 +1806,22 @@ 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() + exe = real_dir / "nano" + exe.touch() + exe.chmod(0o755) + 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_similarity() -> None: suggested_command = cu.suggest_similar("comand", ["command", "UNRELATED", "NOT_SIMILAR"]) assert suggested_command == "command" @@ -2007,3 +2023,54 @@ def test_get_exes_in_path_literal_brackets_in_directory(tmp_path, monkeypatch) - 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: + for name in ("my*tool", "my?tool", "mytool", "myxtool"): + exe = tmp_path / name + exe.touch() + exe.chmod(0o755) + 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() + exe = bin_dir / exe_name + exe.touch() + exe.chmod(0o755) + 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() + exe = real_dir / "mytool" + exe.touch() + exe.chmod(0o755) + 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"] + + # A directory reachable through more than one PATH entry is only searched once + monkeypatch.setenv("PATH", os.pathsep.join([str(real_dir), str(link_dir)])) + with mock.patch("cmd2.utils.files_from_glob_pattern", wraps=cu.files_from_glob_pattern) as glob_mock: + assert cu.get_exes_in_path("my") == ["mytool"] + glob_mock.assert_called_once() From 40a47cf5d93dbfcd5fec85d4dc674580957c8f21 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Mon, 16 Nov 2026 15:29:43 -0500 Subject: [PATCH 4/8] Quote completions containing glob characters and address review findings Tab completion now adds quotes to a match containing '*', '?', or '[', as it already did for a match containing a space. With the wildcard guard gone, completing '!rm my*' to an unquoted 'my*file.txt' would have let the shell expand it to every matching file. get_exes_in_path() no longer raises when PATH has an empty or relative entry and the current working directory has been removed. Only absolute entries are resolved with realpath(). find_editor() now uses shutil.which() instead of walking PATH by hand. As a side effect it can find 'edit' on Windows, which the old search never could because it did not try any file extensions. Documented that a leading '~' is the exception to literal matching, promoted the 'Special Characters in Paths' docs section to H2, and moved the test helper which creates fake executables into conftest.py. --- CHANGELOG.md | 9 +++-- cmd2/cmd2.py | 9 +++-- cmd2/utils.py | 34 +++++++++---------- docs/features/completion.md | 27 ++++++++++----- tests/conftest.py | 14 +++++++- tests/test_completion.py | 55 ++++++++++++++++++++++++------- tests/test_utils.py | 65 +++++++++++++++++++++++++------------ 7 files changed, 146 insertions(+), 67 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f713aae19..5e32c5b43 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,16 @@ 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. Completion results are not escaped for a shell. - See the [Special Characters in Paths](docs/features/completion.md#special-characters-in-paths) + containing those characters can be completed. + - Tab completion now adds quotes to a match containing one of the glob characters `*`, `?`, and + `[`, as it already did for a match containing a space. This keeps a shell from expanding the + completed text when it is passed to one by the `shell` command or a pipe. 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 the search did not try any file extensions. - 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 283661333..a4498667f 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2385,8 +2385,9 @@ def path_complete( ) -> Completions: """Perform completion of local file system paths. - Every character in ``text`` is matched literally. Glob characters like ``*``, ``?``, and ``[`` are not - expanded, and they are not escaped in the results. + 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 @@ -2726,7 +2727,9 @@ def _perform_completion( if not completion_token_quote: matches = completions.to_strings() - if any(" " in match for match in matches): + # A match with a space needs quotes to remain a single token. A match with a glob character + # gets them so it isn't expanded if the command line is passed to a shell. + if any(char in match for match in matches for char in " *?["): _add_opening_quote = True # Determine best quote (single vs double) based on text content diff --git a/cmd2/utils.py b/cmd2/utils.py index ed9a499e4..7a0786ed9 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -6,9 +6,9 @@ import glob import inspect import io -import itertools import os import re +import shutil import subprocess import sys import threading @@ -358,21 +358,12 @@ def find_editor() -> str | None: else: editors = ["vim", "vi", "emacs", "nano", "pico", "joe", "code", "subl", "gedit", "kate"] - # Get a list of every directory in the PATH environment variable - env_path = os.getenv("PATH") - paths = [] if env_path is None else env_path.split(os.path.pathsep) - - for possible_editor, path in itertools.product(editors, paths): - 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": - # Remove extension from Windows file names - editor = os.path.splitext(possible_editor)[0] - else: - editor = possible_editor - break - else: - editor = None + # Use the first of these editors which the shell would be able to find + editor = next((cur_editor for cur_editor in editors if shutil.which(cur_editor)), None) + + # Remove extension from Windows file names + if editor is not None and sys.platform[:3] == "win": + editor = os.path.splitext(editor)[0] return editor @@ -414,10 +405,15 @@ def get_exes_in_path(starts_with: str) -> list[str]: :param starts_with: what the exes should start with. leave blank for all exes in path. :return: a list of matching exe names """ - # Get every directory in the PATH environment variable. Resolve symbolic links so - # a directory which is reachable through more than one entry is only searched once. + # Get every directory in the PATH environment variable. Resolve symbolic links so a directory which is reachable + # through more than one entry is only searched once. Relative entries are left as they are since resolving one + # raises an exception if the current working directory no longer exists. env_path = os.getenv("PATH") - paths = [] if env_path is None else list(dict.fromkeys(os.path.realpath(p) for p in env_path.split(os.path.pathsep))) + paths = ( + set() + if env_path is None + else {os.path.realpath(p) if os.path.isabs(p) else p for p in env_path.split(os.path.pathsep)} + ) # Use a set to store exe names since there can be duplicates exes_set = set() diff --git a/docs/features/completion.md b/docs/features/completion.md index 3d32eeb65..0c1048492 100644 --- a/docs/features/completion.md +++ b/docs/features/completion.md @@ -33,23 +33,32 @@ 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 +## 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. +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` adds an opening quote when a match contains a -space, but it does not escape characters which are special to a shell, because it has no way of -knowing how a command will use the path. Most commands use a path directly in Python, where the -literal name is exactly what is wanted. If a completed path is going to be passed to a shell, as the -[shell](./builtin_commands.md#shell) command does with its arguments, then quote or escape it -yourself: +Completion results are literal names too. `cmd2` does not escape them, because it has no way of +knowing how a command will use a path. Most commands use a path directly in Python, where the +literal name is exactly what is wanted. What `cmd2` does do is add quotes when a match contains a +space or one of the glob characters `*`, `?`, and `[`: ```text -(Cmd) !ls 'my*file.txt' +(Cmd) !ls my* +(Cmd) !ls "my*file.txt" ``` +The quotes keep a match with a space together as a single argument. They also keep a shell from +expanding a glob character if the command line is passed to one, as the +[shell](./builtin_commands.md#shell) command and a [pipe](./redirection.md) do. `cmd2` removes the +quotes before passing the argument to a command, unless that command asked to preserve them. + +Characters which stay special to a shell inside double quotes, such as `$` and a backtick, are not +covered by this. If a path containing one is going to be passed to a shell, then quote or escape it +yourself. + ## 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 52cad1738..9162721d6 100644 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -24,6 +24,7 @@ ) from .conftest import ( + make_exes, normalize, run_cmd, ) @@ -392,17 +393,9 @@ def test_shell_command_completion_does_not_expand_wildcards(cmd_app) -> None: assert not completions -def _make_exes(directory, names) -> None: - """Create an executable file in directory for each name.""" - for name in names: - exe = directory / name - exe.touch() - exe.chmod(0o755) - - @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")) + make_exes(tmp_path, ("[ab]-tool", "[!ab]-tool", "a-tool", "c-tool")) monkeypatch.setenv("PATH", str(tmp_path)) line = f"shell {prefix}" @@ -414,7 +407,7 @@ def test_shell_command_completion_literal_brackets_in_name(cmd_app, tmp_path, mo 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")) + make_exes(bin_dir, ("mytool", "other")) monkeypatch.setenv("PATH", str(bin_dir)) text = "my" line = f"shell {text}" @@ -428,7 +421,7 @@ def test_shell_command_completion_literal_brackets_in_given_path(cmd_app, tmp_pa # 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")) + make_exes(bin_dir, ("[ab]-tool", "a-tool")) monkeypatch.setenv("PATH", "") text = str(bin_dir / "[ab]") line = f"shell {text}" @@ -441,7 +434,7 @@ def test_shell_command_completion_literal_brackets_in_given_path(cmd_app, tmp_pa @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")) + make_exes(tmp_path, ("my*tool", "my?tool", "mytool", "myxtool")) monkeypatch.setenv("PATH", str(tmp_path)) line = f"shell {prefix}" @@ -919,6 +912,44 @@ def test_add_opening_quote_nothing_added(cmd_app) -> None: assert not completions._quote_char +@pytest.mark.parametrize( + "name", + [ + "[ab].txt", + pytest.param("my*file.txt", marks=pytest.mark.skipif(sys.platform == "win32", reason="illegal Windows file name")), + pytest.param("my?file.txt", marks=pytest.mark.skipif(sys.platform == "win32", reason="illegal Windows file name")), + ], +) +def test_add_opening_quote_glob_character(cmd_app, tmp_path, monkeypatch, name) -> None: + (tmp_path / name).touch() + monkeypatch.chdir(tmp_path) + text = name[:3] + line = f"shell cat {text}" + endidx = len(line) + begidx = endidx - len(text) + + # The match has a glob character, so quote it to keep a shell from expanding it + completions = cmd_app.complete(text, line, begidx, endidx) + assert completions.to_strings() == (name,) + assert completions._add_opening_quote + assert completions._quote_char == '"' + + +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.""" diff --git a/tests/test_utils.py b/tests/test_utils.py index 67b6969b0..bf75cdb1d 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!" @@ -1810,9 +1812,7 @@ def test_find_editor_not_specified() -> None: def test_find_editor_symlinked_directory(tmp_path, monkeypatch) -> None: real_dir = tmp_path / "real_bin" real_dir.mkdir() - exe = real_dir / "nano" - exe.touch() - exe.chmod(0o755) + make_exes(real_dir, ["nano"]) link_dir = tmp_path / "link_bin" link_dir.symlink_to(real_dir, target_is_directory=True) @@ -1822,6 +1822,26 @@ def test_find_editor_symlinked_directory(tmp_path, monkeypatch) -> None: 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, ["notepad++.exe"]) + expected = "notepad++" + 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_similarity() -> None: suggested_command = cu.suggest_similar("comand", ["command", "UNRELATED", "NOT_SIMILAR"]) assert suggested_command == "command" @@ -2001,10 +2021,7 @@ def resume(thread_id, signum): @pytest.mark.parametrize("prefix", ["[ab]", "[!ab]"]) def test_get_exes_in_path_literal_brackets_in_name(tmp_path, monkeypatch, prefix: str) -> None: - for name in ("[ab]-tool", "[!ab]-tool", "a-tool", "c-tool"): - exe = tmp_path / name - exe.touch() - exe.chmod(0o755) + 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"] @@ -2013,10 +2030,7 @@ def test_get_exes_in_path_literal_brackets_in_name(tmp_path, monkeypatch, prefix def test_get_exes_in_path_literal_brackets_in_directory(tmp_path, monkeypatch) -> None: bin_dir = tmp_path / "bin[2026]" bin_dir.mkdir() - for name in ("mytool", "other"): - exe = bin_dir / name - exe.touch() - exe.chmod(0o755) + make_exes(bin_dir, ("mytool", "other")) monkeypatch.setenv("PATH", str(bin_dir)) assert sorted(cu.get_exes_in_path("")) == ["mytool", "other"] @@ -2028,10 +2042,7 @@ def test_get_exes_in_path_literal_brackets_in_directory(tmp_path, monkeypatch) - @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: - for name in ("my*tool", "my?tool", "mytool", "myxtool"): - exe = tmp_path / name - exe.touch() - exe.chmod(0o755) + 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 @@ -2045,9 +2056,7 @@ def test_get_exes_in_path_literal_wildcards_in_directory(tmp_path, monkeypatch, for cur_dir, exe_name in ((dir_name, "mytool"), ("bin2", "decoy")): bin_dir = tmp_path / cur_dir bin_dir.mkdir() - exe = bin_dir / exe_name - exe.touch() - exe.chmod(0o755) + make_exes(bin_dir, [exe_name]) monkeypatch.setenv("PATH", str(tmp_path / dir_name)) assert cu.get_exes_in_path("") == ["mytool"] @@ -2059,9 +2068,7 @@ def test_get_exes_in_path_literal_wildcards_in_directory(tmp_path, monkeypatch, def test_get_exes_in_path_symlinked_directory(tmp_path, monkeypatch) -> None: real_dir = tmp_path / "real_bin" real_dir.mkdir() - exe = real_dir / "mytool" - exe.touch() - exe.chmod(0o755) + make_exes(real_dir, ["mytool"]) link_dir = tmp_path / "link_bin" link_dir.symlink_to(real_dir, target_is_directory=True) @@ -2074,3 +2081,19 @@ def test_get_exes_in_path_symlinked_directory(tmp_path, monkeypatch) -> None: with mock.patch("cmd2.utils.files_from_glob_pattern", wraps=cu.files_from_glob_pattern) as glob_mock: assert cu.get_exes_in_path("my") == ["mytool"] glob_mock.assert_called_once() + + +@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"] From 148fb541c39be02028b5c043c7fe9d83064b81b3 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:03:00 -0500 Subject: [PATCH 5/8] Only quote path and shell command completions for the shell The glob-character quoting added in the previous commit applied to every completer. That broke commands which preserve quotes when one of their choices had a glob character, left a stray quote when completing an alias with a glob character in its name, and quoted every shell command when an executable named '[' was among the matches. path_complete() and shell_cmd_complete() now mark their results, and only marked results are quoted for a shell. The check covers the characters which are special to the platform's shell rather than only glob characters, a '[' only counts when a ']' follows it, and single quotes are used on POSIX when a name has a character which a shell still expands within double quotes. All other completions are quoted only for a space, as before. find_editor() goes back to searching the PATH directories itself. shutil.which() also searched the current directory on Windows and fell back to a default path when PATH was not set. The Windows editor list now names edit.exe so it can still be found. find_editor() and get_exes_in_path() share one helper for reading PATH. --- CHANGELOG.md | 9 ++-- cmd2/cmd2.py | 18 ++++--- cmd2/completion.py | 4 ++ cmd2/utils.py | 83 +++++++++++++++++++++++------- docs/features/completion.md | 33 ++++++++---- tests/test_completion.py | 100 +++++++++++++++++++++++++++++++++--- tests/test_utils.py | 70 ++++++++++++++++++++++++- 7 files changed, 269 insertions(+), 48 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e32c5b43..660ae2041 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,15 +8,16 @@ - 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 to a match containing one of the glob characters `*`, `?`, and - `[`, as it already did for a match containing a space. This keeps a shell from expanding the - completed text when it is passed to one by the `shell` command or a pipe. See the + - Tab completion of file paths and shell commands now adds quotes when a match has a character + which is special to a shell, such as `*`, `?`, `(`, `&`, or `$`. Previously only a space did + this. This keeps a shell from interpreting the completed text when it is passed to one by the + `shell` command or a pipe. 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 the search did not try any file extensions. + 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 a4498667f..79296ecf7 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2387,7 +2387,8 @@ def path_complete( 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. + escaped in the results. When these results are used for tab completion, quotes are added if any + of them has a character which is special to a shell. :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 @@ -2480,7 +2481,7 @@ def path_complete( for match, display in zip(matches, display_matches, strict=True) ] - return Completions(items=items, allow_finalization=allow_finalization) + return Completions(items=items, allow_finalization=allow_finalization, _quote_for_shell=True) def shell_cmd_complete( self, text: str, line: str, begidx: int, endidx: int, *, complete_blank: bool = False @@ -2502,7 +2503,7 @@ def shell_cmd_complete( # 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) + return Completions(items=items, _quote_for_shell=True) # Otherwise look for executables in the given path return self.path_complete( @@ -2727,9 +2728,14 @@ def _perform_completion( if not completion_token_quote: matches = completions.to_strings() - # A match with a space needs quotes to remain a single token. A match with a glob character - # gets them so it isn't expanded if the command line is passed to a shell. - if any(char in match for match in matches for char in " *?["): + # Paths and shell commands can end up on a shell's command line, so + # they need quotes if any of them has a character special to a shell. + if completions._quote_for_shell: + _quote_char = utils._path_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 diff --git a/cmd2/completion.py b/cmd2/completion.py index 460b65c12..8ac913df8 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 file system paths or shell commands. Either can end up on a shell's command + # line, so these are also quoted when a match has a character which is special to a shell. + _quote_for_shell: bool = False diff --git a/cmd2/utils.py b/cmd2/utils.py index 7a0786ed9..04bb1208d 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -6,9 +6,9 @@ import glob import inspect import io +import itertools import os import re -import shutil import subprocess import sys import threading @@ -17,6 +17,7 @@ Generator, Iterable, MutableSequence, + Sequence, ) from difflib import SequenceMatcher from typing import ( @@ -323,6 +324,39 @@ def expand_user_in_tokens(tokens: MutableSequence[str]) -> None: tokens[index] = expand_user(tokens[index]) +# Matches a character in a path which is special to a POSIX shell or to cmd2's own parser. +# A '[' only counts when a ']' follows it, since it can't begin a glob pattern otherwise and +# there are common executables with that name. A '#' only counts where it begins a comment. +_POSIX_SPECIAL_RE = re.compile(r"""[ \t"';|<>&()*?{}$`\\]|\[.*]|^#""") + +# The same for cmd.exe, which does not expand glob patterns and has '\' as its path separator +_WINDOWS_SPECIAL_RE = re.compile(r"""[ \t"';|<>&()^]""") + + +def _path_quote_char(paths: Sequence[str]) -> str: + """Return the quote character which paths offered as completions need to be wrapped in. + + A completed path becomes part of a command line which cmd2 parses and which may then be passed to a + shell, so it needs quotes if it has a character which is special to either of them. + + :param paths: the paths being offered as completions + :return: the quote character to use, or an empty string if none of the paths 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(path) for path in paths) else "" + + if not any(_POSIX_SPECIAL_RE.search(path) for path in paths): + return "" + + # A quote character within a path has to be quoted with the other quote character + if any("'" in path for path in paths): + return '"' + + # Only use single quotes when a shell would still expand something within double quotes + return "'" if any(char in path for path in paths 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 +379,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. + + Symbolic links are resolved so a directory which is reachable through more than one entry is only + returned once. Relative entries are returned as they are since resolving one raises an exception if + the current working directory no longer exists. + + :return: the directories, which is an empty set if PATH is not set + """ + env_path = os.getenv("PATH") + if env_path is None: + return set() + return {os.path.realpath(p) if os.path.isabs(p) else p for p in 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,16 +403,22 @@ 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"] - # Use the first of these editors which the shell would be able to find - editor = next((cur_editor for cur_editor in editors if shutil.which(cur_editor)), None) - - # Remove extension from Windows file names - if editor is not None and sys.platform[:3] == "win": - editor = os.path.splitext(editor)[0] + # 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": + # Remove extension from Windows file names + editor = os.path.splitext(possible_editor)[0] + else: + editor = possible_editor + break + else: + editor = None return editor @@ -405,21 +460,11 @@ def get_exes_in_path(starts_with: str) -> list[str]: :param starts_with: what the exes should start with. leave blank for all exes in path. :return: a list of matching exe names """ - # Get every directory in the PATH environment variable. Resolve symbolic links so a directory which is reachable - # through more than one entry is only searched once. Relative entries are left as they are since resolving one - # raises an exception if the current working directory no longer exists. - env_path = os.getenv("PATH") - paths = ( - set() - if env_path is None - else {os.path.realpath(p) if os.path.isabs(p) else p for p in env_path.split(os.path.pathsep)} - ) - # 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(glob.escape(full_path) + "*", access=os.X_OK) diff --git a/docs/features/completion.md b/docs/features/completion.md index 0c1048492..4ee948053 100644 --- a/docs/features/completion.md +++ b/docs/features/completion.md @@ -42,22 +42,35 @@ does in a shell. Completion results are literal names too. `cmd2` does not escape them, because it has no way of knowing how a command will use a path. Most commands use a path directly in Python, where the -literal name is exactly what is wanted. What `cmd2` does do is add quotes when a match contains a -space or one of the glob characters `*`, `?`, and `[`: +literal name is exactly what is wanted. What `cmd2` does do is add quotes when a completed path or +shell command has a character which is special to a shell: ```text (Cmd) !ls my* (Cmd) !ls "my*file.txt" ``` -The quotes keep a match with a space together as a single argument. They also keep a shell from -expanding a glob character if the command line is passed to one, as the -[shell](./builtin_commands.md#shell) command and a [pipe](./redirection.md) do. `cmd2` removes the -quotes before passing the argument to a command, unless that command asked to preserve them. - -Characters which stay special to a shell inside double quotes, such as `$` and a backtick, are not -covered by this. If a path containing one is going to be passed to a shell, then quote or escape it -yourself. +The quotes keep a shell from interpreting the name if the command line is passed to one, as the +[shell](./builtin_commands.md#shell) command and a [pipe](./redirection.md) do. They also keep +`cmd2` from treating a character like `;` or `>` in the name as part of its own syntax. `cmd2` +removes the quotes before passing the argument to a command, unless that command asked to preserve +them. + +On POSIX systems the characters which get a name quoted are a space, a quote character, `*`, `?`, +`[` when a `]` follows it, `{`, `}`, `(`, `)`, `<`, `>`, `|`, `&`, `;`, `$`, a backtick, a +backslash, and a leading `#`. Single quotes are used when a name has a `$`, a backtick, or a +backslash, since a shell still interprets those within double quotes. On Windows the characters are +a space, `'`, `&`, `(`, `)`, `^`, and `;`, and the quotes are always double quotes. + +There are limits to this: + +- The quotes go around the whole argument, so when several matches are offered and only one of them + needs quotes, they all get them. +- A name with a single quote in it is wrapped in double quotes, so a `$`, a backtick, or a backslash + in that same name is still interpreted by a shell. +- A `%` in a name is still interpreted by `cmd.exe` on Windows. +- Only paths and shell commands completed by `cmd2` are quoted this way. Results from your own + completers and choices are only quoted when one of them contains a space. ## Included Tab Completion Functions diff --git a/tests/test_completion.py b/tests/test_completion.py index 9162721d6..77b523a59 100644 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -912,29 +912,115 @@ def test_add_opening_quote_nothing_added(cmd_app) -> None: assert not completions._quote_char +@pytest.mark.skipif(sys.platform == "win32", reason="these characters are either illegal in Windows file names or not special") @pytest.mark.parametrize( - "name", + ("name", "text", "quote_char"), [ - "[ab].txt", - pytest.param("my*file.txt", marks=pytest.mark.skipif(sys.platform == "win32", reason="illegal Windows file name")), - pytest.param("my?file.txt", marks=pytest.mark.skipif(sys.platform == "win32", reason="illegal Windows file name")), + # 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_glob_character(cmd_app, tmp_path, monkeypatch, name) -> None: +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) - text = name[:3] line = f"shell cat {text}" endidx = len(line) begidx = endidx - len(text) - # The match has a glob character, so quote it to keep a shell from expanding it + # 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_not_special(cmd_app, tmp_path, monkeypatch) -> None: + # A '[' which isn't followed by a ']' can't begin a glob pattern. Executables named '[' and 'g[' are + # common, and they must not cause every other shell command to be quoted. + 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 not completions._add_opening_quote + assert not completions._quote_char + + +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 paths are quoted for a shell. 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) diff --git a/tests/test_utils.py b/tests/test_utils.py index bf75cdb1d..5914919b7 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -1830,8 +1830,8 @@ def test_find_editor_prefers_earlier_editor(tmp_path, monkeypatch) -> None: second_dir.mkdir() if sys.platform == "win32": make_exes(first_dir, ["notepad.exe"]) - make_exes(second_dir, ["notepad++.exe"]) - expected = "notepad++" + make_exes(second_dir, ["edit.exe"]) + expected = "edit" else: make_exes(first_dir, ["nano"]) make_exes(second_dir, ["emacs"]) @@ -1842,6 +1842,24 @@ def test_find_editor_prefers_earlier_editor(tmp_path, monkeypatch) -> None: 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" @@ -2097,3 +2115,51 @@ def test_get_exes_in_path_removed_cwd(tmp_path, monkeypatch, unusable_entry: str # 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"], ""), + ("win32", ["file.txt", "C:\\dir\\other-file_2.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 only special when a ']' follows it + ("linux", ["[", "g["], ""), + ("linux", ["]["], ""), + # A '#' is only special at the start + ("linux", ["#autosave#"], '"'), + ("linux", ["c#.txt"], ""), + # 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", ["it's.txt"], '"'), + ("win32", ["cost$5.txt", "notes[2026].txt", "{a,b}", "#autosave#"], ""), + ], +) +def test_path_quote_char(monkeypatch, platform: str, matches: list[str], expected: str) -> None: + monkeypatch.setattr(sys, "platform", platform) + assert cu._path_quote_char(matches) == expected From 19d9a46d48819bd89c33359f9cae9a6c6765eefb Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:31:33 -0500 Subject: [PATCH 6/8] Only quote completions for the shell where they are passed to one Quoting every path_complete() result for shell-special characters reached commands which never involve a shell. A command taking its raw argument, with path_complete as its completer, received the quotes literally for a name like notes[2026].txt and could no longer open the file. The quoting is now decided where cmd2 knows a shell is the consumer: the arguments of the shell command and everything after a pipe. Everywhere else only a match with a space is quoted, as before. Within that scope a '[' is special even with no ']' after it, since zsh rejects it as a bad pattern, a leading '=' is special on POSIX, and the Windows list follows the characters cmd.exe documents as requiring quotes. The private Completions._quote_for_shell field no longer takes part in comparisons. --- CHANGELOG.md | 8 ++-- cmd2/cmd2.py | 37 ++++++++++----- cmd2/completion.py | 6 +-- cmd2/utils.py | 33 ++++++------- docs/features/completion.md | 45 +++++++++--------- tests/test_completion.py | 94 +++++++++++++++++++++++++++++++++---- tests/test_utils.py | 26 ++++++---- 7 files changed, 171 insertions(+), 78 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 660ae2041..9cbe3abe4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,10 +8,10 @@ - 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 of file paths and shell commands now adds quotes when a match has a character - which is special to a shell, such as `*`, `?`, `(`, `&`, or `$`. Previously only a space did - this. This keeps a shell from interpreting the completed text when it is passed to one by the - `shell` command or a pipe. See the + - 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` diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 79296ecf7..f51d254fc 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2387,8 +2387,7 @@ def path_complete( 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. When these results are used for tab completion, quotes are added if any - of them has a character which is special to a shell. + 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 @@ -2481,7 +2480,7 @@ def path_complete( for match, display in zip(matches, display_matches, strict=True) ] - return Completions(items=items, allow_finalization=allow_finalization, _quote_for_shell=True) + return Completions(items=items, allow_finalization=allow_finalization) def shell_cmd_complete( self, text: str, line: str, begidx: int, endidx: int, *, complete_blank: bool = False @@ -2503,7 +2502,7 @@ def shell_cmd_complete( # 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, _quote_for_shell=True) + return Completions(items=items) # Otherwise look for executables in the given path return self.path_complete( @@ -2535,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 @@ -2545,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,10 +2582,12 @@ 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) + completions = self.shell_cmd_complete(text, line, begidx, endidx) + return dataclasses.replace(completions, _quote_for_shell=piped_to_shell) if do_path_completion: - return self.path_complete(text, line, begidx, endidx) + completions = self.path_complete(text, line, begidx, endidx) + return dataclasses.replace(completions, _quote_for_shell=piped_to_shell) # If there were redirection strings anywhere on the command line, then we # are no longer completing for the current command @@ -2728,10 +2734,9 @@ def _perform_completion( if not completion_token_quote: matches = completions.to_strings() - # Paths and shell commands can end up on a shell's command line, so - # they need quotes if any of them has a character special to a shell. + # 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._path_quote_char(matches) + _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 @@ -5042,13 +5047,23 @@ 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 + def _complete_shell_command(self, text: str, line: str, begidx: int, endidx: int) -> Completions: + """Complete the command which do_shell passes to a shell.""" + completions = self.shell_cmd_complete(text, line, begidx, endidx) + return dataclasses.replace(completions, _quote_for_shell=True) + + 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.""" + completions = self.path_complete(text, line, begidx, endidx) + return dataclasses.replace(completions, _quote_for_shell=True) + # 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 8ac913df8..434f72cd6 100644 --- a/cmd2/completion.py +++ b/cmd2/completion.py @@ -306,6 +306,6 @@ 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 file system paths or shell commands. Either can end up on a shell's command - # line, so these are also quoted when a match has a character which is special to a shell. - _quote_for_shell: bool = False + # 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 04bb1208d..9eaa2081f 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -324,37 +324,34 @@ def expand_user_in_tokens(tokens: MutableSequence[str]) -> None: tokens[index] = expand_user(tokens[index]) -# Matches a character in a path which is special to a POSIX shell or to cmd2's own parser. -# A '[' only counts when a ']' follows it, since it can't begin a glob pattern otherwise and -# there are common executables with that name. A '#' only counts where it begins a comment. -_POSIX_SPECIAL_RE = re.compile(r"""[ \t"';|<>&()*?{}$`\\]|\[.*]|^#""") +# 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"';|<>&()*?\[{}$`\\]|^[#=]""") -# The same for cmd.exe, which does not expand glob patterns and has '\' as its path separator -_WINDOWS_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 _path_quote_char(paths: Sequence[str]) -> str: - """Return the quote character which paths offered as completions need to be wrapped in. +def _shell_quote_char(matches: Sequence[str]) -> str: + """Return the quote character which completions being passed to a shell need to be wrapped in. - A completed path becomes part of a command line which cmd2 parses and which may then be passed to a - shell, so it needs quotes if it has a character which is special to either of them. - - :param paths: the paths being offered as completions - :return: the quote character to use, or an empty string if none of the paths need quotes + :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(path) for path in paths) else "" + return '"' if any(_WINDOWS_SPECIAL_RE.search(match) for match in matches) else "" - if not any(_POSIX_SPECIAL_RE.search(path) for path in paths): + if not any(_POSIX_SPECIAL_RE.search(match) for match in matches): return "" - # A quote character within a path has to be quoted with the other quote character - if any("'" in path for path in paths): + # 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 path for path in paths for char in '"$`\\') else '"' + return "'" if any(char in match for match in matches for char in '"$`\\') else '"' def _quote_shell_arg(arg: str) -> str: diff --git a/docs/features/completion.md b/docs/features/completion.md index 4ee948053..1be63a21f 100644 --- a/docs/features/completion.md +++ b/docs/features/completion.md @@ -40,37 +40,38 @@ Path and shell command completion match the text being completed literally. Glob 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 it has no way of -knowing how a command will use a path. Most commands use a path directly in Python, where the -literal name is exactly what is wanted. What `cmd2` does do is add quotes when a completed path or -shell command has a character which is special to 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* (Cmd) !ls "my*file.txt" ``` -The quotes keep a shell from interpreting the name if the command line is passed to one, as the -[shell](./builtin_commands.md#shell) command and a [pipe](./redirection.md) do. They also keep -`cmd2` from treating a character like `;` or `>` in the name as part of its own syntax. `cmd2` -removes the quotes before passing the argument to a command, unless that command asked to preserve -them. - -On POSIX systems the characters which get a name quoted are a space, a quote character, `*`, `?`, -`[` when a `]` follows it, `{`, `}`, `(`, `)`, `<`, `>`, `|`, `&`, `;`, `$`, a backtick, a -backslash, and a leading `#`. Single quotes are used when a name has a `$`, a backtick, or a -backslash, since a shell still interprets those within double quotes. On Windows the characters are -a space, `'`, `&`, `(`, `)`, `^`, and `;`, and the quotes are always double quotes. +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, or a backslash, 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: - The quotes go around the whole argument, so when several matches are offered and only one of them - needs quotes, they all get them. -- A name with a single quote in it is wrapped in double quotes, so a `$`, a backtick, or a backslash - in that same name is still interpreted by a shell. -- A `%` in a name is still interpreted by `cmd.exe` on Windows. -- Only paths and shell commands completed by `cmd2` are quoted this way. Results from your own - completers and choices are only quoted when one of them contains a space. + needs quotes, they all get them. An executable named `[` is common, so completing a shell command + which could match it quotes every match. +- A match with a single quote in it is wrapped in double quotes, so a `$`, a backtick, or a + backslash in that same match is still interpreted by a shell. +- A `%` in a match is still interpreted by `cmd.exe` on Windows. +- 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 diff --git a/tests/test_completion.py b/tests/test_completion.py index 77b523a59..56b2db8ff 100644 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -912,7 +912,7 @@ def test_add_opening_quote_nothing_added(cmd_app) -> None: assert not completions._quote_char -@pytest.mark.skipif(sys.platform == "win32", reason="these characters are either illegal in Windows file names or not special") +@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"), [ @@ -965,10 +965,9 @@ def test_add_opening_quote_shell_special_command(cmd_app, tmp_path, monkeypatch) assert completions._quote_char == '"' -def test_add_opening_quote_unpaired_bracket_not_special(cmd_app, tmp_path, monkeypatch) -> None: - # A '[' which isn't followed by a ']' can't begin a glob pattern. Executables named '[' and 'g[' are - # common, and they must not cause every other shell command to be quoted. - make_exes(tmp_path, ["[", "g[", "git"]) +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}" @@ -977,8 +976,83 @@ def test_add_opening_quote_unpaired_bracket_not_special(cmd_app, tmp_path, monke completions = cmd_app.complete(text, line, begidx, endidx) assert sorted(completions.to_strings()) == ["g[", "git"] - assert not completions._add_opening_quote - assert not completions._quote_char + 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): @@ -999,7 +1073,7 @@ def test_add_opening_quote_not_added_to_non_path(text, expected) -> None: endidx = len(line) begidx = endidx - len(text) - # Only paths are quoted for a shell. Quoting this would break a command which preserves quotes. + # 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 @@ -1317,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 5914919b7..a8fa5857c 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -2121,8 +2121,8 @@ def test_get_exes_in_path_removed_cwd(tmp_path, monkeypatch, unusable_entry: str ("platform", "matches", "expected"), [ # Nothing special - ("linux", ["file.txt", "dir/other-file_2.txt", "~/caf\u00e9.txt"], ""), - ("win32", ["file.txt", "C:\\dir\\other-file_2.txt"], ""), + ("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"], '"'), @@ -2130,12 +2130,11 @@ def test_get_exes_in_path_removed_cwd(tmp_path, monkeypatch, unusable_entry: str ("linux", ["my*file.txt"], '"'), ("linux", ["my?file.txt"], '"'), ("linux", ["notes[2026].txt"], '"'), - # A '[' is only special when a ']' follows it - ("linux", ["[", "g["], ""), - ("linux", ["]["], ""), - # A '#' is only special at the start + # A '[' is a bad pattern to some shells even without a ']' + ("linux", ["g["], '"'), + # These are only special at the start ("linux", ["#autosave#"], '"'), - ("linux", ["c#.txt"], ""), + ("linux", ["=equals"], '"'), # Shell syntax ("linux", ["a&b"], '"'), ("linux", ["a;b"], '"'), @@ -2156,10 +2155,17 @@ def test_get_exes_in_path_removed_cwd(tmp_path, monkeypatch, unusable_entry: str ("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"], '"'), - ("win32", ["cost$5.txt", "notes[2026].txt", "{a,b}", "#autosave#"], ""), ], ) -def test_path_quote_char(monkeypatch, platform: str, matches: list[str], expected: str) -> None: +def test_shell_quote_char(monkeypatch, platform: str, matches: list[str], expected: str) -> None: monkeypatch.setattr(sys, "platform", platform) - assert cu._path_quote_char(matches) == expected + assert cu._shell_quote_char(matches) == expected From 2e066b7621dfcd7fca74e36c3f945be5e3cacee5 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:52:31 -0500 Subject: [PATCH 7/8] Stop resolving PATH entries and fold shell marking into one helper os.path.realpath() can raise for a PATH entry which can't be reached, such as one on an unavailable network share on Windows. Since find_editor() runs when cmd2 is imported, that could keep cmd2 from being imported. The PATH entries are now used as written. Executable names were already de-duplicated, so the only cost is searching a directory twice when it is listed under two names. The places which mark completions as being passed to a shell now share one helper, Cmd._for_shell(). Corrected the docs for how the quote character is chosen when several matches are offered, and documented that a macro which runs a shell command is not quoted for the shell. --- cmd2/cmd2.py | 25 ++++++++++++++----------- cmd2/utils.py | 9 +++------ docs/features/completion.md | 22 ++++++++++++++-------- tests/test_utils.py | 22 +++++++++++++++++----- 4 files changed, 48 insertions(+), 30 deletions(-) diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index f51d254fc..c0c1be687 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -2581,13 +2581,10 @@ def _redirect_complete(self, text: str, line: str, begidx: int, endidx: int, com prior_token = cur_token - if do_shell_completion: - completions = self.shell_cmd_complete(text, line, begidx, endidx) - return dataclasses.replace(completions, _quote_for_shell=piped_to_shell) - - if do_path_completion: - completions = self.path_complete(text, line, begidx, endidx) - return dataclasses.replace(completions, _quote_for_shell=piped_to_shell) + 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 @@ -5054,15 +5051,21 @@ def _build_shell_parser(cls) -> Cmd2ArgumentParser: 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.""" - completions = self.shell_cmd_complete(text, line, begidx, endidx) - return dataclasses.replace(completions, _quote_for_shell=True) + 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.""" - completions = self.path_complete(text, line, begidx, endidx) - return dataclasses.replace(completions, _quote_for_shell=True) + 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) diff --git a/cmd2/utils.py b/cmd2/utils.py index 9eaa2081f..45f3e1e9c 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -379,16 +379,13 @@ def _quote_shell_arg(arg: str) -> str: def _get_path_dirs() -> set[str]: """Return the directories listed in the PATH environment variable. - Symbolic links are resolved so a directory which is reachable through more than one entry is only - returned once. Relative entries are returned as they are since resolving one raises an exception if - the current working directory no longer exists. + 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. :return: the directories, which is an empty set if PATH is not set """ env_path = os.getenv("PATH") - if env_path is None: - return set() - return {os.path.realpath(p) if os.path.isabs(p) else p for p in env_path.split(os.path.pathsep)} + return set() if env_path is None else set(env_path.split(os.path.pathsep)) def find_editor() -> str | None: diff --git a/docs/features/completion.md b/docs/features/completion.md index 1be63a21f..5c4f94daf 100644 --- a/docs/features/completion.md +++ b/docs/features/completion.md @@ -58,18 +58,24 @@ completing `!ls my*` gives: 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, or a backslash, 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. +`=`. 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: -- The quotes go around the whole argument, 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. -- A match with a single quote in it is wrapped in double quotes, so a `$`, a backtick, or a - backslash in that same match is still interpreted by a shell. +- 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. diff --git a/tests/test_utils.py b/tests/test_utils.py index a8fa5857c..e34621f16 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -2094,11 +2094,23 @@ def test_get_exes_in_path_symlinked_directory(tmp_path, monkeypatch) -> None: monkeypatch.setenv("PATH", str(link_dir)) assert cu.get_exes_in_path("my") == ["mytool"] - # A directory reachable through more than one PATH entry is only searched once - monkeypatch.setenv("PATH", os.pathsep.join([str(real_dir), str(link_dir)])) - with mock.patch("cmd2.utils.files_from_glob_pattern", wraps=cu.files_from_glob_pattern) as glob_mock: - assert cu.get_exes_in_path("my") == ["mytool"] - glob_mock.assert_called_once() + # 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") From 80c8ed7004cb2bd5c9294366af6687ab0f29afb8 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt <2812720+tleonhardt@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:39:26 -0500 Subject: [PATCH 8/8] Document why an empty PATH entry is kept as the current directory --- cmd2/utils.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cmd2/utils.py b/cmd2/utils.py index 45f3e1e9c..bc7c20b53 100644 --- a/cmd2/utils.py +++ b/cmd2/utils.py @@ -382,6 +382,9 @@ def _get_path_dirs() -> set[str]: 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")