feat: add YAML IO support and extend mixed-format config loading

This commit introduces YAML read and write helpers, expands load_config to support TOML, JSON, and YAML inputs, and updates the docs and tests accordingly.

Included in this update:

- add read_yaml and write_yaml file helpers

- add YAML-specific IO exceptions and the PyYAML dependency

- extend load_config to merge TOML, JSON, YAML, and YML files in order

- validate that loaded config roots are mappings before merging

- update the README, quickstart guide, and tool docs for YAML and mixed-format config loading

- replace the old static test runner with focused tool-level tests for config loading and YAML IO

Author: b7binw13

README.md

@@ -5,7 +5,7 @@
 ## What You Get
 
 - simple text and binary file helpers
-- JSON and TOML read/write helpers
+- JSON, TOML, and YAML read/write helpers
 - masking for tokens, secrets, IDs, and similar values
 - global configuration for shared error behavior
 - ready-to-use console and file logging
@@ -37,7 +37,7 @@ loaded = read_json("tmp/config.json")
 logger.info("Loaded config: %s", loaded)
 ```
 
-For split TOML setups, `load_config()` merges multiple files into one config object with dot access.
+For split configuration setups, `load_config()` merges multiple TOML, JSON, or YAML files into one config object with dot access.
 
 ## Public API Overview
 
@@ -55,6 +55,8 @@ For split TOML setups, `load_config()` merges multiple files into one config obj
 - `write_json`
 - `read_toml`
 - `write_toml`
+- `read_yaml`
+- `write_yaml`
 - `load_config`
 
 ### Logging helpers

docs/quickstart.md

@@ -26,12 +26,12 @@ loaded = read_json("tmp/config.json")
 logger.info("Loaded config: %s", loaded)
 ```
 
-If your TOML configuration is split across multiple files, `load_config()` merges it into one object:
+If your configuration is split across multiple TOML, JSON, or YAML files, `load_config()` merges it into one object:
 
 ```python
 from clevertools import load_config
 
-config = load_config("config/settings.toml", "config/content.toml")
+config = load_config("config/settings.toml", "config/content.yaml")
 print(config.pipelines.ai.enabled)
 ```
 

docs/tools/README.md

@@ -16,6 +16,8 @@ Each public helper has its own page with signature, behavior, and examples.
 - [write_json](./write_json.md)
 - [read_toml](./read_toml.md)
 - [write_toml](./write_toml.md)
+- [read_yaml](./read_yaml.md)
+- [write_yaml](./write_yaml.md)
 - [load_config](./load_config.md)
 
 ## Logging helpers

docs/tools/load_config.md

@@ -1,19 +1,21 @@
 # `load_config`
 
-`load_config()` reads multiple TOML files, merges overlapping sections, and returns one combined configuration object.
+`load_config()` reads multiple configuration files, merges overlapping sections, and returns one combined configuration object.
 
 ## Signature
 
 ```python
-load_config(*file_paths: str | Path)
+load_config(*file_paths: str | Path, on_error: ErrorMode | None = None)
 ```
 
 ## What it does
 
-- Reads each TOML file in the order you pass it in.
+- Reads each file in the order you pass it in.
+- Supports `.toml`, `.json`, `.yaml`, and `.yml`.
 - Merges nested tables recursively.
 - Combines shared sections such as `pipelines.ai` across multiple files.
 - Exposes the merged result through attribute access and dot-path lookups.
+- Applies the shared error policy when a file cannot be read or parsed.
 
 ## Returns
 
@@ -29,7 +31,11 @@ You can access values like this:
 ```python
 from clevertools import load_config
 
-config = load_config("config/settings.toml", "config/content.toml")
+config = load_config(
+    "config/settings.toml",
+    "config/content.json",
+    "config/content.yaml",
+)
 
 print(config.pipelines.ai.enabled)
 print(config.pipelines.ai.ai_model)
@@ -38,7 +44,8 @@ print(config.get("pipelines.publishing.default_post_status"))
 
 ## Notes
 
-- Nested TOML tables are merged recursively.
-- If the same non-table key exists in multiple files, the later file wins.
-- Missing files and TOML parse errors follow the shared error policy from `read_toml()`.
+- Nested mappings are merged recursively across supported file types.
+- If the same non-mapping key exists in multiple files, the later file wins.
+- Missing files and parse errors follow the shared error policy from the corresponding reader.
+- Each loaded document must have a mapping object at its root so it can be merged safely.
 - Use `as_dict()` when you need the merged result as a plain dictionary.

docs/tools/read_yaml.md

@@ -0,0 +1,26 @@
+# `read_yaml`
+
+`read_yaml()` reads a YAML file and deserializes it with `yaml.safe_load()`.
+
+## Signature
+
+```python
+read_yaml(
+    file_path: str | Path,
+    on_error: Literal["raise", "log", "silent"] | None = None,
+) -> Any | None
+```
+
+## Example
+
+```python
+from clevertools import read_yaml
+
+config = read_yaml("config.yaml")
+print(config["service"])
+```
+
+## Notes
+
+- Invalid YAML returns `None` unless the active error mode raises.
+- Missing files and directory paths are handled through the shared error policy.

docs/tools/write_yaml.md

@@ -0,0 +1,39 @@
+# `write_yaml`
+
+`write_yaml()` serializes a Python value to YAML and writes it to disk.
+
+## Signature
+
+```python
+write_yaml(
+    file_path: str | Path,
+    data: Any,
+    create_if_missing: bool = True,
+    allow_unicode: bool = True,
+    sort_keys: bool = False,
+    on_error: Literal["raise", "log", "silent"] | None = None,
+) -> None
+```
+
+## Example
+
+```python
+from clevertools import write_yaml
+
+write_yaml(
+    "config.yaml",
+    {
+        "service": "clevertools",
+        "enabled": True,
+        "labels": ["yaml", "config"],
+    },
+    allow_unicode=True,
+    sort_keys=False,
+)
+```
+
+## Notes
+
+- `data` must not be `None`.
+- With `create_if_missing=True`, parent folders are created automatically.
+- Serialization errors are handled through the shared error policy.

requirements.txt

@@ -5,4 +5,5 @@ mypy
 faker
 
 # === For tools to work === #
-tomli_w
+tomli_w
+pyyaml

src/clevertools/__init__.py

@@ -14,6 +14,7 @@
 from .file.default_io import read, write
 from .file.json_io import read_json, write_json
 from .file.toml_io import read_toml, write_toml
+from .file.yaml_io import read_yaml, write_yaml
 
 from .system.mask_handler import mask
 
@@ -31,6 +32,8 @@
     "write_json",
     "read_toml",
     "write_toml",
+    "read_yaml",
+    "write_yaml",
     "configure_logger",
     "get_logger",
     "CleverToolsFormatter",

src/clevertools/errors/exceptions.py

@@ -1110,9 +1110,22 @@ class InternalProtocolError(ExecutionError):
 
 class ExternalProtocolMismatchError(ProtocolError):
     """Raised when external protocol versions or formats mismatch."""
-    
+
+class YamlIOError(Exception):
+    """Base exception for YAML IO operations."""
+
+
+class YamlReadError(YamlIOError):
+    """Raised when reading YAML fails."""
+
+
+class YamlWriteError(YamlIOError):
+    """Raised when writing YAML fails."""
 
 __all__ = (
+    "YamlIOError",
+    "YamlReadError",
+    "YamlWriteError",
     "AppError",
     "RecoverableError",
     "FatalError",

src/clevertools/file/yaml_io.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+from pathlib import Path
+import yaml
+
+from ..errors.exceptions import YamlReadError, YamlWriteError
+from ..errors.policy import handle_error
+from ..configuration import ErrorMode
+
+
+def read_yaml(file_path: Path | str, on_error: Optional[ErrorMode] = None) -> Any | None:
+    """
+    Read and deserialize a YAML file.
+
+    Args:
+        file_path: Path to the YAML file that should be loaded.
+        on_error: Error handling mode. If omitted, the global default from
+            `configure()` is used.
+
+    Returns:
+        The parsed YAML value. Returns `None` when the file cannot be read or
+        parsed and the selected error mode does not raise.
+    """
+
+    path = Path(file_path)
+
+    if not path.exists():
+        return handle_error(FileNotFoundError(f"YAML file not found: {path}"), on_error=on_error, fallback=None)
+
+    if not path.is_file():
+        return handle_error(IsADirectoryError(f"YAML is not a file: {path}"), on_error=on_error, fallback=None)
+
+    try:
+        with path.open("r", encoding="utf-8") as file:
+            return yaml.safe_load(file)
+    except yaml.YAMLError as e:
+        return handle_error(YamlReadError(f"Invalid YAML format: {e}"), on_error=on_error, fallback=None)
+    except Exception as e:
+        return handle_error(YamlReadError(f"Failed to read YAML: {e}"), on_error=on_error, fallback=None)
+
+def write_yaml(
+    file_path: Path | str,
+    data: Any,
+    create_if_missing: Optional[bool] = True,
+    allow_unicode: bool = True,
+    sort_keys: bool = False,
+    on_error: ErrorMode | None = None,
+) -> None:
+    """
+    Serialize data as YAML and write it to a file.
+
+    Args:
+        file_path: Target file path.
+        data: YAML-serializable value to write.
+        create_if_missing: When `True`, missing parent directories are created
+            automatically. When `False`, the target file must already exist.
+        allow_unicode: Forwarded to `yaml.safe_dump()` to control whether
+            Unicode characters are emitted directly.
+        sort_keys: Forwarded to `yaml.safe_dump()` to control whether mapping
+            keys are sorted in the output.
+        on_error: Error handling mode. If omitted, the global default from
+            `configure()` is used.
+
+    Returns:
+        `None`. If serialization or writing fails, the outcome depends on the
+        selected error mode.
+    """
+
+    path = Path(file_path)
+
+    if data is None:
+        return handle_error(ValueError("YAML data must not be None."), on_error=on_error, fallback=None)
+
+    try:
+        if create_if_missing:
+            path.parent.mkdir(parents=True, exist_ok=True)
+        else:
+            if not path.exists():
+                return handle_error(FileNotFoundError(f"YAML file not found: {path}"), on_error=on_error, fallback=None)
+            
+            if not path.is_file():
+                return handle_error(IsADirectoryError(f"YAML is not a file: {path}"), on_error=on_error, fallback=None)
+
+        with path.open("w", encoding="utf-8") as file:
+            yaml.safe_dump(data, file, allow_unicode=allow_unicode, sort_keys=sort_keys)
+    except yaml.YAMLError as e:
+        return handle_error(YamlWriteError(f"Invalid YAML data: {e}"), on_error=on_error, fallback=None)
+    except Exception as e:
+        return handle_error(YamlWriteError(f"Failed to write YAML: {e}"), on_error=on_error, fallback=None)