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

chdb/dataframe/__init__.py

@@ -8,8 +8,13 @@ except ImportError as e:
     raise ImportError('Failed to import pyarrow or pandas') from None
 
 # check if pandas version >= 2.0.0
-if pd.__version__[0] < '2':
-    print('Please upgrade pandas to version 2.0.0 or higher to have better performance')
+try:
+    version_parts = pd.__version__.split('.')
+    major_version = int(version_parts[0])
+    if major_version < 2:
+        print('Please upgrade pandas to version 2.0.0 or higher to have better performance')
+except (ValueError, IndexError, AttributeError):
+    pass
 
 from .query import Table, pandas_read_parquet  # noqa: C0413
 

chdb/dataframe/query.py

@@ -8,11 +8,38 @@ from chdb import query as chdb_query
 
 
 class Table:
-    """
-    Table is a wrapper of multiple formats of data buffer, including parquet file path,
-    parquet bytes, and pandas dataframe.
-    if use_memfd is True, will try using memfd_create to create a temp file in memory, which is
-    only available on Linux. If failed, will fallback to use tempfile.mkstemp to create a temp file
+    """Wrapper for multiple data formats enabling SQL queries on DataFrames, Parquet files, and Arrow tables.
+
+    The Table class provides a unified interface for querying different data formats using SQL.
+    It supports pandas DataFrames, Parquet files (both on disk and in memory), and PyArrow Tables.
+    All data is internally converted to Parquet format for efficient querying with chDB.
+
+    Args:
+        parquet_path (str, optional): Path to an existing Parquet file
+        temp_parquet_path (str, optional): Path to a temporary Parquet file
+        parquet_memoryview (memoryview, optional): Parquet data in memory as memoryview
+        dataframe (pd.DataFrame, optional): pandas DataFrame to wrap
+        arrow_table (pa.Table, optional): PyArrow Table to wrap
+        use_memfd (bool, optional): Use memfd_create for temporary files (Linux only). Defaults to False.
+
+    Examples:
+        >>> # Create from pandas DataFrame
+        >>> import pandas as pd
+        >>> df = pd.DataFrame({'id': [1, 2], 'name': ['Alice', 'Bob']})
+        >>> table = Table(dataframe=df)
+        >>> result = table.query("SELECT * FROM __table__ WHERE id > 1")
+
+        >>> # Create from Parquet file
+        >>> table = Table(parquet_path="data.parquet")
+        >>> result = table.query("SELECT COUNT(*) FROM __table__")
+
+        >>> # Multi-table queries
+        >>> table1 = Table(dataframe=df1)
+        >>> table2 = Table(dataframe=df2)
+        >>> result = Table.queryStatic(
+        ...     "SELECT * FROM __table1__ JOIN __table2__ ON __table1__.id = __table2__.id",
+        ...     table1=table1, table2=table2
+        ... )
     """
 
     def __init__(
@@ -24,9 +51,18 @@ class Table:
         arrow_table: pa.Table = None,
         use_memfd: bool = False,
     ):
-        """
-        Initialize a Table object with one of parquet file path, parquet bytes, pandas dataframe or
-        parquet table.
+        """Initialize a Table object with one of the supported data formats.
+
+        Only one data source should be provided. The Table will wrap the provided data
+        and enable SQL querying capabilities.
+
+        Args:
+            parquet_path (str, optional): Path to existing Parquet file
+            temp_parquet_path (str, optional): Path to temporary Parquet file
+            parquet_memoryview (memoryview, optional): Parquet data in memory
+            dataframe (pd.DataFrame, optional): pandas DataFrame to wrap
+            arrow_table (pa.Table, optional): PyArrow Table to wrap
+            use_memfd (bool, optional): Use memory-based file descriptors on Linux
         """
         self._parquet_path = parquet_path
         self._temp_parquet_path = temp_parquet_path
@@ -46,15 +82,47 @@ class Table:
                 pass
 
     def rows_read(self):
+        """Get the number of rows read from the last query operation.
+
+        Returns:
+            int: Number of rows processed in the last query
+        """
         return self._rows_read
 
     def bytes_read(self):
+        """Get the number of bytes read from the last query operation.
+
+        Returns:
+            int: Number of bytes processed in the last query
+        """
         return self._bytes_read
 
     def elapsed(self):
+        """Get the elapsed time for the last query operation.
+
+        Returns:
+            float: Query execution time
+        """
         return self._elapsed
 
     def to_pandas(self) -> pd.DataFrame:
+        """Convert the Table data to a pandas DataFrame.
+
+        This method handles conversion from various internal formats (Parquet files,
+        memory buffers, Arrow tables) to a unified pandas DataFrame representation.
+
+        Returns:
+            pd.DataFrame: The table data as a pandas DataFrame
+
+        Raises:
+            ValueError: If no data source is available in the Table object
+
+        Example:
+            >>> table = Table(dataframe=df)
+            >>> result_table = table.query("SELECT * FROM __table__ LIMIT 5")
+            >>> df_result = result_table.to_pandas()
+            >>> print(df_result)
+        """
         if self._dataframe is None:
             if self._arrow_table is not None:
                 return self._arrow_table.to_pandas()
@@ -71,8 +139,20 @@ class Table:
         return self._dataframe
 
     def flush_to_disk(self):
-        """
-        Flush the data in memory to disk.
+        """Flush in-memory data to disk as a temporary Parquet file.
+
+        This method converts in-memory data (DataFrame, Arrow table, or memory buffer)
+        to a temporary Parquet file on disk. This can be useful for memory management
+        or when working with large datasets.
+
+        The method does nothing if data is already stored on disk.
+
+        Raises:
+            ValueError: If the Table object contains no data to flush
+
+        Example:
+            >>> table = Table(dataframe=large_df)
+            >>> table.flush_to_disk()  # Frees memory, keeps data accessible
         """
         if self._parquet_path is not None or self._temp_parquet_path is not None:
             return
@@ -112,10 +192,33 @@ class Table:
         return str(self.to_pandas())
 
     def query(self, sql: str, **kwargs) -> "Table":
-        """
-        Query on current Table object, return a new Table object.
-        The `FROM` table name in SQL should always be `__table__`. eg:
-            `SELECT * FROM __table__ WHERE ...`
+        """Execute SQL query on the current Table and return a new Table with results.
+
+        This method allows you to run SQL queries on the table data using chDB.
+        The table is referenced as '__table__' in the SQL statement.
+
+        Args:
+            sql (str): SQL query string. Must reference the table as '__table__'
+            **kwargs: Additional arguments passed to the chDB query engine
+
+        Returns:
+            Table: New Table object containing the query results
+
+        Raises:
+            ValueError: If SQL doesn't contain '__table__' reference or if Table is not initialized
+
+        Examples:
+            >>> table = Table(dataframe=df)
+            >>> # Filter rows
+            >>> result = table.query("SELECT * FROM __table__ WHERE age > 25")
+            >>>
+            >>> # Aggregate data
+            >>> summary = table.query("SELECT COUNT(*), AVG(salary) FROM __table__")
+            >>>
+            >>> # Complex operations
+            >>> processed = table.query(
+            ...     "SELECT name, age * 2 as double_age FROM __table__ ORDER BY age DESC"
+            ... )
         """
         self._validate_sql(sql)
 
@@ -138,6 +241,18 @@ class Table:
     sql = query
 
     def show(self):
+        """Display the Table data by printing the pandas DataFrame representation.
+
+        This is a convenience method for quickly viewing the table contents.
+        Equivalent to print(table.to_pandas()).
+
+        Example:
+            >>> table = Table(dataframe=df)
+            >>> table.show()
+               id    name
+            0   1   Alice
+            1   2     Bob
+        """
         print(self.to_pandas())
 
     def _query_on_path(self, path, sql, **kwargs):
@@ -220,12 +335,51 @@ class Table:
 
     @staticmethod
     def queryStatic(sql: str, **kwargs) -> "Table":
-        """
-        Query on multiple Tables, use Table variables as the table name in SQL
-        eg.
-            table1 = Table(...)
-            table2 = Table(...)
-            query("SELECT * FROM __table1__ JOIN __table2__ ON ...", table1=table1, table2=table2)
+        """Execute SQL query across multiple Table objects.
+
+        This static method enables complex queries involving multiple tables by referencing
+        them as '__tablename__' in the SQL and passing them as keyword arguments.
+
+        Args:
+            sql (str): SQL query with table references as '__name__' patterns
+            **kwargs: Table objects referenced in the SQL, where key matches the table name
+                     Can also include pandas DataFrames, which will be auto-converted to Tables
+
+        Returns:
+            Table: New Table object containing the query results
+
+        Raises:
+            ValueError: If referenced table names are missing from kwargs or have invalid types
+
+        Examples:
+            >>> users = Table(dataframe=users_df)
+            >>> orders = Table(dataframe=orders_df)
+            >>>
+            >>> # Join two tables
+            >>> result = Table.queryStatic(
+            ...     "SELECT u.name, COUNT(o.id) as order_count "
+            ...     "FROM __users__ u LEFT JOIN __orders__ o ON u.id = o.user_id "
+            ...     "GROUP BY u.name",
+            ...     users=users, orders=orders
+            ... )
+            >>>
+            >>> # Works with pandas DataFrames directly
+            >>> result = Table.queryStatic(
+            ...     "SELECT * FROM __df1__ UNION ALL SELECT * FROM __df2__",
+            ...     df1=dataframe1, df2=dataframe2
+            ... )
+            >>>
+            >>> # Complex multi-table operations
+            >>> analytics = Table.queryStatic(
+            ...     "SELECT p.category, AVG(o.amount) as avg_order "
+            ...     "FROM __products__ p "
+            ...     "JOIN __order_items__ oi ON p.id = oi.product_id "
+            ...     "JOIN __orders__ o ON oi.order_id = o.id "
+            ...     "GROUP BY p.category ORDER BY avg_order DESC",
+            ...     products=products_table,
+            ...     order_items=order_items_table,
+            ...     orders=orders_table
+            ... )
         """
         ansiTablePattern = re.compile(r"__([a-zA-Z][a-zA-Z0-9_]*)__")
         temp_paths = []
@@ -322,13 +476,47 @@ class Table:
 
 
 def pandas_read_parquet(path) -> pd.DataFrame:
+    """Read a Parquet file into a pandas DataFrame.
+
+    This is a convenience wrapper around pandas.read_parquet() for consistency
+    with the chdb.dataframe module interface.
+
+    Args:
+        path: File path or file-like object to read from
+
+    Returns:
+        pd.DataFrame: The loaded DataFrame
+    """
     return pd.read_parquet(path)
 
 
 def memfd_create(name: str = None) -> int:
-    """
-    Try to use memfd_create(2) to create a file descriptor with memory.
-    Only available on Linux 3.17 or newer with glibc 2.27 or newer.
+    """Create an in-memory file descriptor using memfd_create system call.
+
+    This function attempts to use the Linux-specific memfd_create(2) system call
+    to create a file descriptor that refers to an anonymous memory-backed file.
+    This provides better performance for temporary data operations.
+
+    Args:
+        name (str, optional): Name for the memory file (for debugging). Defaults to None.
+
+    Returns:
+        int: File descriptor on success, -1 on failure or if not supported
+
+    Note:
+        This function only works on Linux 3.17 or newer with glibc 2.27 or newer.
+        On other systems or if the call fails, it returns -1 and callers should
+        fall back to regular temporary files.
+
+    Example:
+        >>> fd = memfd_create("temp_data")
+        >>> if fd != -1:
+        ...     # Use memory-based file descriptor
+        ...     with os.fdopen(fd, 'wb') as f:
+        ...         f.write(data)
+        ... else:
+        ...     # Fall back to regular temp file
+        ...     fd, path = tempfile.mkstemp()
     """
     if hasattr(os, "memfd_create"):
         try:

chdb/dbapi/__init__.py

@@ -13,20 +13,58 @@ paramstyle = "format"
 
 
 class DBAPISet(frozenset):
+    """Extended frozenset for DB-API 2.0 type comparison.
+
+    This class extends frozenset to support DB-API 2.0 type comparison semantics.
+    It allows for flexible type checking where individual items can be compared
+    against the set using both equality and inequality operators.
+
+    This is used for type constants like STRING, BINARY, NUMBER, etc. to enable
+    comparisons like "field_type == STRING" where field_type is a single type value.
+
+    Examples:
+        >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
+        >>> FIELD_TYPE.STRING == string_types  # Returns True
+        >>> FIELD_TYPE.INT != string_types     # Returns True
+        >>> FIELD_TYPE.BLOB in string_types    # Returns False
+    """
 
     def __ne__(self, other):
+        """Check inequality with flexible type comparison.
+
+        Args:
+            other: Value to compare against this set
+
+        Returns:
+            bool: True if other is not in this set (for non-set types) or
+                  True if sets are not equal (for set types)
+        """
         if isinstance(other, set):
             return frozenset.__ne__(self, other)
         else:
             return other not in self
 
     def __eq__(self, other):
+        """Check equality with flexible type comparison.
+
+        Args:
+            other: Value to compare against this set
+
+        Returns:
+            bool: True if other is in this set (for non-set types) or
+                  True if sets are equal (for set types)
+        """
         if isinstance(other, frozenset):
             return frozenset.__eq__(self, other)
         else:
             return other in self
 
     def __hash__(self):
+        """Return hash value for the set.
+
+        Returns:
+            int: Hash value of the underlying frozenset
+        """
         return frozenset.__hash__(self)
 
 
@@ -47,7 +85,17 @@ ROWID = DBAPISet()
 
 
 def Binary(x):
-    """Return x as a binary type."""
+    """Return x as a binary type.
+
+    This function converts the input to bytes type for use with binary
+    database fields, following the DB-API 2.0 specification.
+
+    Args:
+        x: Input data to convert to binary
+
+    Returns:
+        bytes: The input converted to bytes
+    """
     return bytes(x)
 
 
@@ -65,7 +113,14 @@ if _orig_conn.Connection.__init__.__doc__ is not None:
 del _orig_conn
 
 
-def get_client_info():  # for MySQLdb compatibility
+def get_client_info():
+    """Get client version information.
+
+    Returns the chDB client version as a string for MySQLdb compatibility.
+
+    Returns:
+        str: Version string in format 'major.minor.patch'
+    """
     version = chdb_version
     if len(chdb_version) > 3 and chdb_version[3] is None:
         version = chdb_version[:3]

chdb/dbapi/connections.py

@@ -8,11 +8,56 @@ VERBOSE = False
 
 
 class Connection(object):
-    """
-    Representation of a connection with chdb.
+    """DB-API 2.0 compliant connection to chDB database.
+
+    This class provides a standard DB-API interface for connecting to and interacting
+    with chDB databases. It supports both in-memory and file-based databases.
+
+    The connection manages the underlying chDB engine and provides methods for
+    executing queries, managing transactions (no-op for ClickHouse), and creating cursors.
+
+    Args:
+        path (str, optional): Database file path. If None, uses in-memory database.
+                              Can be a file path like 'database.db' or None for ':memory:'
+
+    Attributes:
+        encoding (str): Character encoding for queries, defaults to 'utf8'
+        open (bool): True if connection is open, False if closed
+
+    Examples:
+        >>> # In-memory database
+        >>> conn = Connection()
+        >>> cursor = conn.cursor()
+        >>> cursor.execute("SELECT 1")
+        >>> result = cursor.fetchall()
+        >>> conn.close()
+
+        >>> # File-based database
+        >>> conn = Connection('mydata.db')
+        >>> with conn.cursor() as cur:
+        ...     cur.execute("CREATE TABLE users (id INT, name STRING)")
+        ...     cur.execute("INSERT INTO users VALUES (1, 'Alice')")
+        >>> conn.close()
+
+        >>> # Context manager usage
+        >>> with Connection() as cur:
+        ...     cur.execute("SELECT version()")
+        ...     version = cur.fetchone()
+
+    Note:
+        ClickHouse does not support traditional transactions, so commit() and rollback()
+        operations are no-ops but provided for DB-API compliance.
     """
 
     def __init__(self, path=None):
+        """Initialize a new database connection.
+
+        Args:
+            path (str, optional): Database file path. None for in-memory database.
+
+        Raises:
+            err.Error: If connection cannot be established
+        """
         self._closed = False
         self.encoding = "utf8"
         self._affected_rows = 0
@@ -28,7 +73,14 @@ class Connection(object):
         cursor.close()
 
     def close(self):
-        """Send the quit message and close the socket."""
+        """Close the database connection.
+
+        Closes the underlying chDB connection and marks this connection as closed.
+        Subsequent operations on this connection will raise an Error.
+
+        Raises:
+            err.Error: If connection is already closed
+        """
         if self._closed:
             raise err.Error("Already closed")
         self._closed = True
@@ -36,21 +88,51 @@ class Connection(object):
 
     @property
     def open(self):
-        """Return True if the connection is open"""
+        """Check if the connection is open.
+
+        Returns:
+            bool: True if connection is open, False if closed
+        """
         return not self._closed
 
     def commit(self):
-        """Commit changes to stable storage."""
+        """Commit the current transaction.
+
+        Note:
+            This is a no-op for chDB/ClickHouse as it doesn't support traditional
+            transactions. Provided for DB-API 2.0 compliance.
+        """
         # No-op for ClickHouse
         pass
 
     def rollback(self):
-        """Roll back the current transaction."""
+        """Roll back the current transaction.
+
+        Note:
+            This is a no-op for chDB/ClickHouse as it doesn't support traditional
+            transactions. Provided for DB-API 2.0 compliance.
+        """
         # No-op for ClickHouse
         pass
 
     def cursor(self, cursor=None):
-        """Create a new cursor to execute queries with."""
+        """Create a new cursor for executing queries.
+
+        Args:
+            cursor: Ignored, provided for compatibility
+
+        Returns:
+            Cursor: New cursor object for this connection
+
+        Raises:
+            err.Error: If connection is closed
+
+        Example:
+            >>> conn = Connection()
+            >>> cur = conn.cursor()
+            >>> cur.execute("SELECT 1")
+            >>> result = cur.fetchone()
+        """
         if self._closed:
             raise err.Error("Connection closed")
         if cursor:
@@ -58,7 +140,28 @@ class Connection(object):
         return Cursor(self)
 
     def query(self, sql, fmt="CSV"):
-        """Execute a query and return the raw result."""
+        """Execute a SQL query directly and return raw results.
+
+        This method bypasses the cursor interface and executes queries directly.
+        For standard DB-API usage, prefer using cursor() method.
+
+        Args:
+            sql (str or bytes): SQL query to execute
+            fmt (str, optional): Output format. Defaults to "CSV".
+                Supported formats include "CSV", "JSON", "Arrow", "Parquet", etc.
+
+        Returns:
+            Query result in the specified format
+
+        Raises:
+            err.InterfaceError: If connection is closed or query fails
+
+        Example:
+            >>> conn = Connection()
+            >>> result = conn.query("SELECT 1, 'hello'", "CSV")
+            >>> print(result)
+            "1,hello\\n"
+        """
         if self._closed:
             raise err.InterfaceError("Connection closed")
 
@@ -73,21 +176,67 @@ class Connection(object):
             raise err.InterfaceError(f"Query error: {error}")
 
     def escape(self, obj, mapping=None):
-        """Escape whatever value you pass to it."""
+        """Escape a value for safe inclusion in SQL queries.
+
+        Args:
+            obj: Value to escape (string, bytes, number, etc.)
+            mapping: Optional character mapping for escaping
+
+        Returns:
+            Escaped version of the input suitable for SQL queries
+
+        Example:
+            >>> conn = Connection()
+            >>> safe_value = conn.escape("O'Reilly")
+            >>> query = f"SELECT * FROM users WHERE name = {safe_value}"
+        """
         return converters.escape_item(obj, mapping)
 
     def escape_string(self, s):
+        """Escape a string value for SQL queries.
+
+        Args:
+            s (str): String to escape
+
+        Returns:
+            str: Escaped string safe for SQL inclusion
+        """
         return converters.escape_string(s)
 
     def _quote_bytes(self, s):
+        """Quote and escape bytes data for SQL queries.
+
+        Args:
+            s (bytes): Bytes data to quote
+
+        Returns:
+            str: Quoted and escaped bytes representation
+        """
         return converters.escape_bytes(s)
 
     def __enter__(self):
-        """Context manager that returns a Cursor"""
+        """Enter context manager and return a cursor.
+
+        Returns:
+            Cursor: New cursor for this connection
+
+        Example:
+            >>> with Connection() as cur:
+            ...     cur.execute("SELECT 1")
+            ...     result = cur.fetchone()
+        """
         return self.cursor()
 
     def __exit__(self, exc, value, traceback):
-        """On successful exit, commit. On exception, rollback"""
+        """Exit context manager with proper cleanup.
+
+        Commits on successful exit, rolls back on exception, and always closes connection.
+
+        Args:
+            exc: Exception type (if any)
+            value: Exception value (if any)
+            traceback: Exception traceback (if any)
+        """
         if exc:
             self.rollback()
         else:
@@ -96,5 +245,13 @@ class Connection(object):
 
     @property
     def resp(self):
-        """Return the last query response"""
+        """Get the last query response.
+
+        Returns:
+            The raw response from the last query() call
+
+        Note:
+            This property is updated each time query() is called directly.
+            It does not reflect queries executed through cursors.
+        """
         return self._resp