calute.tools.coding_tools

calute.tools.coding_tools#

Comprehensive coding tools for file management, git operations, and code manipulation.

This module provides a suite of tools for file system operations, git version control, and code analysis. It includes functions for reading, writing, copying, and deleting files, as well as git operations like status, diff, log, and patch management. Additionally, it offers code structure analysis capabilities for multiple programming languages.

calute.tools.coding_tools.analyze_code_structure(file_path: str, context_variables: dict | None = None) → str[source]#

Analyze the structure of a code file.

Performs static analysis on a source code file to extract structural information including imports, classes, functions, and code metrics.

Parameters

  • file_path – Path to the code file to analyze.

  • context_variables – Optional context dictionary for tool execution.

Returns

A formatted analysis report showing the file’s structure including language detection, line counts, imports, classes, and functions, or an error message if the file cannot be analyzed.

Example

>>> analysis = analyze_code_structure("src/main.py")
>>> print(analysis)
Code Structure Analysis: main.py
Language: Python
Total Lines: 150
Blank Lines: 20
Comment Lines: 15
Code Lines: 115
Imports (5):

  • import os

  • from typing import Dict

Classes (2):

  • MyClass

  • AnotherClass

Functions (8):

  • main

  • helper_function

calute.tools.coding_tools.apply_diff(original: str, diff: str, context_variables: dict | None = None) → str[source]#

Apply a unified diff to original content.

Parses a unified diff and applies the changes to the original content to produce the modified result.

Parameters

  • original – The original text content to modify.

  • diff – The unified diff to apply.

  • context_variables – Optional context dictionary for tool execution.

Returns

The modified content after applying the diff, or an error message if the diff cannot be applied.

Example

>>> original = "line1\nline2\nline3"
>>> diff = '''--- a/file.txt
... +++ b/file.txt
... @@ -1,3 +1,3 @@
...  line1
... -line2
... +modified
...  line3'''
>>> result = apply_diff(original, diff)
>>> print(result)
line1
modified
line3
calute.tools.coding_tools.copy_file(source: str, destination: str, overwrite: bool = False, context_variables: dict | None = None) → str[source]#

Copy a file or directory to a new location.

Copies a file or directory from the source path to the destination path. Supports both file and directory copying with optional overwrite behavior.

Parameters

  • source – Path to the source file or directory.

  • destination – Path to the destination location.

  • overwrite – Whether to overwrite existing files at the destination.

  • context_variables – Optional context dictionary for tool execution.

Returns

A success message confirming the copy, or an error message if the operation fails.

Example

>>> result = copy_file("config.yaml", "backup/config.yaml")
>>> print(result)
Successfully copied file config.yaml to backup/config.yaml
calute.tools.coding_tools.create_diff(original: str, modified: str, file_name: str = 'file.txt', context_variables: dict | None = None) → str[source]#

Create a unified diff between two text contents.

Generates a unified diff format showing the differences between the original and modified content.

Parameters

  • original – The original text content.

  • modified – The modified text content.

  • file_name – Name to use in the diff header.

  • context_variables – Optional context dictionary for tool execution.

Returns

A unified diff string showing the differences.

Example

>>> original = "line1\nline2\nline3"
>>> modified = "line1\nmodified\nline3"
>>> diff = create_diff(original, modified, "example.txt")
>>> print(diff)
--- a/example.txt
+++ b/example.txt
@@ -1,3 +1,3 @@
 line1
-line2
+modified
 line3
calute.tools.coding_tools.delete_file(path: str, force: bool = False, context_variables: dict | None = None) → str[source]#

Delete a file or directory.

Removes a file or directory from the filesystem. For directories with many items, the force flag must be set to confirm the deletion.

Parameters

  • path – Path to the file or directory to delete.

  • force – Force deletion of directories with more than 10 items.

  • context_variables – Optional context dictionary for tool execution.

Returns

A success message confirming the deletion, or an error message if the operation fails or requires confirmation.

Example

>>> result = delete_file("temp.txt")
>>> print(result)
Successfully deleted file: temp.txt
calute.tools.coding_tools.find_and_replace(file_path: str, search: str, replace: str, regex: bool = False, case_sensitive: bool = True, backup: bool = True, context_variables: dict | None = None) → str[source]#

Find and replace text in a file.

Searches for occurrences of a pattern in a file and replaces them with the specified replacement text. Supports both literal and regex-based search patterns.

Parameters

  • file_path – Path to the file to modify.

  • search – Text or regex pattern to search for.

  • replace – Replacement text.

  • regex – Whether to interpret search as a regular expression.

  • case_sensitive – Whether the search should be case-sensitive.

  • backup – Whether to create a backup file before modifying.

  • context_variables – Optional context dictionary for tool execution.

Returns

A success message with the count of replacements made, or an error message if the operation fails.

Example

>>> result = find_and_replace("config.py", "DEBUG=True", "DEBUG=False")
>>> print(result)
Replaced 1 occurrence(s) in config.py (backup saved as config.py.bak)
calute.tools.coding_tools.git_add(files: list[str], repo_path: str = '.', context_variables: dict | None = None) → str[source]#

Stage files for commit.

Adds the specified files to the git staging area in preparation for a commit.

Parameters

  • files – List of file paths to stage for commit.

  • repo_path – Path to the git repository. Defaults to current directory.

  • context_variables – Optional context dictionary for tool execution.

Returns

A success message with the count of staged files, or an error message if the operation fails.

Example

>>> result = git_add(["src/main.py", "README.md"])
>>> print(result)
Successfully staged 2 file(s)
calute.tools.coding_tools.git_apply_patch(patch_content: str, repo_path: str = '.', check_only: bool = False, context_variables: dict | None = None) → str[source]#

Apply a git patch to the repository.

Applies a unified diff patch to the repository. Can optionally check if the patch applies cleanly without actually applying it.

Parameters

  • patch_content – The unified diff patch content to apply.

  • repo_path – Path to the git repository. Defaults to current directory.

  • check_only – If True, only verify the patch applies without applying.

  • context_variables – Optional context dictionary for tool execution.

Returns

A success message if the patch is applied or validated, or an error message if the patch cannot be applied.

Example

>>> patch = '''--- a/file.txt
... +++ b/file.txt
... @@ -1 +1 @@
... -old line
... +new line'''
>>> result = git_apply_patch(patch, check_only=True)
>>> print(result)
Patch can be applied cleanly
calute.tools.coding_tools.git_diff(repo_path: str = '.', file_path: str | None = None, staged: bool = False, context_lines: int = 3, context_variables: dict | None = None) → str[source]#

Get the git diff showing changes in the repository.

Retrieves a unified diff of changes in the working directory or staging area. Can be filtered to a specific file.

Parameters

  • repo_path – Path to the git repository. Defaults to current directory.

  • file_path – Specific file to show diff for. None shows all changes.

  • staged – Whether to show staged changes instead of unstaged.

  • context_lines – Number of context lines to include around changes.

  • context_variables – Optional context dictionary for tool execution.

Returns

The unified diff output showing changes, or “No changes detected” if there are no modifications.

Example

>>> diff = git_diff(".", file_path="src/main.py", staged=True)
>>> print(diff)
--- a/src/main.py
+++ b/src/main.py
@@ -1,3 +1,4 @@
 import os
+import sys
calute.tools.coding_tools.git_log(repo_path: str = '.', max_commits: int = 10, oneline: bool = True, file_path: str | None = None, context_variables: dict | None = None) → str[source]#

Get the git commit history.

Retrieves the commit log for the repository. Can be filtered to show only commits affecting a specific file.

Parameters

  • repo_path – Path to the git repository. Defaults to current directory.

  • max_commits – Maximum number of commits to display.

  • oneline – Whether to use compact one-line format per commit.

  • file_path – Specific file to show commit history for.

  • context_variables – Optional context dictionary for tool execution.

Returns

The commit log output, or an error message if the repository is not accessible.

Example

>>> log = git_log(".", max_commits=5)
>>> print(log)
abc1234 Add new feature
def5678 Fix bug in parser
ghi9012 Update documentation
calute.tools.coding_tools.git_status(repo_path: str = '.', context_variables: dict | None = None) → str[source]#

Get the current status of a git repository.

Retrieves the git status including branch information and file modifications (staged, unstaged, untracked, etc.).

Parameters

  • repo_path – Path to the git repository. Defaults to current directory.

  • context_variables – Optional context dictionary for tool execution.

Returns

A formatted status output showing branch and file states, or an error message if the repository is not accessible.

Example

>>> status = git_status(".")
>>> print(status)
Branch: main
  Modified (unstaged): src/main.py
  Untracked: new_file.txt
calute.tools.coding_tools.list_directory(directory: str = '.', pattern: str = '*', recursive: bool = False, show_hidden: bool = False, max_depth: int = 3, context_variables: dict | None = None) → str[source]#

List files and directories with filtering options.

Lists the contents of a directory with support for glob pattern filtering, recursive traversal, and hidden file visibility control.

Parameters

  • directory – Directory path to list. Defaults to current directory.

  • pattern – Glob pattern for filtering files (e.g., ‘.py’, ‘.txt’).

  • recursive – Whether to list contents recursively.

  • show_hidden – Whether to include hidden files (starting with ‘.’).

  • max_depth – Maximum depth for recursive listing.

  • context_variables – Optional context dictionary for tool execution.

Returns

A formatted directory listing with file sizes, or an error message if the directory cannot be accessed.

Example

>>> listing = list_directory("src", pattern="*.py", recursive=True)
>>> print(listing)
Directory listing for: /path/to/src
Pattern: *.py | Recursive: True | Hidden: False
------------------------------------------------------------
📄 main.py (1.2KB)
📁 utils/
  📄 utils/helpers.py (0.5KB)
calute.tools.coding_tools.move_file(source: str, destination: str, overwrite: bool = False, context_variables: dict | None = None) → str[source]#

Move a file or directory to a new location.

Moves a file or directory from the source path to the destination path. This effectively renames or relocates the item.

Parameters

  • source – Path to the source file or directory.

  • destination – Path to the destination location.

  • overwrite – Whether to overwrite existing files at the destination.

  • context_variables – Optional context dictionary for tool execution.

Returns

A success message confirming the move, or an error message if the operation fails.

Example

>>> result = move_file("old_name.py", "new_name.py")
>>> print(result)
Successfully moved old_name.py to new_name.py
calute.tools.coding_tools.read_file(file_path: str, start_line: int = 1, end_line: int | None = None, context_variables: dict | None = None) → str[source]#

Read a file or specific lines from a file.

Reads the contents of a file and returns it with line numbers. Supports reading a specific range of lines for large files.

Parameters

  • file_path – Path to the file to read.

  • start_line – Starting line number (1-based indexing).

  • end_line – Ending line number (inclusive). None reads to end of file.

  • context_variables – Optional context dictionary for tool execution.

Returns

The file content with line numbers, or an error message if the file cannot be read.

Example

>>> content = read_file("example.py", start_line=1, end_line=10)
>>> print(content)
     1 | import os
     2 | import sys
calute.tools.coding_tools.write_file(file_path: str, content: str, create_dirs: bool = True, context_variables: dict | None = None) → str[source]#

Write content to a file, creating directories if needed.

Writes the specified content to a file at the given path. Can optionally create parent directories if they don’t exist.

Parameters

  • file_path – Path to the file to write.

  • content – Content to write to the file.

  • create_dirs – Whether to create parent directories if they don’t exist.

  • context_variables – Optional context dictionary for tool execution.

Returns

A success message with the number of characters and lines written, or an error message if the write fails.

Example

>>> result = write_file("output.txt", "Hello, World!")
>>> print(result)
Successfully wrote 13 characters (1 lines) to output.txt
Contents