claude20

Author: bdowning

sql_athame/base.py

@@ -358,9 +358,49 @@ def join(self, parts: Iterable["Fragment"]) -> "Fragment":
 
 
 class SQLFormatter:
+    """Main SQL formatting class providing the sql() function and utility methods.
+    
+    This class is instantiated as the global 'sql' object that provides the primary
+    interface for building SQL fragments. It supports format string syntax with
+    placeholders and provides utility methods for common SQL operations.
+    """
     def __call__(
         self, fmt: str, *args: Any, preserve_formatting: bool = False, **kwargs: Any
     ) -> Fragment:
+        """Create a SQL Fragment from a format string with placeholders.
+        
+        The format string contains literal SQL and may contain positional references
+        marked by {} and named references marked by {name}. Positional references
+        must have matching arguments in *args. Named references may have matching
+        arguments in **kwargs; if not provided, they remain as named slots to be
+        filled later.
+        
+        If a referenced argument is a Fragment, it is substituted into the SQL
+        along with its embedded placeholders. Otherwise, it becomes a placeholder value.
+        
+        Args:
+            fmt: SQL format string with {} placeholders
+            *args: Positional arguments for {} placeholders
+            preserve_formatting: If True, preserve whitespace; if False, normalize whitespace
+            **kwargs: Named arguments for {name} placeholders
+            
+        Returns:
+            Fragment containing the SQL with placeholders
+            
+        Raises:
+            ValueError: If there are unfilled positional arguments
+            
+        Example:
+            >>> sql("SELECT * FROM users WHERE id = {}", 42)
+            Fragment(['SELECT * FROM users WHERE id = ', Placeholder('0', 42)])
+            
+            >>> sql("SELECT * FROM users WHERE id = {id} AND name = {name}", id=42, name="Alice")
+            Fragment(['SELECT * FROM users WHERE id = ', Placeholder('id', 42), ' AND name = ', Placeholder('name', 'Alice')])
+            
+            >>> # Fragments can be embedded
+            >>> where_clause = sql("active = {}", True)
+            >>> sql("SELECT * FROM users WHERE {}", where_clause)
+        """
         if not preserve_formatting:
             fmt = newline_whitespace_re.sub(" ", fmt)
         fmtr = string.Formatter()
@@ -389,23 +429,110 @@ def __call__(
 
     @staticmethod
     def value(value: Any) -> Fragment:
+        """Create a Fragment with a single placeholder value.
+        
+        Equivalent to sql("{}", value) but more explicit.
+        
+        Args:
+            value: The value to create a placeholder for
+            
+        Returns:
+            Fragment containing a single placeholder
+            
+        Example:
+            >>> sql.value(42)
+            Fragment([Placeholder('value', 42)])
+        """
         placeholder = Placeholder("value", value)
         return Fragment([placeholder])
 
     @staticmethod
     def escape(value: Any) -> Fragment:
+        """Create a Fragment with a value escaped and embedded into the SQL.
+        
+        Unlike placeholders, escaped values are embedded directly into the SQL text.
+        Types currently supported are strings, floats, ints, UUIDs, None, and
+        sequences of the above. Use with caution and only for trusted values.
+        
+        Args:
+            value: The value to escape and embed
+            
+        Returns:
+            Fragment with the escaped value as literal SQL
+            
+        Example:
+            >>> list(sql("SELECT * FROM tbl WHERE qty = ANY({})", sql.escape([1, 3, 5])))
+            ['SELECT * FROM tbl WHERE qty = ANY(ARRAY[1, 3, 5])']
+            
+            >>> # Compare to placeholder version:
+            >>> list(sql("SELECT * FROM tbl WHERE qty = ANY({})", [1, 3, 5]))
+            ['SELECT * FROM tbl WHERE qty = ANY($1)', [1, 3, 5]]
+            
+        Note:
+            Burning invariant values into the query can potentially help the query optimizer.
+        """
         return lit(escape(value))
 
     @staticmethod
     def slot(name: str) -> Fragment:
+        """Create a Fragment with a single empty slot.
+        
+        Equivalent to sql("{name}") but more explicit.
+        
+        Args:
+            name: The name of the slot
+            
+        Returns:
+            Fragment containing a single slot
+            
+        Example:
+            >>> template = sql("SELECT * FROM users WHERE {}", sql.slot("condition"))
+            >>> query = template.fill(condition=sql("active = {}", True))
+        """
         return Fragment([Slot(name)])
 
     @staticmethod
     def literal(text: str) -> Fragment:
+        """Create a Fragment with literal SQL text.
+        
+        No substitution of any kind is performed. Be very careful of SQL injection
+        when using this method.
+        
+        Args:
+            text: Raw SQL text to include
+            
+        Returns:
+            Fragment containing the literal SQL
+            
+        Warning:
+            Only use with trusted SQL text to avoid SQL injection vulnerabilities.
+            
+        Example:
+            >>> sql.literal("ORDER BY created_at DESC")
+            Fragment(['ORDER BY created_at DESC'])
+        """
         return Fragment([text])
 
     @staticmethod
     def identifier(name: str, prefix: Optional[str] = None) -> Fragment:
+        """Create a Fragment with a quoted SQL identifier.
+        
+        Creates a properly quoted identifier name, optionally with a dotted prefix
+        for schema or table qualification.
+        
+        Args:
+            name: The identifier name to quote
+            prefix: Optional prefix (schema, table, etc.)
+            
+        Returns:
+            Fragment containing the quoted identifier
+            
+        Example:
+            >>> list(sql("SELECT {col} FROM {table}", 
+            ...           col=sql.identifier("user_name"), 
+            ...           table=sql.identifier("users", prefix="public")))
+            ['SELECT "user_name" FROM "public"."users"']
+        """
         if prefix:
             return lit(f"{quote_identifier(prefix)}.{quote_identifier(name)}")
         else:
@@ -418,6 +545,24 @@ def all(self, parts: Iterable[Fragment]) -> Fragment: ...  # pragma: no cover
     def all(self, *parts: Fragment) -> Fragment: ...  # pragma: no cover
 
     def all(self, *parts) -> Fragment:  # type: ignore
+        """Join fragments with AND, returning TRUE if no parts provided.
+        
+        Creates a SQL Fragment joining the fragments in parts together with AND.
+        If parts is empty, returns TRUE. Each fragment is wrapped in parentheses.
+        
+        Args:
+            *parts: Fragment objects to join, or single iterable of fragments
+            
+        Returns:
+            Fragment containing the AND-joined conditions
+            
+        Example:
+            >>> where = [sql("a = {}", 42), sql("x <> {}", "foo")]
+            >>> list(sql("SELECT * FROM tbl WHERE {}", sql.all(where)))
+            ['SELECT * FROM tbl WHERE (a = $1) AND (x <> $2)', 42, 'foo']
+            >>> list(sql("SELECT * FROM tbl WHERE {}", sql.all([])))
+            ['SELECT * FROM tbl WHERE TRUE']
+        """
         if parts and not isinstance(parts[0], Fragment):
             parts = parts[0]
         return any_all(list(parts), "AND", "TRUE")
@@ -429,6 +574,24 @@ def any(self, parts: Iterable[Fragment]) -> Fragment: ...  # pragma: no cover
     def any(self, *parts: Fragment) -> Fragment: ...  # pragma: no cover
 
     def any(self, *parts) -> Fragment:  # type: ignore
+        """Join fragments with OR, returning FALSE if no parts provided.
+        
+        Creates a SQL Fragment joining the fragments in parts together with OR.
+        If parts is empty, returns FALSE. Each fragment is wrapped in parentheses.
+        
+        Args:
+            *parts: Fragment objects to join, or single iterable of fragments
+            
+        Returns:
+            Fragment containing the OR-joined conditions
+            
+        Example:
+            >>> where = [sql("a = {}", 42), sql("x <> {}", "foo")]
+            >>> list(sql("SELECT * FROM tbl WHERE {}", sql.any(where)))
+            ['SELECT * FROM tbl WHERE (a = $1) OR (x <> $2)', 42, 'foo']
+            >>> list(sql("SELECT * FROM tbl WHERE {}", sql.any([])))
+            ['SELECT * FROM tbl WHERE FALSE']
+        """
         if parts and not isinstance(parts[0], Fragment):
             parts = parts[0]
         return any_all(list(parts), "OR", "FALSE")
@@ -440,18 +603,66 @@ def list(self, parts: Iterable[Fragment]) -> Fragment: ...  # pragma: no cover
     def list(self, *parts: Fragment) -> Fragment: ...  # pragma: no cover
 
     def list(self, *parts) -> Fragment:  # type: ignore
+        """Join fragments with commas.
+        
+        Creates a SQL Fragment joining the fragments in parts together with commas.
+        Commonly used for column lists, value lists, etc.
+        
+        Args:
+            *parts: Fragment objects to join, or single iterable of fragments
+            
+        Returns:
+            Fragment containing the comma-separated fragments
+            
+        Example:
+            >>> cols = [sql.identifier("id"), sql.identifier("name"), sql.identifier("email")]
+            >>> list(sql("SELECT {} FROM users", sql.list(cols)))
+            ['SELECT "id", "name", "email" FROM users']
+        """
         if parts and not isinstance(parts[0], Fragment):
             parts = parts[0]
         return Fragment(list(join_parts(parts, infix=", ")))
 
     def unnest(self, data: Iterable[Sequence[Any]], types: Iterable[str]) -> Fragment:
+        """Create a Fragment containing an UNNEST expression with associated data.
+        
+        The data is specified as tuples (in the "database columns" sense) in data,
+        and the PostgreSQL types must be specified in types. The data is transposed
+        into the correct form for UNNEST and embedded as placeholders.
+        
+        Args:
+            data: Iterable of sequences, where each sequence represents a row
+            types: Iterable of PostgreSQL type names for each column
+            
+        Returns:
+            Fragment containing UNNEST expression with typed array placeholders
+            
+        Example:
+            >>> list(sql("SELECT * FROM {}", sql.unnest([("a", 1), ("b", 2), ("c", 3)], ["text", "integer"])))
+            ['SELECT * FROM UNNEST($1::text[], $2::integer[])', ('a', 'b', 'c'), (1, 2, 3)]
+            
+            >>> # Useful for bulk operations
+            >>> users_data = [("Alice", 25), ("Bob", 30), ("Charlie", 35)]
+            >>> insert_query = sql("INSERT INTO users (name, age) SELECT * FROM {}", 
+            ...                   sql.unnest(users_data, ["text", "integer"]))
+        """
         nested = [nest_for_type(x, t) for x, t in zip(zip(*data), types)]
         if not nested:
             nested = [nest_for_type([], t) for t in types]
         return Fragment(["UNNEST(", self.list(nested), ")"])
 
 
 sql = SQLFormatter()
+"""Global SQLFormatter instance providing the main sql() function and utilities.
+
+This is the primary interface for creating SQL fragments. Use it to:
+- Create fragments: sql("SELECT * FROM users WHERE id = {}", user_id)
+- Join fragments: sql.all([condition1, condition2])
+- Create identifiers: sql.identifier("table_name")
+- And much more
+
+See SQLFormatter class documentation for all available methods.
+"""
 
 
 json_types = ("JSON", "JSONB")