fix #189

Author: bckohan

doc/source/changelog.rst

@@ -7,6 +7,7 @@ Change Log
 v3.1.0 (2024-03-xx)
 ===================
 
+* Implemented `Prompt before writing to dotfiles when installing completions <https://github.com/django-commons/django-typer/issues/189>`_
 * Fixed `Shell completion tests let failures through in CI <https://github.com/django-commons/django-typer/issues/194>`_
 * Fixed `fish completion installs should respect XDG_CONFIG_HOME <https://github.com/django-commons/django-typer/issues/193>`_
 * Fixed `zsh completion installs should respect ZDOTDIR <https://github.com/django-commons/django-typer/issues/192>`_

doc/source/conf.py

@@ -5,11 +5,13 @@
 from sphinx.ext.autodoc import between
 import shutil
 import django
+from django.conf import settings
 
 sys.path.append(str(Path(__file__).parent.parent.parent))
 sys.path.append(str(Path(__file__).parent / 'ext'))
 
 os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'tests.settings.base')
+settings.configure()
 django.setup()
 
 import django_typer

doc/source/shell_completion.rst

@@ -134,6 +134,9 @@ project simply run the install command:
 
     ./manage.py shellcompletion install
 
+**The install command will list the precise edits to dotfiles and shell configuration files that it
+will make and ask for permission before proceeding. To skip the prompt use** ``--no-prompt``.
+
 .. note::
 
     The manage script may be named differently in your project - this is fine. The only requirement

justfile

@@ -160,6 +160,28 @@ check-docs-links: _link_check
 check-docs:
     @just run doc8 --ignore-path ./doc/build --max-line-length 100 -q ./doc
 
+# fetch the intersphinx references for the given package
+[script]
+fetch-refs LIB: install-docs
+    import os
+    from pathlib import Path
+    import logging as _logging
+    import sys
+    import runpy
+    from sphinx.ext.intersphinx import inspect_main
+    _logging.basicConfig()
+
+    libs = runpy.run_path(Path(os.getcwd()) / "doc/source/conf.py").get("intersphinx_mapping")
+    url = libs.get("{{ LIB }}", None)
+    if not url:
+        sys.exit(f"Unrecognized {{ LIB }}, must be one of: {', '.join(libs.keys())}")
+    if url[1] is None:
+        url = f"{url[0].rstrip('/')}/objects.inv"
+    else:
+        url = url[1]
+
+    raise SystemExit(inspect_main([url]))
+
 # lint the code
 check-lint:
     @just run ruff check --select I
@@ -242,26 +264,38 @@ list-missed-tests: install log-tests test-all
 [script("bash")]
 test-bash:
     source .venv/bin/activate && pytest --cov-append tests/shellcompletion/test_shell_resolution.py::TestShellResolution::test_bash tests/test_parser_completers.py tests/shellcompletion/test_bash.py
+    uv pip uninstall rich
+    source .venv/bin/activate && pytest --cov-append tests/shellcompletion/test_bash.py::BashExeTests::test_prompt_install
 
 # test zsh shell completions
 [script("zsh")]
 test-zsh:
     source .venv/bin/activate && pytest --cov-append tests/shellcompletion/test_shell_resolution.py::TestShellResolution::test_zsh tests/test_parser_completers.py tests/shellcompletion/test_zsh.py
+    uv pip uninstall rich
+    source .venv/bin/activate && pytest --cov-append tests/shellcompletion/test_zsh.py::ZshExeTests::test_prompt_install
 
 # test powershell shell completions
 [script("powershell")]
 test-powershell:
     .venv/Scripts/activate.ps1; pytest --cov-append tests/shellcompletion/test_shell_resolution.py::TestShellResolution::test_powershell tests/test_parser_completers.py tests/test_parser_completers.py tests/shellcompletion/test_powershell.py::PowerShellTests tests/shellcompletion/test_powershell.py::PowerShellExeTests
+    # TODO - not implemented on windows
+    # uv pip uninstall rich
+    # source .venv/bin/activate && pytest --cov-append tests/shellcompletion/test_powershell.py::PowerShellExeTests::test_prompt_install
 
 # test pwsh shell completions
 [script("pwsh")]
 test-pwsh:
     .venv/Scripts/activate.ps1; pytest --cov-append tests/shellcompletion/test_shell_resolution.py::TestShellResolution::test_pwsh tests/test_parser_completers.py tests/shellcompletion/test_powershell.py::PWSHTests tests/shellcompletion/test_powershell.py::PWSHExeTests
+    # TODO - not implemented on windows
+    # uv pip uninstall rich
+    # source .venv/bin/activate && pytest --cov-append tests/shellcompletion/test_powershell.py::PWSHExeTests::test_prompt_install
 
 # test fish shell completions
 [script("fish")]
 test-fish:
     source .venv/bin/activate.fish && pytest --cov-append tests/shellcompletion/test_shell_resolution.py::TestShellResolution::test_fish tests/test_parser_completers.py tests/shellcompletion/test_fish.py
+    uv pip uninstall rich
+    source .venv/bin/activate && pytest --cov-append tests/shellcompletion/test_fish.py::FishExeTests::test_prompt_install
 
 # run tests
 test *TESTS:

src/django_typer/management/commands/shellcompletion.py

@@ -29,6 +29,8 @@
 from pathlib import Path
 from types import ModuleType
 
+from click import get_current_context
+from click.core import ParameterSource
 from click.parser import split_arg_string
 from click.shell_completion import CompletionItem
 from django.core.management import CommandError, ManagementUtility
@@ -122,6 +124,8 @@ class Command(TyperCommand):
     _fallback: t.Optional[t.Callable[[t.List[str], str], t.List[CompletionItem]]] = None
     _manage_script: t.Optional[t.Union[str, Path]] = None
 
+    color_default: bool = True
+
     @property
     def fallback(
         self,
@@ -264,6 +268,15 @@ def init(
         self.no_color = (not self.shell_class.color) if no_color is None else no_color
         if self.force_color:
             self.no_color = False
+        ctx = get_current_context(silent=True)
+        self.color_default = (
+            (
+                ctx.get_parameter_source("no_color") is ParameterSource.DEFAULT
+                and ctx.get_parameter_source("force_color") is ParameterSource.DEFAULT
+            )
+            if ctx
+            else False
+        )
         return self
 
     @command(
@@ -309,7 +322,17 @@ def install(
                 # todo - add template name completer - see django-render-static
             ),
         ] = None,
-    ):
+        prompt: t.Annotated[
+            bool,
+            Option(
+                "--no-prompt",
+                help=t.cast(
+                    str,
+                    _("Do not ask for conformation before editing dotfiles."),
+                ),
+            ),
+        ] = True,
+    ) -> t.Optional[t.List[Path]]:
         """
         Install autocompletion for the given shell. If the shell is not specified, it
         will try to detect the shell. If the shell is not detected, it will fail.
@@ -319,6 +342,8 @@ def install(
         .. typer:: django_typer.management.commands.shellcompletion.Command:typer_app:install
             :width: 85
             :convert-png: latex
+
+        Returns the list of edited and/or created paths or None if no edits were made.
         """
         self.fallback = fallback  # type: ignore[assignment]
         self.manage_script = manage_script  # type: ignore[assignment]
@@ -340,17 +365,26 @@ def install(
                     )
                 )
 
-        install_path = self.shell_class(
+        install_paths = self.shell_class(
             prog_name=str(manage_script or self.manage_script_name),
             command=self,
             template=template,
             color=not self.no_color or self.force_color,
-        ).install()
-        self.stdout.write(
-            self.style.SUCCESS(
-                f"Installed autocompletion for {self.shell} @ {install_path}"
+            color_default=self.color_default,
+        ).install(prompt=prompt)
+        if install_paths:
+            self.stdout.write(
+                self.style.SUCCESS(
+                    _("Installed autocompletion for {shell}").format(shell=self.shell)
+                )
             )
-        )
+        else:
+            self.stdout.write(
+                self.style.ERROR(
+                    t.cast(str, _("Aborted shell completion installation."))
+                )
+            )
+        return install_paths or None
 
     @command(
         help=t.cast(str, _("Uninstall autocompletion for the current or given shell."))
@@ -389,6 +423,7 @@ def uninstall(
             prog_name=str(manage_script or self.manage_script_name),
             command=self,
             color=not self.no_color or self.force_color,
+            color_default=self.color_default,
         ).uninstall()
         self.stdout.write(
             self.style.WARNING(f"Uninstalled autocompletion for {self.shell}.")
@@ -490,6 +525,7 @@ def get_completion() -> str:
                         command_str=command,
                         command_args=args,
                         color=not self.no_color or self.force_color,
+                        color_default=self.color_default,
                     ).complete()
 
             # only try to set the fallback if we have to use it
@@ -499,6 +535,7 @@ def get_completion() -> str:
                 command_str=command,
                 command_args=args,
                 color=not self.no_color or self.force_color,
+                color_default=self.color_default,
             ).complete()
 
         def strip_color(text: str) -> str:

src/django_typer/shells/__init__.py

@@ -13,6 +13,7 @@
 from django.template.backends.django import Template as DjangoTemplate
 from django.template.base import Template as BaseTemplate
 from django.template.loader import TemplateDoesNotExist, get_template
+from django.utils.translation import gettext as _
 
 if t.TYPE_CHECKING:  # pragma: no cover
     from django_typer.management.commands.shellcompletion import (
@@ -63,8 +64,12 @@ class with
     command_args: t.List[str]
 
     console = None  # type: ignore[var-annotated]
+
+    rich_console = None  # type: ignore[var-annotated]
     console_buffer: io.StringIO
 
+    color_default: bool = True
+
     def __init__(
         self,
         cli: t.Optional[ClickCommand] = None,
@@ -76,6 +81,7 @@ def __init__(
         command_args: t.Optional[t.List[str]] = None,
         template: t.Optional[str] = None,
         color: t.Optional[bool] = None,
+        color_default: bool = color_default,
         **kwargs,
     ):
         # we don't always need the initialization parameters during completion
@@ -90,12 +96,20 @@ def __init__(
             self.template = template
         if color is not None:
             self.color = color
+        self.color_default = color_default
 
         self.console_buffer = io.StringIO()
         try:
             from rich.console import Console
 
             self.console = Console(
+                # do not disable color output if not explicitly disabled
+                color_system="auto" if self.color_default or self.color else None,
+                force_terminal=True,
+                file=command.stdout if command else None,  # type: ignore[arg-type]
+                stderr=command.stderr if command else None,  # type: ignore[arg-type]
+            )
+            self.rich_console = Console(
                 color_system="auto" if self.color else None,
                 force_terminal=True,
                 file=self.console_buffer,
@@ -224,11 +238,16 @@ def source(self) -> str:
             return self.load_template().render(Context(self.source_vars()))  # type: ignore
 
     @abstractmethod
-    def install(self) -> Path:
+    def install(self, prompt: bool = True) -> t.List[Path]:
         """
         Deriving classes must implement this method to install the completion script.
 
         This method should return the path to the installed script.
+
+        :param prompt: If True, prompt the user for confirmation before installing
+            the completion script.
+        :return: The paths that were created or edited or None if the user declined
+            installation or no changes were made.
         """
 
     @abstractmethod
@@ -245,21 +264,63 @@ def get_user_profile(self) -> Path:
         of that script.
         """
 
+    def prompt(
+        self,
+        source: str,
+        file: Path,
+        prompt: bool = True,
+        start_line: int = 0,
+    ) -> bool:
+        """
+        Prompt the user for confirmation before editing the file with the given
+        source edits.
+
+        :param source: The source string that will be written to the file.
+        :param file: The path of the file that will be created or edited.
+        :param prompt: Prompt toggle, if False, will not prompt the user and return True
+        :param start_line: The line number the edit will start at.
+        :return: True if the user confirmed the edit, False otherwise.
+        """
+        if not prompt:
+            return True
+
+        prompt_text = (
+            _("Append the above contents to {file}?").format(file=file)
+            if start_line
+            else _("Create {file} with the above contents?").format(file=file)
+        )
+        if self.console:
+            from rich.prompt import Confirm
+            from rich.syntax import Syntax
+
+            syntax = Syntax(
+                source,
+                self.name,
+                theme="monokai",
+                start_line=start_line,
+                line_numbers=False,
+            )
+            self.console.print(syntax)
+            return Confirm.ask(prompt_text)
+        else:
+            print(source)
+            return input(prompt_text + " [y/N] ").lower() in {"y", "yes"}
+
     def process_rich_text(self, text: str) -> str:
         """
         Removes rich text markup from a string if color is disabled, otherwise it
         will render the rich markup to ansi control codes. If rich is not installed,
         none of this happens and the markup will be passed through as is.
         """
-        if self.console:
+        if self.rich_console:
             if self.color:
                 self.console_buffer.truncate(0)
                 self.console_buffer.seek(0)
-                self.console.print(text, end="")
+                self.rich_console.print(text, end="")
                 return self.console_buffer.getvalue()
             else:
                 return "".join(
-                    segment.text for segment in self.console.render(text)
+                    segment.text for segment in self.rich_console.render(text)
                 ).rstrip("\n")
         return text
 

src/django_typer/shells/bash.py

@@ -86,19 +86,32 @@ def source_vars(self) -> t.Dict[str, t.Any]:
     def format_completion(self, item: CompletionItem) -> str:
         return f"{item.type},{item.value}"
 
-    def install(self) -> Path:
+    def install(self, prompt: bool = True) -> t.List[Path]:
         assert self.prog_name
-        Path.home().mkdir(parents=True, exist_ok=True)
+        edited = []
         script = self.install_dir / f"{self.prog_name}.sh"
         bashrc = self.get_user_profile()
         bashrc_source = bashrc.read_text() if bashrc.is_file() else ""
         source_line = f"source {script}"
         if source_line not in bashrc_source:
             bashrc_source += f"\n{source_line}\n"
-        bashrc.write_text(bashrc_source)
-        script.parent.mkdir(parents=True, exist_ok=True)
-        script.write_text(self.source())
-        return script
+            if self.prompt(
+                prompt=prompt,
+                source=source_line,
+                file=bashrc,
+                start_line=bashrc_source.count("\n") + 1,
+            ):
+                Path.home().mkdir(parents=True, exist_ok=True)
+                with open(bashrc, "a") as f:
+                    f.write(f"\n{source_line}\n")
+                edited.append(bashrc)
+
+        source = self.source()
+        if self.prompt(prompt=prompt, source=source, file=script):
+            script.parent.mkdir(parents=True, exist_ok=True)
+            script.write_text(self.source())
+            edited.append(script)
+        return edited
 
     def uninstall(self):
         assert self.prog_name