io

src.utils.io

Safe JSON and YAML file I/O helpers.

All generators and enrichers should use these helpers instead of raw json.load / yaml.safe_load to get consistent error messages and graceful handling of missing or malformed files.

load_json(path: str | Path, *, default: Any = None) -> Any

Read and parse a JSON file.

Returns default (None) when the file is missing or unparseable, logging a warning in either case.

Source code in src/utils/io.py

def load_json(path: str | Path, *, default: Any = None) -> Any:
    """Read and parse a JSON file.

    Returns *default* (``None``) when the file is missing or unparseable,
    logging a warning in either case.
    """
    path = Path(path)
    try:
        with open(path, encoding="utf-8") as fh:
            return json.load(fh)
    except FileNotFoundError:
        logger.warning("File not found: %s", path)
        return default
    except (json.JSONDecodeError, OSError) as exc:
        logger.warning("Failed to read %s: %s", path, exc)
        return default

save_json(path: str | Path, data: Any, *, indent: int = 2) -> None

Write data as pretty-printed JSON, creating parent dirs as needed.

Source code in src/utils/io.py

def save_json(path: str | Path, data: Any, *, indent: int = 2) -> None:
    """Write *data* as pretty-printed JSON, creating parent dirs as needed."""
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, "w", encoding="utf-8") as fh:
        json.dump(data, fh, indent=indent, ensure_ascii=False)
        fh.write("\n")

load_yaml(path: str | Path, *, default: Any = None) -> Any

Read and parse a YAML file.

Returns default (None) when the file is missing or unparseable, logging a warning in either case.

Source code in src/utils/io.py

def load_yaml(path: str | Path, *, default: Any = None) -> Any:
    """Read and parse a YAML file.

    Returns *default* (``None``) when the file is missing or unparseable,
    logging a warning in either case.
    """
    path = Path(path)
    try:
        with open(path, encoding="utf-8") as fh:
            return yaml.safe_load(fh)
    except FileNotFoundError:
        logger.warning("File not found: %s", path)
        return default
    except (yaml.YAMLError, OSError) as exc:
        logger.warning("Failed to read %s: %s", path, exc)
        return default

save_yaml(path: str | Path, data: Any) -> None

Write data as YAML, creating parent dirs as needed.

Source code in src/utils/io.py

def save_yaml(path: str | Path, data: Any) -> None:
    """Write *data* as YAML, creating parent dirs as needed."""
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, "w", encoding="utf-8") as fh:
        yaml.dump(data, fh, default_flow_style=False, allow_unicode=True, sort_keys=False)