Squashed 'packages/tools/' content from commit 78317b9c

git-subtree-dir: packages/tools
git-subtree-split: 78317b9c127f18bd040c1d77e3c0840cdc9a5b38

crewai_tools/tools/files_compressor_tool/README.md

@@ -0,0 +1,119 @@
+# 📦 FileCompressorTool
+
+The **FileCompressorTool** is a utility for compressing individual files or entire directories (including nested subdirectories) into different archive formats, such as `.zip` or `.tar` (including `.tar.gz`, `.tar.bz2`, and `.tar.xz`). This tool is useful for archiving logs, documents, datasets, or backups in a compact format, and ensures flexibility in how the archives are created.
+
+---
+
+## Description
+
+This tool:
+- Accepts a **file or directory** as input.
+- Supports **recursive compression** of subdirectories.
+- Lets you define a **custom output archive path** or defaults to the current directory.
+- Handles **overwrite protection** to avoid unintentional data loss.
+- Supports multiple compression formats: `.zip`, `.tar`, `.tar.gz`, `.tar.bz2`, and `.tar.xz`.
+
+---
+
+## Arguments
+
+| Argument      | Type      | Required | Description                                                                 |
+|---------------|-----------|----------|-----------------------------------------------------------------------------|
+| `input_path`  | `str`     | ✅       | Path to the file or directory you want to compress.                         |
+| `output_path` | `str`     | ❌       | Optional path for the resulting archive file. Defaults to `./<name>.<format>`. |
+| `overwrite`   | `bool`    | ❌       | Whether to overwrite an existing archive file. Defaults to `False`.         |
+| `format`      | `str`     | ❌       | Compression format to use. Can be one of `zip`, `tar`, `tar.gz`, `tar.bz2`, `tar.xz`. Defaults to `zip`. |
+
+---
+
+
+## Usage Example
+
+```python
+from crewai_tools import FileCompressorTool
+
+# Initialize the tool
+tool = FileCompressorTool()
+
+# Compress a directory with subdirectories and files into a zip archive
+result = tool._run(
+    input_path="./data/project_docs",           # Folder containing subfolders & files
+    output_path="./output/project_docs.zip",    # Optional output path (defaults to zip format)
+    overwrite=True                              # Allow overwriting if file exists
+)
+print(result)
+# Example output: Successfully compressed './data/project_docs' into './output/project_docs.zip'
+
+```
+
+---
+
+## Example Scenarios
+
+### Compress a single file into a zip archive:
+```python
+# Compress a single file into a zip archive
+result = tool._run(input_path="report.pdf")
+# Example output: Successfully compressed 'report.pdf' into './report.zip'
+```
+
+### Compress a directory with nested folders into a zip archive:
+```python
+# Compress a directory containing nested subdirectories and files
+result = tool._run(input_path="./my_data", overwrite=True)
+# Example output: Successfully compressed 'my_data' into './my_data.zip'
+```
+
+### Use a custom output path with a zip archive:
+```python
+# Compress a directory and specify a custom zip output location
+result = tool._run(input_path="./my_data", output_path="./backups/my_data_backup.zip", overwrite=True)
+# Example output: Successfully compressed 'my_data' into './backups/my_data_backup.zip'
+```
+
+### Prevent overwriting an existing zip file:
+```python
+# Try to compress a directory without overwriting an existing zip file
+result = tool._run(input_path="./my_data", output_path="./backups/my_data_backup.zip", overwrite=False)
+# Example output: Output zip './backups/my_data_backup.zip' already exists and overwrite is set to False.
+```
+
+### Compress into a tar archive:
+```python
+# Compress a directory into a tar archive
+result = tool._run(input_path="./my_data", format="tar", overwrite=True)
+# Example output: Successfully compressed 'my_data' into './my_data.tar'
+```
+
+### Compress into a tar.gz archive:
+```python
+# Compress a directory into a tar.gz archive
+result = tool._run(input_path="./my_data", format="tar.gz", overwrite=True)
+# Example output: Successfully compressed 'my_data' into './my_data.tar.gz'
+```
+
+### Compress into a tar.bz2 archive:
+```python
+# Compress a directory into a tar.bz2 archive
+result = tool._run(input_path="./my_data", format="tar.bz2", overwrite=True)
+# Example output: Successfully compressed 'my_data' into './my_data.tar.bz2'
+```
+
+### Compress into a tar.xz archive:
+```python
+# Compress a directory into a tar.xz archive
+result = tool._run(input_path="./my_data", format="tar.xz", overwrite=True)
+# Example output: Successfully compressed 'my_data' into './my_data.tar.xz'
+```
+
+---
+
+## Error Handling and Validations
+
+- **File Extension Validation**: The tool ensures that the output file extension matches the selected format (e.g., `.zip` for `zip` format, `.tar` for `tar` format, etc.).
+- **File/Directory Existence**: If the input path does not exist, an error message will be returned.
+- **Overwrite Protection**: If a file already exists at the output path, the tool checks the `overwrite` flag before proceeding. If `overwrite=False`, it prevents overwriting the existing file.
+
+---
+
+This tool provides a flexible and robust way to handle file and directory compression across multiple formats for efficient storage and backups.