toonify 0.0.1__py3-none-any.whl

toon/encoder.py

@@ -0,0 +1,317 @@
+"""TOON encoder - convert Python objects to TOON format."""
+from typing import Any, Dict, List, Optional
+from .constants import (
+    COMMA, TAB, PIPE, COLON, NEWLINE,
+    DEFAULT_DELIMITER, DEFAULT_INDENT,
+    KEY_FOLDING_OFF, KEY_FOLDING_SAFE,
+    DELIMITER_TAB, DELIMITER_PIPE, DELIMITER_COMMA,
+    LEFT_BRACKET, RIGHT_BRACKET, LEFT_BRACE, RIGHT_BRACE
+)
+from .utils import (
+    needs_quoting, quote_string, is_primitive,
+    is_uniform_array_of_objects, get_indent
+)
+
+
+class EncoderOptions:
+    """Options for TOON encoding."""
+    
+    def __init__(
+        self,
+        delimiter: str = DEFAULT_DELIMITER,
+        indent: int = DEFAULT_INDENT,
+        key_folding: str = KEY_FOLDING_OFF,
+        flatten_depth: Optional[int] = None
+    ):
+        """
+        Initialize encoder options.
+        
+        Args:
+            delimiter: Array value delimiter (',' | '\t' | '|')
+            indent: Number of spaces per indentation level
+            key_folding: Key folding mode ('off' | 'safe')
+            flatten_depth: Maximum depth for key folding (None = unlimited)
+        """
+        # Normalize delimiter names
+        if delimiter == DELIMITER_TAB:
+            delimiter = TAB
+        elif delimiter == DELIMITER_PIPE:
+            delimiter = PIPE
+        elif delimiter == DELIMITER_COMMA:
+            delimiter = COMMA
+        
+        self.delimiter = delimiter
+        self.indent = indent
+        self.key_folding = key_folding
+        self.flatten_depth = flatten_depth
+
+
+def encode(data: Any, options: Optional[Dict[str, Any]] = None) -> str:
+    """
+    Encode Python data structure to TOON format.
+    
+    Args:
+        data: Python object to encode (dict or list)
+        options: Encoding options
+            - delimiter: ',' (default), '\t', or '|'
+            - indent: int (default 2)
+            - key_folding: 'off' (default) or 'safe'
+            - flatten_depth: int or None
+            
+    Returns:
+        TOON formatted string
+        
+    Example:
+        >>> data = {'users': [{'id': 1, 'name': 'Alice'}]}
+        >>> print(encode(data))
+        users[1]{id,name}:
+          1,Alice
+    """
+    if options is None:
+        options = {}
+    
+    opts = EncoderOptions(
+        delimiter=options.get('delimiter', DEFAULT_DELIMITER),
+        indent=options.get('indent', DEFAULT_INDENT),
+        key_folding=options.get('key_folding', KEY_FOLDING_OFF),
+        flatten_depth=options.get('flatten_depth')
+    )
+    
+    return _encode_value(data, 0, opts)
+
+
+def _encode_value(value: Any, level: int, opts: EncoderOptions) -> str:
+    """Encode a value at a given indentation level."""
+    if value is None:
+        return 'null'
+    elif isinstance(value, bool):
+        return 'true' if value else 'false'
+    elif isinstance(value, (int, float)):
+        # Handle special float values
+        if isinstance(value, float):
+            if value != value:  # NaN
+                return 'null'
+            elif value == float('inf') or value == float('-inf'):
+                return 'null'
+        return str(value)
+    elif isinstance(value, str):
+        if needs_quoting(value):
+            return quote_string(value)
+        return value
+    elif isinstance(value, list):
+        return _encode_array(value, level, opts)
+    elif isinstance(value, dict):
+        return _encode_object(value, level, opts)
+    else:
+        # Handle other types (dates, etc.) as null
+        return 'null'
+
+
+def _encode_object(obj: dict, level: int, opts: EncoderOptions) -> str:
+    """Encode a dictionary object."""
+    if not obj:
+        return '{}'
+    
+    # Apply key folding if enabled
+    if opts.key_folding == KEY_FOLDING_SAFE:
+        obj = _apply_key_folding(obj, opts.flatten_depth)
+    
+    lines = []
+    indent = get_indent(level, opts.indent)
+    
+    for key, value in obj.items():
+        # Special handling for arrays to include key in header
+        if isinstance(value, list):
+            encoded_value = _encode_array_with_key(key, value, level, opts)
+            if NEWLINE in encoded_value:
+                lines.append(encoded_value)
+            else:
+                lines.append(f'{indent}{key}{COLON} {encoded_value}')
+        elif isinstance(value, dict):
+            # Nested object handling
+            if not value:
+                # Empty object - inline
+                lines.append(f'{indent}{key}{COLON} {{}}')
+            else:
+                # Non-empty object - multiline
+                encoded_value = _encode_value(value, level + 1, opts)
+                lines.append(f'{indent}{key}{COLON}')
+                lines.append(encoded_value)
+        else:
+            # Primitive value
+            encoded_value = _encode_value(value, level + 1, opts)
+            lines.append(f'{indent}{key}{COLON} {encoded_value}')
+    
+    return NEWLINE.join(lines)
+
+
+def _encode_array(arr: list, level: int, opts: EncoderOptions) -> str:
+    """Encode an array."""
+    if not arr:
+        return '[]'
+    
+    # Check if it's a uniform array of objects (tabular format)
+    fields = is_uniform_array_of_objects(arr)
+    if fields:
+        return _encode_tabular_array(arr, fields, level, opts, key=None)
+    
+    # Check if all elements are primitives (inline format)
+    if all(is_primitive(item) for item in arr):
+        return _encode_primitive_array(arr, opts)
+    
+    # Mixed array (list format)
+    return _encode_list_array(arr, level, opts, key=None)
+
+
+def _encode_array_with_key(key: str, arr: list, level: int, opts: EncoderOptions) -> str:
+    """Encode an array with its key prefix for object context."""
+    if not arr:
+        return '[]'
+    
+    indent = get_indent(level, opts.indent)
+    
+    # Check if it's a uniform array of objects (tabular format)
+    fields = is_uniform_array_of_objects(arr)
+    if fields:
+        return _encode_tabular_array(arr, fields, level, opts, key=key)
+    
+    # Check if all elements are primitives (inline format)
+    if all(is_primitive(item) for item in arr):
+        return _encode_primitive_array(arr, opts)
+    
+    # Mixed array (list format)
+    return _encode_list_array(arr, level, opts, key=key)
+
+
+
+def _encode_primitive_array(arr: list, opts: EncoderOptions) -> str:
+    """Encode an array of primitives as inline values."""
+    encoded_values = []
+    for item in arr:
+        if item is None:
+            encoded_values.append('null')
+        elif isinstance(item, bool):
+            encoded_values.append('true' if item else 'false')
+        elif isinstance(item, (int, float)):
+            if isinstance(item, float) and (item != item or item == float('inf') or item == float('-inf')):
+                encoded_values.append('null')
+            else:
+                encoded_values.append(str(item))
+        elif isinstance(item, str):
+            if needs_quoting(item):
+                encoded_values.append(quote_string(item))
+            else:
+                encoded_values.append(item)
+    
+    return f'[{opts.delimiter.join(encoded_values)}]'
+
+
+def _encode_tabular_array(arr: list, fields: list, level: int, opts: EncoderOptions, key: Optional[str] = None) -> str:
+    """Encode a uniform array of objects in tabular format."""
+    indent = get_indent(level, opts.indent)
+    
+    # Header: [N]{field1,field2,...}: or key[N]{field1,field2,...}:
+    if key:
+        header = f'{indent}{key}[{len(arr)}]{LEFT_BRACE}{COMMA.join(fields)}{RIGHT_BRACE}{COLON}'
+    else:
+        header = f'[{len(arr)}]{LEFT_BRACE}{COMMA.join(fields)}{RIGHT_BRACE}{COLON}'
+    
+    lines = [header]
+    
+    # Rows: indented values separated by delimiter
+    for obj in arr:
+        row_values = []
+        for field in fields:
+            value = obj.get(field)
+            encoded = _encode_primitive_value(value)
+            row_values.append(encoded)
+        
+        row = opts.delimiter.join(row_values)
+        lines.append(f'{indent}  {row}')
+    
+    return NEWLINE.join(lines)
+
+
+def _encode_primitive_value(value: Any) -> str:
+    """Encode a primitive value for use in arrays."""
+    if value is None:
+        return 'null'
+    elif isinstance(value, bool):
+        return 'true' if value else 'false'
+    elif isinstance(value, (int, float)):
+        if isinstance(value, float) and (value != value or value == float('inf') or value == float('-inf')):
+            return 'null'
+        return str(value)
+    elif isinstance(value, str):
+        if needs_quoting(value):
+            return quote_string(value)
+        return value
+    else:
+        return 'null'
+
+
+def _encode_list_array(arr: list, level: int, opts: EncoderOptions, key: Optional[str] = None) -> str:
+    """Encode a non-uniform array in list format."""
+    indent = get_indent(level, opts.indent)
+    
+    # Header: [N]: or key[N]:
+    if key:
+        header = f'{indent}{key}[{len(arr)}]{COLON}'
+    else:
+        header = f'[{len(arr)}]{COLON}'
+    
+    lines = [header]
+    
+    # Items: indented encoded values
+    for item in arr:
+        encoded = _encode_value(item, level + 1, opts)
+        if NEWLINE in encoded:
+            lines.append(encoded)
+        else:
+            lines.append(f'{indent}  {encoded}')
+    
+    return NEWLINE.join(lines)
+
+
+def _apply_key_folding(obj: dict, max_depth: Optional[int] = None) -> dict:
+    """
+    Apply key folding to collapse single-key chains into dotted paths.
+    
+    Args:
+        obj: Object to fold
+        max_depth: Maximum depth for folding (None = unlimited)
+        
+    Returns:
+        Folded object
+    """
+    result = {}
+    
+    for key, value in obj.items():
+        if isinstance(value, dict) and len(value) == 1:
+            # Single-key object - check if we can fold
+            nested_key = list(value.keys())[0]
+            nested_value = value[nested_key]
+            
+            # Calculate current depth
+            depth = 1
+            current = nested_value
+            while isinstance(current, dict) and len(current) == 1 and (max_depth is None or depth < max_depth):
+                depth += 1
+                current = list(current.values())[0]
+            
+            # Fold if within depth limit
+            if max_depth is None or depth <= max_depth:
+                folded_key = f'{key}.{nested_key}'
+                # Recursively fold
+                if isinstance(nested_value, dict) and len(nested_value) == 1:
+                    folded = _apply_key_folding({nested_key: nested_value}, max_depth)
+                    for fk, fv in folded.items():
+                        result[f'{key}.{fk}'] = fv
+                else:
+                    result[folded_key] = nested_value
+            else:
+                result[key] = value
+        else:
+            result[key] = value
+    
+    return result

toon/utils.py

@@ -0,0 +1,243 @@
+"""Utility functions for the TOON library."""
+from typing import Any, Optional
+from .constants import (
+    QUOTE, BACKSLASH, NEWLINE, COMMA, TAB, PIPE,
+    TRUE_LITERAL, FALSE_LITERAL, NULL_LITERAL,
+    SPACE, COLON
+)
+
+
+def needs_quoting(value: str) -> bool:
+    """
+    Check if a string value needs to be quoted.
+    
+    Quoting is needed when:
+    - Value contains special characters (comma, colon, newline, quotes)
+    - Value has leading or trailing whitespace
+    - Value looks like a boolean or null literal
+    - Value is empty
+    
+    Args:
+        value: String to check
+        
+    Returns:
+        True if quoting is needed, False otherwise
+    """
+    if not value:
+        return True
+    
+    # Check for leading/trailing whitespace
+    if value != value.strip():
+        return True
+    
+    # Check if it looks like a literal
+    lower_value = value.lower()
+    if lower_value in (TRUE_LITERAL, FALSE_LITERAL, NULL_LITERAL):
+        return True
+    
+    # Check for special characters
+    special_chars = {COMMA, COLON, NEWLINE, QUOTE, TAB, PIPE, BACKSLASH, '[', ']', '{', '}'}
+    if any(char in value for char in special_chars):
+        return True
+    
+    # Check if it looks like a number but has trailing content
+    # This handles cases like "123abc" which should be quoted
+    try:
+        float(value)
+        return False
+    except ValueError:
+        pass
+    
+    return False
+
+
+def escape_string(value: str) -> str:
+    """
+    Escape special characters in a string for TOON encoding.
+    
+    Args:
+        value: String to escape
+        
+    Returns:
+        Escaped string
+    """
+    # Escape backslashes first
+    value = value.replace(BACKSLASH, BACKSLASH + BACKSLASH)
+    # Escape quotes
+    value = value.replace(QUOTE, BACKSLASH + QUOTE)
+    # Escape newlines
+    value = value.replace(NEWLINE, BACKSLASH + 'n')
+    # Escape tabs
+    value = value.replace('\t', BACKSLASH + 't')
+    # Escape carriage returns
+    value = value.replace('\r', BACKSLASH + 'r')
+    return value
+
+
+def unescape_string(value: str) -> str:
+    """
+    Unescape special characters in a TOON string.
+    
+    Args:
+        value: Escaped string
+        
+    Returns:
+        Unescaped string
+    """
+    result = []
+    i = 0
+    while i < len(value):
+        if value[i] == BACKSLASH and i + 1 < len(value):
+            next_char = value[i + 1]
+            if next_char == 'n':
+                result.append(NEWLINE)
+                i += 2
+            elif next_char == 't':
+                result.append('\t')
+                i += 2
+            elif next_char == 'r':
+                result.append('\r')
+                i += 2
+            elif next_char == QUOTE:
+                result.append(QUOTE)
+                i += 2
+            elif next_char == BACKSLASH:
+                result.append(BACKSLASH)
+                i += 2
+            else:
+                result.append(value[i])
+                i += 1
+        else:
+            result.append(value[i])
+            i += 1
+    return ''.join(result)
+
+
+def quote_string(value: str) -> str:
+    """
+    Quote and escape a string for TOON encoding.
+    
+    Args:
+        value: String to quote
+        
+    Returns:
+        Quoted and escaped string
+    """
+    escaped = escape_string(value)
+    return f'{QUOTE}{escaped}{QUOTE}'
+
+
+def is_primitive(value: Any) -> bool:
+    """
+    Check if a value is a primitive type (str, int, float, bool, None).
+    
+    Args:
+        value: Value to check
+        
+    Returns:
+        True if primitive, False otherwise
+    """
+    return isinstance(value, (str, int, float, bool, type(None)))
+
+
+def is_array_of_objects(value: Any) -> bool:
+    """
+    Check if a value is an array of objects (list of dicts).
+    
+    Args:
+        value: Value to check
+        
+    Returns:
+        True if array of objects, False otherwise
+    """
+    if not isinstance(value, list) or not value:
+        return False
+    return all(isinstance(item, dict) for item in value)
+
+
+def is_uniform_array_of_objects(value: list) -> Optional[list]:
+    """
+    Check if an array contains objects with identical primitive fields.
+    
+    Args:
+        value: Array to check
+        
+    Returns:
+        List of field names if uniform, None otherwise
+    """
+    if not value or not all(isinstance(item, dict) for item in value):
+        return None
+    
+    # Get fields from first object
+    first_obj = value[0]
+    fields = []
+    
+    for key, val in first_obj.items():
+        if is_primitive(val):
+            fields.append(key)
+    
+    if not fields:
+        return None
+    
+    # Check all objects have the same primitive fields
+    for obj in value[1:]:
+        obj_fields = [k for k, v in obj.items() if is_primitive(v)]
+        if set(obj_fields) != set(fields):
+            return None
+    
+    return fields
+
+
+def get_indent(level: int, indent_size: int = 2) -> str:
+    """
+    Get indentation string for a given level.
+    
+    Args:
+        level: Indentation level
+        indent_size: Number of spaces per level
+        
+    Returns:
+        Indentation string
+    """
+    return SPACE * (level * indent_size)
+
+
+def parse_number(value: str) -> Any:
+    """
+    Parse a string as a number (int or float).
+    
+    Args:
+        value: String to parse
+        
+    Returns:
+        Parsed number or original string if not a number
+    """
+    try:
+        # Try integer first
+        if '.' not in value and 'e' not in value.lower():
+            return int(value)
+        # Try float
+        return float(value)
+    except ValueError:
+        return value
+
+
+def parse_literal(value: str) -> Any:
+    """
+    Parse a string as a boolean, null, or number literal.
+    
+    Args:
+        value: String to parse
+        
+    Returns:
+        Parsed value or original string if not a literal
+    """
+    lower_value = value.lower()
+    if lower_value == TRUE_LITERAL:
+        return True
+    elif lower_value == FALSE_LITERAL:
+        return False
+    elif lower_value == NULL_LITERAL:
+        return None
+    else:
+        return parse_number(value)