utils.py

"""Shared utility functions for Pytalon."""

import io
import sys
import difflib
from config import FILLER_WORDS, NEGATION_WORDS, COMMON_SHORT_WORDS, COMMAND_PREFIXES

# ========== NEGATION HANDLING ==========

_SINGLE_NEGATIONS = {w for w in NEGATION_WORDS if " " not in w}
_MULTI_NEGATIONS = {p for p in NEGATION_WORDS if " " in p}

# ------- Helper function to detect negation cues in text -------
def _text_has_negation(text):

    """True if text contains an explicit negation cue."""

    lowered = text.lower()
    words = set(lowered.split())
    if words & _SINGLE_NEGATIONS:
        return True
    return any(phrase in lowered for phrase in _MULTI_NEGATIONS)

# ------- Helper function to adjust similarity score based on negation cues -------

def _apply_negation_cap(score, user_text, reference_text):

    """Lower score when the reference is negative but the user did not negate."""

    if _text_has_negation(reference_text) and not _text_has_negation(user_text):
        return min(score, 0.5)
    return score

# ========== UTILITY FUNCTIONS ==========
# These functions provide common utilities used across the Pytalon

# Global Separator Function
def print_global_separator():
    """Prints a visual separator line for better readability"""
    global_separator = "\n" + "="*50
    print(global_separator, flush=True)


# CODE PRACTICE SYSTEM Helper Functions
 
# ===== Step 1: Get multiline code input from the user =====
def get_multiline_code_input():
    """
    Gets multiple lines of Python code from the user.
    User types code line by line, then types 'DONE' to finish.
    
    - String containing all the code lines joined together
    - Validates stdin is available before attempting input
    """
    # ----check if stdin is available or not ----
    if sys.stdin.closed:
        print("⚠️ Input stream is closed. Restarting practice session...", flush=True)
        return ""
    
    print("\n📝 ENTER YOUR PYTHON CODE (type 'DONE' on a new line when finished):", flush=True)
    print_global_separator()
    
    code_lines = []
    try:
        while True:
            line = input()
            # Check if user wants to stop entering code
            if line.strip().upper() == 'DONE':
                break
            code_lines.append(line)
    except EOFError:
        print("\n⚠️ It's not your fault input ended unexpectedly, using entered code...", flush=True)
        # Return whatever was entered so far
    
    # Join all lines with newline characters
    return "\n".join(code_lines)
 
 
# ===== Step 2: Execute code and check for expected/forbidden keywords =====
def execute_and_check_code(code, expected_keywords=None, forbidden_keywords=None):
    """
    Safely executes the user's Python code and checks for required elements.
    
    Parameters:
        code: The Python code string to execute
        expected_keywords: List of keywords that MUST be in the code
        forbidden_keywords: List of keywords that must NOT be in the code
    
    Returns:
        (success, output, error_message)
        - success: True if code ran correctly and passed all checks
        - output: What the code printed (if anything)
        - error_message: Description of any problems found
    """
    success = True
    error_message = ""
    output = ""
    
    # ---- BLOCK INFINITE LOOPS (before stdout redirect) ----
    # Check for common infinite loop patterns (best-effort detection)
    # Note: Variable-based loops may still bypass this check
    infinite_loop_patterns = [
        'while True',
        'while 1',
        'while(True)',
        'while(1)',
        'while (True)',
        'while (1)',
        'while 1==1',
        'while 1 == 1',
    ]
    
    code_lower = code.lower()
    detected_pattern = None
    
    for pattern in infinite_loop_patterns:
        if pattern.lower() in code_lower:
            detected_pattern = pattern
            break
    
    if detected_pattern:
        success = False
        error_message = f"⚠️ Infinite loops are not allowed in practice mode (detected: {detected_pattern})"
        return success, output, error_message
    
    # ---- SETUP: Capture printed output ----
    old_stdout = sys.stdout
    sys.stdout = captured_output = io.StringIO()
    
    try:
        # ---- Namespace with exit/quit blocked ----
        # This prevents users from calling exit() or quit() in their code
        def _blocked_exit(*args, **kwargs):
            raise Exception("exit() is not allowed in practice exercises")
        
        def _blocked_quit(*args, **kwargs):
            raise Exception("quit() is not allowed in practice exercises")
        
        namespace = {
            'exit': _blocked_exit,
            'quit': _blocked_quit,
        }
        
        # ---- EXECUTE: Run the code in isolated namespace ----
        exec(code, namespace)
        output = captured_output.getvalue()
        
        # ---- CHECK: Verify expected keywords are present ----
        if expected_keywords:
            # Find which expected keywords are missing
            missing_keywords = [
                kw for kw in expected_keywords 
                if kw.lower() not in code.lower()
            ]
            
            if missing_keywords:
                success = False
                error_message = f"Missing required elements: {', '.join(missing_keywords)}"
        
        # ---- CHECK: Verify forbidden keywords are absent ----
        if forbidden_keywords:
            # Find which forbidden keywords were used
            found_forbidden = [
                kw for kw in forbidden_keywords 
                if kw.lower() in code.lower()
            ]
            
            if found_forbidden:
                success = False
                error_message = f"Please don't use: {', '.join(found_forbidden)}"
 
    except SyntaxError as e:
        success = False
        error_message = f"Syntax Error: {str(e)}"
    except SystemExit:
        success = False
        error_message = "⚠️ Code attempted to exit. Please don't use exit() in practice."
    except Exception as e:
        success = False
        error_message = f"Error: {str(e)}"
    finally:
        # ---- CLEANUP: Restore normal output and close StringIO ----
        sys.stdout = old_stdout
        # ---- Explicitly close the StringIO to prevent I/O state corruption ----
        captured_output.close()
    
    return success, output, error_message
 
# ===== Step 3: Main practice session flow =====
def run_practice_session(topic_name, instructions, expected_keywords, example_code, custom_check_function=None):
    """
    Runs a complete interactive practice session for a specific topic.
    
    Flow:
    1. Shows instructions and example
    2. Gets user's code
    3. Executes and validates the code
    4. If correct: shows success message
    5. If wrong: shows error, lets user try again
    
    Parameters:
        topic_name:          Display name of the topic (e.g., "Variables")
        instructions:        What the user needs to do
        expected_keywords:   Keywords that must appear in the code
        example_code:        A working example to show the user
        custom_check_function: Optional extra validation function
    """
    # ---- SUB STEP 1: Show practice header and instructions ----
    print_global_separator()
    print(f"🧪 INTERACTIVE PRACTICE: {topic_name}", flush=True)
    print_global_separator()
    
    print(f"\n📋 TASK:", flush=True)
    print(instructions, flush=True)
    
    print(f"\n💡 EXAMPLE SOLUTION:", flush=True)
    print(f"{example_code}", flush=True)
    
    print(f"\n🔑 Required elements: {', '.join(expected_keywords)}", flush=True)
 
    # ----  SUB STEP 2: Main practice loop with attempt limit ----
    attempts = 0
    MAX_ATTEMPTS = 3
 
    while True:
        # Get user's code attempt
        user_code = get_multiline_code_input()
 
        # Check for empty submission
        if not user_code.strip():
            print("⚠️  Please enter some Python code!", flush=True)
            continue
 
        # Execute the code and check for basic requirements
        success, output, error_message = execute_and_check_code(
            user_code,
            expected_keywords=expected_keywords
        )
 
        # Run custom validation if provided (for topic-specific checks)
        if success and custom_check_function:
            success, error_message = custom_check_function(user_code, output)
 
    # ---- SUB STEP 3: Show results ----
        if success:
            print_global_separator()
            print("✅ PERFECT! Your code is correct!", flush=True)
            if output:
                print(f"\n📤 YOUR OUTPUT:", flush=True)
                print(output, flush=True)
            print(f"\n💡 Code structure and elements are correct!", flush=True)
            print("✅ Practice complete! You can continue to the next topic.", flush=True)
            print_global_separator()
            break
        else:
            attempts += 1
            print_global_separator()
            print(f"❌ Not quite right! {error_message}", flush=True)
            if attempts >= MAX_ATTEMPTS:
                from validators import get_global_valid_input
                retry = get_global_valid_input("\n🔹 You've tried several times. Try again? (yes/no): ")
                if retry == 'yes':
                    attempts = 0
                    continue
                elif retry == 'exit':
                    print("👋 Exiting practice session. See you next time!", flush=True)
                    break
                else:  # retry == 'no'
                    print("✅ Skipping practice. You can always come back later!", flush=True)
                    break
            else:
                print(f"\n🔄 Attempt {attempts}/{MAX_ATTEMPTS}. Please try again!", flush=True)
                print_global_separator()
        
# ========= MENU DISPLAY FUNCTION ==========
def show_topic_menu(topics, prompt="Which topic would you like to start with?"):
    """
    Displays the full topic list and returns the chosen number (string) or 'exit'.
    """
    from validators import get_global_menu_choice # Imported here to avoid circular dependency

    print_global_separator()
    print("I can teach you Python basics! Here are the topics:", flush=True)
    print_global_separator()
    for num, topic in topics.items():
        print(f"   {num}. {topic}", flush=True)

    choice = get_global_menu_choice(
        f"\n🔹 {prompt} (1-13/exit): ",
        1,
        len(topics)
    )
    return choice

# ========= Helper: Smart Detection Function ==========

# Smart Detection Function for detecting the users intent during the conservation.
def smart_detection(s1, s2):
    """
    Compares two strings and returns a similarity score between 0 and 1.
    Checks for:
    - Sub‑string containment
    - Full‑string similarity
    - Each word of s1 against s2 and vice‑versa
    - Word‑order reversal
    - All words of one string present in the other (subset match)
    """
    if not s1 or not s2:
        return 0.0
    
    s1 = s1.lower().strip()
    s2 = s2.lower().strip()

    # Direct containment
    if s1 in s2 or s2 in s1:
        return 1.0

    # --- New check: all words of s2 appear in s1 (or vice‑versa) ---
    words1 = set(s1.split())
    words2 = set(s2.split())

    if words2 and words2.issubset(words1):
        # All keywords are present in the user's topic phrase → strong match
        return 1.0
    if words1 and words1.issubset(words2):
        return 1.0

    # ----------------------------------------------------------------

    # Full‑string comparison
    best = difflib.SequenceMatcher(None, s1, s2).ratio()

    # Word‑by‑word comparisons
    for word in s1.split():
        score = difflib.SequenceMatcher(None, word, s2).ratio()
        if score > best:
            best = score

    for word in s2.split():
        score = difflib.SequenceMatcher(None, word, s1).ratio()
        if score > best:
            best = score

    # Handle swapped word order
    if " " in s2:
        reversed_s2 = " ".join(reversed(s2.split()))
        score = difflib.SequenceMatcher(None, s1, reversed_s2).ratio()
        if score > best:
            best = score

    return best

# Smart Validations for the Validators to detect the users intent during the conservation.
def smart_validators(s1, s2, w1, w2):
    """
    Validates the user's input based on smart detection logic.
    Parameters:
        - s1: User's input string
        - s2: Reference string to compare against
        - w1: Extracted keywords from user's input
        - w2: Extracted keywords from reference string
        Returns:
        - A similarity score between 0 and 1, with adjustments for negation cues.
        The function performs multiple checks:
        1. Direct containment of one string in the other.
        2. Subset match where all keywords of one string are present in the other.
        3. Full-string similarity using difflib.
        4. Word-by-word comparisons for both the main strings and the keywords.
        5. Handling of swapped word order.
        6. Adjusting the final score if negation cues are detected in the reference string but not in the user's input, 
           to prevent false positives in cases of negation.
    """

    s1 = s1.lower().strip()
    s2 = s2.lower().strip()

    w1 = w1.lower().strip()
    w2 = w2.lower().strip()
    
    # Extract keywords and filter out common short words to prevent false positives
    s1_clean = {w for w in _extract_keywords(s1).split() if w not in COMMON_SHORT_WORDS}
    s2_clean = {w for w in _extract_keywords(s2).split() if w not in COMMON_SHORT_WORDS}
    w1_words = {w for w in w1.split() if w not in COMMON_SHORT_WORDS}
    w2_words = {w for w in w2.split() if w not in COMMON_SHORT_WORDS}
    min_overlap = 2 

    overlap1 = len(s1_clean & s2_clean)
    overlap2 = len(w1_words & w2_words)
    overlap3 = len(s1_clean & w2_words)
    overlap4 = len(w1_words & s2_clean)

    # Strong match requires min_overlap=2 in both main strings AND keyword sets
    if (overlap1 >= min_overlap or overlap2 >= min_overlap) and (overlap3 >= min_overlap or overlap4 >= min_overlap):
        return _apply_negation_cap(1.0, s1, s2)
    
    # Weaker match with at least 1 overlap in each (but not common short words)
    if (overlap1 >= 1 or overlap2 >= 1) and (overlap3 >= 1 or overlap4 >= 1):
        return _apply_negation_cap(0.5, s1, s2)
    # ----------------------------------------------------------------
    
    # Full‑string comparison
    best = difflib.SequenceMatcher(None, s1, s2).ratio()
    
    # Word‑by‑word comparisons
    for word in s1.split():
        score = difflib.SequenceMatcher(None, word, s2).ratio()
        if score > best:
            best = score

    for word in s2.split():
        score = difflib.SequenceMatcher(None, word, s1).ratio()
        if score > best:
            best = score
    
    # String-by-string comparisons for keywords
    for word_w1 in w1.split():
        score = difflib.SequenceMatcher(None, word_w1, w2).ratio()
        if score > best:
            best = score
    
    for word_w2 in w2.split():
        score = difflib.SequenceMatcher(None, word_w2, w1).ratio()
        if score > best:
            best = score
    
    # Handle swapped word order for both the main strings and the keywords
    if " " in s2:
        reversed_s2 = " ".join(reversed(s2.split()))
        score = difflib.SequenceMatcher(None, s1, reversed_s2).ratio()
        if score > best:
            best = score
    
    if " " in w2:
        reversed_w2 = " ".join(reversed(w2.split()))
        score = difflib.SequenceMatcher(None, s1, reversed_w2).ratio()
        if score > best:
            best = score

    return _apply_negation_cap(best, s1, s2)

# ========== HELPER: Extract intent keywords from a string ==========

def _extract_keywords(text):
    """
    Extracts the most intent-carrying words from a string.
    Strips common filler words and punctuation so smart_validators 
    gets meaningful w1/w2.
    
    Returns a string of the remaining words joined by spaces.
    """
    # Convert to lowercase and strip whitespace
    text = text.lower().strip()
    
    # Remove common punctuation by keeping only alphanumeric, spaces, and apostrophes
    # This handles contractions like "don't", "I'm", etc.
    cleaned_chars = []
    for char in text:
        if char.isalnum() or char.isspace() or char == "'":
            cleaned_chars.append(char)
        else:
            # Replace punctuation with space to separate words
            cleaned_chars.append(' ')
    
    cleaned = ''.join(cleaned_chars)
    
    # Split into words and filter out filler words
    words = cleaned.split()
    keywords = [w for w in words if w not in FILLER_WORDS]
    
    return ' '.join(keywords) if keywords else cleaned

# ========== HELPER: Remove command-style prefixes from user input ==========
def remove_command_prefix(text):
    """
    Remove command-style prefixes from user input.
    Handles cases like: /lists, !functions, #variables, \\loops, etc.
    
    This function checks if the first character is a command prefix
    and removes it along with any following whitespace.
    
    Uses COMMAND_PREFIXES from config.py for maintainability.
    Custom implementation without using lstrip() or strip().
    
    Args:
        text: The input text to clean
        
    Returns:
        Text with leading command prefix removed if present
    """
    # Handle empty or single-character input
    if not text or len(text) <= 1:
        return text
    
    # Check if first character is a command prefix
    first_char = text[0]
    is_command_prefix = False
    
    for prefix in COMMAND_PREFIXES:
        if first_char == prefix:
            is_command_prefix = True
            break
    
    # If not a command prefix, return original text
    if not is_command_prefix:
        return text
    
    # Remove the prefix character
    cleaned = text[1:]
    
    # Remove leading whitespace manually (custom implementation)
    start_index = 0
    while start_index < len(cleaned) and cleaned[start_index] == ' ':
        start_index += 1
    
    # Return the text with prefix and leading spaces removed
    return cleaned[start_index:] if start_index < len(cleaned) else cleaned