orxtra v0.13.0 /tool.src.orxtra.tool._read_tools
Updated
On this page

Read tool constructors: read (line-numbered, preview/full-retrieval gated), list_dir (gitignore-aware), glob, grep (content/files_only/count modes), stat, and diff -- all path-contained via resolve_and_check.

#tool.src.orxtra.tool._read_tools

#tool.src.orxtra.tool._read_tools

File read tool constructors for the orxtra tool module.

#_extension_to_language

python
def _extension_to_language(ext: str) -> str | None

Map a file extension to a language name, or None if unknown.

#_is_binary

python
def _is_binary(path: Path) -> bool

Check if a file is binary by reading the first chunk.

Tries to decode as UTF-8. If that fails or null bytes are present, the file is considered binary.

#_path_error_to_tool_error

python
def _path_error_to_tool_error(exc: PathError) -> ToolError

Convert a PathError to a ToolError.

#_format_with_line_numbers

python
def _format_with_line_numbers(lines: list[str], start_lineno: int) -> str

Format lines with right-aligned cat -n style line numbers.

Args:

  • lines: Lines of text (without trailing newlines from splitlines).
  • start_lineno: The 1-based line number for the first line.

Returns:

  • Formatted string with {lineno}\t{content} per line.

#_resolve_path

python
def _resolve_path(raw_path: str, root: Path) -> Path

Resolve a path, converting PathError to ToolError.

#_read_text_file

python
def _read_text_file(resolved: Path) -> str

Read a text file, raising ToolError on failure.

#_require_file

python
def _require_file(resolved: Path, label: str) -> None

Raise ToolError if the path is not an existing file.

#_require_text_file

python
def _require_text_file(resolved: Path, label: str) -> None

Raise ToolError if the file is binary.

#_require_dir

python
def _require_dir(resolved: Path, label: str) -> None

Raise ToolError if the path is not a directory.

#_resolve_root

python
def _resolve_root(root: Path) -> Path

Resolve the root path.

Extracted to a non-async helper so ASYNC240 does not fire.

#_glob_within_root

python
def _glob_within_root(base: Path, pattern: str, root_resolved: Path) -> list[Path]

Glob for pattern and filter results to stay within root.

#make_read_tool

python
def make_read_tool(read_root: Path, preview_threshold: int, preview_lines: int, session_id: str='default', previewer: Any | None=None) -> Tool

Construct the read file tool.

Args:

  • read_root: Root directory for path containment.
  • preview_threshold: Byte threshold above which content is previewed.
  • preview_lines: Number of head/tail lines in a preview.
  • session_id: Identifier for the session using this tool.
  • previewer: Unused, reserved for future custom preview logic.

#_load_gitignore

python
def _load_gitignore(read_root: Path) -> pathspec.PathSpec | None

Load .gitignore patterns from the read root directory.

#_list_recursive

python
def _list_recursive(resolved: Path, pattern: str | None, gitignore: pathspec.PathSpec | None=None) -> list[tuple[str, str, str]]

Walk directory recursively, collecting entries.

#_list_immediate

python
def _list_immediate(resolved: Path, pattern: str | None, gitignore: pathspec.PathSpec | None=None) -> list[tuple[str, str, str]]

List immediate children of a directory.

#make_list_dir_tool

python
def make_list_dir_tool(read_root: Path) -> Tool

Construct the list directory tool.

Args:

  • read_root: Root directory for path containment.

#make_glob_tool

python
def make_glob_tool(read_root: Path) -> Tool

Construct the glob tool.

Args:

  • read_root: Root directory for path containment.

#_grep_compile

python
def _grep_compile(pattern: str, case_sensitive: bool) -> re.Pattern[str]

Compile a regex pattern, raising ToolError on invalid input.

#_grep_search_file

python
def _grep_search_file(file_lines: list[str], rel_path: str, compiled: re.Pattern[str], context_lines_count: int, mode: str) -> tuple[list[str], int, bool]

Search a single file for grep matches.

Returns:

  • Tuple of (output_lines, match_count, file_has_match).

#_grep_iter_files

python
def _grep_iter_files(search_path: Path, read_root: Path, include: str | None) -> list[tuple[Path, str]]

Walk directory tree and yield (filepath, rel_path) for searchable files.

Skips hidden dirs/files, binary files, and applies the include filter.

#_grep_format_results

python
def _grep_format_results(mode: str, output_lines: list[str], matched_files: list[str], total_match_count: int, max_results: int, hit_limit: bool, preview_threshold: int, preview_lines_count: int) -> str

Format grep results based on mode.

#make_grep_tool

python
def make_grep_tool(read_root: Path, preview_threshold: int, preview_lines: int) -> Tool

Construct the grep tool.

Args:

  • read_root: Root directory for path containment.
  • preview_threshold: Byte threshold above which output is previewed.
  • preview_lines: Number of head/tail lines in a preview.

#_stat_single

python
def _stat_single(path: Path, root: Path) -> dict[str, Any]

Collect stat information for a single path.

#make_stat_tool

python
def make_stat_tool(read_root: Path) -> Tool

Construct the stat tool.

Args:

  • read_root: Root directory for path containment.

#make_diff_tool

python
def make_diff_tool(read_root: Path) -> Tool

Construct the diff tool.

Args:

  • read_root: Root directory for path containment.
Search