feat: add support for prompting filesystem paths (#2210)

Co-authored-by: Sigurd Spieckermann <2206639+sisp@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 3 people

copier/_user_data.py

@@ -427,7 +427,9 @@ def _validate(answer: str) -> str | Literal[True]:
             result["multiline"] = self.get_multiline()
             if placeholder := self.get_placeholder():
                 result["placeholder"] = placeholder
-        if questionary_type in {"input", "checkbox", "password"}:
+        if type_name == "path":
+            questionary_type = "path"
+        if questionary_type in {"input", "checkbox", "password", "path"}:
             result["validate"] = _validate
         result.update({"type": questionary_type})
         return result
@@ -593,4 +595,5 @@ def load_answersfile_data(
     "json": json.loads,
     "str": cast_to_str,
     "yaml": parse_yaml_string,
+    "path": str,
 }

docs/configuring.md

@@ -73,7 +73,7 @@ to ask users for data. To use it, the value must be a dict.
 Supported keys:
 
 -   **type**: User input must match this type. Options are: `bool`, `float`, `int`,
-    `json`, `str`, `yaml` (default).
+    `json`, `path`, `str`, `yaml` (default).
 -   **help**: Additional text to help the user know what's this question for.
 -   **choices**: To restrict possible values.
 

tests/helpers.py

@@ -9,7 +9,7 @@
 from enum import Enum
 from hashlib import sha1
 from pathlib import Path
-from typing import Any, Protocol
+from typing import TYPE_CHECKING, Any, Protocol
 
 from pexpect.popen_spawn import PopenSpawn
 from plumbum import local
@@ -22,6 +22,9 @@
 import copier
 from copier._types import StrOrPath
 
+if TYPE_CHECKING:
+    from pexpect.spawnbase import SpawnBase
+
 PROJECT_TEMPLATE = Path(__file__).parent / "demo"
 
 DATA = {
@@ -73,6 +76,7 @@ def __call__(self, cmd: tuple[str, ...], *, timeout: int | None) -> PopenSpawn:
 
 class Keyboard(str, Enum):
     ControlH = REVERSE_ANSI_SEQUENCES[Keys.ControlH]
+    ControlI = REVERSE_ANSI_SEQUENCES[Keys.ControlI]
     ControlC = REVERSE_ANSI_SEQUENCES[Keys.ControlC]
     Enter = "\r"
     Esc = REVERSE_ANSI_SEQUENCES[Keys.Escape]
@@ -89,6 +93,7 @@ class Keyboard(str, Enum):
     # further explanations
     Alt = Esc
     Backspace = ControlH
+    Tab = ControlI
 
 
 def render(tmp_path: Path, **kwargs: Any) -> None:
@@ -133,7 +138,10 @@ def build_file_tree(
 
 
 def expect_prompt(
-    tui: PopenSpawn, name: str, expected_type: str, help: str | None = None
+    tui: SpawnBase,
+    name: str,
+    expected_type: str,
+    help: str | None = None,
 ) -> None:
     """Check that we get a prompt in the standard form"""
     if help:

tests/test_copy.py

@@ -604,6 +604,73 @@ def test_value_with_forward_slash(tmp_path_factory: pytest.TempPathFactory) -> N
             "yellow",
             does_not_raise(),
         ),
+        (
+            {"type": "path"},
+            "/etc/hostname",
+            does_not_raise(),
+        ),
+        (
+            {"type": "path"},
+            "/this/does/not/exist",
+            does_not_raise(),
+        ),
+        (
+            {
+                "type": "path",
+                "choices": {
+                    "one": None,
+                    "two": "/etc/hostname",
+                    "three": "/does/not/exist",
+                },
+            },
+            "/etc/hostname",
+            does_not_raise(),
+        ),
+        (
+            {
+                "type": "path",
+                "choices": {
+                    "one": None,
+                    "two": "/etc/hostname",
+                    "three": "/does/not/exist",
+                },
+            },
+            "/does/not/exist",
+            does_not_raise(),
+        ),
+        (
+            {
+                "type": "path",
+                "choices": {
+                    "one": None,
+                    "two": "/etc/hostname",
+                    "three": "/does/not/exist",
+                },
+            },
+            "/another/path/that/does/not/exist",
+            pytest.raises(ValueError),
+        ),
+        (
+            {"type": "path", "validator": ""},
+            "/this/does/not/exist",
+            does_not_raise(),
+        ),
+        (
+            {
+                "type": "path",
+                "validator": "[% if q | length < 1 or q[0] != '/' %]must be absolute path[% endif %]",
+            },
+            "/this/does/not/exist",
+            does_not_raise(),
+        ),
+        (
+            {
+                "type": "path",
+                "validator": "[% if q | length < 1 or q[0] != '/' %]must be absolute path[% endif %]",
+            },
+            "./local/path",
+            pytest.raises(ValueError),
+        ),
         (
             {"type": "yaml", "choices": {"one": None, "two": 2, "three": "null"}},
             "one",
@@ -910,6 +977,10 @@ def test_required_choice_question_without_data(
         ({"type": "json", "default": []}, does_not_raise()),
         ({"type": "json", "default": "null"}, does_not_raise()),
         ({"type": "json", "default": None}, does_not_raise()),
+        ({"type": "path", "default": None}, pytest.raises(TypeError)),
+        ({"type": "path", "default": ""}, does_not_raise()),
+        ({"type": "path", "default": "/etc/hostname"}, does_not_raise()),
+        ({"type": "path", "default": "/does/not/exist"}, does_not_raise()),
         ({"type": "yaml", "default": '"string"'}, does_not_raise()),
         ({"type": "yaml", "default": "string"}, does_not_raise()),
         ({"type": "yaml", "default": "1"}, does_not_raise()),

tests/test_prompt.py

@@ -10,6 +10,7 @@
 import pexpect
 import pytest
 import yaml
+from coverage.tracer import CTracer
 from pexpect.popen_spawn import PopenSpawn
 from plumbum import local
 
@@ -89,6 +90,23 @@
     "[[ _copier_conf.answers_file ]].tmpl": "[[_copier_answers|to_nice_yaml]]",
 }
 
+PATH_TREE: Mapping[StrOrPath, str | bytes] = {
+    "copier.yml": (
+        f"""\
+        _templates_suffix: {SUFFIX_TMPL}
+        _envops: {BRACKET_ENVOPS_JSON}
+        current_location:
+            type: path
+            default: /dev/warppipe0
+
+        star_location:
+            type: path
+            help: "Location of a bonus star"
+        """
+    ),
+    "[[ _copier_conf.answers_file ]].tmpl": "[[_copier_answers|to_nice_yaml]]",
+}
+
 
 @pytest.mark.parametrize(
     "name, args",
@@ -156,6 +174,50 @@ def test_copy_default_advertised(
         assert load_answersfile_data(".").get("_commit") == "v2"
 
 
+@pytest.mark.skipif(
+    condition=platform.system() == "Windows",
+    reason="pexpect.spawn does not work on Windows",
+)
+def test_path_completion(tmp_path_factory: pytest.TempPathFactory) -> None:
+    """Test that file paths can handle tab completion."""
+    from pexpect.pty_spawn import spawn as pexpect_spawn
+
+    src, dst, completedir = map(tmp_path_factory.mktemp, ("src", "dst", "my-directory"))
+    with local.cwd(src):
+        build_file_tree(PATH_TREE)
+        git_save(tag="v1")
+        git("commit", "--allow-empty", "-m", "v2")
+        git("tag", "v2")
+    with local.cwd(dst):
+        # Disable subprocess timeout if debugging (except coverage)
+        # See https://stackoverflow.com/a/67065084/1468388
+        tracer = getattr(sys, "gettrace", lambda: None)()
+        timeout = 10 if not isinstance(tracer, (CTracer, type(None))) else None
+
+        # Copy the v1 template
+        cmd = COPIER_PATH + ("copy", str(src), ".", "--vcs-ref=v1")
+        tui = pexpect_spawn(cmd[0], list(cmd[1:]), timeout=timeout)
+
+        # Check that default values are maintained
+        expect_prompt(tui, "current_location", "path")
+        tui.sendline()
+
+        # Check tab completion of a filesystem path (/path/to/my-direct<TAB> should
+        # complete to /path/to/my-directory0)
+        expect_prompt(tui, "star_location", "path", help="Location of a bonus star")
+        tui.send(str(completedir)[:-4])
+        tui.send(Keyboard.Tab)
+        tui.sendline()
+        tui.sendline()
+
+        tui.expect_exact(pexpect.EOF)
+
+        answers = load_answersfile_data(".")
+        assert answers.get("_commit") == "v1"
+        assert answers.get("current_location") == "/dev/warppipe0"
+        assert answers.get("star_location") == str(completedir)
+
+
 @pytest.mark.parametrize(
     "name, args",
     [