Support removing badges and update docs (#162)

Author: nathanjmcdougall

README.md

@@ -68,6 +68,7 @@ Supported arguments:
 
 - `--remove` to remove the tool instead of adding it
 - `--offline` to disable network access and rely on caches
+- `--quiet` to suppress output
 
 ### `usethis badge`
 
@@ -78,6 +79,12 @@ Currently supported badges:
 - Ruff
 - pre-commit
 
+Supported arguments:
+
+- `--remove` to remove the badge instead of adding it
+- `--offline` to disable network access and rely on caches
+- `--quiet` to suppress output
+
 ### `usethis ci`
 
 Add Continuous Integration pipelines to the project.
@@ -90,6 +97,12 @@ Example:
 
 `usethis ci bitbucket`.
 
+Supported arguments:
+
+- `--remove` to remove the CI configuration instead of adding it
+- `--offline` to disable network access and rely on caches
+- `--quiet` to suppress output
+
 ### `usethis browse pypi`
 
 Dispaly or open the PyPI landing page associated with another project.

src/usethis/_core/badge.py

@@ -45,6 +45,14 @@ def add_pre_commit_badge():
     add_badge(PRE_COMMIT_BADGE)
 
 
+def remove_ruff_badge():
+    remove_badge(RUFF_BADGE)
+
+
+def remove_pre_commit_badge():
+    remove_badge(PRE_COMMIT_BADGE)
+
+
 def add_badge(badge: Badge) -> None:
     path = Path.cwd() / "README.md"
 
@@ -95,16 +103,25 @@ def add_badge(badge: Badge) -> None:
             lines.append("")
         tick_print(f"Adding {badge.name} badge to 'README.md'.")
         lines.append(badge.markdown)
+        have_added = True
 
     # If the first line is blank, we basically just want to replace it.
     if is_blank(lines[0]):
         del lines[0]
 
+    output = "\n".join(lines)
+
     # Ensure final newline
-    if lines[-1] != "":
-        lines.append("")
+    if have_added:
+        output = _ensure_final_newline(output)
+
+    path.write_text(output)
 
-    path.write_text("\n".join(lines))
+
+def _ensure_final_newline(content: str) -> str:
+    if not content or content[-1] != "\n":
+        content += "\n"
+    return content
 
 
 def is_blank(line: str) -> bool:
@@ -121,3 +138,49 @@ def is_badge(line: str) -> bool:
         re.match(r"^\[!\[.*\]\(.*\)\]\(.*\)$", line) is not None
         or re.match(r"^\!\[.*\]\(.*\)$", line) is not None
     )
+
+
+def remove_badge(badge: Badge) -> None:
+    path = Path.cwd() / "README.md"
+
+    if not path.exists():
+        return
+
+    content = path.read_text()
+
+    original_lines = content.splitlines()
+    if content.endswith("\n"):
+        original_lines.append("")
+
+    lines: list[str] = []
+    have_removed = False
+    skip_blank = False
+    for idx, original_line in enumerate(original_lines):
+        if not skip_blank:
+            if Badge(markdown=original_line).equivalent_to(badge):
+                tick_print(f"Removing {badge.name} badge from 'README.md'.")
+                have_removed = True
+
+                # Merge consecutive blank lines around the badges,
+                # if there is only one left
+                if (
+                    idx - 1 >= 0
+                    and idx + 1 < len(original_lines)
+                    and is_blank(original_lines[idx - 1])
+                    and is_blank(original_lines[idx + 1])
+                ):
+                    skip_blank = True  # i.e. next iteration once we hit a blank
+
+                continue
+
+            lines.append(original_line)
+        else:
+            skip_blank = False
+
+    output = "\n".join(lines)
+
+    # Ensure final newline
+    if have_removed:
+        output = _ensure_final_newline(output)
+
+    path.write_text(output)

src/usethis/_interface/badge.py

@@ -1,26 +1,41 @@
 import typer
 
 from usethis._config import offline_opt, quiet_opt, usethis_config
-from usethis._core.badge import add_pre_commit_badge, add_ruff_badge
+from usethis._core.badge import (
+    add_pre_commit_badge,
+    add_ruff_badge,
+    remove_pre_commit_badge,
+    remove_ruff_badge,
+)
 
 app = typer.Typer(help="Add badges to the top of the README.md file.")
 
+remove_opt = typer.Option(
+    False, "--remove", help="Remove the badge instead of adding it."
+)
+
 
 @app.command(help="Add a badge for the Ruff linter.")
 def ruff(
-    *,
+    remove: bool = remove_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
 ) -> None:
-    with usethis_config.set(offline=offline, quiet=quiet):
-        add_ruff_badge()
+    if not remove:
+        with usethis_config.set(offline=offline, quiet=quiet):
+            add_ruff_badge()
+    else:
+        remove_ruff_badge()
 
 
 @app.command(help="Add a badge for the pre-commit framework.")
 def pre_commit(
-    *,
+    remove: bool = remove_opt,
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
 ) -> None:
-    with usethis_config.set(offline=offline, quiet=quiet):
-        add_pre_commit_badge()
+    if not remove:
+        with usethis_config.set(offline=offline, quiet=quiet):
+            add_pre_commit_badge()
+    else:
+        remove_pre_commit_badge()

tests/usethis/_core/test_badge.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from usethis._core.badge import Badge, add_badge
+from usethis._core.badge import Badge, add_badge, remove_badge
 from usethis._test import change_cwd
 
 
@@ -340,3 +340,162 @@ def test_recognized_gets_put_before_unknown(self, tmp_path: Path):
 ![Don't Know What This Is](<https://example.com>)
 """
         )
+
+    def test_already_exists_no_newline_added(self):
+        # Arrange
+        path = Path("README.md")
+        content = """![Ruff](<https://example.com>)"""
+        path.write_text(content)
+
+        # Act
+        with change_cwd(path.parent):
+            add_badge(Badge(markdown="![Ruff](<https://example.com>)"))
+
+        # Assert
+        assert path.read_text() == content
+
+
+class TestRemoveBadge:
+    def test_empty(self, tmp_path: Path, capfd: pytest.CaptureFixture[str]):
+        # Arrange
+        path = tmp_path / "README.md"
+        path.touch()
+
+        # Act
+        with change_cwd(tmp_path):
+            remove_badge(
+                Badge(
+                    markdown="![Licence](<https://img.shields.io/badge/licence-mit-green>)",
+                )
+            )
+
+        # Assert
+        content = path.read_text()
+        assert not content
+        out, err = capfd.readouterr()
+        assert not err
+        assert not out
+
+    def test_single(self, tmp_path: Path, capfd: pytest.CaptureFixture[str]):
+        # Arrange
+        path = tmp_path / "README.md"
+        path.write_text("""\
+![Licence](<https://img.shields.io/badge/licence-mit-green>)
+""")
+
+        # Act
+        with change_cwd(tmp_path):
+            remove_badge(
+                Badge(
+                    markdown="![Licence](<https://img.shields.io/badge/licence-mit-green>)",
+                )
+            )
+
+        # Assert
+        content = path.read_text()
+        assert content == "\n"
+        out, err = capfd.readouterr()
+        assert not err
+        assert out == "✔ Removing Licence badge from 'README.md'.\n"
+
+    def test_no_reademe_file(self, tmp_path: Path):
+        # Arrange
+        path = tmp_path / "README.md"
+
+        # Act
+        with change_cwd(tmp_path):
+            remove_badge(
+                Badge(
+                    markdown="![Licence](<https://img.shields.io/badge/licence-mit-green>)",
+                )
+            )
+
+        # Assert
+        assert not path.exists()
+
+    def test_header_and_text(self, tmp_path: Path):
+        # Arrange
+        path = tmp_path / "README.md"
+        path.write_text("""\
+# Header
+
+![Licence](<https://img.shields.io/badge/licence-mit-green>)
+                        
+And some text
+""")
+
+        # Act
+        with change_cwd(tmp_path):
+            remove_badge(
+                Badge(
+                    markdown="![Licence](<https://img.shields.io/badge/licence-mit-green>)",
+                )
+            )
+
+        # Assert
+        assert (
+            path.read_text()
+            == """\
+# Header
+
+And some text
+"""
+        )
+
+    def test_multiple_badges(self, tmp_path: Path):
+        # Arrange
+        path = tmp_path / "README.md"
+        path.write_text("""\
+![Ruff](<https://example.com>)
+![pre-commit](<https://example.com>)
+""")
+
+        # Act
+        with change_cwd(tmp_path):
+            remove_badge(
+                Badge(
+                    markdown="![Ruff](<https://example.com>)",
+                )
+            )
+
+        # Assert
+        assert (
+            path.read_text()
+            == """\
+![pre-commit](<https://example.com>)
+"""
+        )
+
+    def test_no_badges_but_header_and_text(self):
+        # Arrange
+        path = Path("README.md")
+        content = """\
+# Header
+
+And some text
+"""
+        path.write_text(content)
+
+        # Act
+        with change_cwd(path.parent):
+            remove_badge(
+                Badge(
+                    markdown="![Licence](<https://img.shields.io/badge/licence-mit-green>)",
+                )
+            )
+
+        # Assert
+        assert path.read_text() == content
+
+    def test_already_exists_no_newline_added(self):
+        # Arrange
+        path = Path("README.md")
+        content = """Nothing will be removed"""
+        path.write_text(content)
+
+        # Act
+        with change_cwd(path.parent):
+            remove_badge(Badge(markdown="![Ruff](<https://example.com>)"))
+
+        # Assert
+        assert path.read_text() == content