chdb 3.6.0__cp38-abi3-macosx_11_0_arm64.whl → 3.7.0__cp38-abi3-macosx_11_0_arm64.whl

chdb/dbapi/cursors.py

@@ -13,14 +13,32 @@ RE_INSERT_VALUES = re.compile(
 
 
 class Cursor(object):
-    """
-    This is the object you use to interact with the database.
-
-    Do not create an instance of a Cursor yourself. Call
-    connections.Connection.cursor().
-
-    See `Cursor <https://www.python.org/dev/peps/pep-0249/#cursor-objects>`_ in
-    the specification.
+    """DB-API 2.0 cursor for executing queries and fetching results.
+
+    The cursor provides methods for executing SQL statements, managing query results,
+    and navigating through result sets. It supports parameter binding, bulk operations,
+    and follows DB-API 2.0 specifications.
+
+    Do not create Cursor instances directly. Use Connection.cursor() instead.
+
+    Attributes:
+        description (tuple): Column metadata for the last query result
+        rowcount (int): Number of rows affected by the last query (-1 if unknown)
+        arraysize (int): Default number of rows to fetch at once (default: 1)
+        lastrowid: ID of the last inserted row (if applicable)
+        max_stmt_length (int): Maximum statement size for executemany() (default: 1024000)
+
+    Examples:
+        >>> conn = Connection()
+        >>> cur = conn.cursor()
+        >>> cur.execute("SELECT 1 as id, 'test' as name")
+        >>> result = cur.fetchone()
+        >>> print(result)  # (1, 'test')
+        >>> cur.close()
+
+    Note:
+        See `DB-API 2.0 Cursor Objects <https://www.python.org/dev/peps/pep-0249/#cursor-objects>`_
+        for complete specification details.
     """
 
     #: Max statement size which :meth:`executemany` generates.
@@ -29,6 +47,11 @@ class Cursor(object):
     max_stmt_length = 1024000
 
     def __init__(self, connection):
+        """Initialize cursor for the given connection.
+
+        Args:
+            connection (Connection): Database connection to use
+        """
         self.connection = connection
         self._cursor = connection._conn.cursor()
         self.description = None
@@ -38,58 +61,89 @@ class Cursor(object):
         self._executed = None
 
     def __enter__(self):
+        """Enter context manager and return self.
+
+        Returns:
+            Cursor: This cursor instance
+        """
         return self
 
     def __exit__(self, *exc_info):
+        """Exit context manager and close cursor.
+
+        Args:
+            *exc_info: Exception information (ignored)
+        """
         del exc_info
         self.close()
 
     def __iter__(self):
+        """Make cursor iterable over result rows.
+
+        Returns:
+            iterator: Iterator yielding rows until None is returned
+
+        Example:
+            >>> cur.execute("SELECT id FROM users")
+            >>> for row in cur:
+            ...     print(row[0])
+        """
         return iter(self.fetchone, None)
 
     def callproc(self, procname, args=()):
-        """Execute stored procedure procname with args
-
-        procname -- string, name of procedure to execute on server
-
-        args -- Sequence of parameters to use with procedure
-
-        Returns the original args.
-
-        Compatibility warning: PEP-249 specifies that any modified
-        parameters must be returned. This is currently impossible
-        as they are only available by storing them in a server
-        variable and then retrieved by a query. Since stored
-        procedures return zero or more result sets, there is no
-        reliable way to get at OUT or INOUT parameters via callproc.
-        The server variables are named @_procname_n, where procname
-        is the parameter above and n is the position of the parameter
-        (from zero). Once all result sets generated by the procedure
-        have been fetched, you can issue a SELECT @_procname_0, ...
-        query using .execute() to get any OUT or INOUT values.
-
-        Compatibility warning: The act of calling a stored procedure
-        itself creates an empty result set. This appears after any
-        result sets generated by the procedure. This is non-standard
-        behavior with respect to the DB-API. Be sure to use nextset()
-        to advance through all result sets; otherwise you may get
-        disconnected.
+        """Execute a stored procedure (placeholder implementation).
+
+        Args:
+            procname (str): Name of stored procedure to execute
+            args (sequence): Parameters to pass to the procedure
+
+        Returns:
+            sequence: The original args parameter (unmodified)
+
+        Note:
+            chDB/ClickHouse does not support stored procedures in the traditional sense.
+            This method is provided for DB-API 2.0 compliance but does not perform
+            any actual operation. Use execute() for all SQL operations.
+
+        Compatibility Warning:
+            This is a placeholder implementation. Traditional stored procedure
+            features like OUT/INOUT parameters, multiple result sets, and server
+            variables are not supported by the underlying ClickHouse engine.
         """
 
         return args
 
     def close(self):
-        """
-        Closing a cursor just exhausts all remaining data.
+        """Close the cursor and free associated resources.
+
+        After closing, the cursor becomes unusable and any operation will raise an exception.
+        Closing a cursor exhausts all remaining data and releases the underlying cursor.
         """
         self._cursor.close()
 
     def _get_db(self):
+        """Internal method to get the database connection.
+
+        Returns:
+            Connection: The database connection
+
+        Raises:
+            ProgrammingError: If cursor is closed
+        """
         if not self.connection:
             raise err.ProgrammingError("Cursor closed")
         return self.connection
 
     def _escape_args(self, args, conn):
+        """Internal method to escape query arguments.
+
+        Args:
+            args (tuple/list/dict): Arguments to escape
+            conn (Connection): Database connection for escaping
+
+        Returns:
+            Escaped arguments in the same structure as input
+        """
         if isinstance(args, (tuple, list)):
             return tuple(conn.escape(arg) for arg in args)
         elif isinstance(args, dict):
@@ -100,7 +154,22 @@ class Cursor(object):
             return conn.escape(args)
 
     def _format_query(self, query, args, conn):
-        """Format query with arguments supporting ? and % placeholders."""
+        """Format SQL query by substituting parameter placeholders.
+
+        This internal method handles parameter binding for both question mark (?) and
+        format (%s) style placeholders, with proper escaping for SQL injection prevention.
+
+        Args:
+            query (str): SQL query with parameter placeholders
+            args (tuple/list): Parameter values to substitute
+            conn (Connection): Database connection for escaping values
+
+        Returns:
+            str: SQL query with parameters substituted and properly escaped
+
+        Note:
+            This is an internal method. Use execute() or mogrify() instead.
+        """
         if args is None or ('?' not in query and '%' not in query):
             return query
 
@@ -143,29 +212,59 @@ class Cursor(object):
         return ''.join(result)
 
     def mogrify(self, query, args=None):
-        """
-        Returns the exact string that is sent to the database by calling the
-        execute() method.
+        """Return the exact query string that would be sent to the database.
 
-        This method follows the extension to the DB API 2.0 followed by Psycopg.
-        """
-        conn = self._get_db()
-        return self._format_query(query, args, conn)
+        This method shows the final SQL query after parameter substitution,
+        which is useful for debugging and logging purposes.
 
-    def execute(self, query, args=None):
-        """Execute a query
+        Args:
+            query (str): SQL query with parameter placeholders
+            args (tuple/list/dict, optional): Parameters to substitute
 
-        :param str query: Query to execute.
+        Returns:
+            str: The final SQL query string with parameters substituted
 
-        :param args: parameters used with query. (optional)
-        :type args: tuple, list or dict
+        Example:
+            >>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
+            "SELECT * FROM users WHERE id = 123"
 
-        :return: Number of affected rows
-        :rtype: int
+        Note:
+            This method follows the extension to DB-API 2.0 used by Psycopg.
+        """
+        conn = self._get_db()
+        return self._format_query(query, args, conn)
 
-        If args is a list or tuple, ? can be used as a placeholder in the query.
-        If args is a dict, %(name)s can be used as a placeholder in the query.
-        Also supports %s placeholder for backward compatibility.
+    def execute(self, query, args=None):
+        """Execute a SQL query with optional parameter binding.
+
+        This method executes a single SQL statement with optional parameter substitution.
+        It supports multiple parameter placeholder styles for flexibility.
+
+        Args:
+            query (str): SQL query to execute
+            args (tuple/list/dict, optional): Parameters to bind to placeholders
+
+        Returns:
+            int: Number of affected rows (-1 if unknown)
+
+        Parameter Styles:
+            - Question mark style: "SELECT * FROM users WHERE id = ?"
+            - Named style: "SELECT * FROM users WHERE name = %(name)s"
+            - Format style: "SELECT * FROM users WHERE age = %s" (legacy)
+
+        Examples:
+            >>> # Question mark parameters
+            >>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18))
+            >>>
+            >>> # Named parameters
+            >>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'})
+            >>>
+            >>> # No parameters
+            >>> cur.execute("SELECT COUNT(*) FROM users")
+
+        Raises:
+            ProgrammingError: If cursor is closed or query is malformed
+            InterfaceError: If database error occurs during execution
         """
         query = self._format_query(query, args, self.connection)
         self._cursor.execute(query)
@@ -189,16 +288,36 @@ class Cursor(object):
         return self.rowcount
 
     def executemany(self, query, args):
-        # type: (str, list) -> int
-        """Run several data against one query
-
-        :param query: query to execute on server
-        :param args:  Sequence of sequences or mappings.  It is used as parameter.
-        :return: Number of rows affected, if any.
-
-        This method improves performance on multiple-row INSERT and
-        REPLACE. Otherwise, it is equivalent to looping over args with
-        execute().
+        """Execute a query multiple times with different parameter sets.
+
+        This method efficiently executes the same SQL query multiple times with
+        different parameter values. It's particularly useful for bulk INSERT operations.
+
+        Args:
+            query (str): SQL query to execute multiple times
+            args (sequence): Sequence of parameter tuples/dicts/lists for each execution
+
+        Returns:
+            int: Total number of affected rows across all executions
+
+        Examples:
+            >>> # Bulk insert with question mark parameters
+            >>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
+            >>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data)
+            >>>
+            >>> # Bulk insert with named parameters
+            >>> users_data = [
+            ...     {'id': 1, 'name': 'Alice'},
+            ...     {'id': 2, 'name': 'Bob'}
+            ... ]
+            >>> cur.executemany(
+            ...     "INSERT INTO users VALUES (%(id)s, %(name)s)",
+            ...     users_data
+            ... )
+
+        Note:
+            This method improves performance for multiple-row INSERT and UPDATE operations
+            by optimizing the query execution process.
         """
         if not args:
             return 0
@@ -318,34 +437,109 @@ class Cursor(object):
         return rows
 
     def _check_executed(self):
+        """Internal method to verify that execute() has been called.
+
+        Raises:
+            ProgrammingError: If no query has been executed yet
+        """
         if not self._executed:
             raise err.ProgrammingError("execute() first")
 
     def fetchone(self):
-        """Fetch the next row"""
+        """Fetch the next row from the query result.
+
+        Returns:
+            tuple or None: Next row as a tuple, or None if no more rows available
+
+        Raises:
+            ProgrammingError: If execute() has not been called first
+
+        Example:
+            >>> cursor.execute("SELECT id, name FROM users LIMIT 3")
+            >>> row = cursor.fetchone()
+            >>> print(row)  # (1, 'Alice')
+            >>> row = cursor.fetchone()
+            >>> print(row)  # (2, 'Bob')
+        """
         if not self._executed:
             raise err.ProgrammingError("execute() first")
         return self._cursor.fetchone()
 
     def fetchmany(self, size=1):
-        """Fetch several rows"""
+        """Fetch multiple rows from the query result.
+
+        Args:
+            size (int, optional): Number of rows to fetch. Defaults to 1.
+                                 If not specified, uses cursor.arraysize.
+
+        Returns:
+            list: List of tuples representing the fetched rows
+
+        Raises:
+            ProgrammingError: If execute() has not been called first
+
+        Example:
+            >>> cursor.execute("SELECT id, name FROM users")
+            >>> rows = cursor.fetchmany(3)
+            >>> print(rows)  # [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
+        """
         if not self._executed:
             raise err.ProgrammingError("execute() first")
         return self._cursor.fetchmany(size)
 
     def fetchall(self):
-        """Fetch all the rows"""
+        """Fetch all remaining rows from the query result.
+
+        Returns:
+            list: List of tuples representing all remaining rows
+
+        Raises:
+            ProgrammingError: If execute() has not been called first
+
+        Warning:
+            This method can consume large amounts of memory for big result sets.
+            Consider using fetchmany() for large datasets.
+
+        Example:
+            >>> cursor.execute("SELECT id, name FROM users")
+            >>> all_rows = cursor.fetchall()
+            >>> print(len(all_rows))  # Number of total rows
+        """
         if not self._executed:
             raise err.ProgrammingError("execute() first")
         return self._cursor.fetchall()
 
     def nextset(self):
-        """Get the next query set"""
+        """Move to the next result set (not supported).
+
+        Returns:
+            None: Always returns None as multiple result sets are not supported
+
+        Note:
+            chDB/ClickHouse does not support multiple result sets from a single query.
+            This method is provided for DB-API 2.0 compliance but always returns None.
+        """
         # Not support for now
         return None
 
     def setinputsizes(self, *args):
-        """Does nothing, required by DB API."""
+        """Set input sizes for parameters (no-op implementation).
+
+        Args:
+            *args: Parameter size specifications (ignored)
+
+        Note:
+            This method does nothing but is required by DB-API 2.0 specification.
+            chDB automatically handles parameter sizing internally.
+        """
 
     def setoutputsizes(self, *args):
-        """Does nothing, required by DB API."""
+        """Set output column sizes (no-op implementation).
+
+        Args:
+            *args: Column size specifications (ignored)
+
+        Note:
+            This method does nothing but is required by DB-API 2.0 specification.
+            chDB automatically handles output sizing internally.
+        """