Skip to content

EXAMPLES.md

Latest commit

 

History

History
359 lines (258 loc) · 6.86 KB

EXAMPLES.md

File metadata and controls

359 lines (258 loc) · 6.86 KB
Raw

PyRead Usage Examples

This guide provides practical examples for common use cases.

Basic Usage

Convert a Single File

# Simple conversion (output in same directory)
python pyread.py document.pdf
# Output: document.txt

# Run again - creates versioned file automatically
python pyread.py document.pdf
# Output: document_v2.txt (original document.txt is preserved)

# Run again
python pyread.py document.pdf
# Output: document_v3.txt

Overwrite Existing Files

# Replace existing file instead of creating versioned file
python pyread.py document.pdf --overwrite
# Output: document.txt (replaces existing file)

Specify Output Directory

# Output to a different location
python pyread.py document.pdf --output-dir ./output/

# Output: ./output/document.txt

Batch Processing

Process All Files in a Directory

# Non-recursive (only files in the directory)
python pyread.py ./documents/ --output-dir ./text_output/

Recursive Processing

# Process all subdirectories
python pyread.py ./documents/ --output-dir ./text_output/ --recursive

# Directory structure is preserved:
# Input:  ./documents/folder1/file.pdf
# Output: ./text_output/folder1/file.txt

Parallel Processing for Large Batches

# Use 8 workers for faster processing
python pyread.py ./large_batch/ --workers 8 --recursive

# Adjust based on CPU count (default: 4)

Format-Specific Examples

PDF Files

# Standard PDF
python pyread.py report.pdf

# Scanned PDF with OCR
python pyread.py scanned_document.pdf --ocr

# Note: OCR requires tesseract to be installed

EPUB eBooks

# Convert ebook to text
python pyread.py novel.epub

# Batch convert entire library
python pyread.py ./ebooks/ --output-dir ./ebook_texts/ -r

HTML Files

# Extract text from HTML
python pyread.py webpage.html

# Batch process saved webpages
python pyread.py ./saved_pages/ --output-dir ./text/ -r

Advanced Options

Overwrite Existing Files

# By default, existing files are skipped
python pyread.py docs/ --output-dir output/

# Force overwrite
python pyread.py docs/ --output-dir output/ --overwrite

ASCII-Only Output

# Remove all non-ASCII characters
python pyread.py unicode_document.pdf --force-ascii

# Useful for compatibility with ASCII-only systems
# "café" becomes "cafe", "中文" is removed

Verbose Logging

# See detailed processing information
python pyread.py docs/ -r --verbose

# Save logs to file
python pyread.py docs/ -r --verbose --log-file processing.log

Real-World Scenarios

1. Research Paper Archive

Convert a collection of research PDFs to searchable text:

python pyread.py ./research_papers/ \
  --output-dir ./searchable_text/ \
  --recursive \
  --workers 8 \
  --verbose \
  --log-file conversion.log

2. Scanned Document Batch (OCR)

Process scanned documents with OCR:

python pyread.py ./scanned_docs/ \
  --output-dir ./ocr_output/ \
  --recursive \
  --ocr \
  --workers 4 \
  --overwrite

Note: OCR is slower, so use fewer workers to avoid memory issues.

3. eBook Library Conversion

Convert an entire ebook library:

python pyread.py ~/ebooks/ \
  --output-dir ~/ebook_texts/ \
  --recursive \
  --workers 6

4. Web Archive Processing

Extract text from saved HTML pages:

python pyread.py ./web_archive/ \
  --output-dir ./extracted_text/ \
  --recursive \
  --force-ascii \
  --overwrite

5. Clean Legacy Text Files

Re-process old text files with encoding issues:

python pyread.py ./old_texts/ \
  --output-dir ./cleaned_texts/ \
  --recursive \
  --overwrite \
  --verbose

Performance Tips

Optimize Worker Count

# Check CPU count
python -c "import os; print(os.cpu_count())"

# Use CPU count - 1 for best performance
# Example for 8-core system:
python pyread.py docs/ -r -w 7

Processing Very Large Files

# Use verbose mode to monitor progress
python pyread.py huge_document.pdf --verbose

# The tool processes page-by-page to minimize memory usage

Skip Already Processed Files

# First run - processes all files
python pyread.py docs/ --output-dir output/ -r

# Second run - skips existing files (default behavior)
python pyread.py docs/ --output-dir output/ -r

# Only new files are processed

Troubleshooting Examples

Test Installation

# Create a simple test file
echo "Hello, World!" > test.txt

# Convert it
python pyread.py test.txt

# Check output
cat test.txt  # or: type test.txt (Windows)

Debug Extraction Issues

# Use verbose mode to see what's happening
python pyread.py problematic.pdf --verbose

# Try with OCR if text extraction fails
python pyread.py problematic.pdf --ocr --verbose

Check Format Support

# Try to convert an unsupported format
python pyread.py file.docx

# Error message will indicate unsupported format
# Supported: PDF, EPUB, TXT, HTML

Output Quality Examples

Before (raw PDF text):

The    quick   brown
fox
jumps  over   the   lazy
dog.

© 2024  Company™

After (cleaned text):

The quick brown
fox
jumps over the lazy
dog.

© 2024 Company TM

Note:

  • Multiple spaces collapsed to single space
  • Excessive newlines reduced (preserves paragraph breaks)
  • Special characters normalized (™ → TM)
  • Unicode normalized (NFKC)

Integration Examples

Pipe Output to Another Tool

# Convert and search in one command (Linux/macOS)
python pyread.py document.pdf && grep "keyword" document.txt

# Windows PowerShell
python pyread.py document.pdf; Select-String "keyword" document.txt

Batch Script

#!/bin/bash
# process_all.sh - Convert all PDFs in current directory

for pdf in *.pdf; do
    echo "Processing $pdf..."
    python pyread.py "$pdf" --overwrite
done

Python Integration

# Use as a library
import subprocess
import sys

def convert_to_text(pdf_path):
    result = subprocess.run(
        [sys.executable, "pyread.py", pdf_path],
        capture_output=True,
        text=True
    )
    if result.returncode == 0:
        print(f"Success: {result.stdout}")
    else:
        print(f"Error: {result.stderr}")

convert_to_text("document.pdf")

Quick Reference

Task Command
Single file python pyread.py file.pdf
Custom output python pyread.py file.pdf -o output/
Directory python pyread.py docs/ -o output/
Recursive python pyread.py docs/ -r
OCR python pyread.py scan.pdf --ocr
Parallel python pyread.py docs/ -w 8
Overwrite python pyread.py docs/ --overwrite
ASCII only python pyread.py file.pdf --force-ascii
Verbose python pyread.py file.pdf -v
Log file python pyread.py docs/ --log-file log.txt

Need more help? Check the README or Installation Guide.