Add to empty README files in add_readme (#749)

nathanjmcdougall · web-flow · commit 2169415d71cb · 2025-06-18T18:55:22.000+12:00
* Add to empty README files in add_readme

* Various refactorings and new tests

* Tweak tests to reflect new add_readme behaviour for empty/all-whitespace files

* Update tests to reflect new behaviour

* Handle non-UTF8 encodings in add_readme existing file check
diff --git a/README.md b/README.md
@@ -105,6 +105,8 @@ To start a new project from scratch with a complete set of recommended tooling,
 ```console
 $ uvx usethis init
 ✔ Writing 'pyproject.toml' and initializing project.
+✔ Writing 'README.md'.
+☐ Populate 'README.md' to help users understand the project.
 ✔ Adding recommended linters.
 ☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
 ☐ Run 'uv run deptry src' to run deptry.
diff --git a/src/usethis/_core/badge.py b/src/usethis/_core/badge.py
@@ -8,12 +8,14 @@
 
 from usethis._config import usethis_config
 from usethis._console import plain_print, tick_print, warn_print
-from usethis._core.readme import add_readme, get_readme_path
+from usethis._core.readme import (
+    NonMarkdownREADMEError,
+    add_readme,
+    get_markdown_readme_path,
+)
 from usethis._integrations.project.name import get_project_name
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
     from typing_extensions import Self
 
 
@@ -106,9 +108,11 @@ def add_badge(badge: Badge) -> None:
     add_readme()
 
     try:
-        path = _get_markdown_readme_path()
-    except FileNotFoundError:
-        warn_print("README file not found, printing badge markdown instead...")
+        path = get_markdown_readme_path()
+    except NonMarkdownREADMEError:
+        warn_print(
+            "No Markdown-based README file found, printing badge markdown instead..."
+        )
         plain_print(badge.markdown)
         return
 
@@ -196,20 +200,6 @@ def _get_prerequisites(badge: Badge) -> list[Badge]:
     return prerequisites
 
 
-def _get_markdown_readme_path() -> Path:
-    path = get_readme_path()
-
-    if path.name == "README.md":
-        pass
-    elif path.name == "README":
-        warn_print("Assuming 'README' file is Markdown.")
-    else:
-        msg = f"README file '{path.name}' is not Markdown based on its extension."
-        raise FileNotFoundError(msg)
-
-    return path
-
-
 def _ensure_final_newline(content: str) -> str:
     if not content or content[-1] != "\n":
         content += "\n"
@@ -236,7 +226,7 @@ def remove_badge(badge: Badge) -> None:
     path = usethis_config.cpd() / "README.md"
 
     try:
-        path = _get_markdown_readme_path()
+        path = get_markdown_readme_path()
     except FileNotFoundError:
         # If there's no README.md, there's nothing to remove
         return
diff --git a/src/usethis/_core/readme.py b/src/usethis/_core/readme.py
@@ -1,22 +1,34 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from usethis._config import usethis_config
-from usethis._console import box_print, tick_print
+from usethis._console import box_print, tick_print, warn_print
 from usethis._integrations.file.pyproject_toml.errors import PyprojectTOMLError
 from usethis._integrations.file.pyproject_toml.name import get_description
 from usethis._integrations.project.name import get_project_name
+from usethis.errors import UsethisError
+
+if TYPE_CHECKING:
+    from pathlib import Path
 
 
 def add_readme() -> None:
     """Add a README.md file to the project."""
     # Any file extension is fine, but we'll use '.md' for consistency.
 
     try:
-        get_readme_path()
+        path = get_readme_path()
     except FileNotFoundError:
         pass
     else:
-        return
+        # Check if the file is non-empty; if so, we will exit early
+        try:
+            existing_content = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            return
+        if existing_content.strip():
+            return
 
     project_name = get_project_name()
 
@@ -64,6 +76,24 @@ def get_readme_path():
     raise FileNotFoundError(msg)
 
 
+class NonMarkdownREADMEError(UsethisError):
+    """Raised when the README file is not Markdown based on its extension."""
+
+
+def get_markdown_readme_path() -> Path:
+    path = get_readme_path()
+
+    if path.name == "README.md":
+        pass
+    elif path.name == "README":
+        warn_print("Assuming 'README' file is Markdown.")
+    else:
+        msg = f"README file '{path.name}' is not Markdown based on its extension."
+        raise NonMarkdownREADMEError(msg)
+
+    return path
+
+
 def is_readme_used():
     """Check if the README.md file is used."""
     try:
diff --git a/tests/usethis/_core/test_core_badge.py b/tests/usethis/_core/test_core_badge.py
@@ -50,10 +50,28 @@ def test_not_badge(self):
 
 
 class TestAddBadge:
+    def test_no_readme(self, bare_dir: Path, capfd: pytest.CaptureFixture[str]):
+        # Act
+        with change_cwd(bare_dir), PyprojectTOMLManager():
+            add_badge(
+                Badge(
+                    markdown="![Licence](https://img.shields.io/badge/licence-mit-green)",
+                )
+            )
+
+        # Assert (that the badge markdown is printed)
+        out, err = capfd.readouterr()
+        assert not err
+        assert out == (
+            "✔ Writing 'README.md'.\n"
+            "☐ Populate 'README.md' to help users understand the project.\n"
+            "✔ Adding Licence badge to 'README.md'.\n"
+        )
+
     def test_not_markdown(self, bare_dir: Path, capfd: pytest.CaptureFixture[str]):
         # Arrange
         path = bare_dir / "README.foo"
-        path.touch()
+        path.write_text("# Header\n")
 
         # Act
         with change_cwd(bare_dir), PyprojectTOMLManager():
@@ -67,15 +85,14 @@ def test_not_markdown(self, bare_dir: Path, capfd: pytest.CaptureFixture[str]):
         out, err = capfd.readouterr()
         assert not err
         assert out == (
-            "⚠ README file not found, printing badge markdown instead...\n"
+            "⚠ No Markdown-based README file found, printing badge markdown instead...\n"
             "![Licence](https://img.shields.io/badge/licence-mit-green)\n"
         )
 
     def test_empty(self, bare_dir: Path, capfd: pytest.CaptureFixture[str]):
         # Arrange
         path = bare_dir / "README.md"
-        path.write_text("""\
-""")
+        path.write_text("")
 
         # Act
         with change_cwd(bare_dir), PyprojectTOMLManager():
@@ -89,12 +106,18 @@ def test_empty(self, bare_dir: Path, capfd: pytest.CaptureFixture[str]):
         assert (
             (bare_dir / "README.md").read_text()
             == """\
+# test_empty0
+
 ![Licence](https://img.shields.io/badge/licence-mit-green)
 """
         )
         out, err = capfd.readouterr()
         assert not err
-        assert out == "✔ Adding Licence badge to 'README.md'.\n"
+        assert out == (
+            "✔ Writing 'README.md'.\n"
+            "☐ Populate 'README.md' to help users understand the project.\n"
+            "✔ Adding Licence badge to 'README.md'.\n"
+        )
 
     def test_only_newline(self, bare_dir: Path):
         # Arrange
@@ -115,6 +138,8 @@ def test_only_newline(self, bare_dir: Path):
         assert (
             (bare_dir / "README.md").read_text()
             == """\
+# test_only_newline0
+
 ![Licence](https://img.shields.io/badge/licence-mit-green)
 """
         )
diff --git a/tests/usethis/_core/test_core_readme.py b/tests/usethis/_core/test_core_readme.py
@@ -26,7 +26,7 @@ def test_start_from_nothing(
 
     def test_different_suffix(self, tmp_path: Path):
         # Arrange
-        (tmp_path / "README.rst").touch()
+        (tmp_path / "README.rst").write_text("Existing content")
 
         # Act
         with change_cwd(tmp_path), PyprojectTOMLManager():
@@ -48,10 +48,10 @@ def test_readme_directory(self, tmp_path: Path):
 
     def test_readme_no_suffix(self, tmp_path: Path, capfd: pytest.CaptureFixture[str]):
         # Arrange
-        (tmp_path / "README").touch()
+        (tmp_path / "README").write_text("Existing content")
 
         # Act
-        with change_cwd(tmp_path):
+        with change_cwd(tmp_path), PyprojectTOMLManager():
             add_readme()
 
         # Assert
@@ -139,3 +139,21 @@ def test_project_name_and_description(self, tmp_path: Path):
         # Assert
         assert (tmp_path / "README.md").exists()
         assert (tmp_path / "README.md").read_text() == "# A name\n\nA description\n"
+
+    def test_start_from_readme_empty(self, tmp_path: Path):
+        # Arrange
+        (tmp_path / "pyproject.toml").write_text(
+            """\
+[project]
+name = "A name"
+description = "A description"
+"""
+        )
+        (tmp_path / "README.md").touch()
+
+        # Act
+        with change_cwd(tmp_path), PyprojectTOMLManager():
+            add_readme()
+
+        # Assert
+        assert (tmp_path / "README.md").read_text() == "# A name\n\nA description\n"
diff --git a/tests/usethis/_interface/test_init.py b/tests/usethis/_interface/test_init.py
@@ -19,6 +19,8 @@ def test_pre_commit_included(self, tmp_path: Path):
         assert (tmp_path / "pyproject.toml").exists()
         assert result.output == (
             "✔ Writing 'pyproject.toml' and initializing project.\n"
+            "✔ Writing 'README.md'.\n"
+            "☐ Populate 'README.md' to help users understand the project.\n"
             "✔ Adding the pre-commit framework.\n"
             "☐ Run 'uv run pre-commit run --all-files' to run the hooks manually.\n"
             "✔ Adding recommended linters.\n"
@@ -67,6 +69,8 @@ def test_readme_example(self, tmp_path: Path):
             # ###################################
             == """\
 ✔ Writing 'pyproject.toml' and initializing project.
+✔ Writing 'README.md'.
+☐ Populate 'README.md' to help users understand the project.
 ✔ Adding recommended linters.
 ☐ Run 'uv run ruff check --fix' to run the Ruff linter with autofixes.
 ☐ Run 'uv run deptry src' to run deptry.
@@ -120,6 +124,8 @@ def test_bitbucket_and_docstyle(self, tmp_path: Path):
         assert (tmp_path / "pyproject.toml").exists()
         assert result.output == (
             "✔ Writing 'pyproject.toml' and initializing project.\n"
+            "✔ Writing 'README.md'.\n"
+            "☐ Populate 'README.md' to help users understand the project.\n"
             "✔ Adding the pre-commit framework.\n"
             "☐ Run 'uv run pre-commit run --all-files' to run the hooks manually.\n"
             "✔ Adding recommended linters.\n"
