Improve error string formatting for consistency (#818)

nathanjmcdougall · web-flow · commit 6f48238d2b97 · 2025-06-28T16:05:19.000+12:00
* Improve error string formatting for consistency

End in full stops, use quote marks for variable quantities, cosmetic changes

* Tweak error message to reflect new behaviour
diff --git a/src/usethis/_integrations/ci/bitbucket/dump.py b/src/usethis/_integrations/ci/bitbucket/dump.py
@@ -31,7 +31,7 @@ def bitbucket_fancy_dump(
     if not isinstance(dump, dict):
         msg = (
             f"Invalid '{type(config)}' representation when dumping; expected dict, got "
-            f"{type(dump)}"
+            f"{type(dump)}."
         )
         raise TypeError(msg)
 
diff --git a/src/usethis/_integrations/ci/bitbucket/steps.py b/src/usethis/_integrations/ci/bitbucket/steps.py
@@ -126,7 +126,7 @@ def _add_step_in_default_via_doc(
                 try:
                     script_item = _SCRIPT_ITEM_LOOKUP[script_item.name]
                 except KeyError:
-                    msg = f"Unrecognized script item anchor: {script_item.name}"
+                    msg = f"Unrecognized script item anchor: '{script_item.name}'."
                     raise NotImplementedError(msg) from None
 
                 if config.definitions is None:
diff --git a/src/usethis/_integrations/ci/github/tags.py b/src/usethis/_integrations/ci/github/tags.py
@@ -30,13 +30,13 @@ def get_github_latest_tag(owner: str, repo: str) -> str:
         response = requests.get(api_url, timeout=1)
         response.raise_for_status()  # Raise an error for HTTP issues
     except (requests.exceptions.HTTPError, requests.exceptions.ConnectionError) as err:
-        msg = f"Failed to fetch tags from GitHub API: {err}"
+        msg = f"Failed to fetch tags from GitHub API:\n{err}"
         raise GitHubTagError(msg) from None
 
     tags = response.json()
 
     if not tags:
-        msg = f"No tags found for repository '{owner}/{repo}'"
+        msg = f"No tags found for repository '{owner}/{repo}'."
         raise NoGitHubTagsFoundError(msg)
 
     # Most recent tag's name
diff --git a/src/usethis/_integrations/file/ini/io_.py b/src/usethis/_integrations/file/ini/io_.py
@@ -56,7 +56,7 @@ def read_file(self) -> None:
         except UnexpectedFileIOError as err:
             raise UnexpectedINIIOError(err) from None
         except configparser.ParsingError as err:
-            msg = f"Failed to decode '{self.name}': {err}"
+            msg = f"Failed to decode '{self.name}':\n{err}"
             raise INIDecodeError(msg) from None
 
     def _dump_content(self) -> str:
@@ -142,7 +142,7 @@ def __getitem__(self, item: Sequence[Key]) -> Any:
         else:
             msg = (
                 f"INI files do not support nested config, whereas access to "
-                f"'{self.name}' was attempted at '{print_keys(keys)}'"
+                f"'{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise KeyError(msg)
 
@@ -174,7 +174,7 @@ def set_value(
         else:
             msg = (
                 f"INI files do not support nested config, whereas access to "
-                f"'{self.name}' was attempted at '{print_keys(keys)}'"
+                f"'{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise ININestingError(msg)
 
@@ -187,7 +187,7 @@ def _set_value_in_root(
         root_dict = value
 
         if any(root) and not exists_ok:
-            msg = "The INI file already has content at the root level"
+            msg = "The INI file already has content at the root level."
             raise INIValueAlreadySetError(msg)
 
         # We need to remove section that are not in the new dict
@@ -237,7 +237,9 @@ def _set_value_in_section(
 
         if section_key in root:
             if not exists_ok:
-                msg = f"The INI file already has content at the section '{section_key}'"
+                msg = (
+                    f"The INI file already has content at the section '{section_key}'."
+                )
                 raise INIValueAlreadySetError(msg)
 
             if not isinstance(section_key, str):
@@ -282,7 +284,7 @@ def _set_value_in_option(
         if root.has_option(section=section_key, option=option_key) and not exists_ok:
             msg = (
                 f"The INI file already has content at the section '{section_key}' "
-                f"and option '{option_key}'"
+                f"and option '{option_key}'."
             )
             raise INIValueAlreadySetError(msg)
 
@@ -371,14 +373,12 @@ def __delitem__(self, keys: Sequence[Key]) -> None:
         else:
             msg = (
                 f"INI files do not support nested config, whereas access to "
-                f"'{self.name}' was attempted at '{print_keys(keys)}'"
+                f"'{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise ININestingError(msg)
 
         if not seqs:
-            msg = (
-                f"INI file '{self.name}' does not contain the keys '{print_keys(keys)}'"
-            )
+            msg = f"INI file '{self.name}' does not contain the keys '{print_keys(keys)}'."
             raise INIValueMissingError(msg)
 
         for seq in seqs:
@@ -412,12 +412,12 @@ def _delete_strkeys(self, strkeys: Sequence[str]) -> None:
         else:
             msg = (
                 f"INI files do not support nested config, whereas access to "
-                f"'{self.name}' was attempted at '{print_keys(strkeys)}'"
+                f"'{self.name}' was attempted at '{print_keys(strkeys)}'."
             )
             raise ININestingError(msg)
 
         if not removed:
-            msg = f"INI file '{self.name}' does not contain the keys '{print_keys(strkeys)}'"
+            msg = f"INI file '{self.name}' does not contain the keys '{print_keys(strkeys)}'."
             raise INIValueMissingError(msg)
 
         self.commit(root)
@@ -432,13 +432,13 @@ def extend_list(self, *, keys: Sequence[Key], values: list[str]) -> None:
         if len(keys) == 0:
             msg = (
                 f"INI files do not support lists at the root level, whereas access to "
-                f"'{self.name}' was attempted at '{print_keys(keys)}'"
+                f"'{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise InvalidINITypeError(msg)
         elif len(keys) == 1:
             msg = (
                 f"INI files do not support lists at the section level, whereas access "
-                f"to '{self.name}' was attempted at '{print_keys(keys)}'"
+                f"to '{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise InvalidINITypeError(msg)
         elif len(keys) == 2:
@@ -449,7 +449,7 @@ def extend_list(self, *, keys: Sequence[Key], values: list[str]) -> None:
         else:
             msg = (
                 f"INI files do not support nested config, whereas access to "
-                f"'{self.name}' was attempted at '{print_keys(keys)}'"
+                f"'{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise ININestingError(msg)
 
@@ -509,13 +509,13 @@ def remove_from_list(self, *, keys: Sequence[Key], values: list[str]) -> None:
         if len(keys) == 0:
             msg = (
                 f"INI files do not support lists at the root level, whereas access to "
-                f"'{self.name}' was attempted at '{print_keys(keys)}'"
+                f"'{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise InvalidINITypeError(msg)
         elif len(keys) == 1:
             msg = (
                 f"INI files do not support lists at the section level, whereas access "
-                f"to '{self.name}' was attempted at '{print_keys(keys)}'"
+                f"to '{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise InvalidINITypeError(msg)
         elif len(keys) == 2:
@@ -526,7 +526,7 @@ def remove_from_list(self, *, keys: Sequence[Key], values: list[str]) -> None:
         else:
             msg = (
                 f"INI files do not support nested config, whereas access to "
-                f"'{self.name}' was attempted at '{print_keys(keys)}'"
+                f"'{self.name}' was attempted at '{print_keys(keys)}'."
             )
             raise ININestingError(msg)
 
diff --git a/src/usethis/_integrations/file/pyproject_toml/name.py b/src/usethis/_integrations/file/pyproject_toml/name.py
@@ -19,9 +19,7 @@ def get_name() -> str:
         msg = "The 'project.name' value is missing from 'pyproject.toml'."
         raise PyprojectTOMLProjectNameError(msg) from None
     except ValidationError as err:
-        msg = (
-            f"The 'project.name' value in 'pyproject.toml' is not a valid string: {err}"
-        )
+        msg = f"The 'project.name' value in 'pyproject.toml' is not a valid string:\n{err}"
         raise PyprojectTOMLProjectNameError(msg) from None
 
     return name
@@ -36,7 +34,7 @@ def get_description() -> str:
         msg = "The 'project.description' value is missing from 'pyproject.toml'."
         raise PyprojectTOMLProjectDescriptionError(msg) from None
     except ValidationError as err:
-        msg = f"The 'project.description' value in 'pyproject.toml' is not a valid string: {err}"
+        msg = f"The 'project.description' value in 'pyproject.toml' is not a valid string:\n{err}"
         raise PyprojectTOMLProjectDescriptionError(msg) from None
 
     return description
diff --git a/src/usethis/_integrations/file/pyproject_toml/project.py b/src/usethis/_integrations/file/pyproject_toml/project.py
@@ -22,7 +22,7 @@ def get_project_dict() -> dict[str, Any]:
         msg = "The 'project' section is missing from 'pyproject.toml'."
         raise PyprojectTOMLProjectSectionError(msg) from None
     except ValidationError as err:
-        msg = f"The 'project' section in 'pyproject.toml' is not a valid map: {err}"
+        msg = f"The 'project' section in 'pyproject.toml' is not a valid map:\n{err}"
         raise PyprojectTOMLProjectSectionError(msg) from None
 
     return project
diff --git a/src/usethis/_integrations/file/pyproject_toml/valid.py b/src/usethis/_integrations/file/pyproject_toml/valid.py
@@ -37,7 +37,7 @@ def _ensure_project_section(toml_document: TOMLDocument) -> Table:
 
     project = toml_document["project"]
     if not isinstance(project, Table):
-        msg = f"Expected 'project' to be a TOML Table, got {type(project)}."
+        msg = f"Expected 'project' to be a TOML Table, got '{type(project)}'."
         raise TypeError(msg)
 
     return project
diff --git a/src/usethis/_integrations/file/toml/io_.py b/src/usethis/_integrations/file/toml/io_.py
@@ -61,7 +61,7 @@ def read_file(self) -> None:
         except UnexpectedFileIOError as err:
             raise UnexpectedTOMLIOError(err) from None
         except TOMLKitError as err:
-            msg = f"Failed to decode '{self.name}': {err}"
+            msg = f"Failed to decode '{self.name}':\n{err}"
             raise TOMLDecodeError(msg) from None
 
     def _dump_content(self) -> str:
diff --git a/src/usethis/_integrations/file/yaml/update.py b/src/usethis/_integrations/file/yaml/update.py
@@ -33,7 +33,7 @@ def update_ruamel_yaml_map(
     """
     """Update the values of a ruamel.yaml map in-place using a diff-like algorithm."""
     if not isinstance(cmap, CommentedMap):
-        msg = f"Expected CommentedMap, but got {type(cmap)}."
+        msg = f"Expected CommentedMap, but got '{type(cmap)}'."
         raise TypeError(msg)
 
     if not preserve_comments:
diff --git a/src/usethis/_integrations/pre_commit/dump.py b/src/usethis/_integrations/pre_commit/dump.py
@@ -21,7 +21,7 @@ def pre_commit_fancy_dump(
     if not isinstance(dump, dict):
         msg = (
             f"Invalid '{type(config)}' representation when dumping; expected dict, got "
-            f"{type(dump)}"
+            f"'{type(dump)}'."
         )
         raise TypeError(msg)
 
diff --git a/src/usethis/_integrations/pre_commit/hooks.py b/src/usethis/_integrations/pre_commit/hooks.py
@@ -49,7 +49,7 @@ def add_repo(repo: LocalRepo | UriRepo) -> None:
         (hook_config,) = repo.hooks
 
         if hook_config.id is None:
-            msg = "Hook ID must be specified"
+            msg = "The hook ID must be specified."
             raise ValueError(msg)
 
         # Ordered list of the hooks already in the file
@@ -72,7 +72,7 @@ def add_repo(repo: LocalRepo | UriRepo) -> None:
             try:
                 hook_idx = _HOOK_ORDER.index(hook_config.id)
             except ValueError:
-                msg = f"Hook '{hook_config.id}' not recognized"
+                msg = f"Hook '{hook_config.id}' not recognized."
                 raise NotImplementedError(msg) from None
             precedents = _HOOK_ORDER[:hook_idx]
             successors = _HOOK_ORDER[hook_idx + 1 :]
diff --git a/src/usethis/_integrations/sonarqube/config.py b/src/usethis/_integrations/sonarqube/config.py
@@ -86,7 +86,7 @@ def get_sonar_project_properties() -> str:
 def _get_short_version(version: str) -> str:
     match = re.match(r"^(\d{1,2}\.\d{1,2})", version)
     if match is None:
-        msg = f"Could not parse Python version from {version}"
+        msg = f"Could not parse Python version from '{version}'."
         raise _NonstandardPythonVersionError(msg)
 
     return match.group(1)
@@ -109,5 +109,5 @@ def _validate_project_key(project_key: str) -> None:
     """
     _RE = r"^[a-zA-Z0-9\-_:.]+$"
     if re.match(_RE, project_key) is None or project_key.isdigit():
-        msg = f"Invalid SonarQube project key: {project_key}"
+        msg = f"Invalid SonarQube project key: '{project_key}'."
         raise InvalidSonarQubeProjectKeyError(msg)
diff --git a/src/usethis/_integrations/uv/python.py b/src/usethis/_integrations/uv/python.py
@@ -43,7 +43,7 @@ def _parse_python_version_from_uv_output(version: str) -> str:
     if match:
         return match.group(1)
     else:
-        msg = f"Could not parse version from {version}"
+        msg = f"Could not parse version from '{version}'."
         raise UVUnparsedPythonVersionError(msg)
 
 
diff --git a/src/usethis/_io.py b/src/usethis/_io.py
@@ -132,7 +132,7 @@ def read_file(self) -> None:
         try:
             self._content = self._parse_content(self.path.read_text())
         except FileNotFoundError:
-            msg = f"'{self.name}' not found in the current directory at '{self.path}'"
+            msg = f"'{self.name}' not found in the current directory at '{self.path}'."
             raise FileNotFoundError(msg) from None
 
     @abstractmethod
@@ -157,7 +157,7 @@ def _validate_lock(self) -> None:
         if not self.is_locked():
             msg = (
                 f"The '{self.name}' file has not been opened yet. Please enter the "
-                f"context manager, e.g. 'with {self.__class__.__name__}():'"
+                f"context manager, e.g. 'with {self.__class__.__name__}():'."
             )
             raise UnexpectedFileIOError(msg)
 
diff --git a/src/usethis/_pipeweld/func.py b/src/usethis/_pipeweld/func.py
@@ -297,7 +297,7 @@ def _flatten_partition(partition: Partition) -> Series:
         partition.postrequisite_component,
     )
     if component is None:
-        msg = "Flatten failed: no components"
+        msg = "Flatten failed: no components."
         raise ValueError(msg)
     return component
 
@@ -584,7 +584,7 @@ def get_endpoint(component: str | Series | DepGroup | Parallel) -> str:
             except ValueError:
                 pass
 
-        msg = """No endpoints are defined for a Series with no steps"""
+        msg = "No endpoints are defined for a Series with no steps."
         raise ValueError(msg)
     elif isinstance(component, Parallel):
         endpoints = []
@@ -594,7 +594,7 @@ def get_endpoint(component: str | Series | DepGroup | Parallel) -> str:
         # Any endpoint will do so choose the first one
         # alphabetically
         if not endpoints:
-            msg = """No endpoints are defined for a Parallel block with no steps"""
+            msg = "No endpoints are defined for a Parallel block with no steps."
             raise ValueError(msg)
         return sorted(endpoints)[0]
     elif isinstance(component, DepGroup):
diff --git a/src/usethis/_tool/base.py b/src/usethis/_tool/base.py
@@ -325,7 +325,7 @@ def _get_active_config_file_managers_from_resolution(
             msg = (
                 f"The preferred file manager '{preferred_file_manager}' is not "
                 f"among the file managers '{file_managers}' for the tool "
-                f"'{self.name}'"
+                f"'{self.name}'."
             )
             raise NotImplementedError(msg)
         return {preferred_file_manager}
@@ -385,7 +385,7 @@ def add_configs(self) -> None:
 
             if not file_managers:
                 if config_item.applies_to_all:
-                    msg = f"No active config file managers found for one of the '{self.name}' config items"
+                    msg = f"No active config file managers found for one of the '{self.name}' config items."
                     raise NotImplementedError(msg)
                 else:
                     # Early exist; this config item is not managed by any active files
@@ -399,9 +399,7 @@ def add_configs(self) -> None:
                 in {file_manager.relative_path for file_manager in file_managers}
             ]
             if not config_entries:
-                msg = (
-                    f"No config entries found for one of the '{self.name}' config items"
-                )
+                msg = f"No config entries found for one of the '{self.name}' config items."
                 raise NotImplementedError(msg)
             if len(config_entries) != 1:
                 msg = (
diff --git a/src/usethis/_tool/impl/import_linter.py b/src/usethis/_tool/impl/import_linter.py
@@ -307,7 +307,7 @@ def _is_root_package_singular(self) -> bool:
         elif isinstance(file_manager, SetupCFGManager | DotImportLinterManager):
             return ["importlinter", "root_package"] in file_manager
         else:
-            msg = f"Unsupported file manager: {file_manager}"
+            msg = f"Unsupported file manager: '{file_manager}'."
             raise NotImplementedError(msg)
 
     def get_pre_commit_config(self) -> PreCommitConfig:
diff --git a/src/usethis/_tool/impl/pytest.py b/src/usethis/_tool/impl/pytest.py
@@ -203,7 +203,7 @@ def get_active_config_file_managers(self) -> set[KeyValueFileManager]:
             msg = (
                 f"The preferred file manager '{preferred_file_manager}' is not "
                 f"among the file managers '{file_managers}' for the tool "
-                f"'{self.name}'"
+                f"'{self.name}'."
             )
             raise NotImplementedError(msg)
         return {preferred_file_manager}
diff --git a/src/usethis/_tool/impl/ruff.py b/src/usethis/_tool/impl/ruff.py
diff --git a/src/usethis/_tool/rule.py b/src/usethis/_tool/rule.py
diff --git a/tests/test_suite.py b/tests/test_suite.py
diff --git a/tests/usethis/_integrations/ci/github/test_tags.py b/tests/usethis/_integrations/ci/github/test_tags.py
diff --git a/tests/usethis/_tool/test_base.py b/tests/usethis/_tool/test_base.py

Original file line number	Diff line number	Diff line change
`@@ -31,7 +31,7 @@ def bitbucket_fancy_dump(`
`31`	`31`	`if not isinstance(dump, dict):`
`32`	`32`	`msg = (`
`33`	`33`	`f"Invalid '{type(config)}' representation when dumping; expected dict, got "`
`34`		`- f"{type(dump)}"`
	`34`	`+ f"{type(dump)}."`
`35`	`35`	`)`
`36`	`36`	`raise TypeError(msg)`
`37`	`37`
Original file line number	Diff line number	Diff line change
`@@ -21,7 +21,7 @@ def pre_commit_fancy_dump(`
`21`	`21`	`if not isinstance(dump, dict):`
`22`	`22`	`msg = (`
`23`	`23`	`f"Invalid '{type(config)}' representation when dumping; expected dict, got "`
`24`		`- f"{type(dump)}"`
	`24`	`+ f"'{type(dump)}'."`
`25`	`25`	`)`
`26`	`26`	`raise TypeError(msg)`
`27`	`27`