guidellm.utils.text

def clean_text(text: str) -> str:
    """
    Normalize text by fixing encoding issues and standardizing whitespace.

    Applies Unicode normalization and whitespace standardization for consistent
    text processing. Removes excessive whitespace and fixes common encoding problems.

    :param text: Raw text string to clean and normalize
    :return: Cleaned text with normalized encoding and whitespace
    """
    return re.sub(r"\s+", " ", ftfy.fix_text(text)).strip()

def filter_text(
    text: str,
    filter_start: str | int | None = None,
    filter_end: str | int | None = None,
) -> str:
    """
    Extract text substring using start and end markers or indices.

    Filters text content by locating string markers or using numeric indices
    to extract specific portions. Supports flexible filtering for content
    extraction and preprocessing operations.

    :param text: Source text to filter and extract from
    :param filter_start: Starting marker string or index position
    :param filter_end: Ending marker string or index position
    :return: Filtered text substring between specified boundaries
    :raises ValueError: If filter indices are invalid or markers not found
    """
    filter_start_index = -1
    filter_end_index = -1

    if filter_start and isinstance(filter_start, str):
        filter_start_index = text.index(filter_start)
    elif filter_start:
        if not isinstance(filter_start, int):
            raise ValueError(f"Invalid filter start index: {filter_start}")
        filter_start_index = filter_start

    if filter_end and isinstance(filter_end, str):
        filter_end_index = text.index(filter_end)
    elif filter_end:
        if not isinstance(filter_end, int):
            raise ValueError(f"Invalid filter end index: {filter_end}")
        filter_end_index = filter_end

    if filter_start_index > -1:
        text = text[filter_start_index:]
    if filter_end_index > -1:
        text = text[:filter_end_index]

    return text

def format_value_display(
    value: float,
    label: str,
    units: str = "",
    total_characters: int | None = None,
    digits_places: int | None = None,
    decimal_places: int | None = None,
) -> str:
    """
    Format a numeric value with units and label for consistent display output.

    Creates standardized display strings for metrics and measurements with
    configurable precision, width, and color formatting. Supports both
    fixed-width and variable-width output for tabular displays.

    :param value: Numeric value to format and display
    :param label: Descriptive label for the value
    :param units: Units string to append after the value
    :param total_characters: Total width for right-aligned output formatting
    :param digits_places: Total number of digits for numeric formatting
    :param decimal_places: Number of decimal places for numeric precision
    :return: Formatted string with value, units, and colored label
    """
    if decimal_places is None and digits_places is None:
        formatted_number = f"{value:.0f}"
    elif digits_places is None:
        formatted_number = f"{value:.{decimal_places}f}"
    elif decimal_places is None:
        formatted_number = f"{value:>{digits_places}f}"
    else:
        formatted_number = f"{value:>{digits_places}.{decimal_places}f}"

    result = f"{formatted_number}{units} [{Colors.info}]{label}[/{Colors.info}]"

    if total_characters is not None:
        total_characters += len(Colors.info) * 2 + 5

        if len(result) < total_characters:
            result = result.rjust(total_characters)

    return result

def is_punctuation(text: str) -> bool:
    """
    Check if a single character is a punctuation mark.

    Identifies punctuation characters by excluding alphanumeric characters
    and whitespace from single-character strings.

    :param text: Single character string to test
    :return: True if the character is punctuation, False otherwise
    """
    return len(text) == 1 and not text.isalnum() and not text.isspace()

def load_text(data: str | Path, encoding: str | None = None) -> str:
    """
    Load text content from various sources including URLs, files, and package data.

    Supports loading from HTTP/FTP URLs, local files, compressed archives, package
    resources, and raw text strings. Automatically detects source type and applies
    appropriate loading strategy with encoding support.

    :param data: Source location or raw text - URL, file path, package resource
        identifier, or text content
    :param encoding: Character encoding for file reading operations
    :return: Loaded text content as string
    :raises FileNotFoundError: If local file path does not exist
    :raises httpx.HTTPStatusError: If URL request fails
    """
    logger.debug("Loading text: {}", data)

    if not data:
        return ""

    # check URLs
    if isinstance(data, str) and data.strip().startswith(("http", "ftp")):
        with httpx.Client() as client:
            response = client.get(data.strip())
            response.raise_for_status()
            return response.text

    # check gzipped files
    if isinstance(data, str) and data.endswith(".gz"):
        with gzip.open(data, "rt", encoding=encoding) as file:
            return file.read()

    # check if it's raw text by not being a path
    if isinstance(data, str) and (
        len(data) > MAX_PATH_LENGTH or not Path(data).exists()
    ):
        return data

    # assume local file
    if not isinstance(data, Path):
        data = Path(data)

    if not data.exists() or not data.is_file():
        raise FileNotFoundError(f"File not found: {data}")

    return data.read_text(encoding=encoding)

def split_text(text: str, split_punctuation: bool = False) -> list[str]:
    """
    Split text into tokens with optional punctuation separation.

    Tokenizes text into words and optionally separates punctuation marks
    for detailed text analysis and processing operations.

    :param text: Text string to tokenize and split
    :param split_punctuation: Separate punctuation marks as individual tokens
    :return: List of text tokens
    """
    text = clean_text(text)

    if split_punctuation:
        return re.findall(r"[\w]+|[.,!?;]", text)

    return text.split()

def split_text_list_by_length(
    text_list: list[Any],
    max_characters: int | list[int],
    pad_horizontal: bool = True,
    pad_vertical: bool = True,
) -> list[list[str]]:
    """
    Split text strings into wrapped lines with specified maximum character limits.

    Processes each string in the input list by wrapping text to fit within character
    limits, with optional padding for consistent formatting in tabular displays.
    Supports different character limits per string and uniform padding across results.

    :param text_list: List of strings to process and wrap
    :param max_characters: Maximum characters per line, either single value or
        per-string limits
    :param pad_horizontal: Right-align lines within their character limits
    :param pad_vertical: Pad shorter results to match the longest wrapped result
    :return: List of wrapped line lists, one per input string
    :raises ValueError: If max_characters list length doesn't match text_list length
    """
    if not isinstance(max_characters, list):
        max_characters = [max_characters] * len(text_list)

    if len(max_characters) != len(text_list):
        raise ValueError(
            f"max_characters must be a list of the same length as text_list, "
            f"but got {len(max_characters)} and {len(text_list)}"
        )

    result: list[list[str]] = []
    for index, text in enumerate(text_list):
        lines = textwrap.wrap(text, max_characters[index])
        result.append(lines)

    if pad_vertical:
        max_lines = max(len(lines) for lines in result)
        for lines in result:
            while len(lines) < max_lines:
                lines.append(" ")

    if pad_horizontal:
        for index in range(len(result)):
            lines = result[index]
            max_chars = max_characters[index]
            new_lines = []
            for line in lines:
                new_lines.append(line.rjust(max_chars))
            result[index] = new_lines

    return result