Python Filename Sanitization with Fallback

Python Filename Sanitization with Fallback

Purpose

This skill provides expertise in implementing robust filename sanitization that goes beyond removing invalid characters to ensure the resulting filename meets downstream validation requirements. It addresses the critical gap where user-provided titles containing only special characters (emoji, ellipsis, whitespace) produce invalid filenames after standard sanitization.

Core Problem

Conventional Approach Limitation: Standard filename sanitization only removes invalid filesystem characters:

# Incomplete sanitization - can produce invalid names
filename = title.replace('/', '-').replace(':', ' -')
filename = re.sub(r'[<>"\\\|?*]', '', filename)

Real-World Failure Cases (from Readwise MCP Server, 2026-01-24):

• Title: "…" → Filename: "….md" → qmd indexer error
• Title: "🍿🍿" → Filename: "🍿🍿.md" → qmd indexer error
• Title: "" → Filename: ".md" → qmd indexer error

Root Issue: Many indexers and tools require filenames to contain at least one alphanumeric character (/[\p{L}\p{N}]/u). Titles with only special characters fail this validation.

The Validation-Aware Pattern

Core Principle

Validate output, not just transform input. After sanitization, verify the filename meets downstream requirements; fallback to metadata-based naming when validation fails.

Implementation Pattern

def sanitize_filename(title: str, doc: Optional[Dict] = None) -> str:
    """
    Sanitize title for filename with fallback for invalid names.

    Args:
        title: The document title to sanitize
        doc: Optional document dict for fallback metadata (author, saved_at, category)

    Returns:
        Sanitized filename ending in .md, guaranteed to have alphanumeric content
    """
    # Step 1: Standard character sanitization
    filename = title.replace('/', '-').replace(':', ' -')
    filename = re.sub(r'[<>"\\\|?*]', '', filename)
    filename = filename[:100].strip()

    # Step 2: Validate output meets requirements
    if not any(c.isalnum() for c in filename):
        # Step 3: Intelligent fallback using available metadata
        if doc:
            author = doc.get('author', 'Unknown')
            # Sanitize author name (may also have special chars)
            author = re.sub(r'[<>"\\\|?*/:]', '', author)[:30].strip()

            saved_at = doc.get('saved_at', '')
            date_str = saved_at[:10] if saved_at else datetime.now().strftime('%Y-%m-%d')

            # Use category for context
            category = doc.get('category', 'Document')
            category_label = 'Tweet' if category == 'tweet' else category.capitalize()

            filename = f"{category_label} by {author} - {date_str}"
        else:
            # Generic timestamp-based fallback
            filename = f"Untitled - {datetime.now().strftime('%Y-%m-%d-%H%M%S')}"

    return filename + ".md"