Function save_file

functions/function_calling/file.py:358–409

Persist data to a workspace file while optionally registering it as an attachment. Args: path: Relative path where the file will be written. content: Plain-text payload encoded with `encoding`. encoding: Text encoding used when `content` is provided. mode: W

(
    path: str,
    content: str,
    *,
    encoding: str = "utf-8",
    mode: Literal["overwrite", "append"] = "overwrite",
    _context: Dict[str, Any] | None = None,
)

def save_file(
    path: str,
    content: str,
    *,
    encoding: str = "utf-8",
    mode: Literal["overwrite", "append"] = "overwrite",
    _context: Dict[str, Any] | None = None,
) -> Dict[str, Any]:
    """
    Persist data to a workspace file while optionally registering it as an attachment.

    Args:
        path: Relative path where the file will be written.
        content: Plain-text payload encoded with `encoding`.
        encoding: Text encoding used when `content` is provided.
        mode: Whether to replace the file (`overwrite`) or append to it (`append`).

    Returns:
        A dictionary describing the persisted file, including workspace path, absolute path,
        and byte size.

    Raises:
        ValueError: If arguments are missing/invalid or the path escapes the workspace.
        OSError: If the file cannot be written.
    """

    if mode not in {"overwrite", "append"}:
        raise ValueError("mode must be either 'overwrite' or 'append'")

    ctx = FileToolContext(_context)
    target = ctx.resolve_under_workspace(path)
    if target.exists() and target.is_dir():
        raise ValueError("Target path points to a directory")
    target.parent.mkdir(parents=True, exist_ok=True)

    data = content.encode(encoding)

    write_mode = "wb" if mode == "overwrite" else "ab"
    try:
        with target.open(write_mode) as handle:
            handle.write(data)
    except OSError as exc:
        raise OSError(f"Failed to write file '{target}': {exc}") from exc

    size = target.stat().st_size if target.exists() else None
    return {
        "path": ctx.to_workspace_relative(target),
        "absolute_path": str(target),
        "size": size,
        # "mode": mode,
        # "encoding": encoding if content is not None else None,
    }


def read_text_file_snippet(