toolregistry.hub.file_ops module

file_ops.py - Atomic file operations toolkit for LLM agents

Key features: - All methods are static for stateless usage - Atomic writes with automatic backups - Unified error handling - Diff/patch and git conflict support - Structured data parsing

class toolregistry.hub.file_ops.FileOps

Bases: object

Core file operations toolkit designed for LLM agent integration.

Handles file reading, atomic writing, appending, searching, and diff-based modifications.

static replace_by_diff(path: str, diff: str) → None

Apply unified diff format changes atomically to a file.

Parameters:

• path – The file path to modify.

• diff – Unified diff text (must use standard format with —/+++ headers and @@ hunk markers).

Example diff text:

— a/original_file +++ b/modified_file @@ -1,3 +1,3 @@ -line2 +line2 modified

Raises:

ValueError – On invalid diff format or patch failure

static search_files(path: str, regex: str, file_pattern: str = '*') → List[dict]

Perform regex search across files in a directory, returning matches with context.

Parameters:

• path – The directory path to search recursively.

• regex – The regex pattern to search for.

• file_pattern – Glob pattern to filter files (default=’*’).

Returns:

• file: file path

• line_num: line number of match (1-based)

• line: matched line content

• context: list of context lines (tuples of line_num, line content)

Return type:

List of dicts with keys

static replace_by_git(path: str, diff: str) → None

Apply git conflict style diff atomically to a file, replacing conflicted sections.

Parameters:

• path – File path to modify.

• diff – Git conflict style diff text (using <<<<<<< SEARCH, =======, >>>>>>> REPLACE markers).

Example diff text:

<<<<<<< SEARCH line2 ======= line2 modified >>>>>>> REPLACE

Raises:

ValueError – On invalid diff format or patch failure

static read_file(path: str) → str

Read text file content.

Parameters:

path – File path to read

Returns:

File content as string

Raises:

• FileNotFoundError – If path doesn’t exist

• UnicodeError – On encoding failures

static write_file(path: str, content: str) → None

Atomically write content to a text file (overwrite). Creates the file if it doesn’t exist.

Parameters:

• path – Destination file path

• content – Content to write

static append_file(path: str, content: str) → None

Append content to a text file. Creates the file if it doesn’t exist.

Parameters:

• path – Destination file path

• content – Content to append

static make_diff(ours: str, theirs: str) → str

Generate unified diff text between two strings.

Parameters:

• ours – The ‘ours’ version string.

• theirs – The ‘theirs’ version string.

Note

Intended for comparison/visualization, not direct modification. not for direct text modification tasks.

Returns:

Unified diff text

static make_git_conflict(ours: str, theirs: str) → str

Generate git merge conflict marker text between two strings.

Parameters:

• ours – The ‘ours’ version string.

• theirs – The ‘theirs’ version string.

Note

Intended for comparison/visualization, not direct modification. not for direct text modification tasks.

Returns:

Text with conflict markers

static validate_path(path: str) → Dict[str, bool | str]

Validate file path safety (checks for empty paths, dangerous characters).

Parameters:

path – The path string to validate.

Returns:

• valid (bool): Path safety status

• message (str): Description if invalid

Return type:

Dictionary with keys