ENH: modify pyproject.toml with context manager (#316)

* BREAK: rename `PyprojectToml` to `Pyproject`
* FEAT: extract `ModifiablePyproject` class
* FIX: fix `executor` class typo

pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "pre-commit",
     "ruamel.yaml", # better YAML dumping
     "tomlkit",
-    'typing-extensions; python_version <"3.11.0"',
+    'typing-extensions; python_version <"3.12.0"', # override
 ]
 description = "Pre-commit hooks that ensure that ComPWA repositories have a similar developer set-up"
 dynamic = ["version"]

src/compwa_policy/check_dev_files/black.py

@@ -10,15 +10,14 @@
     remove_precommit_hook,
     update_single_hook_precommit_repo,
 )
-from compwa_policy.utilities.pyproject import PyprojectTOML, complies_with_subset
+from compwa_policy.utilities.pyproject import ModifiablePyproject, complies_with_subset
 from compwa_policy.utilities.toml import to_toml_array
 
 
 def main(has_notebooks: bool) -> None:
     if not CONFIG_PATH.pyproject.exists():
         return
-    pyproject = PyprojectTOML.load()
-    with Executor() as do:
+    with Executor() as do, ModifiablePyproject.load() as pyproject:
         do(_remove_outdated_settings, pyproject)
         do(_update_black_settings, pyproject)
         do(
@@ -47,10 +46,9 @@ def main(has_notebooks: bool) -> None:
             },
         )
         do(remove_precommit_hook, "nbqa-black")
-        do(pyproject.finalize)
 
 
-def _remove_outdated_settings(pyproject: PyprojectTOML) -> None:
+def _remove_outdated_settings(pyproject: ModifiablePyproject) -> None:
     settings = pyproject.get_table("tool.black", create=True)
     forbidden_options = ("line-length",)
     removed_options = set()
@@ -63,10 +61,10 @@ def _remove_outdated_settings(pyproject: PyprojectTOML) -> None:
             f"Removed {', '.join(sorted(removed_options))} option from black"
             f" configuration in {CONFIG_PATH.pyproject}"
         )
-        pyproject.modifications.append(msg)
+        pyproject.append_to_changelog(msg)
 
 
-def _update_black_settings(pyproject: PyprojectTOML) -> None:
+def _update_black_settings(pyproject: ModifiablePyproject) -> None:
     settings = pyproject.get_table("tool.black", create=True)
     versions = pyproject.get_supported_python_versions()
     target_version = to_toml_array(sorted("py" + v.replace(".", "") for v in versions))
@@ -77,7 +75,7 @@ def _update_black_settings(pyproject: PyprojectTOML) -> None:
     if not complies_with_subset(settings, minimal_settings):
         settings.update(minimal_settings)
         msg = f"Updated black configuration in {CONFIG_PATH.pyproject}"
-        pyproject.modifications.append(msg)
+        pyproject.append_to_changelog(msg)
 
 
 def _update_precommit_repo(has_notebooks: bool) -> None:

src/compwa_policy/check_dev_files/github_workflows.py

@@ -19,11 +19,7 @@
 )
 from compwa_policy.utilities.executor import Executor
 from compwa_policy.utilities.precommit import load_precommit_config
-from compwa_policy.utilities.pyproject import (
-    PyprojectTOML,
-    PythonVersion,
-    get_build_system,
-)
+from compwa_policy.utilities.pyproject import Pyproject, PythonVersion, get_build_system
 from compwa_policy.utilities.yaml import create_prettier_round_trip_yaml
 
 if TYPE_CHECKING:
@@ -238,7 +234,7 @@ def __update_with_section(config: dict, job_name: str) -> None:
 
 
 def __get_package_name() -> str:
-    pypi_name = PyprojectTOML.load().get_package_name(raise_on_missing=True)
+    pypi_name = Pyproject.load().get_package_name(raise_on_missing=True)
     package_name = pypi_name.replace("-", "_").lower()
     if os.path.exists(f"src/{package_name}/"):
         return package_name

src/compwa_policy/check_dev_files/gitpod.py

@@ -8,7 +8,7 @@
 from compwa_policy.errors import PrecommitError
 from compwa_policy.utilities import COMPWA_POLICY_DIR, CONFIG_PATH
 from compwa_policy.utilities.pyproject import (
-    PyprojectTOML,
+    Pyproject,
     PythonVersion,
     get_constraints_file,
 )
@@ -37,7 +37,7 @@ def main(no_gitpod: bool, python_version: PythonVersion) -> None:
         error_message += ". Problem has been fixed."
         raise PrecommitError(error_message)
     try:
-        repo_url = PyprojectTOML.load().get_repo_url()
+        repo_url = Pyproject.load().get_repo_url()
         add_badge(
             f"[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#{repo_url})"
         )

src/compwa_policy/check_dev_files/jupyter.py

@@ -1,7 +1,6 @@
 """Update the developer setup when using Jupyter notebooks."""
 
-from compwa_policy.utilities.executor import Executor
-from compwa_policy.utilities.pyproject import PyprojectTOML, get_build_system
+from compwa_policy.utilities.pyproject import ModifiablePyproject, get_build_system
 
 
 def main() -> None:
@@ -11,11 +10,10 @@ def main() -> None:
 def _update_dev_requirements() -> None:
     if get_build_system() is None:
         return
-    pyproject = PyprojectTOML.load()
-    supported_python_versions = pyproject.get_supported_python_versions()
-    if "3.6" in supported_python_versions:
-        return
-    with Executor() as do:
+    with ModifiablePyproject.load() as pyproject:
+        supported_python_versions = pyproject.get_supported_python_versions()
+        if "3.6" in supported_python_versions:
+            return
         for package in [
             "black",
             "isort",
@@ -27,4 +25,4 @@ def _update_dev_requirements() -> None:
             "python-lsp-ruff",
             "python-lsp-server[rope]",
         ]:
-            do(pyproject.add_dependency, package, optional_key=["jupyter", "dev"])
+            pyproject.add_dependency(package, optional_key=["jupyter", "dev"])

src/compwa_policy/check_dev_files/mypy.py

@@ -5,21 +5,18 @@
 import tomlkit
 from ini2toml.api import Translator
 
-from compwa_policy.errors import PrecommitError
 from compwa_policy.utilities import CONFIG_PATH, vscode
 from compwa_policy.utilities.executor import Executor
-from compwa_policy.utilities.pyproject import PyprojectTOML
+from compwa_policy.utilities.pyproject import ModifiablePyproject, Pyproject
 
 
 def main() -> None:
-    pyproject = PyprojectTOML.load()
-    with Executor() as do:
+    with Executor() as do, ModifiablePyproject.load() as pyproject:
         do(_merge_mypy_into_pyproject, pyproject)
         do(_update_vscode_settings, pyproject)
-        do(pyproject.finalize)
 
 
-def _update_vscode_settings(pyproject: PyprojectTOML) -> None:
+def _update_vscode_settings(pyproject: Pyproject) -> None:
     mypy_config = pyproject.get_table("tool.mypy")
     with Executor() as do:
         if not mypy_config:
@@ -40,7 +37,7 @@ def _update_vscode_settings(pyproject: PyprojectTOML) -> None:
             do(vscode.update_settings, settings)
 
 
-def _merge_mypy_into_pyproject(pyproject: PyprojectTOML) -> None:
+def _merge_mypy_into_pyproject(pyproject: ModifiablePyproject) -> None:
     config_path = ".mypy.ini"
     if not os.path.exists(config_path):
         return
@@ -52,4 +49,4 @@ def _merge_mypy_into_pyproject(pyproject: PyprojectTOML) -> None:
     tool_table.update(mypy_config)
     os.remove(config_path)
     msg = f"Moved mypy configuration to {CONFIG_PATH.pyproject}"
-    raise PrecommitError(msg)
+    pyproject.append_to_changelog(msg)

src/compwa_policy/check_dev_files/precommit.py

@@ -19,7 +19,7 @@
     load_precommit_config,
     load_roundtrip_precommit_config,
 )
-from compwa_policy.utilities.pyproject import PyprojectTOML, get_constraints_file
+from compwa_policy.utilities.pyproject import Pyproject, get_constraints_file
 from compwa_policy.utilities.yaml import create_prettier_round_trip_yaml
 
 
@@ -91,7 +91,7 @@ def _update_precommit_ci_commit_msg() -> None:
 
 
 def __has_constraint_files() -> bool:
-    python_versions = PyprojectTOML.load().get_supported_python_versions()
+    python_versions = Pyproject.load().get_supported_python_versions()
     constraint_files = [get_constraints_file(v) for v in python_versions]
     constraint_paths = [Path(path) for path in constraint_files if path is not None]
     return any(path.exists() for path in constraint_paths)

src/compwa_policy/check_dev_files/pyright.py

@@ -6,20 +6,17 @@
 import os
 
 from compwa_policy.utilities import CONFIG_PATH
-from compwa_policy.utilities.executor import Executor
-from compwa_policy.utilities.pyproject import PyprojectTOML, complies_with_subset
+from compwa_policy.utilities.pyproject import ModifiablePyproject, complies_with_subset
 from compwa_policy.utilities.toml import to_toml_array
 
 
 def main() -> None:
-    pyproject = PyprojectTOML.load()
-    with Executor() as do:
-        do(_merge_config_into_pyproject, pyproject)
-        do(_update_settings, pyproject)
-        do(pyproject.finalize)
+    with ModifiablePyproject.load() as pyproject:
+        _merge_config_into_pyproject(pyproject)
+        _update_settings(pyproject)
 
 
-def _merge_config_into_pyproject(pyproject: PyprojectTOML) -> None:
+def _merge_config_into_pyproject(pyproject: ModifiablePyproject) -> None:
     config_path = "pyrightconfig.json"  # cspell:ignore pyrightconfig
     if not os.path.exists(config_path):
         return
@@ -32,10 +29,10 @@ def _merge_config_into_pyproject(pyproject: PyprojectTOML) -> None:
     tool_table.update(existing_config)
     os.remove(config_path)
     msg = f"Moved pyright configuration to {CONFIG_PATH.pyproject}"
-    pyproject.modifications.append(msg)
+    pyproject.append_to_changelog(msg)
 
 
-def _update_settings(pyproject: PyprojectTOML) -> None:
+def _update_settings(pyproject: ModifiablePyproject) -> None:
     table_key = "tool.pyright"
     if not pyproject.has_table(table_key):
         return
@@ -46,4 +43,4 @@ def _update_settings(pyproject: PyprojectTOML) -> None:
     if not complies_with_subset(pyright_settings, minimal_settings):
         pyright_settings.update(minimal_settings)
         msg = f"Updated pyright configuration in {CONFIG_PATH.pyproject}"
-        pyproject.modifications.append(msg)
+        pyproject.append_to_changelog(msg)

src/compwa_policy/check_dev_files/pytest.py

@@ -7,27 +7,24 @@
 import tomlkit
 from ini2toml.api import Translator
 
-from compwa_policy.errors import PrecommitError
 from compwa_policy.utilities import CONFIG_PATH
 from compwa_policy.utilities.cfg import open_config
 from compwa_policy.utilities.executor import Executor
-from compwa_policy.utilities.pyproject import PyprojectTOML
+from compwa_policy.utilities.pyproject import ModifiablePyproject
 from compwa_policy.utilities.toml import to_toml_array
 
 if TYPE_CHECKING:
     from tomlkit.items import Array
 
 
 def main() -> None:
-    pyproject = PyprojectTOML.load()
-    with Executor() as do:
+    with Executor() as do, ModifiablePyproject.load() as pyproject:
         do(_merge_coverage_into_pyproject, pyproject)
         do(_merge_pytest_into_pyproject, pyproject)
         do(_update_settings, pyproject)
-        do(pyproject.finalize)
 
 
-def _merge_coverage_into_pyproject(pyproject: PyprojectTOML) -> None:
+def _merge_coverage_into_pyproject(pyproject: ModifiablePyproject) -> None:
     if not CONFIG_PATH.pytest_ini.exists():
         return
     pytest_ini = open_config(CONFIG_PATH.pytest_ini)
@@ -43,10 +40,10 @@ def _merge_coverage_into_pyproject(pyproject: PyprojectTOML) -> None:
     tool_table = pyproject.get_table("tool.coverage.run", create=True)
     tool_table.update(coverage_config)
     msg = f"Merged Coverage.py configuration into {CONFIG_PATH.pyproject}"
-    pyproject.modifications.append(msg)
+    pyproject.append_to_changelog(msg)
 
 
-def _merge_pytest_into_pyproject(pyproject: PyprojectTOML) -> None:
+def _merge_pytest_into_pyproject(pyproject: ModifiablePyproject) -> None:
     if not CONFIG_PATH.pytest_ini.exists():
         return
     with open(CONFIG_PATH.pytest_ini) as stream:
@@ -58,10 +55,10 @@ def _merge_pytest_into_pyproject(pyproject: PyprojectTOML) -> None:
     tool_table.update(config)
     CONFIG_PATH.pytest_ini.unlink()
     msg = f"Moved pytest configuration to {CONFIG_PATH.pyproject}"
-    raise PrecommitError(msg)
+    pyproject.append_to_changelog(msg)
 
 
-def _update_settings(pyproject: PyprojectTOML) -> None:
+def _update_settings(pyproject: ModifiablePyproject) -> None:
     if not pyproject.has_table("tool.pytest.ini_options"):
         return
     config = pyproject.get_table("tool.pytest.ini_options")
@@ -70,7 +67,7 @@ def _update_settings(pyproject: PyprojectTOML) -> None:
     if isinstance(existing, str) or sorted(existing) != sorted(expected):
         config["addopts"] = expected
         msg = f"Updated tool.pytest.ini_options.addopts under {CONFIG_PATH.pyproject}"
-        pyproject.modifications.append(msg)
+        pyproject.append_to_changelog(msg)
 
 
 def __get_expected_addopts(existing: str | Array) -> Array:

src/compwa_policy/check_dev_files/pyupgrade.py

@@ -11,7 +11,7 @@
     update_precommit_hook,
     update_single_hook_precommit_repo,
 )
-from compwa_policy.utilities.pyproject import PyprojectTOML
+from compwa_policy.utilities.pyproject import Pyproject
 
 
 def main(no_ruff: bool) -> None:
@@ -53,7 +53,7 @@ def __get_pyupgrade_version_argument() -> CommentedSeq:
     >>> __get_pyupgrade_version_argument()
     ['--py37-plus']
     """
-    supported_python_versions = PyprojectTOML.load().get_supported_python_versions()
+    supported_python_versions = Pyproject.load().get_supported_python_versions()
     lowest_version = supported_python_versions[0]
     version_repr = lowest_version.replace(".", "")
     yaml = YAML(typ="rt")