py/envoy.base.utils: Add changelogs.yaml (#4562)

Signed-off-by: Ryan Northey <ryan@synca.io>

Author: phlax

py/envoy.base.utils/envoy/base/utils/BUILD

@@ -16,6 +16,7 @@ toolshed_library(
         "//py/deps:reqs#pyyaml",
         "//py/deps:reqs#trycast",
         "//py/deps:reqs#types-protobuf",
+        "//py/deps:reqs#types-pyyaml",
         "//py/deps:reqs#zstandard",
     ],
     sources=[

py/envoy.base.utils/envoy/base/utils/abstract/project/changelog.py

@@ -30,7 +30,7 @@
 CHANGELOG_CURRENT_PATH = "changelogs/current.yaml"
 CHANGELOG_CURRENT_DIR_PATH = "changelogs/current"
 CHANGELOG_ENTRY_GLOB = "*/*.rst"
-CHANGELOG_SECTIONS_PATH = "changelogs/sections.yaml"
+CHANGELOG_CONFIG_PATH = "changelogs/changelogs.yaml"
 ENTRY_SEPARATOR = "__"
 CHANGELOG_SUMMARY_PATH = "changelogs/summary.md"
 CHANGELOG_URL_TPL = (
@@ -316,20 +316,28 @@ def section_re(self) -> re.Pattern[str]:
         return re.compile(r"\n[a-z_]*:")
 
     @cached_property
-    def sections(self) -> typing.ChangelogSectionsDict:
+    def config(self) -> typing.ChangelogConfigDict:
         try:
             return utils.from_yaml(
-                self.sections_path,
-                typing.ChangelogSectionsDict)
+                self.config_path,
+                typing.ChangelogConfigDict)
         except _yaml.reader.ReaderError as e:
             raise exceptions.ChangelogError(
-                "Failed to parse changelog sections "
-                f"({self.sections_path}): {e}")
+                "Failed to parse changelog config "
+                f"({self.config_path}): {e}")
         except utils.TypeCastingError as e:
             logger.warning(
-                "Changelog section parsing error: "
-                f"({self.sections_path})\n{e}")
-            return cast(typing.ChangelogSectionsDict, e.value)
+                "Changelog config parsing error: "
+                f"({self.config_path})\n{e}")
+            return cast(typing.ChangelogConfigDict, e.value)
+
+    @cached_property
+    def sections(self) -> typing.ChangelogSectionsDict:
+        return self.config["sections"]
+
+    @cached_property
+    def areas(self) -> typing.ChangelogAreasDict:
+        return self.config["areas"]
 
     def validate_sections(
             self,
@@ -353,12 +361,12 @@ def validate_sections(
             raise exceptions.ChangelogParseError(
                 f"Unknown changelog section(s){where}: "
                 f"{', '.join(unknown)}. "
-                f"Valid sections come from {CHANGELOG_SECTIONS_PATH}.")
+                f"Valid sections come from {CHANGELOG_CONFIG_PATH}.")
         return data
 
     @property
-    def sections_path(self) -> pathlib.Path:
-        return self.project.path.joinpath(CHANGELOG_SECTIONS_PATH)
+    def config_path(self) -> pathlib.Path:
+        return self.project.path.joinpath(CHANGELOG_CONFIG_PATH)
 
     @property
     def summary_path(self) -> pathlib.Path:

py/envoy.base.utils/envoy/base/utils/interface.py

@@ -233,6 +233,12 @@ async def is_pending(self) -> bool:
         `Pending`."""
         raise NotImplementedError
 
+    @property
+    @abstracts.interfacemethod
+    def areas(self) -> typing.ChangelogAreasDict:
+        """Changelog areas."""
+        raise NotImplementedError
+
     @property
     @abstracts.interfacemethod
     def sections(self) -> typing.ChangelogSectionsDict:

py/envoy.base.utils/envoy/base/utils/typing.py

@@ -54,6 +54,19 @@ class ChangelogSectionDict(BaseChangelogSectionDict, total=False):
 
 ChangelogSectionsDict = dict[str, ChangelogSectionDict]
 
+
+class ChangelogAreaDict(BaseChangelogSectionDict):
+    pass
+
+
+ChangelogAreasDict = dict[str, ChangelogAreaDict]
+
+
+class ChangelogConfigDict(TypedDict):
+    sections: ChangelogSectionsDict
+    areas: ChangelogAreasDict
+
+
 VersionConfigDict = dict[str, str]
 
 

py/envoy.base.utils/tests/test_abstract_project_changelogs.py

@@ -334,13 +334,13 @@ def test_abstract_changelogs_rel_current_dir_path(patches):
 @pytest.mark.parametrize(
     "raises",
     [None, Exception, yaml.reader.ReaderError, exceptions.TypeCastingError])
-def test_abstract_changelogs_sections(patches, raises):
+def test_abstract_changelogs_config(patches, raises):
     changelogs = DummyChangelogs("PROJECT")
     patched = patches(
         "cast",
         "utils.from_yaml",
         "logger",
-        ("AChangelogs.sections_path",
+        ("AChangelogs.config_path",
          dict(new_callable=PropertyMock)),
         prefix="envoy.base.utils.abstract.project.changelog")
 
@@ -350,53 +350,89 @@ def test_abstract_changelogs_sections(patches, raises):
             m_yaml.side_effect = error
         if raises == Exception:
             with pytest.raises(Exception):
-                changelogs.sections
+                changelogs.config
         elif raises == yaml.reader.ReaderError:
             with pytest.raises(exceptions.ChangelogError) as e:
-                changelogs.sections
+                changelogs.config
         else:
             assert (
-                changelogs.sections
+                changelogs.config
                 == (m_yaml.return_value
                     if not raises
                     else m_cast.return_value))
 
     if raises == exceptions.TypeCastingError:
         assert (
             m_cast.call_args
-            == [(typing.ChangelogSectionsDict, error.value), {}])
+            == [(typing.ChangelogConfigDict, error.value), {}])
         assert (
             m_logger.warning.call_args
-            == [("Changelog section parsing error: "
+            == [("Changelog config parsing error: "
                 f"({m_path.return_value})\n{error}", ), {}])
     else:
         assert not m_logger.called
         assert not m_cast.called
 
     assert (
         m_yaml.call_args
-        == [(m_path.return_value, typing.ChangelogSectionsDict), {}])
+        == [(m_path.return_value, typing.ChangelogConfigDict), {}])
     assert (
-        ("sections" in changelogs.__dict__)
+        ("config" in changelogs.__dict__)
         == (not raises or raises == exceptions.TypeCastingError))
     if raises != yaml.reader.ReaderError:
         return
     assert (
         e.value.args[0]
-        == ("Failed to parse changelog sections "
+        == ("Failed to parse changelog config "
             f"({m_path.return_value}): {str(error)}"))
 
 
-def test_abstract_changelogs_sections_path():
+def test_abstract_changelogs_sections(patches):
+    changelogs = DummyChangelogs("PROJECT")
+    patched = patches(
+        ("AChangelogs.config",
+         dict(new_callable=PropertyMock)),
+        prefix="envoy.base.utils.abstract.project.changelog")
+
+    with patched as (m_config, ):
+        assert (
+            changelogs.sections
+            == m_config.return_value.__getitem__.return_value)
+
+    assert (
+        m_config.return_value.__getitem__.call_args
+        == [("sections", ), {}])
+    assert "sections" in changelogs.__dict__
+
+
+def test_abstract_changelogs_areas(patches):
+    changelogs = DummyChangelogs("PROJECT")
+    patched = patches(
+        ("AChangelogs.config",
+         dict(new_callable=PropertyMock)),
+        prefix="envoy.base.utils.abstract.project.changelog")
+
+    with patched as (m_config, ):
+        assert (
+            changelogs.areas
+            == m_config.return_value.__getitem__.return_value)
+
+    assert (
+        m_config.return_value.__getitem__.call_args
+        == [("areas", ), {}])
+    assert "areas" in changelogs.__dict__
+
+
+def test_abstract_changelogs_config_path():
     project = MagicMock()
     changelogs = DummyChangelogs(project)
     assert (
-        changelogs.sections_path
+        changelogs.config_path
         == project.path.joinpath.return_value)
     assert (
         project.path.joinpath.call_args
-        == [(abstract.project.changelog.CHANGELOG_SECTIONS_PATH, ), {}])
-    assert "sections_path" not in changelogs.__dict__
+        == [(abstract.project.changelog.CHANGELOG_CONFIG_PATH, ), {}])
+    assert "config_path" not in changelogs.__dict__
 
 
 def test_abstract_changelogs_validate_sections():
@@ -423,7 +459,7 @@ def test_abstract_changelogs_validate_sections_unknown(path):
 
     message = e.value.args[0]
     assert "unknown" in message
-    assert abstract.project.changelog.CHANGELOG_SECTIONS_PATH in message
+    assert abstract.project.changelog.CHANGELOG_CONFIG_PATH in message
     if path is None:
         assert "changelogs/current.yaml" not in message
         assert "(None)" not in message
@@ -1737,9 +1773,10 @@ async def test_abstract_changelog_data_unknown_section(tmp_path):
         "unknown:\n"
         "  - area: api\n"
         "    change: changed\n")
-    tmp_path.joinpath("changelogs/sections.yaml").write_text(
-        "known:\n"
-        "  title: Known\n")
+    tmp_path.joinpath("changelogs/changelogs.yaml").write_text(
+        "sections:\n"
+        "  known:\n"
+        "    title: Known\n")
 
     project = MagicMock()
     project.path = tmp_path