FileWriteToolkit

class FileWriteToolkit(BaseToolkit):

A toolkit for creating, writing, and modifying text in files.

This class provides cross-platform (macOS, Linux, Windows) support for writing to various file formats (Markdown, DOCX, PDF, and plaintext), replacing text in existing files, automatic backups, custom encoding, and enhanced formatting options for specialized formats.

init

def __init__(
    self,
    output_dir: str = './',
    timeout: Optional[float] = None,
    default_encoding: str = 'utf-8',
    backup_enabled: bool = True
):

Initialize the FileWriteToolkit.

Parameters:

  • output_dir (str): The default directory for output files. Defaults to the current working directory.
  • timeout (Optional[float]): The timeout for the toolkit. (default: :obj: None)
  • default_encoding (str): Default character encoding for text operations. (default: :obj: utf-8)
  • backup_enabled (bool): Whether to create backups of existing files before overwriting. (default: :obj: True)

_resolve_filepath

def _resolve_filepath(self, file_path: str):

Convert the given string path to a Path object.

If the provided path is not absolute, it is made relative to the default output directory. The filename part is sanitized to replace spaces and special characters with underscores, ensuring safe usage in downstream processing.

Parameters:

  • file_path (str): The file path to resolve.

Returns:

Path: A fully resolved (absolute) and sanitized Path object.

_write_text_file

def _write_text_file(
    self,
    file_path: Path,
    content: str,
    encoding: str = 'utf-8'
):

Write text content to a plaintext file.

Parameters:

  • file_path (Path): The target file path.
  • content (str): The text content to write.
  • encoding (str): Character encoding to use. (default: :obj: utf-8) (default: utf-8)

_create_backup

def _create_backup(self, file_path: Path):

Create a backup of the file if it exists and backup is enabled.

Parameters:

  • file_path (Path): Path to the file to backup.

_write_docx_file

def _write_docx_file(self, file_path: Path, content: str):

Write text content to a DOCX file with default formatting.

Parameters:

  • file_path (Path): The target file path.
  • content (str): The text content to write.

_write_pdf_file

def _write_pdf_file(
    self,
    file_path: Path,
    content: str,
    use_latex: bool = False
):

Write text content to a PDF file with default formatting.

Parameters:

  • file_path (Path): The target file path.
  • content (str): The text content to write.
  • use_latex (bool): Whether to use LaTeX for rendering. (requires LaTeX toolchain). If False, uses FPDF for simpler PDF generation. (default: :obj: False)

_write_csv_file

def _write_csv_file(
    self,
    file_path: Path,
    content: Union[str, List[List]],
    encoding: str = 'utf-8'
):

Write CSV content to a file.

Parameters:

  • file_path (Path): The target file path.
  • content (Union[str, List[List]]): The CSV content as a string or list of lists.
  • encoding (str): Character encoding to use. (default: :obj: utf-8) (default: utf-8)

_write_json_file

def _write_json_file(
    self,
    file_path: Path,
    content: str,
    encoding: str = 'utf-8'
):

Write JSON content to a file.

Parameters:

  • file_path (Path): The target file path.
  • content (str): The JSON content as a string.
  • encoding (str): Character encoding to use. (default: :obj: utf-8) (default: utf-8)

_write_yaml_file

def _write_yaml_file(
    self,
    file_path: Path,
    content: str,
    encoding: str = 'utf-8'
):

Write YAML content to a file.

Parameters:

  • file_path (Path): The target file path.
  • content (str): The YAML content as a string.
  • encoding (str): Character encoding to use. (default: :obj: utf-8) (default: utf-8)

_write_html_file

def _write_html_file(
    self,
    file_path: Path,
    content: str,
    encoding: str = 'utf-8'
):

Write text content to an HTML file.

Parameters:

  • file_path (Path): The target file path.
  • content (str): The HTML content to write.
  • encoding (str): Character encoding to use. (default: :obj: utf-8) (default: utf-8)

_write_markdown_file

def _write_markdown_file(
    self,
    file_path: Path,
    content: str,
    encoding: str = 'utf-8'
):

Write text content to a Markdown file.

Parameters:

  • file_path (Path): The target file path.
  • content (str): The Markdown content to write.
  • encoding (str): Character encoding to use. (default: :obj: utf-8) (default: utf-8)

write_to_file

def write_to_file(
    self,
    content: Union[str, List[List[str]]],
    filename: str,
    encoding: Optional[str] = None,
    use_latex: bool = False
):

Write the given content to a file.

If the file exists, it will be overwritten. Supports multiple formats: Markdown (.md, .markdown, default), Plaintext (.txt), CSV (.csv), DOC/DOCX (.doc, .docx), PDF (.pdf), JSON (.json), YAML (.yml, .yaml), and HTML (.html, .htm).

Parameters:

  • content (Union[str, List[List[str]]]): The content to write to the file. Content format varies by file type: - Text formats (txt, md, html, yaml): string - CSV: string or list of lists - JSON: string or serializable object
  • filename (str): The name or path of the file. If a relative path is supplied, it is resolved to self.output_dir.
  • encoding (Optional[str]): The character encoding to use. (default: :obj: None)
  • use_latex (bool): For PDF files, whether to use LaTeX rendering (True) or simple FPDF rendering (False). (default: :obj: False)

Returns:

str: A message indicating success or error details.

get_tools

def get_tools(self):

Returns:

List[FunctionTool]: A list of FunctionTool objects representing the available functions in this toolkit.

_sanitize_filename

def _sanitize_filename(self, filename: str):

Sanitize a filename by replacing any character that is not alphanumeric, a dot (.), hyphen (-), or underscore () with an underscore ().

Parameters:

  • filename (str): The original filename which may contain spaces or special characters.

Returns:

str: The sanitized filename with disallowed characters replaced by underscores.