griptape-nodes 0.59.3__py3-none-any.whl → 0.60.0__py3-none-any.whl

griptape_nodes/common/macro_parser/parsing.py

@@ -0,0 +1,172 @@
+"""Parsing logic for macro templates."""
+
+from __future__ import annotations
+
+import re
+
+from griptape_nodes.common.macro_parser.exceptions import MacroSyntaxError
+from griptape_nodes.common.macro_parser.formats import (
+    FORMAT_REGISTRY,
+    DateFormat,
+    FormatSpec,
+    NumericPaddingFormat,
+    SeparatorFormat,
+)
+from griptape_nodes.common.macro_parser.segments import (
+    ParsedSegment,
+    ParsedStaticValue,
+    ParsedVariable,
+    VariableInfo,
+)
+
+
+def parse_segments(template: str) -> list[ParsedSegment]:
+    """Parse template into alternating static/variable segments.
+
+    Args:
+        template: Template string to parse
+
+    Returns:
+        List of ParsedSegment (static and variable)
+
+    Raises:
+        MacroSyntaxError: If template syntax is invalid
+    """
+    segments: list[ParsedSegment] = []
+    current_pos = 0
+
+    while current_pos < len(template):
+        # Find next opening brace
+        brace_start = template.find("{", current_pos)
+
+        if brace_start == -1:
+            # No more variables, rest is static text
+            static_text = template[current_pos:]
+            if static_text:
+                # Check for unmatched closing braces in remaining text
+                if "}" in static_text:
+                    closing_pos = current_pos + static_text.index("}")
+                    msg = f"Unmatched closing brace at position {closing_pos}"
+                    raise MacroSyntaxError(msg)
+                segments.append(ParsedStaticValue(text=static_text))
+            break
+
+        # Add static text before the brace (if any)
+        if brace_start > current_pos:
+            static_text = template[current_pos:brace_start]
+            # Check for unmatched closing braces in static text
+            if "}" in static_text:
+                closing_pos = current_pos + static_text.index("}")
+                msg = f"Unmatched closing brace at position {closing_pos}"
+                raise MacroSyntaxError(msg)
+            segments.append(ParsedStaticValue(text=static_text))
+
+        # Find matching closing brace
+        brace_end = template.find("}", brace_start)
+        if brace_end == -1:
+            msg = f"Unclosed brace at position {brace_start}"
+            raise MacroSyntaxError(msg)
+
+        # Check for nested braces (opening brace before closing brace)
+        next_open = template.find("{", brace_start + 1)
+        if next_open != -1 and next_open < brace_end:
+            msg = f"Nested braces are not allowed at position {next_open}"
+            raise MacroSyntaxError(msg)
+
+        # Extract and parse the variable content
+        variable_content = template[brace_start + 1 : brace_end]
+        if not variable_content:
+            msg = f"Empty variable at position {brace_start}"
+            raise MacroSyntaxError(msg)
+
+        variable = parse_variable(variable_content)
+        segments.append(variable)
+
+        # Move past the closing brace
+        current_pos = brace_end + 1
+
+    return segments
+
+
+def parse_variable(variable_content: str) -> ParsedVariable:
+    """Parse a variable from its content (text between braces).
+
+    Args:
+        variable_content: Content between braces (e.g., "workflow_name?:_:lower")
+
+    Returns:
+        ParsedVariable with name, format specs, and default value
+
+    Raises:
+        MacroSyntaxError: If variable syntax is invalid
+    """
+    # Parse variable content: name[?][:format[:format...]][|default]
+
+    # Check for default value (|)
+    default_value = None
+    if "|" in variable_content:
+        parts = variable_content.split("|", 1)
+        variable_content = parts[0]
+        default_value = parts[1]
+
+    # Check for format specifiers (:)
+    format_specs: list[FormatSpec] = []
+    if ":" in variable_content:
+        parts = variable_content.split(":")
+        variable_part = parts[0]
+        format_parts = parts[1:]
+
+        # Parse format specifiers
+        for format_part in format_parts:
+            format_spec = parse_format_spec(format_part)
+            format_specs.append(format_spec)
+    else:
+        variable_part = variable_content
+
+    # Check for optional marker (?)
+    if variable_part.endswith("?"):
+        name = variable_part[:-1]
+        is_required = False
+    else:
+        name = variable_part
+        is_required = True
+
+    info = VariableInfo(name=name, is_required=is_required)
+    return ParsedVariable(info=info, format_specs=format_specs, default_value=default_value)
+
+
+def parse_format_spec(format_text: str) -> FormatSpec:
+    """Parse a single format specifier.
+
+    Args:
+        format_text: Format specifier text (e.g., "lower", "03", "_")
+
+    Returns:
+        Appropriate FormatSpec subclass instance
+
+    Raises:
+        MacroSyntaxError: If format specifier is invalid
+    """
+    # Remove quotes if present (for explicit separators like 'lower')
+    if format_text.startswith("'") and format_text.endswith("'"):
+        # Quoted text is always a separator, even if it matches other keywords
+        return SeparatorFormat(separator=format_text[1:-1])
+
+    # Check for date format (starts with %)
+    if format_text.startswith("%"):
+        # Date format pattern like %Y-%m-%d
+        return DateFormat(pattern=format_text)
+
+    # Check for numeric padding (e.g., "03", "04")
+    if re.match(r"^\d+$", format_text):
+        width = int(format_text)
+        # Numeric padding like 03 means pad to 3 digits with zeros
+        return NumericPaddingFormat(width=width)
+
+    # Check for known transformations
+    if format_text in FORMAT_REGISTRY:
+        # Known transformation keyword (lower, upper, slug)
+        return FORMAT_REGISTRY[format_text]
+
+    # Otherwise, treat as separator (unquoted text that doesn't match any format)
+    return SeparatorFormat(separator=format_text)

griptape_nodes/common/macro_parser/resolution.py

@@ -0,0 +1,168 @@
+"""Resolution logic for macro templates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from griptape_nodes.common.macro_parser.exceptions import MacroResolutionError
+from griptape_nodes.common.macro_parser.segments import ParsedSegment, ParsedStaticValue, ParsedVariable
+
+if TYPE_CHECKING:
+    from griptape_nodes.retained_mode.managers.secrets_manager import SecretsManager
+
+
+@dataclass
+class PartiallyResolvedMacro:
+    """Result of partially resolving a macro with known variables.
+
+    Contains both resolved segments (known variables → static text) and
+    unresolved segments (unknown variables still as variables).
+    """
+
+    original_template: str
+    segments: list[ParsedSegment]
+    known_variables: dict[str, str | int]
+
+    def is_fully_resolved(self) -> bool:
+        """Check if all variables have been resolved."""
+        return all(isinstance(seg, ParsedStaticValue) for seg in self.segments)
+
+    def to_string(self) -> str:
+        """Convert to string (only valid if fully resolved)."""
+        if not self.is_fully_resolved():
+            msg = "Cannot convert partially resolved macro to string - unresolved variables remain"
+            raise MacroResolutionError(msg)
+        # All segments are ParsedStaticValue at this point
+        return "".join(seg.text for seg in self.segments if isinstance(seg, ParsedStaticValue))
+
+    def get_unresolved_variables(self) -> list[ParsedVariable]:
+        """Get list of unresolved variables."""
+        return [seg for seg in self.segments if isinstance(seg, ParsedVariable)]
+
+
+def partial_resolve(
+    template: str,
+    segments: list[ParsedSegment],
+    variables: dict[str, str | int],
+    secrets_manager: SecretsManager,
+) -> PartiallyResolvedMacro:
+    """Partially resolve the macro template with known variables.
+
+    Resolves known variables (including env vars and format specs) into static
+    text, leaving unknown variables as-is. This is the core resolution logic
+    used by both resolve() and find_matches().
+
+    Args:
+        template: Original template string
+        segments: Parsed segments from template
+        variables: Variable name -> value mapping for known variables
+        secrets_manager: SecretsManager instance for resolving env vars
+
+    Returns:
+        PartiallyResolvedMacro with resolved and unresolved segments
+
+    Raises:
+        MacroResolutionError: If:
+            - Required variable is provided but env var resolution fails
+            - Format specifier cannot be applied to value type
+    """
+    resolved_segments: list[ParsedSegment] = []
+
+    for segment in segments:
+        match segment:
+            case ParsedStaticValue():
+                resolved_segments.append(segment)
+            case ParsedVariable():
+                if segment.info.name in variables:
+                    # Known variable - resolve it
+                    resolved_value = resolve_variable(segment, variables, secrets_manager)
+                    if resolved_value is not None:
+                        # Variable was resolved, add as static
+                        resolved_segments.append(ParsedStaticValue(text=resolved_value))
+                    # else: Optional variable provided as None, skip it
+                    continue
+
+                if segment.info.is_required:
+                    # Required variable not in variables dict - keep as unresolved
+                    resolved_segments.append(segment)
+                    continue
+
+                # Optional variable not in variables dict - skip it
+                continue
+            case _:
+                msg = f"Unexpected segment type: {type(segment).__name__}"
+                raise MacroResolutionError(msg)
+
+    return PartiallyResolvedMacro(
+        original_template=template,
+        segments=resolved_segments,
+        known_variables=variables,
+    )
+
+
+def resolve_variable(
+    variable: ParsedVariable, variables: dict[str, str | int], secrets_manager: SecretsManager
+) -> str | None:
+    """Resolve a single variable with format specs and env var resolution.
+
+    Args:
+        variable: The parsed variable to resolve
+        variables: Variable name -> value mapping
+        secrets_manager: SecretsManager instance for resolving env vars
+
+    Returns:
+        Resolved string value, or None if optional variable not provided
+
+    Raises:
+        MacroResolutionError: If required variable missing or env var not found
+    """
+    variable_name = variable.info.name
+
+    if variable_name not in variables:
+        if variable.info.is_required:
+            msg = f"Required variable '{variable_name}' not found in variables dict"
+            raise MacroResolutionError(msg)
+        # Optional variable not provided, return None to signal it should be skipped
+        return None
+
+    value = variables[variable_name]
+    resolved_value: str | int = resolve_env_var(value, secrets_manager)
+
+    for format_spec in variable.format_specs:
+        resolved_value = format_spec.apply(resolved_value)
+
+    # Return fully resolved value as string
+    return str(resolved_value)
+
+
+def resolve_env_var(value: str | int, secrets_manager: SecretsManager) -> str | int:
+    """Resolve environment variables in a value.
+
+    Args:
+        value: Value that may contain env var reference (e.g., "$VAR")
+        secrets_manager: SecretsManager instance for resolving env vars
+
+    Returns:
+        Resolved value (env var substituted if found)
+
+    Raises:
+        MacroResolutionError: If value starts with $ but env var not found
+    """
+    if not isinstance(value, str):
+        # Integer values don't contain env vars, return as-is
+        return value
+
+    if not value.startswith("$"):
+        # String doesn't reference an env var, return as-is
+        return value
+
+    env_var_name = value[1:]
+    env_value = secrets_manager.get_secret(env_var_name, should_error_on_not_found=False)
+
+    if env_value is None:
+        msg = f"Environment variable '{env_var_name}' not found"
+        raise MacroResolutionError(msg)
+
+    # Return resolved env var value
+    return env_value

griptape_nodes/common/macro_parser/segments.py

@@ -0,0 +1,42 @@
+"""Segment classes for representing parsed macro templates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NamedTuple
+
+if TYPE_CHECKING:
+    from griptape_nodes.common.macro_parser.formats import FormatSpec
+
+
+class VariableInfo(NamedTuple):
+    """Metadata about a variable in a macro template.
+
+    Attributes:
+        name: Variable name (e.g., "workflow_name", "file_name")
+        is_required: True if variable is required (not marked with ?)
+    """
+
+    name: str
+    is_required: bool
+
+
+@dataclass
+class ParsedSegment:
+    """Base class for template segments."""
+
+
+@dataclass
+class ParsedStaticValue(ParsedSegment):
+    """Static text segment in template."""
+
+    text: str
+
+
+@dataclass
+class ParsedVariable(ParsedSegment):
+    """Variable segment in template."""
+
+    info: VariableInfo  # name + is_required
+    format_specs: list[FormatSpec]  # Applied in order during resolution
+    default_value: str | None  # From {var|default} syntax