add no-progress-bar and uninstall CLI options (#29)

* resolve #28

switch to '\b' char & update tests

* add pytest config to toml

* compensate for error creating symlinks on windows

- add a note to README
- show error message from exception that was caught
- urge windows users to enable dev mode from a prompt after showing the exception's message.

* add note to README about what files we touch

* Use ANSII escape sequence

instead of '\r`, use the ANSII escape sequence to
move the cursor backward.

* use multiple ANSII escape code to move cursor back

* use ANSII move to previous line

* update docs

- update logo & favicon
- generate doc about CLI args
- replace CLI info in readme with link to new doc

* add uninstall option

add uninstall functionality and CLI option
  - use new functionality when SHA512 is invalid
  - uninstall before installing (accordingly)

update CLI args' defaults, description, and unit test
  - print a prompt about non-operation (before displaying --help msg)

change parse_args() into get_parser() for direct access to  parser obj in test.

* test uninstall_tool()

coverage ignores a function that we already test in units and
an exception's handling that cannot be manually induced

* ignore some other exception handling

also move coverage config into toml

* throw exception when failed to download bin

This meant to provide an explanatory message that users can understand.`

* add coverage to test a user prompt about PATH

* cover OSError about failure to download

* [no ci] raise setuptools vers req as we use toml

* better doc for CLI args

* add color to non-op prompt

fix line too long

* concatenate f-str w/ f-str

Author: 2bndy5

.coveragerc

@@ -13,3 +13,4 @@ tests/__pycache__/
 .eggs
 .mypy_cache/
 *env
+docs/cli_args.rst

.gitignore

@@ -20,6 +20,11 @@ clang-tools Introduction
 
 Install clang-tools binaries (clang-format, clang-tidy) with pip.
 
+.. important::
+    This package only manages binary executables (& corresponding symbolic links) that
+    are installed using this package's executable script. It does not intend to change or
+    modify any binary executable installed from other sources (like LLVM releases).
+
 Features
 --------
 
@@ -31,6 +36,11 @@ Features
 - Installed binaries are symbolically linked for better cross-platform usage.
   For example (on Windows), the ``clang-tidy-13.exe`` binary executable can
   also be invoked with the symbolic link titled ``clang-tidy.exe``
+
+  .. note::
+      To create symbolic links on Windows, you must enable developer mode
+      from the Windows settings under "Privacy & security" > "For developers"
+      category.
 - Customizable install path.
 
 Install
@@ -71,17 +81,11 @@ Install `clang-tools` from git repo
 Usage
 -----
 
-.. code-block:: shell
-
-    usage: clang-tools [-h] [-i INSTALL] [-d DIRECTORY] [-f]
+For a list of supported Command Line Interface options, see
+`the CLI documentation <https://cpp-linter.github.io/clang-tools-pip/cli_args.html>`_
 
-    optional arguments:
-      -h, --help            show this help message and exit
-      -i INSTALL, --install INSTALL
-                            Install clang-tools with specific version. default is 13.
-      -d DIRECTORY, --directory DIRECTORY
-                            The directory where is the clang-tools install.
-      -f                    Force overwriting the symlink to the installed binary. This will only overwrite an existing symlink.
+Examples
+********
 
 Use ``clang-tools`` command to install version 13 binaries.
 

README.rst

@@ -32,12 +32,15 @@ def clang_tools_binary_url(
     return download_url.replace(" ", "")
 
 
-def install_tool(tool_name: str, version: str, directory: str) -> bool:
+def install_tool(
+    tool_name: str, version: str, directory: str, no_progress_bar: bool
+) -> bool:
     """An abstract function that can install either clang-tidy or clang-format.
 
     :param tool_name: The name of the clang-tool to install.
     :param version: The version of the tools to install.
     :param directory: The installation directory.
+    :param no_progress_bar: A flag used to disable the downloads' progress bar.
 
     :returns: `True` if the binary had to be downloaded and installed.
         `False` if the binary was not downloaded but is installed in ``directory``.
@@ -51,12 +54,16 @@ def install_tool(tool_name: str, version: str, directory: str) -> bool:
             print("valid")
             return False
         print("invalid")
+        uninstall_tool(tool_name, version, directory)
     print("downloading", tool_name, f"(version {version})")
     bin_name = str(PurePath(bin_url).stem)
-    download_file(bin_url, bin_name)
+    if download_file(bin_url, bin_name, no_progress_bar) is None:
+        raise OSError(f"Failed to download {bin_name} from {bin_url}")
     move_and_chmod_bin(bin_name, f"{tool_name}-{version}{suffix}", directory)
     if not verify_sha512(get_sha_checksum(bin_url), destination.read_bytes()):
-        raise ValueError(f"file was corrupted during download from {bin_url}")
+        raise ValueError(
+            f"file was corrupted during download from {bin_url}"
+        )  # pragma: no cover
     return True
 
 
@@ -92,7 +99,7 @@ def move_and_chmod_bin(old_bin_name: str, new_bin_name: str, install_dir: str) -
             os.makedirs(install_dir)
         shutil.move(old_bin_name, f"{install_dir}/{new_bin_name}")
         os.chmod(os.path.join(install_dir, new_bin_name), 0o755)
-    except PermissionError as exc:
+    except PermissionError as exc:  # pragma: no cover
         raise SystemExit(
             f"Don't have permission to install {new_bin_name} to {install_dir}."
             + " Try to run with the appropriate permissions."
@@ -129,21 +136,67 @@ def create_sym_link(
                 "already exists. Use '-f' to overwrite. Leaving it as is.",
             )
             return False
-        os.remove(str(link))
+        link.unlink()
         print("overwriting symbolic link", str(link))
     assert target.exists()
-    link.symlink_to(target)
-    print("symbolic link created", str(link))
-    return True
+    try:
+        link.symlink_to(target)
+        print("symbolic link created", str(link))
+        return True
+    except OSError as exc:  # pragma: no cover
+        print(
+            "Encountered an error when trying to create the symbolic link:",
+            exc.strerror,
+            sep="\n    ",
+        )
+        if install_os == "windows":
+            print("Enable developer mode to create symbolic links")
+        return False
+
+
+def uninstall_tool(tool_name: str, version: str, directory: str):
+    """Remove a specified tool of a given version.
+
+    :param tool_name: The name of the clang tool to uninstall.
+    :param version: The version of the clang-tools to remove.
+    :param directory: the directory from which to remove the
+        installed clang-tools.
+    """
+    tool_path = Path(directory, f"{tool_name}-{version}{suffix}")
+    if tool_path.exists():
+        print("Removing", tool_path.name, "from", str(tool_path.parent))
+        tool_path.unlink()
+
+    # check for a dead symlink
+    symlink = Path(directory, f"{tool_name}{suffix}")
+    if symlink.is_symlink() and not symlink.exists():
+        print("Removing dead symbolic link", str(symlink))
+        symlink.unlink()
+
+
+def uninstall_clang_tools(version: str, directory: str):
+    """Uninstall a clang tool of a given version.
+
+    :param version: The version of the clang-tools to remove.
+    :param directory: the directory from which to remove the
+        installed clang-tools.
+    """
+    install_dir = install_dir_name(directory)
+    print(f"Uninstalling version {version} from {str(install_dir)}")
+    for tool in ("clang-format", "clang-tidy"):
+        uninstall_tool(tool, version, install_dir)
 
 
-def install_clang_tools(version: str, directory: str, overwrite: bool) -> None:
+def install_clang_tools(
+    version: str, directory: str, overwrite: bool, no_progress_bar: bool
+) -> None:
     """Wraps functions used to individually install tools.
 
     :param version: The version of the tools to install.
     :param directory: The installation directory.
     :param overwrite: A flag to indicate if the creation of a symlink has
         permission to overwrite an existing symlink.
+    :param no_progress_bar: A flag used to disable the downloads' progress bar.
     """
     install_dir = install_dir_name(directory)
     if install_dir.rstrip(os.sep) not in os.environ.get("PATH"):
@@ -152,6 +205,6 @@ def install_clang_tools(version: str, directory: str, overwrite: bool) -> None:
             f"directory is not in your environment variable PATH.{RESET_COLOR}",
         )
     for tool_name in ("clang-format", "clang-tidy"):
-        install_tool(tool_name, version, install_dir)
+        install_tool(tool_name, version, install_dir, no_progress_bar)
         # `install_tool()` guarantees that the binary exists now
-        create_sym_link(tool_name, version, install_dir, overwrite)
+        create_sym_link(tool_name, version, install_dir, overwrite)  # pragma: no cover

clang_tools/install.py

@@ -5,46 +5,67 @@
 The module containing main entrypoint function.
 """
 import argparse
-from typing import List
 
-from .install import install_clang_tools
+from .install import install_clang_tools, uninstall_clang_tools
+from . import RESET_COLOR, YELLOW
 
-
-def parse_args(args: List[str] = None) -> argparse.Namespace:
-    """Get and parse args given on the CLI.
-
-    :param args: The arguments given on the command line. If specified, this does not
-        need to include the name of the program (ie "clang_tools").
-    """
-    parser = argparse.ArgumentParser(prog="clang-tools")
+def get_parser() -> argparse.ArgumentParser:
+    """Get and parser to interpret CLI args."""
+    parser = argparse.ArgumentParser()
 
     parser.add_argument(
         "-i",
         "--install",
-        default="13",
-        help="Install clang-tools with specific version. default is 13.",
+        metavar="VERSION",
+        help="Install clang-tools about a specific version.",
     )
-
     parser.add_argument(
         "-d",
         "--directory",
         default="",
-        help="The directory where is the clang-tools install.",
+        metavar="DIR",
+        help="The directory where the clang-tools are installed.",
     )
     parser.add_argument(
         "-f",
+        "--overwrite",
         action="store_true",
-        dest="overwrite",
         help="Force overwriting the symlink to the installed binary. This will only "
         "overwrite an existing symlink.",
     )
-    return parser.parse_args(args)
+    parser.add_argument(
+        "-b",
+        "--no-progress-bar",
+        action="store_true",
+        help="Do not display a progress bar for downloads.",
+    )
+    parser.add_argument(
+        "-u",
+        "--uninstall",
+        metavar="VERSION",
+        help="Uninstall clang-tools with specific version. "
+        "This is done before any install.",
+    )
+    return parser
 
 
 def main():
     """The main entrypoint to the CLI program."""
-    args = parse_args()
-    install_clang_tools(args.install, args.directory, args.overwrite)
+    parser = get_parser()
+    args = parser.parse_args()
+    if not args.install and not args.uninstall:
+        print(
+            f"{YELLOW}Nothing to do because `--install` and `--uninstall`",
+            f"was not specified.{RESET_COLOR}"
+        )
+        parser.print_help()
+    else:
+        if args.uninstall:
+            uninstall_clang_tools(args.uninstall, args.directory)
+        if args.install:
+            install_clang_tools(
+                args.install, args.directory, args.overwrite, args.no_progress_bar
+            )
 
 
 if __name__ == "__main__":

clang_tools/main.py

@@ -5,7 +5,6 @@
 A module containing utility functions.
 """
 import platform
-import math
 import hashlib
 from pathlib import Path
 import urllib.request
@@ -14,6 +13,7 @@
 from http.client import HTTPResponse
 
 
+
 def check_install_os() -> str:
     """Identify this Operating System.
 
@@ -32,7 +32,7 @@ def check_install_os() -> str:
     return this_os
 
 
-def download_file(url: str, file_name: str) -> Optional[str]:
+def download_file(url: str, file_name: str, no_progress_bar: bool) -> Optional[str]:
     """Download the given file_name from the given url.
 
     :param url: The URL to download from.
@@ -47,20 +47,26 @@ def download_file(url: str, file_name: str) -> Optional[str]:
 
     if response.status != 200:
         return None
+    assert response.length is not None
     length = response.length
     buffer = bytes()
     progress_bar = "=" if check_install_os() == "windows" else "█"
     while len(buffer) < length:
         block_size = int(length / 20)
-        # show completed
-        completed = len(buffer) / length
-        print("    |" + progress_bar * int(completed * 20), end="")
-        print(" " * math.ceil((1 - completed) * 20), end="|")
-        print(f"{int(completed * 100)}% (of {length} bytes)", end="\r")
+        if not no_progress_bar:  # show completed
+            percent = len(buffer) / length
+            completed = int(percent * 20)
+            display = "    |" + (progress_bar * completed)
+            display += " " * (20 - completed) + "| "
+            display += f"{int(percent * 100)}% (of {length} bytes)"
+            reset_pos = "" if not buffer else "\033[F"
+            print(reset_pos + display)
         remaining = length - len(buffer)
         buffer += response.read(block_size if remaining > block_size else remaining)
     response.close()
-    print("    |" + (progress_bar * 20) + f"| 100% (of {length} bytes)")
+    if not no_progress_bar:
+        display = f"    |{(progress_bar * 20)}| 100% (of {length} bytes)"
+        print("\033[F" + display)
     file = Path(file_name)
     file.write_bytes(buffer)
     return file.as_posix()