Provide support for ConfigItem to manage a regex pattern of keys (#522)

* Implement regex-based key interface

* Test removal of a regex-based ConfigEntry (and null effect of adding)

* Remove unnecessary trailing whitespace in test file

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Better document reason for not implementing regex-based keys for TOML config

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: nathanjmcdougall

src/usethis/_integrations/file/ini/io_.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
 
 import configparser
+import re
 from functools import singledispatch
 from typing import TYPE_CHECKING
 
 from configupdater import ConfigUpdater as INIDocument
 from configupdater import Option, Section
 from pydantic import TypeAdapter
+from typing_extensions import assert_never
 
 from usethis._integrations.file.ini.errors import (
     INIDecodeError,
@@ -27,7 +29,7 @@
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Iterable, Sequence
     from pathlib import Path
     from typing import Any, ClassVar
 
@@ -121,9 +123,21 @@ def __getitem__(self, item: Sequence[Key]) -> Any:
             return _as_dict(root)
         elif len(keys) == 1:
             (section_key,) = keys
+            if not isinstance(section_key, str):
+                msg = (
+                    f"Only hard-coded strings are supported as keys when "
+                    f"accessing values, but a {type(section_key)} was provided."
+                )
+                raise NotImplementedError(msg)
             return _as_dict(root[section_key])
         elif len(keys) == 2:
             (section_key, option_key) = keys
+            if not isinstance(section_key, str) or not isinstance(option_key, str):
+                msg = (
+                    f"Only hard-coded strings are supported as keys when "
+                    f"accessing values, but a {type(section_key)} was provided."
+                )
+                raise NotImplementedError(msg)
             return root[section_key][option_key].value
         else:
             msg = (
@@ -210,7 +224,7 @@ def _set_value_in_root(
     def _set_value_in_section(
         *,
         root: INIDocument,
-        section_key: str,
+        section_key: Key,
         value: dict[str, str | list[str]],
         exists_ok: bool,
     ) -> None:
@@ -224,6 +238,13 @@ def _set_value_in_section(
                 msg = f"The INI file already has content at the section '{section_key}'"
                 raise INIValueAlreadySetError(msg)
 
+            if not isinstance(section_key, str):
+                msg = (
+                    f"Only hard-coded strings are supported as section keys when "
+                    f"setting values, but a {type(section_key)} was provided."
+                )
+                raise NotImplementedError(msg)
+
             for option_key in root[section_key]:
                 # We need to remove options that are not in the new dict
                 # We don't want to remove existing ones to keep their positions.
@@ -242,11 +263,18 @@ def _set_value_in_section(
     def _set_value_in_option(
         *,
         root: INIDocument,
-        section_key: str,
-        option_key: str,
+        section_key: Key,
+        option_key: Key,
         value: str,
         exists_ok: bool,
     ) -> None:
+        if not isinstance(section_key, str) or not isinstance(option_key, str):
+            msg = (
+                f"Only hard-coded strings are supported as keys when "
+                f"setting values, but a {type(section_key)} was provided."
+            )
+            raise NotImplementedError(msg)
+
         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}' "
@@ -260,7 +288,7 @@ def _set_value_in_option(
 
     @staticmethod
     def _validated_set(
-        *, root: INIDocument, section_key: str, option_key: str, value: str | list[str]
+        *, root: INIDocument, section_key: Key, option_key: Key, value: str | list[str]
     ) -> None:
         if not isinstance(value, str | list):
             msg = (
@@ -269,14 +297,21 @@ def _validated_set(
             )
             raise InvalidINITypeError(msg)
 
+        if not isinstance(section_key, str) or not isinstance(option_key, str):
+            msg = (
+                f"Only hard-coded strings are supported as keys when "
+                f"setting values, but a {type(section_key)} was provided."
+            )
+            raise NotImplementedError(msg)
+
         if section_key not in root:
             root.add_section(section_key)
 
         root.set(section=section_key, option=option_key, value=value)
 
     @staticmethod
     def _validated_append(
-        *, root: INIDocument, section_key: str, option_key: str, value: str
+        *, root: INIDocument, section_key: Key, option_key: Key, value: str
     ) -> None:
         if not isinstance(value, str):
             msg = (
@@ -285,6 +320,13 @@ def _validated_append(
             )
             raise InvalidINITypeError(msg)
 
+        if not isinstance(section_key, str) or not isinstance(option_key, str):
+            msg = (
+                f"Only hard-coded strings are supported as keys when "
+                f"setting values, but a {type(section_key)} was provided."
+            )
+            raise NotImplementedError(msg)
+
         if section_key not in root:
             root.add_section(section_key)
 
@@ -299,17 +341,62 @@ def __delitem__(self, keys: Sequence[Key]) -> None:
 
         An empty list of keys corresponds to the root of the document.
         """
-        root = self.get()
+        # We will iterate through keys and find all matches in the document
+        seqs: list[list[str]] = []
 
         if len(keys) == 0:
+            seqs.append([])
+        elif len(keys) == 1:
+            (section_key,) = keys
+
+            for seq in _itermatches(self.get().sections(), key=section_key):
+                seqs.append([seq])
+        elif len(keys) == 2:
+            (section_key, option_key) = keys
+
+            section_strkeys = []
+            for section_strkey in _itermatches(self.get().sections(), key=section_key):
+                section_strkeys.append(section_strkey)
+
+            for section_strkey in section_strkeys:
+                for option_strkey in _itermatches(
+                    self.get()[section_strkey].options(), key=option_key
+                ):
+                    seqs.append([section_strkey, option_strkey])
+        else:
+            msg = (
+                f"INI files do not support nested config, whereas access to "
+                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)}'"
+            )
+            raise INIValueMissingError(msg)
+
+        for seq in seqs:
+            self._delete_strkeys(seq)
+
+    def _delete_strkeys(self, strkeys: Sequence[str]) -> None:
+        """Delete a specific value in the INI file.
+
+        An empty list of strkeys corresponds to the root of the document.
+
+        Assumes that the keys exist in the file.
+        """
+        root = self.get()
+
+        if len(strkeys) == 0:
             removed = False
             for section_key in root.sections():
                 removed |= root.remove_section(name=section_key)
-        elif len(keys) == 1:
-            (section_key,) = keys
+        elif len(strkeys) == 1:
+            (section_key,) = strkeys
             removed = root.remove_section(name=section_key)
-        elif len(keys) == 2:
-            section_key, option_key = keys
+        elif len(strkeys) == 2:
+            section_key, option_key = strkeys
             removed = root.remove_option(section=section_key, option=option_key)
 
             # Cleanup section if empty
@@ -318,14 +405,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(strkeys)}'"
             )
-            raise INIValueMissingError(msg)
+            raise ININestingError(msg)
 
         if not removed:
-            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(strkeys)}'"
             raise INIValueMissingError(msg)
 
         self.commit(root)
@@ -365,7 +450,7 @@ def extend_list(self, *, keys: Sequence[Key], values: list[str]) -> None:
 
     @staticmethod
     def _extend_list_in_option(
-        *, root: INIDocument, section_key: str, option_key: str, values: list[str]
+        *, root: INIDocument, section_key: Key, option_key: Key, values: list[str]
     ) -> None:
         for value in values:
             INIFileManager._validated_append(
@@ -374,14 +459,21 @@ def _extend_list_in_option(
 
     @staticmethod
     def _remove_from_list_in_option(
-        *, root: INIDocument, section_key: str, option_key: str, values: list[str]
+        *, root: INIDocument, section_key: Key, option_key: Key, values: list[str]
     ) -> None:
         if section_key not in root:
             return
 
         if option_key not in root[section_key]:
             return
 
+        if not isinstance(section_key, str) or not isinstance(option_key, str):
+            msg = (
+                f"Only hard-coded strings are supported as keys when "
+                f"modifying values, but a {type(section_key)} was provided."
+            )
+            raise NotImplementedError(msg)
+
         original_values = root[section_key][option_key].as_list()
         # If already not present, silently pass
         new_values = [value for value in original_values if value not in values]
@@ -449,3 +541,16 @@ def _(value: INIDocument) -> dict[str, dict[str, Any]]:
 @_as_dict.register(Section)
 def _(value: Section) -> dict[str, Any]:
     return {option.key: option.value for option in value.iter_options()}
+
+
+def _itermatches(values: Iterable[str], /, *, key: Key):
+    """Iterate through an iterable and find all matches for a key."""
+    for value in values:
+        if isinstance(key, str):
+            if key == value:
+                yield value
+        elif isinstance(key, re.Pattern):
+            if key.fullmatch(value):
+                yield value
+        else:
+            assert_never(key)

src/usethis/_integrations/file/toml/io_.py

@@ -2,6 +2,7 @@
 
 import contextlib
 import copy
+import re
 from typing import TYPE_CHECKING, Any
 
 import mergedeep
@@ -10,6 +11,7 @@
 from pydantic import TypeAdapter
 from tomlkit import TOMLDocument
 from tomlkit.exceptions import TOMLKitError
+from typing_extensions import assert_never
 
 from usethis._integrations.file.toml.errors import (
     TOMLDecodeError,
@@ -34,6 +36,8 @@
 
     from typing_extensions import Self
 
+    from usethis._io import Key
+
 
 class TOMLFileManager(KeyValueFileManager):
     """An abstract class for managing TOML files."""
@@ -92,6 +96,7 @@ def __contains__(self, keys: Sequence[Key]) -> bool:
 
         An non-existent file will return False.
         """
+        keys = _validate_keys(keys)
         try:
             try:
                 container = self.get()
@@ -108,6 +113,7 @@ def __contains__(self, keys: Sequence[Key]) -> bool:
 
     def __getitem__(self, item: Sequence[Key]) -> Any:
         keys = item
+        keys = _validate_keys(keys)
 
         d = self.get()
         for key in keys:
@@ -125,6 +131,7 @@ def set_value(
         An empty list of keys corresponds to the root of the document.
         """
         toml_document = copy.copy(self.get())
+        keys = _validate_keys(keys)
 
         if not keys:
             # Root level config - value must be a mapping.
@@ -196,6 +203,7 @@ def __delitem__(self, keys: Sequence[Key]) -> None:
             toml_document = copy.copy(self.get())
         except FileNotFoundError:
             return
+        keys = _validate_keys(keys)
 
         # Exit early if the configuration is not present.
         try:
@@ -250,6 +258,7 @@ def extend_list(self, *, keys: Sequence[Key], values: list[Any]) -> None:
         if not keys:
             msg = "At least one ID key must be provided."
             raise ValueError(msg)
+        keys = _validate_keys(keys)
 
         toml_document = copy.copy(self.get())
 
@@ -283,6 +292,7 @@ def remove_from_list(self, *, keys: Sequence[Key], values: list[Any]) -> None:
         if not keys:
             msg = "At least one ID key must be provided."
             raise ValueError(msg)
+        keys = _validate_keys(keys)
 
         toml_document = copy.copy(self.get())
 
@@ -312,7 +322,35 @@ def remove_from_list(self, *, keys: Sequence[Key], values: list[Any]) -> None:
         self.commit(toml_document)
 
 
+def _validate_keys(keys: Sequence[Key]) -> list[str]:
+    """Validate the keys.
+
+    Args:
+        keys: The keys to validate.
+
+    Raises:
+        ValueError: If the keys are not valid.
+    """
+    so_far_keys: list[str] = []
+    for key in keys:
+        if isinstance(key, str):
+            so_far_keys.append(key)
+        elif isinstance(key, re.Pattern):
+            # Currently no need for this, perhaps we may add it in the future.
+            msg = (
+                f"Regex-based keys are not currently supported in TOML files: "
+                f"{print_keys([*so_far_keys, key])}"
+            )
+            raise NotImplementedError(msg)
+        else:
+            assert_never(key)
+
+    return so_far_keys
+
+
 def _get_unified_key(keys: Sequence[Key]) -> tomlkit.items.Key:
+    keys = _validate_keys(keys)
+
     single_keys = [tomlkit.items.SingleKey(key) for key in keys]
     if len(single_keys) == 1:
         (unified_key,) = single_keys