# ---------------------------------------------------------------------------
# read / write  (read_from_file / write_to_file) -- local-only rewrite
# ---------------------------------------------------------------------------
def _write_to_file(contents, file_path, **kwargs):
    os.makedirs(os.path.dirname(file_path) or ".", exist_ok=True)
    with open(file_path, "w", encoding="utf-8") as f:
        f.write(str(contents))
    return file_path


def write_to_file(*, contents, file_path, **kwargs):
    """Overwrite ``file_path`` with ``contents`` (creating parent dirs)."""
    try:
        return _write_to_file(contents=contents, file_path=file_path, **kwargs)
    except Exception as e:
        print("WRITE ERROR:", e)
        raise RuntimeError(f"Failed writing: {file_path}")


def read_from_file(file_path=None, **kwargs):
    """Read and return the text contents of ``file_path``."""
    with open(file_path, "r", encoding="utf-8") as f:
        return f.read()
