Text2File

A powerful utility to generate test files in various formats from text content. Perfect for testing, development, and automation tasks.

Table of Contents

• Features
• Installation
  • Using pip (recommended)
  • From source
• Usage
  • Basic Syntax
  • Available Commands
  • Examples
• File Format Examples
  • Text Files
  • Code Files
  • Documents
  • Spreadsheets
  • Images
  • Archives
• API Reference
• Development
• Contributing
• License

Features

• 🚀 Generate files in multiple formats with a single command
• 📄 Support for various file types:
  • Text: .txt, .md, .html, .css, .js, .py, .json, .csv
  • Documents: .pdf, .docx, .odt
  • Spreadsheets: .xlsx (Excel)
  • Images: .jpg, .jpeg, .png, .bmp, .gif, .svg
  • Videos: .mp4, .avi, .mov (basic support)
  • Archives: .zip, .tar, .tar.gz, .tgz
• ✅ File validation to ensure generated files are not corrupted
• 🔄 Clean up invalid files with a single command
• 📂 Customizable output directory and filename prefix
• 🔍 Recursive directory scanning for validation and cleanup
• 🛠️ Extensible architecture for adding new file formats
• 🧪 Built-in testing and validation

Installation

Using pip (recommended)

pip install text2file

From source

1. Clone the repository:

   git clone https://github.com/veridock/text2file.git
   cd text2file
   

2. Install with Poetry (recommended):

   poetry install
   

   Or with pip:

   pip install .
   

Usage

Basic Syntax

text2file [COMMAND] [OPTIONS]

Available Commands

• generate - Generate files in various formats
• generate-set - Generate a set of images from a JSON configuration
• validate - Validate generated files
• cleanup - Clean up invalid files
• --version - Show version and exit
• --help - Show help message and exit

Examples

Generate a text file

# Short syntax
text2file "Hello, World!" txt

# Long syntax
text2file generate --content "Hello, World!" --extension txt

# Specify output directory and filename prefix
text2file generate --content "Hello, World!" --extension txt --output-dir ./output --prefix myfile

List all supported file formats

text2file list

Generate a video file

# Generate a basic video with text overlay
text2file generate --content "Sample video content" --extension mp4

# Generate a video with custom duration and resolution
text2file generate --content "Custom video" --extension mp4 --duration 10 --resolution 1280x720

# Generate a video with custom colors and font size
text2file generate --content "Styled Video" --extension mp4 --bg-color "#000000" --text-color "#ffffff" --font-size 48

# Generate a video with a specific output path
text2file generate --content "Saved Video" --extension mp4 -o ./videos/custom_output.mp4

Video generation supports the following formats:

• .mp4 - MPEG-4 video (most widely supported)
• .avi - Audio Video Interleave
• .mov - QuickTime Movie
• .mkv - Matroska Video

Video Generation Options

Option	Description	Default
--duration	Duration of the video in seconds	5
--fps	Frames per second	24
--resolution	Video resolution (WxH)	1280x720
--bg-color	Background color (name or hex)	"black"
--text-color	Text color (name or hex)	"white"
--font-size	Font size in pixels	40
-o, --output	Output file path	auto-generated

Example: Create a YouTube Short

text2file generate \
  --content "Check out our new feature!" \
  --extension mp4 \
  --duration 15 \
  --resolution 1080x1920 \
  --bg-color "#1a1a1a" \
  --text-color "#ff6b6b" \
  --font-size 64 \
  -o my_youtube_short.mp4

Dependencies

Video generation requires the following Python packages which are automatically installed with pip install text2file:

• opencv-python
• numpy
• pillow
• moviepy

Note: For best performance, it's recommended to have ffmpeg installed on your system, though it's not strictly required as moviepy will use a fallback if needed.

Advanced Image Generation

Generate a set of images from a JSON configuration

Create a JSON file (e.g., icons.json) with the following format:

{
  "icons": [
    {"src": "icon-16x16.png", "sizes": "16x16"},
    {"src": "icon-32x32.png", "sizes": "32x32"},
    {"src": "icon-64x64.png", "sizes": "64x64"}
  ]
}

Then run:

# Generate placeholder images with default text
text2file generate-set icons.json

# Use a base image and resize it
text2file generate-set icons.json --base-image source-icon.png

# Customize the placeholder appearance
text2file generate-set icons.json --text "My App" --background-color "#f0f0f0" --text-color "#333333"

# Generate SVG images with custom content
text2file generate --content "<svg><circle cx='50' cy='50' r='40' fill='blue'/></svg>" --extension svg

Options:

• -o, --output-dir: Output directory (default: current directory)
• -b, --base-image: Base image to use for resizing (optional)
• --bg, --background-color: Background color for placeholders (default: "#ffffff")
• -t, --text: Text to render on placeholder images
• --fg, --text-color: Text color for placeholders (default: "#000000")

Create a JSON file (e.g., icons.json) with the following format:

{
  "icons": [
    {"src": "icon-16x16.png", "sizes": "16x16"},
    {"src": "icon-32x32.png", "sizes": "32x32"},
    {"src": "icon-64x64.png", "sizes": "64x64"}
  ]
}

Then run:

# Generate placeholder images with default text
text2file generate-set icons.json

# Use a base image and resize it
text2file generate-set icons.json --base-image source-icon.png

# Customize the placeholder appearance
text2file generate-set icons.json --text "My App" --background-color "#f0f0f0" --text-color "#333333"

Options:

• -o, --output-dir: Output directory (default: current directory)
• -b, --base-image: Base image to use for resizing (optional)
• --bg, --background-color: Background color for placeholders (default: "#ffffff")
• -t, --text: Text to render on placeholder images
• --fg, --text-color: Text color for placeholders (default: "#000000")

Generate an Excel (.xlsx) file

Generate Excel spreadsheets with support for:

• Multiple worksheets
• Auto-adjusted column widths
• Custom sheet names
• CSV-like data input

# Basic usage with CSV-like content
content="Name,Age,City\nJohn,30,New York\nAlice,25,London"
text2file generate --content "$content" --extension xlsx

# Custom sheet name
text2file generate --content "$content" --extension xlsx --sheet-name "Users"

# Disable auto-adjust column widths
text2file generate --content "$content" --extension xlsx --no-auto-adjust

Options:

• --sheet-name: Custom worksheet name (default: "Sheet1")
• --no-auto-adjust: Disable auto-adjustment of column widths (enabled by default)

The input content should be in CSV format where:

• Rows are separated by newlines (\n)
• Cells within a row are separated by commas (,)
• The first row is treated as headers if present

Example with multiple data types:

content="Name,Age,Salary,HireDate\nJohn Doe,35,75000,2020-05-15\nJane Smith,28,85000,2021-03-22"
text2file generate --content "$content" --extension xlsx --sheet-name "Employees"

This will create an Excel file with properly formatted cells, including:

• Text alignment
• Number formatting
• Date recognition
• Auto-adjusted column widths

For more complex spreadsheets, you can generate the XLSX file programmatically using the Python API:

from text2file import generate_file

# Generate with custom options
generate_file(
    content="Product,Price,Stock\nLaptop,999,15\nMouse,25,100",
    extension="xlsx",
    output_dir="./reports",
    prefix="inventory",
    sheet_name="Products",
    auto_adjust=True
)

Basic Excel file from CSV-like content

content="Name,Age,City\nJohn,30,New York\nAlice,25,London" text2file generate --content "$content" --extension xlsx

With custom sheet name

text2file generate --content "$content" --extension xlsx --sheet_name "Employees"

Disable auto-adjusting column widths

text2file generate --content "$content" --extension xlsx --no-auto-adjust

### Generate multiple files with different formats
```bash
text2file generate --content "Sample content" --extension txt,md,html,xlsx --output-dir ./output

Validate generated files

text2file validate --path ./output --recursive --verbose

Clean up invalid files

text2file cleanup --path ./output --recursive --dry-run

File Format Examples

Text Files

Plain Text (.txt)

text2file generate --content "This is a plain text file" --extension txt

Markdown (.md)

content="# Sample Markdown\n\n- Item 1\n- Item 2\n- Item 3"
text2file generate --content "$content" --extension md

Code Files

Python (.py)

content="def hello_world():\n    print('Hello, World!')\n\nif __name__ == '__main__':\n    hello_world()"
text2file generate --content "$content" --extension py

JavaScript (.js)

content="function helloWorld() {\n  console.log('Hello, World!');\n}\n\nhelloWorld();"
text2file generate --content "$content" --extension js

Documents

PDF (.pdf)

text2file generate --content "This is a sample PDF document" --extension pdf

Word Document (.docx)

text2file generate --content "This is a sample Word document" --extension docx

Spreadsheets

Excel (.xlsx)

content="Name,Age,City\nJohn,30,New York\nAlice,25,London"
text2file generate --content "$content" --extension xlsx

Image Sets

Generate multiple images from a JSON configuration file. This is useful for creating icon sets or multiple resolutions of the same image.

JSON Configuration Format

Create a file (e.g., icons.json) with the following structure:

{
  "icons": [
    {
      "src": "icon-16x16.png",
      "sizes": "16x16"
    },
    {
      "src": "icon-32x32.png",
      "sizes": "32x32"
    },
    {
      "src": "subdir/icon-64x64.png",
      "sizes": "64x64"
    }
  ]
}

Each entry in the icons array should have:

• src: Output file path (relative to output directory)
• sizes: Dimensions in format "WIDTHxHEIGHT" (e.g., "32x32")

Usage Examples

# Generate placeholder images with default text
text2file generate-set icons.json

# Use a base image and resize it
text2file generate-set icons.json --base-image source-icon.png

# Customize the placeholder appearance
text2file generate-set icons.json --text "My App" --background-color "#f0f0f0" --text-color "#333333"

# Specify output directory
text2file generate-set icons.json --output-dir ./output

Options

• -o, --output-dir: Output directory (default: current directory)
• -b, --base-image: Base image to use for resizing (optional)
• --bg, --background-color: Background color for placeholders (default: "#ffffff")
• -t, --text: Text to render on placeholder images
• --fg, --text-color: Text color for placeholders (default: "#000000")

Single Images

JPEG (.jpg, .jpeg)

text2file generate --content "Sample image content" --extension jpg --width 800 --height 600

PNG (.png)

text2file generate --content "Sample image content" --extension png --width 800 --height 600

SVG Image (.svg)

text2file generate --content "Sample SVG" --extension svg

# With custom dimensions (width x height)
text2file generate --content "Custom Size" --extension svg --width 400 --height 200

Archives

ZIP (.zip)

text2file generate --content "Sample content for archive" --extension zip

TAR.GZ (.tar.gz)

text2file generate --content "Sample content for tar.gz archive" --extension tar.gz

API Reference

text2file.generate_file(content: str, extension: str, output_dir: str = ".", filename: Optional[str] = None) -> str

Generate a file with the given content and extension.

Parameters

• content: The content to write to the file
• extension: The file extension (without dot)
• output_dir: Output directory (default: current directory)
• filename: Optional custom filename (without extension)

Returns

• Path to the generated file

text2file.validate_file(filepath: str) -> bool

Validate if a file is not corrupted.

Parameters

• filepath: Path to the file to validate

Returns

• True if file is valid, False otherwise

text2file.cleanup_invalid_files(directory: str, recursive: bool = False, dry_run: bool = False) -> List[str]

Remove invalid files from a directory.

Parameters

• directory: Directory to clean up
• recursive: Whether to scan subdirectories
• dry_run: If True, only show what would be deleted

Returns

• List of removed files

Development

Prerequisites

• Python 3.8+
• Poetry

Optional Dependencies

• Pillow for image generation
• openpyxl for Excel file generation
• python-docx for Word document generation
• PyPDF2 for PDF file generation

Setup

1. Clone the repository:

   git clone https://github.com/veridock/text2file.git
   cd text2file
   

2. Install development dependencies:

   # Install Poetry if you haven't already
   curl -sSL https://install.python-poetry.org | python3 -
   
   # Install project with all optional dependencies
   make install-dev
   

3. Run tests:

   make test
   

4. Run linters and formatters:

   make lint       # Run all linters
   make format     # Auto-format code
   make typecheck  # Run static type checking
   

5. Install the package in development mode:

   pip install -e .
   

6. Run the CLI directly:

   python -m text2file --help
   

Linting and Formatting

# Run linter
ruff check .

# Format code
black .

# Check types
mypy .

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Adding New File Formats

To add support for a new file format:

1. Create a new generator function in the appropriate module under src/text2file/generators/
2. Add a validator in src/text2file/validators/
3. Register the generator using the @register_generator decorator
4. Add tests in the tests/ directory
5. Update the documentation

Changelog

0.2.0 (Unreleased)

• Added lazy loading of generators for better performance
• Added support for video file generation (.mp4, .avi, .mov)
• Added text2file list command to show supported formats
• Improved error messages for missing dependencies
• Updated documentation and examples

See CHANGELOG.md for the full changelog.

License

Distributed under the MIT License. See LICENSE for more information.

---

Created with ❤️ by Veridock

Commands

Generate Files

text2file generate "Your text content" [EXTENSIONS...] [OPTIONS]

Options:

• -o, --output-dir PATH: Output directory (default: current directory)
• -p, --prefix TEXT: Filename prefix (default: "generated")
• --help: Show help message and exit

Examples:

1. Generate a simple text file:

   text2file generate "This is a test file" txt
   

2. Generate multiple file formats at once:

   text2file generate "Sample content" txt md pdf jpg
   

3. Custom output directory and prefix:

   text2file generate "Test content" -o ./output -p custom_ txt pdf
   

Validate Files

text2file validate PATH [OPTIONS]

Options:

• -r, --recursive: Recursively validate files in subdirectories
• -v, --verbose: Show detailed validation results
• --json: Output results in JSON format
• --help: Show help message and exit

Examples:

1. Validate a single file:

   text2file validate document.pdf
   

2. Validate all files in a directory recursively:

   text2file validate ./test_files -r
   

3. Get detailed validation output in JSON:

   text2file validate ./test_files --json
   

Clean Up Invalid Files

text2file cleanup PATH [OPTIONS]

Options:

• -r, --recursive: Recursively clean up files in subdirectories
• --dry-run: Show what would be deleted without actually deleting
• -v, --verbose: Show detailed information
• --help: Show help message and exit

Examples:

1. Clean up invalid files in a directory:

   text2file cleanup ./test_files
   

2. Preview what would be deleted (dry run):

   text2file cleanup ./test_files --dry-run -v
   

File Format Examples

Text Files (.txt, .md)

text2file generate "# Markdown Title\n\nThis is a **markdown** file with *formatting*.\n\n- Item 1\n- Item 2\n- Item 3" md

Code Files (.py, .js, .html)

text2file generate "def hello_world():\n    print('Hello, World!')" py

Images (.jpg, .png)

text2file generate "Sample text to be converted to image" jpg png

Documents (.pdf, .docx)

text2file generate "Formal Document\n\nThis is a sample document with multiple paragraphs. The text will be automatically wrapped to fit the output format. Great for creating test data!" pdf docx

Development

Setup

1. Install development dependencies:

   poetry install --with dev
   

2. Run tests:

   poetry run pytest
   

3. Run linter:

   poetry run ruff check .
   

4. Run formatter:

   poetry run black .
   

Adding New File Formats

1. Create a new generator function in src/text2file/generators/
2. Add validation logic in src/text2file/validators.py if needed
3. Register the generator in src/text2file/__init__.py
4. Add tests in tests/
5. Update documentation

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a history of changes.