alphapil 0.1.0__py3-none-any.whl

alphapil/__init__.py

@@ -0,0 +1,24 @@
+"""
+AlphaPIL - An asynchronous, template-based image generation engine.
+
+This package provides a powerful recursive parser for handling nested functions
+in image generation templates, with support for asynchronous operations.
+"""
+
+__version__ = "0.1.0"
+__author__ = "AlphaPIL Team"
+
+from .engine import CanvasEngine
+from .interpreter import CanvasInterpreter
+from .modules import AlphaMixin, ShapesMixin, TextMixin, ImagesMixin, UtilsMixin, MaskingMixin
+
+__all__ = [
+    "CanvasEngine", 
+    "CanvasInterpreter", 
+    "AlphaMixin", 
+    "ShapesMixin", 
+    "TextMixin", 
+    "ImagesMixin",
+    "UtilsMixin",
+    "MaskingMixin"
+]

alphapil/engine.py

@@ -0,0 +1,259 @@
+"""
+CanvasEngine - High-level canvas operations for AlphaPIL.
+
+This module provides the CanvasEngine class that inherits from CanvasInterpreter
+and all module mixins to provide comprehensive image generation capabilities.
+"""
+
+import io
+from typing import Tuple, Union, Optional
+from PIL import Image, ImageDraw, ImageFont
+from .interpreter import CanvasInterpreter
+from .modules import AlphaMixin, ShapesMixin, TextMixin, ImagesMixin, UtilsMixin, MaskingMixin
+
+
+class CanvasEngine(CanvasInterpreter, AlphaMixin, ShapesMixin, TextMixin, ImagesMixin, UtilsMixin, MaskingMixin):
+    """
+    High-level canvas engine that extends CanvasInterpreter with Pillow-based
+    image generation capabilities and all module mixins.
+    """
+    
+    def __init__(self):
+        """Initialize the canvas engine and register built-in functions."""
+        # Initialize all parent classes properly
+        CanvasInterpreter.__init__(self)
+        AlphaMixin.__init__(self)
+        ShapesMixin.__init__(self)
+        TextMixin.__init__(self)
+        ImagesMixin.__init__(self)
+        UtilsMixin.__init__(self)
+        MaskingMixin.__init__(self)
+        
+        # Initialize mixin states
+        self._init_state()
+        self._init_text()
+        
+        # Initialize canvas-specific attributes
+        self.canvas: Optional[Image.Image] = None
+        self.draw: Optional[ImageDraw.Draw] = None
+        self.canvas_size: Tuple[int, int] = (0, 0)
+        
+        # Register all built-in functions from modules
+        self._register_builtin_functions()
+    
+    async def render_template(self, template_text: str, data: dict = None) -> bytes:
+        """
+        Render a template with optional data injection (Async).
+        
+        Args:
+            template_text: Template content as string
+            data: Optional dictionary of variables to set
+            
+        Returns:
+            Canvas image as bytes
+            
+        Raises:
+            RuntimeError: If template rendering fails
+        """
+        try:
+            # Reset engine state
+            self.reset()
+            
+            # Inject data if provided
+            if data:
+                for key, value in data.items():
+                    self.set_variable(key, str(value))
+            
+            # Parse template line by line
+            lines = template_text.strip().split('\n')
+            for line_num, line in enumerate(lines, 1):
+                line = line.strip()
+                
+                # Skip comments and empty lines
+                if not line or line.startswith('#'):
+                    continue
+                
+                # Parse and execute the line (awaiting async parse)
+                result = await self.parse(line)
+            
+            # Return canvas as bytes
+            return self.get_canvas_bytes()
+            
+        except Exception as e:
+            raise RuntimeError(f"Template rendering failed: {e}")
+    
+    async def render_template_file(self, template_path: str, data: dict = None) -> bytes:
+        """
+        Render a template from file with optional data injection (Async).
+        
+        Args:
+            template_path: Path to template file
+            data: Optional dictionary of variables to set
+            
+        Returns:
+            Canvas image as bytes
+            
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+            RuntimeError: If template rendering fails
+        """
+        try:
+            # Use async file reading if possible, but standard open is fine for text files
+            # or could use aiofiles if dependency added. For now sync read is okay.
+            with open(template_path, 'r', encoding='utf-8') as f:
+                template_text = f.read()
+            return await self.render_template(template_text, data)
+        except FileNotFoundError:
+            raise FileNotFoundError(f"Template file not found: {template_path}")
+        except Exception as e:
+            raise RuntimeError(f"Template rendering failed: {e}")
+    
+    def _register_builtin_functions(self) -> None:
+        """Register all built-in canvas manipulation functions from all modules."""
+        # Core canvas functions
+        self.register_function("createCanvas", self._create_canvas)
+        self.register_function("save", self._save_canvas)
+        self.register_function("setVar", self._set_var)
+        
+        # State management functions
+        # State management functions - Registered at end to use new implementations
+        # self.register_function("setFont", self._set_font)
+        # self.register_function("setColor", self._set_color)
+        # self.register_function("setStroke", self._set_stroke)
+        
+        # Shape functions from ShapesMixin
+        self.register_function("drawRect", self._draw_rect)
+        self.register_function("drawCircle", self._draw_circle)
+        self.register_function("drawRoundedRect", self._draw_rounded_rect)
+        self.register_function("drawLine", self._draw_line)
+        
+        # Text functions from TextMixin
+        self.register_function("drawText", self._draw_text)
+        self.register_function("drawTextStroke", self._draw_text_stroke)
+        self.register_function("drawTextGradient", self._draw_text_gradient)
+        self.register_function("toUpper", self._to_upper)
+        self.register_function("toLower", self._to_lower)
+        self.register_function("toTitle", self._to_title)
+        self.register_function("measureText", self._measure_text)
+        self.register_function("wrapText", self._wrap_text)
+        self.register_function("autoSizeText", self._auto_size_text)
+        self.register_function("truncateText", self._truncate_text)
+        self.register_function("drawTextMid", self._draw_text_mid)
+        self.register_function("drawTextIn", self._draw_text_in)
+        
+        # Image functions from ImagesMixin
+        self.register_function("drawImage", self._draw_image)
+        self.register_function("useImageAsCanvas", self._use_image_as_canvas)
+        self.register_function("imageFilter", self._image_filter)
+        self.register_function("clearImageCache", self.clear_image_cache)
+        
+        # Utility functions from UtilsMixin
+        self.register_function("math", self._math)
+        self.register_function("if", self._if)
+        self.register_function("random", self._random)
+        self.register_function("getHex", self._get_hex)
+        self.register_function("replace", self._replace)
+        self.register_function("length", self._length)
+        self.register_function("substring", self._substring)
+        self.register_function("join", self._join)
+        self.register_function("split", self._split)
+
+        # Masking functions from MaskingMixin
+        self.register_function("createLayer", self._create_layer)
+        self.register_function("switchLayer", self._switch_layer)
+        self.register_function("mergeLayer", self._merge_layer)
+        self.register_function("applyMask", self._apply_mask)
+
+        # State management commands
+        self.register_function("setFont", self._cmd_set_font)
+        self.register_function("loadFont", self._load_font)
+        self.register_function("setColor", self._cmd_set_color)
+        self.register_function("setStroke", self._cmd_set_stroke)
+    
+    def _create_canvas(self, width: str, height: str, color: str = "white") -> str:
+        """
+        Create a new canvas with specified dimensions and background color.
+        
+        Args:
+            width: Canvas width as string
+            height: Canvas height as string  
+            color: Background color (default: "white")
+            
+        Returns:
+            Confirmation message
+        """
+        try:
+            w = int(width)
+            h = int(height)
+            self.canvas_size = (w, h)
+            
+            # Parse color using the helper from AlphaMixin
+            bg_color = self._get_color(color) or (255, 255, 255)
+            
+            self.canvas = Image.new("RGB", (w, h), bg_color)
+            self.draw = ImageDraw.Draw(self.canvas)
+            return f"Canvas created: {w}x{h}"
+        except ValueError as e:
+            raise ValueError(f"Invalid canvas dimensions: {e}")
+    
+    def _set_var(self, name: str, value: str) -> str:
+        """
+        Set a variable value.
+        
+        Args:
+            name: Variable name (without {} wrapper)
+            value: Variable value
+            
+        Returns:
+            Confirmation message
+        """
+        self.set_variable(name, value)
+        return f"Variable {name} set to {value}"
+    
+    def _save_canvas(self, filename: str = "output.png") -> str:
+        """
+        Save the current canvas to a file with maximum quality.
+        """
+        if not self.canvas:
+            raise RuntimeError("No canvas to save. Call $createCanvas first.")
+        
+        try:
+            # Set high quality parameters for various formats
+            save_params = {"optimize": True}
+            if filename.lower().endswith(('.jpg', '.jpeg')):
+                save_params.update({"quality": 100, "subsampling": 0})
+            
+            self.canvas.save(filename, **save_params)
+            return f"Canvas saved as {filename}"
+        except Exception as e:
+            raise RuntimeError(f"Failed to save canvas: {e}")
+    
+    def get_canvas_bytes(self, format: str = "PNG") -> bytes:
+        """
+        Get the canvas as bytes with maximum quality.
+        """
+        if not self.canvas:
+            raise RuntimeError("No canvas available. Call $createCanvas first.")
+        
+        img_bytes = io.BytesIO()
+        
+        # Set high quality parameters
+        save_params = {"format": format, "optimize": True}
+        if format.upper() in ["JPEG", "JPG"]:
+            save_params.update({"quality": 100, "subsampling": 0})
+            
+        self.canvas.save(img_bytes, **save_params)
+        img_bytes.seek(0)
+        return img_bytes.getvalue()
+    
+    def reset(self) -> None:
+        """Reset the canvas, drawing context, and state."""
+        self.canvas = None
+        self.draw = None
+        self.canvas_size = (0, 0)
+        self._init_state()
+        self._init_text()
+        if hasattr(self, '_image_cache'):
+            self._image_cache.clear()
+            
+    # State management is now handled via AlphaMixin _cmd_* methods

alphapil/interpreter.py

@@ -0,0 +1,342 @@
+"""
+CanvasInterpreter - Core recursive parser for AlphaPIL.
+
+This module provides the fundamental parsing logic for handling nested functions
+using a while loop and re.search pattern matching.
+"""
+
+import re
+import asyncio
+import inspect
+from typing import Any, Dict, List, Optional, Callable
+
+
+class CanvasInterpreter:
+    """
+    Core interpreter class that handles recursive parsing of nested functions.
+    
+    The parser resolves functions from inside-out using a while loop with re.search
+    to find and replace nested function calls until no more patterns remain.
+    """
+    
+    def __init__(self):
+        """Initialize the interpreter with an empty function registry."""
+        self.functions: Dict[str, Callable] = {}
+        self.variables: Dict[str, Any] = {}
+    
+    def register_function(self, name: str, func: Callable) -> None:
+        """
+        Register a function that can be called in templates.
+        
+        Args:
+            name: Function name (without $ prefix)
+            func: Callable that will be executed when the function is encountered
+        """
+        self.functions[name] = func
+    
+    def set_variable(self, name: str, value: Any) -> None:
+        """
+        Set a variable that can be used in templates.
+        
+        Args:
+            name: Variable name (without {} wrapper)
+            value: Value to assign to the variable
+        """
+        self.variables[name] = value
+    
+    def _find_innermost_function(self, text: str) -> Optional[re.Match]:
+        """
+        Find the innermost function call in the text.
+        
+        This regex pattern matches function calls like $functionName[...;...] 
+        and ensures we find the innermost nested calls first.
+        
+        Args:
+            text: Text to search for function calls
+            
+        Returns:
+            Match object if function found, None otherwise
+        """
+        # Pattern matches: $functionName[arguments]
+        # Uses negative lookahead to avoid matching nested brackets incorrectly
+        pattern = r'\$(\w+)\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]'
+        return re.search(pattern, text)
+    
+    def _parse_arguments(self, args_str: str) -> List[str]:
+        """
+        Parse function arguments, handling quoted strings and semicolon separators.
+        
+        Args:
+            args_str: String containing function arguments
+            
+        Returns:
+            List of parsed arguments
+        """
+        if not args_str.strip():
+            return []
+        
+        args = []
+        current_arg = ""
+        in_quotes = False
+        quote_char = None
+        nesting_depth = 0
+        
+        i = 0
+        while i < len(args_str):
+            char = args_str[i]
+            
+            if char in ('"', "'") and not in_quotes:
+                in_quotes = True
+                quote_char = char
+                current_arg += char
+            elif char == quote_char and in_quotes:
+                in_quotes = False
+                quote_char = None
+                current_arg += char
+            elif not in_quotes:
+                if char in ('[', '('):
+                    nesting_depth += 1
+                    current_arg += char
+                elif char in (']', ')'):
+                    nesting_depth -= 1
+                    current_arg += char
+                elif char == ';' and nesting_depth == 0:
+                    args.append(current_arg.strip())
+                    current_arg = ""
+                else:
+                    current_arg += char
+            else:
+                current_arg += char
+            
+            i += 1
+        
+        # Always append the last argument, even if empty, to ensure correct argument count
+        args.append(current_arg.strip())
+        
+        return args
+    
+    def _resolve_variables(self, text: str) -> str:
+        """
+        Resolve variable placeholders like {variable_name} in the text.
+        
+        Args:
+            text: Text containing variable placeholders
+            
+        Returns:
+            Text with variables replaced by their values
+        """
+        def replace_var(match):
+            var_name = match.group(1)
+            # Support default values: {var|default}
+            default_val = ""
+            if '|' in var_name:
+                var_name, default_val = var_name.split('|', 1)
+            
+            # Use get() with default_val (or empty string if not provided)
+            # Note: variables dict values should be strings ideally
+            val = self.variables.get(var_name, default_val)
+            return str(val) if val is not None else default_val
+        
+        # Match variables with optional |default part: {name} or {name|default}
+        # Allow any characters except closing brace inside
+        return re.sub(r'\{([^\}]+)\}', replace_var, text)
+    
+    async def _preprocess_argument(self, arg: str) -> str:
+        """
+        Recursively resolve all nested functions and variables in an argument.
+        
+        Execution order:
+        1. Variable replacement: {var} → value
+        2. Nested function evaluation: $func[...] → result (recursively)
+        
+        This ensures that expressions like $drawRect[10;10;$math[100 * 2];50;red]
+        work correctly by evaluating $math[100 * 2] → "200" before passing to _drawRect.
+        
+        Args:
+            arg: Argument string that may contain nested functions and variables
+            
+        Returns:
+            Fully resolved argument value
+        """
+        # First pass: resolve variables
+        arg = self._resolve_variables(arg)
+        
+        # Second pass: resolve nested functions recursively
+        max_iterations = 100  # Prevent infinite loops in nested functions
+        iteration = 0
+        
+        while iteration < max_iterations:
+            iteration += 1
+            match = self._find_innermost_function(arg)
+            
+            if not match:
+                break  # No more functions to resolve
+            
+            func_name = match.group(1)
+            args_str = match.group(2)
+            
+            # Recursively preprocess nested arguments
+            nested_args = self._parse_arguments(args_str)
+            
+            # Process nested arguments async
+            processed_nested_args = []
+            for a in nested_args:
+                processed_nested_args.append(await self._preprocess_argument(a))
+            
+            # Execute the function
+            if func_name not in self.functions:
+                raise ValueError(f"Unknown function: ${func_name}")
+            
+            try:
+                result = await self._execute_function(func_name, processed_nested_args)
+                # Clean up numeric results
+                if func_name in ['math', 'random', 'length', 'getHex']:
+                    result = str(result).strip()
+                else:
+                    result = str(result)
+            except Exception as e:
+                raise RuntimeError(f"Error in nested function ${func_name}: {e}")
+            
+            # Replace in original string
+            arg = arg[:match.start()] + result + arg[match.end():]
+        
+        if iteration >= max_iterations:
+            raise RuntimeError(f"Argument preprocessing exceeded maximum iterations: {arg}")
+        
+        return arg
+    
+    async def _execute_function(self, func_name: str, args: List[str]) -> str:
+        """
+        Execute a registered function with parsed arguments (Async).
+        Supports both sync and async functions, and flexible argument mapping.
+        
+        Args:
+            func_name: Name of the function to execute
+            args: List of argument strings
+            
+        Returns:
+            String result of the function execution
+        """
+        if func_name not in self.functions:
+            raise ValueError(f"Unknown function: ${func_name}")
+        
+        try:
+            func = self.functions[func_name]
+            
+            # Split into named and unnamed arguments
+            named_args = {}
+            unnamed_args = []
+            
+            for arg in args:
+                if '=' in arg and not arg.startswith(('http://', 'https://')):
+                    parts = arg.split('=', 1)
+                    key = parts[0].strip()
+                    val = parts[1].strip()
+                    
+                    # Only treat as named arg if:
+                    # 1. key is a valid identifier
+                    # 2. value doesn't start with '=' (avoids '==')
+                    # 3. key doesn't end with common comparison symbols (avoids '!=', '<=', '>=')
+                    if key.isidentifier() and not val.startswith('=') and not key.endswith(('!', '<', '>')):
+                        named_args[key] = val
+                        continue
+                unnamed_args.append(arg)
+            
+            # Use inspect to map arguments to the function signature
+            sig = inspect.signature(func)
+            params = list(sig.parameters.values())
+            
+            # Build the argument set
+            final_kwargs = {}
+            
+            # 1. Apply named arguments
+            final_kwargs.update(named_args)
+            
+            # 2. Map unnamed arguments to remaining parameters
+            unnamed_idx = 0
+            for param in params:
+                if param.name not in final_kwargs and unnamed_idx < len(unnamed_args):
+                    final_kwargs[param.name] = unnamed_args[unnamed_idx]
+                    unnamed_idx += 1
+            
+            # Execute the function - only pass arguments that exist in the function signature
+            safe_kwargs = {k: v for k, v in final_kwargs.items() if k in sig.parameters}
+            result = func(**safe_kwargs)
+            
+            # Handle async functions
+            if inspect.iscoroutine(result):
+                result = await result
+            
+            # Strip whitespace from result for numeric functions
+            if func_name in ['math', 'random', 'length', 'getHex']:
+                result = str(result).strip()
+            
+            return str(result)
+        except Exception as e:
+            # Provide more detailed error info for debugging
+            raise RuntimeError(f"Error executing function ${func_name} with args {args}: {e}")
+    
+    async def parse(self, template: str) -> str:
+        """
+        Parse a template string with correct execution order (Async).
+        
+        Execution order:
+        1. Resolve variables: {var} → value
+        2. Find innermost function
+        3. Preprocess arguments (recursively resolve variables + nested functions)
+        4. Execute function with fully resolved arguments
+        5. Replace function call with result
+        6. Repeat until no functions remain
+        
+        This ensures expressions like $drawRect[10;10;$math[100 * 2];50;red]
+        work correctly by evaluating nested $math before passing to _drawRect.
+        
+        Args:
+            template: Template string containing function calls and variables
+            
+        Returns:
+            Fully resolved template string
+        """
+        result = template
+        
+        # Main parsing loop with iteration limit to prevent infinite loops
+        max_iterations = 1000
+        iteration = 0
+        
+        while iteration < max_iterations:
+            iteration += 1
+            
+            # Step 1: Resolve variables first
+            result = self._resolve_variables(result)
+            
+            # Step 2: Find the innermost function call
+            match = self._find_innermost_function(result)
+            
+            if not match:
+                break  # No more function calls to resolve
+            
+            func_name = match.group(1)
+            args_str = match.group(2)
+            
+            # Step 3: Parse and preprocess arguments
+            # This recursively resolves all variables and nested functions in each argument
+            args = self._parse_arguments(args_str)
+            
+            # Process arguments async
+            processed_args = []
+            for arg in args:
+                processed_args.append(await self._preprocess_argument(arg))
+            
+            # Step 4: Execute function with fully resolved arguments
+            try:
+                func_result = await self._execute_function(func_name, processed_args)
+            except Exception as e:
+                raise RuntimeError(f"Failed to execute ${func_name}: {e}")
+            
+            # Step 5: Replace the function call with its result
+            result = result[:match.start()] + func_result + result[match.end():]
+        
+        if iteration >= max_iterations:
+            raise RuntimeError("Parser exceeded maximum iterations - possible infinite loop in template")
+        
+        return result

alphapil/modules/__init__.py

@@ -0,0 +1,15 @@
+"""
+AlphaPIL Modules - Modular functionality for image generation.
+
+This package contains modular components that can be easily extended
+by adding new Python files to this directory.
+"""
+
+from .base import AlphaMixin
+from .shapes import ShapesMixin
+from .text import TextMixin
+from .images import ImagesMixin
+from .utils import UtilsMixin
+from .masking import MaskingMixin
+
+__all__ = ["AlphaMixin", "ShapesMixin", "TextMixin", "ImagesMixin", "UtilsMixin", "MaskingMixin"]