text_escape_demo.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Demonstrate what happens when auto_escape=True is used for text templates
"""

from template_engine import TemplateEngine

def text_template_escaping_demo():
    """Show the effects of HTML escaping on text templates."""
    
    print("📄 TEXT TEMPLATE ESCAPING DEMO")
    print("=" * 60)
    
    engine = TemplateEngine(strict_mode=False)  # Use non-strict mode
    
    # Sample data with characters that would be escaped in HTML
    text_data = {
        'user_name': 'John & Jane',
        'email_subject': 'Meeting @ 3:00 PM <urgent>',
        'message': 'Please review the proposal & send feedback',
        'code_example': 'if (x < 5 && y > 10) { return true; }',
        'html_content': '<p>This is a paragraph with <strong>bold</strong> text</p>',
        'special_chars': 'Symbols: < > & " \' = % # @',
        'math_formula': '5 < x < 10 && result = x & y',
        'file_path': 'C:\\Users\\Admin\\Documents\\file.txt'
    }
    
    # Text template (like for emails, reports, config files)
    text_template = '''
Email Notification
==================

To: $user_name
Subject: $email_subject

Message:
$message

Code Example:
$code_example

HTML Content:
$html_content

Special Characters:
$special_chars

Math Formula:
$math_formula

File Path:
$file_path

Best regards,
System Administrator
    '''.strip()
    
    print("📋 Sample Data:")
    for key, value in text_data.items():
        print(f"  📝 {key}: {repr(value)}")
    
    print(f"\n📄 TEXT OUTPUT (auto_escape=False) - CORRECT:")
    print("=" * 50)
    text_result = engine.render(text_template, text_data, auto_escape=False)
    print(text_result)
    
    print(f"\n🌐 TEXT OUTPUT (auto_escape=True) - WRONG:")
    print("=" * 50)
    html_escaped_result = engine.render(text_template, text_data, auto_escape=True)
    print(html_escaped_result)
    
    return text_result, html_escaped_result

def show_specific_problems():
    """Show specific problems when HTML escaping text."""
    
    print(f"\n\n⚠️  SPECIFIC PROBLEMS WITH HTML ESCAPING TEXT")
    print("=" * 60)
    
    engine = TemplateEngine(strict_mode=False)
    
    examples = [
        {
            'name': 'Email Addresses',
            'data': {'email': 'user@example.com'},
            'template': 'Contact: $email',
            'problem': 'The @ symbol might get escaped in some contexts'
        },
        {
            'name': 'File Paths',
            'data': {'path': 'C:\\Program Files\\App\\config.xml'},
            'template': 'Config file: $path',
            'problem': 'Backslashes and angle brackets in paths get escaped'
        },
        {
            'name': 'Programming Code',
            'data': {'code': 'if (x < y && z > 0) return true;'},
            'template': 'Code: $code',
            'problem': 'Comparison operators < > get escaped'
        },
        {
            'name': 'Natural Language',
            'data': {'text': 'I love <3 this & that!'},
            'template': 'Comment: $text',
            'problem': 'Heart symbol <3 and ampersand get escaped'
        },
        {
            'name': 'Mathematical Expressions',
            'data': {'formula': '2 < x < 10 & y >= 5'},
            'template': 'Formula: $formula',
            'problem': 'Math symbols become unreadable'
        }
    ]
    
    for example in examples:
        print(f"\n📝 {example['name']}:")
        print(f"   Input: {repr(example['data'])}")
        
        correct = engine.render(example['template'], example['data'], auto_escape=False)
        wrong = engine.render(example['template'], example['data'], auto_escape=True)
        
        print(f"   ✅ Correct (no escape): {correct}")
        print(f"   ❌ Wrong (escaped):     {wrong}")
        print(f"   💡 Problem: {example['problem']}")

def use_case_scenarios():
    """Show different use case scenarios."""
    
    print(f"\n\n🎯 USE CASE SCENARIOS")
    print("=" * 50)
    
    print("📧 EMAIL TEMPLATES:")
    print("  ✅ auto_escape=False - Preserve natural text")
    print("  ❌ auto_escape=True  - Makes emails hard to read")
    
    print("\n📄 PLAIN TEXT REPORTS:")
    print("  ✅ auto_escape=False - Clean, readable output")
    print("  ❌ auto_escape=True  - Cluttered with HTML entities")
    
    print("\n📋 LOG FILES:")
    print("  ✅ auto_escape=False - Proper log formatting")
    print("  ❌ auto_escape=True  - Corrupted log entries")
    
    print("\n⚙️  CONFIG FILES:")
    print("  ✅ auto_escape=False - Valid syntax")
    print("  ❌ auto_escape=True  - Broken configuration")
    
    print("\n📨 SMS/TEXT MESSAGES:")
    print("  ✅ auto_escape=False - Natural text flow")
    print("  ❌ auto_escape=True  - Weird HTML entities in messages")

def recommendations():
    """Provide clear recommendations."""
    
    print(f"\n\n💡 RECOMMENDATIONS")
    print("=" * 50)
    
    print("🎯 DECISION MATRIX:")
    print("  📋 Text Templates (emails, logs, configs):")
    print("     → auto_escape=False ✅")
    print("     → Preserves natural text formatting")
    print("     → No HTML entities in output")
    
    print("\n  🌐 HTML Templates (web pages, HTML emails):")
    print("     → auto_escape=True ✅")
    print("     → Prevents XSS attacks")
    print("     → Safe for web browsers")
    
    print("\n🚨 WHEN TO BE CAREFUL:")
    print("  ⚠️  HTML Email Templates:")
    print("     → auto_escape=True (for security)")
    print("     → But be aware text might look different")
    
    print("\n  ⚠️  Mixed Content:")
    print("     → Consider separate templates")
    print("     → Or manual escaping for specific fields")

if __name__ == "__main__":
    text_result, html_result = text_template_escaping_demo()
    show_specific_problems()
    use_case_scenarios()
    recommendations()
    
    print(f"\n\n📊 SUMMARY:")
    print("=" * 50)
    print("Setting auto_escape=True for text templates:")
    print("✅ PROS: None for plain text")
    print("❌ CONS: Makes text harder to read")
    print("❌ CONS: Corrupts natural language")
    print("❌ CONS: Breaks code examples")
    print("❌ CONS: Mangles file paths")
    print("\n🎯 CONCLUSION: Use auto_escape=False for text templates!")