claude21

Author: bdowning

sql_athame/base.py

@@ -669,10 +669,34 @@ def unnest(self, data: Iterable[Sequence[Any]], types: Iterable[str]) -> Fragmen
 
 
 def is_json_type(typename: str) -> bool:
+    """Check if a type name represents a JSON type.
+    
+    Args:
+        typename: PostgreSQL type name to check
+        
+    Returns:
+        True if typename is JSON or JSONB (case insensitive)
+    """
     return typename.upper() in json_types
 
 
 def nest_for_type(data: Sequence[Any], typename: str) -> Fragment:
+    """Create a typed array fragment for UNNEST operations.
+    
+    Converts a sequence of data into a properly typed PostgreSQL array fragment.
+    Handles JSON/JSONB types specially by converting objects to JSON strings.
+    
+    Args:
+        data: Sequence of values to convert to array
+        typename: PostgreSQL type name for the array
+        
+    Returns:
+        Fragment containing a typed array placeholder
+        
+    Note:
+        For JSON/JSONB types, non-string values are converted to JSON strings
+        to work around asyncpg limitations.
+    """
     if is_json_type(typename):
         # https://github.com/MagicStack/asyncpg/issues/345
 
@@ -689,10 +713,33 @@ def nest_for_type(data: Sequence[Any], typename: str) -> Fragment:
 
 
 def lit(text: str) -> Fragment:
+    """Create a Fragment containing literal SQL text.
+    
+    Convenience function equivalent to Fragment([text]).
+    
+    Args:
+        text: Literal SQL text
+        
+    Returns:
+        Fragment containing the literal text
+    """
     return Fragment([text])
 
 
 def any_all(frags: list[Fragment], op: str, base_case: str) -> Fragment:
+    """Join fragments with a logical operator, with a base case for empty lists.
+    
+    Used by sql.all() and sql.any() to implement AND/OR joining with appropriate
+    base cases (TRUE for AND, FALSE for OR).
+    
+    Args:
+        frags: List of fragments to join
+        op: Operator to use for joining ("AND" or "OR")
+        base_case: Value to return if frags is empty ("TRUE" or "FALSE")
+        
+    Returns:
+        Fragment with fragments joined by operator, or base case if empty
+    """
     if not frags:
         return lit(base_case)
     parts = join_parts(frags, prefix="(", infix=f") {op} (", suffix=")")
@@ -705,6 +752,20 @@ def join_parts(
     prefix: Optional[Part] = None,
     suffix: Optional[Part] = None,
 ) -> Iterator[Part]:
+    """Join parts with a separator, optionally adding prefix and suffix.
+    
+    Generator function that yields parts with infix separators between them,
+    and optional prefix/suffix parts.
+    
+    Args:
+        parts: Parts to join
+        infix: Separator to place between parts
+        prefix: Optional part to yield first
+        suffix: Optional part to yield last
+        
+    Yields:
+        Parts with separators, prefix, and suffix as appropriate
+    """
     if prefix:
         yield prefix
     for i, part in enumerate(parts):
@@ -716,5 +777,19 @@ def join_parts(
 
 
 def quote_identifier(name: str) -> str:
+    """Quote a SQL identifier with double quotes, escaping internal quotes.
+    
+    Args:
+        name: Identifier name to quote
+        
+    Returns:
+        Quoted identifier with internal quotes escaped
+        
+    Example:
+        >>> quote_identifier("user_name")
+        '"user_name"'
+        >>> quote_identifier('table"with"quotes')
+        '"table""with""quotes"'
+    """
     quoted = name.replace('"', '""')
     return f'"{quoted}"'