claude19

Author: bdowning

sql_athame/base.py

@@ -23,6 +23,14 @@
 
 
 def auto_numbered(field_name):
+    """Check if a field name should be auto-numbered.
+    
+    Args:
+        field_name: The field name to check
+        
+    Returns:
+        True if the field name should be auto-numbered (doesn't start with alphanumeric)
+    """
     return not auto_numbered_re.match(field_name)
 
 
@@ -31,6 +39,16 @@ def process_slot_value(
     value: Any,
     placeholders: dict[str, Placeholder],
 ) -> Union["Fragment", Placeholder]:
+    """Process a slot value during fragment compilation.
+    
+    Args:
+        name: The slot name
+        value: The value to process
+        placeholders: Dictionary of existing placeholders
+        
+    Returns:
+        Either a Fragment if value is a Fragment, or a Placeholder
+    """
     if isinstance(value, Fragment):
         return value
     else:
@@ -41,17 +59,64 @@ def process_slot_value(
 
 @dataclasses.dataclass
 class Fragment:
+    """Core SQL fragment class representing a piece of SQL with placeholders.
+    
+    A Fragment contains SQL text and placeholders that can be combined with other
+    fragments to build complex queries. Fragments automatically handle parameter
+    binding and can be rendered to parameterized queries suitable for database drivers.
+    
+    Attributes:
+        parts: List of SQL parts (strings, placeholders, slots, or other fragments)
+        
+    Example:
+        >>> from sql_athame import sql
+        >>> frag = sql("SELECT * FROM users WHERE id = {}", 42)
+        >>> query, params = frag.query()
+        >>> query
+        'SELECT * FROM users WHERE id = $1'
+        >>> params
+        [42]
+        
+        >>> # Fragments can be combined
+        >>> where_clause = sql("active = {}", True)
+        >>> full_query = sql("SELECT * FROM users WHERE id = {} AND {}", 42, where_clause)
+        >>> list(full_query)
+        ['SELECT * FROM users WHERE id = $1 AND active = $2', 42, True]
+    """
     __slots__ = ["parts"]
     parts: list[Part]
 
     def flatten_into(self, parts: list[FlatPart]) -> None:
+        """Recursively flatten this fragment into a list of flat parts.
+        
+        This method traverses nested fragments and adds all parts to the provided list.
+        String parts are not combined here - that's done in flatten().
+        
+        Args:
+            parts: List to append flattened parts to
+        """
         for part in self.parts:
             if isinstance(part, Fragment):
                 part.flatten_into(parts)
             else:
                 parts.append(part)
 
     def compile(self) -> Callable[..., "Fragment"]:
+        """Create an optimized function for filling slots in this fragment.
+        
+        Returns a compiled function that when called with **kwargs will create a new
+        Fragment equivalent to calling self.fill(**kwargs). The compilation process
+        does as much work as possible up front, making repeated slot filling much faster.
+        
+        Returns:
+            Function that takes **kwargs and returns a Fragment with slots filled
+            
+        Example:
+            >>> template = sql("SELECT * FROM users WHERE name = {name} AND age > {age}")
+            >>> compiled_template = template.compile()
+            >>> query1 = compiled_template(name="Alice", age=25)
+            >>> query2 = compiled_template(name="Bob", age=30)
+        """
         flattened = self.flatten()
         env = dict(
             process_slot_value=process_slot_value,
@@ -77,6 +142,14 @@ def compile(self) -> Callable[..., "Fragment"]:
         return env["compiled"]  # type: ignore
 
     def flatten(self) -> "Fragment":
+        """Create a flattened version of this fragment.
+        
+        Recursively flattens all nested fragments and combines adjacent string parts
+        into single strings for efficiency.
+        
+        Returns:
+            New Fragment with no nested fragments and adjacent strings combined
+        """
         parts: list[FlatPart] = []
         self.flatten_into(parts)
         out_parts: list[Part] = []
@@ -88,6 +161,24 @@ def flatten(self) -> "Fragment":
         return Fragment(out_parts)
 
     def fill(self, **kwargs: Any) -> "Fragment":
+        """Create a new fragment by filling any empty slots with provided values.
+        
+        Searches for Slot objects in this fragment and replaces them with the
+        corresponding values from kwargs. If a value is a Fragment, it's substituted
+        in-place; otherwise it becomes a placeholder.
+        
+        Args:
+            **kwargs: Named values to fill into slots
+            
+        Returns:
+            New Fragment with slots filled
+            
+        Example:
+            >>> template = sql("SELECT * FROM {table} WHERE id = {id}")
+            >>> query = template.fill(table=sql.identifier("users"), id=42)
+            >>> list(query)
+            ['SELECT * FROM "users" WHERE id = $1', 42]
+        """
         parts: list[Part] = []
         self.flatten_into(cast(list[FlatPart], parts))
         placeholders: dict[str, Placeholder] = {}
@@ -109,6 +200,20 @@ def prep_query(
     ) -> tuple[str, list[Placeholder]]: ...  # pragma: no cover
 
     def prep_query(self, allow_slots: bool = False) -> tuple[str, list[Any]]:
+        """Prepare the fragment for query execution.
+        
+        Flattens the fragment and converts placeholders to numbered parameters ($1, $2, etc.)
+        suitable for database drivers like asyncpg.
+        
+        Args:
+            allow_slots: If True, allows unfilled slots; if False, raises ValueError for unfilled slots
+            
+        Returns:
+            Tuple of (query_string, parameter_objects)
+            
+        Raises:
+            ValueError: If allow_slots is False and there are unfilled slots
+        """
         parts: list[FlatPart] = []
         self.flatten_into(parts)
         args: list[Union[Placeholder, Slot]] = []
@@ -134,14 +239,63 @@ def prep_query(self, allow_slots: bool = False) -> tuple[str, list[Any]]:
         return "".join(out_parts).strip(), args
 
     def query(self) -> tuple[str, list[Any]]:
+        """Render the fragment into a query string and parameter list.
+        
+        Returns:
+            Tuple of (query_string, parameter_values) ready for database execution
+            
+        Raises:
+            ValueError: If there are any unfilled slots
+            
+        Example:
+            >>> frag = sql("SELECT * FROM users WHERE id = {}", 42)
+            >>> frag.query()
+            ('SELECT * FROM users WHERE id = $1', [42])
+        """
         query, args = self.prep_query()
         placeholder_values = [arg.value for arg in args]
         return query, placeholder_values
 
     def sqlalchemy_text(self) -> Any:
+        """Convert this fragment to a SQLAlchemy TextClause.
+        
+        Renders the fragment into a SQLAlchemy TextClause with bound parameters.
+        Placeholder values will be bound with bindparams. Unfilled slots will be
+        included as unbound parameters.
+        
+        Returns:
+            SQLAlchemy TextClause object
+            
+        Raises:
+            ImportError: If SQLAlchemy is not installed
+            
+        Example:
+            >>> frag = sql("SELECT * FROM users WHERE id = {}", 42)
+            >>> text_clause = frag.sqlalchemy_text()
+            >>> # Can be used with SQLAlchemy engine.execute(text_clause)
+        """
         return sqlalchemy_text_from_fragment(self)
 
     def prepare(self) -> tuple[str, Callable[..., list[Any]]]:
+        """Prepare fragment for use with prepared statements.
+        
+        Returns a query string and a function that generates parameter lists.
+        The query string contains numbered placeholders, and the function takes
+        **kwargs for any unfilled slots and returns the complete parameter list.
+        
+        Returns:
+            Tuple of (query_string, parameter_generator_function)
+            
+        Example:
+            >>> template = sql("UPDATE users SET name={name}, age={age} WHERE id < {}", 100)
+            >>> query, param_func = template.prepare()
+            >>> query
+            'UPDATE users SET name=$1, age=$2 WHERE id < $3'
+            >>> param_func(name="Alice", age=25)
+            ['Alice', 25, 100]
+            >>> param_func(name="Bob", age=30)
+            ['Bob', 30, 100]
+        """
         query, args = self.prep_query(allow_slots=True)
         env = {}
         func = [
@@ -159,10 +313,47 @@ def prepare(self) -> tuple[str, Callable[..., list[Any]]]:
         return query, env["generate_args"]  # type: ignore
 
     def __iter__(self) -> Iterator[Any]:
+        """Make Fragment iterable for use with asyncpg and similar drivers.
+        
+        Returns an iterator that yields the query string followed by all parameter
+        values. This matches the (query, *args) calling convention of asyncpg.
+        
+        Yields:
+            Query string, then each parameter value
+            
+        Example:
+            >>> frag = sql("SELECT * FROM users WHERE id = {} AND name = {}", 42, "Alice")
+            >>> list(frag)
+            ['SELECT * FROM users WHERE id = $1 AND name = $2', 42, 'Alice']
+            >>> # Can be used directly with asyncpg
+            >>> await conn.fetch(*frag)
+        """
         sql, args = self.query()
         return iter((sql, *args))
 
     def join(self, parts: Iterable["Fragment"]) -> "Fragment":
+        """Join multiple fragments using this fragment as a separator.
+        
+        Creates a new fragment by joining the provided fragments with this fragment
+        as the separator between them.
+        
+        Args:
+            parts: Iterable of Fragment objects to join
+            
+        Returns:
+            New Fragment with parts joined by this fragment
+            
+        Example:
+            >>> separator = sql(" AND ")
+            >>> conditions = [sql("a = {}", 1), sql("b = {}", 2), sql("c = {}", 3)]
+            >>> result = separator.join(conditions)
+            >>> list(result)
+            ['a = $1 AND b = $2 AND c = $3', 1, 2, 3]
+            
+            >>> # More commonly used for CASE statements
+            >>> clauses = [sql("WHEN {} THEN {}", x, y) for x, y in [("a", 1), ("b", 2)]]
+            >>> case = sql("CASE {clauses} END", clauses=sql(" ").join(clauses))
+        """
         return Fragment(list(join_parts(parts, infix=self)))