feat: add base config mixin class

Author: cuinixam

.claude/CLAUDE.md

@@ -0,0 +1,3 @@
+# Instructions for Using Agents in Claude
+
+The instructions for using agents in Claude can be found in the @AGENTS.md file in the project root directory.

AGENTS.md

@@ -148,15 +148,3 @@ pypeline run --step CreateVEnv --step PyTest --input python_version=3.13
    - `pypeline run` executes with **zero failures**
    - All pre-commit checks pass
    - New functionality has appropriate test coverage
-
-## Commit Message Format
-
-This repository uses [conventional commits](https://www.conventionalcommits.org). Format:
-
-```
-<type>(<scope>): <description>
-```
-
-Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
-
-Example: `feat(core): add async runnable support`

pyproject.toml

@@ -47,7 +47,7 @@ dev = [
 ]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 line-length = 180
 lint.select = [
   "B",   # flake8-bugbear

src/py_app_dev/core/config.py

@@ -1,8 +1,19 @@
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
 from typing import Any, TypeVar
 
 from mashumaro import DataClassDictMixin
 from mashumaro.config import BaseConfig
 
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+from mashumaro.mixins.json import DataClassJSONMixin
+
 
 class BaseConfigDictMixin(DataClassDictMixin):
     class Config(BaseConfig):
@@ -13,6 +24,38 @@ class Config(BaseConfig):
 TConfig = TypeVar("TConfig", bound="BaseConfigDictMixin")
 
 
+@dataclass
+class BaseConfigJsonMixin(DataClassJSONMixin):
+    """Shared mixin providing mashumaro config and JSON file I/O."""
+
+    class Config(BaseConfig):
+        omit_none = True
+
+    @classmethod
+    def from_json_file(cls, file_path: Path) -> Self:
+        return cls.from_dict(json.loads(file_path.read_text()))
+
+    @classmethod
+    def from_file(cls, file_path: Path) -> Self:
+        match file_path.suffix:
+            case ".json":
+                return cls.from_json_file(file_path)
+            case _:
+                raise ValueError(f"Unsupported format: {file_path.suffix}")
+
+    def to_json_string(self) -> str:
+        return json.dumps(self.to_dict(), indent=2)
+
+    def to_string(self) -> str:
+        return self.to_json_string()
+
+    def to_json_file(self, file_path: Path) -> None:
+        file_path.write_text(self.to_json_string())
+
+    def to_file(self, file_path: Path) -> None:
+        self.to_json_file(file_path)
+
+
 def deep_merge(base_dict: dict[Any, Any], new_dict: dict[Any, Any]) -> dict[Any, Any]:
     """Recursively merge two dictionaries, where values in new_dict override values in base_dict."""
     result: dict[Any, Any] = {}

src/py_app_dev/core/find.py

@@ -1,6 +1,7 @@
 """Utility functions for working with collections and type filtering."""
 
-from typing import Any, Callable, Optional, TypeVar
+from collections.abc import Callable
+from typing import Any, TypeVar
 
 T = TypeVar("T")
 
@@ -15,7 +16,7 @@ def filter_elements(elements: list[T], filter_fn: Callable[[T], bool]) -> list[T
     return [elem for elem in elements if filter_fn(elem)]
 
 
-def find_first_element_of_type(elements: list[Any], element_type: type[T], filter_fn: Optional[Callable[[T], bool]] = None) -> Optional[T]:
+def find_first_element_of_type(elements: list[Any], element_type: type[T], filter_fn: Callable[[T], bool] | None = None) -> T | None:
     """Find the first element of a specific type, optionally matching a filter condition."""
     filtered_elements = find_elements_of_type(elements, element_type)
     if filter_fn:

src/py_app_dev/core/scoop_wrapper.py

@@ -5,7 +5,7 @@
 from functools import cmp_to_key
 from pathlib import Path
 from tempfile import TemporaryDirectory
-from typing import Any, Optional
+from typing import Any
 
 from mashumaro import field_options
 from mashumaro.config import BaseConfig
@@ -70,14 +70,14 @@ def to_json_file(self, file_path: Path) -> None:
 class ScoopFileElement(BaseConfigJSONMixin):
     """Represents an app or bucket entry in the scoopfile.json."""
 
-    _name_lc: Optional[str] = field(default=None, metadata=field_options(alias="name"))
-    _name_uc: Optional[str] = field(default=None, metadata=field_options(alias="Name"))
+    _name_lc: str | None = field(default=None, metadata=field_options(alias="name"))
+    _name_uc: str | None = field(default=None, metadata=field_options(alias="Name"))
     #: Source bucket
-    _source_lc: Optional[str] = field(default=None, metadata=field_options(alias="source"))
-    _source_uc: Optional[str] = field(default=None, metadata=field_options(alias="Source"))
+    _source_lc: str | None = field(default=None, metadata=field_options(alias="source"))
+    _source_uc: str | None = field(default=None, metadata=field_options(alias="Source"))
 
-    _version_lc: Optional[str] = field(default=None, metadata=field_options(alias="version"))
-    _version_uc: Optional[str] = field(default=None, metadata=field_options(alias="Version"))
+    _version_lc: str | None = field(default=None, metadata=field_options(alias="version"))
+    _version_uc: str | None = field(default=None, metadata=field_options(alias="Version"))
 
     @property
     def name(self) -> str:
@@ -98,7 +98,7 @@ def source(self) -> str:
             raise UserNotificationException("ScoopApp must have a 'Source' or 'source' field defined.")
 
     @property
-    def version(self) -> Optional[str]:
+    def version(self) -> str | None:
         if self._version_uc:
             return self._version_uc
         elif self._version_lc:

tests/test_cmd_line.py

@@ -2,7 +2,6 @@
 from dataclasses import dataclass, field
 from enum import Enum, auto
 from pathlib import Path
-from typing import Optional, Union
 
 import pytest
 
@@ -74,7 +73,7 @@ def test_duplicate_commands():
 class MyConfigDataclass:
     my_first_arg: Path = field(metadata={"help": "Some help for arg1."})
     arg: str = field(default="value1", metadata={"help": "Some help for arg1."})
-    opt_arg: Optional[str] = field(default=None, metadata={"help": "Some help for arg1."})
+    opt_arg: str | None = field(default=None, metadata={"help": "Some help for arg1."})
     opt_arg_bool: bool | None = field(
         default=False,
         metadata={
@@ -85,14 +84,14 @@ class MyConfigDataclass:
 
 
 def test_is_type_optional():
-    assert is_type_optional(Optional[str])
+    assert is_type_optional(str | None)
     assert not is_type_optional(str)
-    assert is_type_optional(Union[Path | None, str])
+    assert is_type_optional((Path | str) | None)
     # Test modern union syntax (Python 3.10+)
     assert is_type_optional(Path | None)
     assert is_type_optional(str | None)
     assert not is_type_optional(Path | str)  # Union without None should not be optional
-    assert not is_type_optional(Union[Path, str])
+    assert not is_type_optional(Path | str)
 
 
 def test_register_arguments_for_config_dataclass():

tests/test_config.py

@@ -1,7 +1,16 @@
+import json
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
-from py_app_dev.core.config import BaseConfigDictMixin, deep_merge, merge_configs
+import pytest
+
+from py_app_dev.core.config import (
+    BaseConfigDictMixin,
+    BaseConfigJsonMixin,
+    deep_merge,
+    merge_configs,
+)
 
 
 @dataclass
@@ -47,3 +56,56 @@ def test_merge_configs_override_none_value():
     assert merged.name == "final", "Name should be taken from override"
     assert merged.nested == {"k": 1}, "Nested should not be overridden by None"
     assert merged.retries == 0, "Retries should be taken from the default value in override"
+
+
+# ---------- BaseConfigJsonMixin tests ----------
+
+
+@dataclass
+class SampleJsonConfig(BaseConfigJsonMixin):
+    name: str = ""
+    count: int = 0
+    label: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+def test_json_mixin_roundtrip_file(tmp_path: Path) -> None:
+    original = SampleJsonConfig(name="svc", count=3, metadata={"env": "prod"})
+    file = tmp_path / "config.json"
+
+    original.to_json_file(file)
+    restored = SampleJsonConfig.from_json_file(file)
+
+    assert restored == original
+
+
+def test_json_mixin_from_file_json(tmp_path: Path) -> None:
+    file = tmp_path / "config.json"
+    file.write_text(json.dumps({"name": "app", "count": 7}))
+
+    loaded = SampleJsonConfig.from_file(file)
+
+    assert loaded.name == "app"
+    assert loaded.count == 7
+
+
+def test_json_mixin_from_file_unsupported(tmp_path: Path) -> None:
+    file = tmp_path / "config.yaml"
+    file.write_text("name: oops")
+
+    with pytest.raises(ValueError, match=r"\.yaml"):
+        SampleJsonConfig.from_file(file)
+
+
+def test_json_mixin_omit_none() -> None:
+    cfg = SampleJsonConfig(name="x", label=None, metadata=None)
+    parsed = json.loads(cfg.to_json_string())
+
+    assert "label" not in parsed
+    assert "metadata" not in parsed
+
+
+def test_json_mixin_to_string() -> None:
+    cfg = SampleJsonConfig(name="a", count=1)
+
+    assert cfg.to_string() == cfg.to_json_string()