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

chdb/state/sqlitelike.py

@@ -19,7 +19,39 @@ _process_result_format_funs = {
 
 # return pyarrow table
 def to_arrowTable(res):
-    """convert res to arrow table"""
+    """Convert query result to PyArrow Table.
+
+    This function converts chdb query results to a PyArrow Table format,
+    which provides efficient columnar data access and interoperability
+    with other data processing libraries.
+
+    Args:
+        res: Query result object from chdb containing Arrow format data
+
+    Returns:
+        pyarrow.Table: PyArrow Table containing the query results
+
+    Raises:
+        ImportError: If pyarrow or pandas packages are not installed
+
+    .. note::
+        This function requires both pyarrow and pandas to be installed.
+        Install them with: ``pip install pyarrow pandas``
+
+    .. warning::
+        Empty results return an empty PyArrow Table with no schema.
+
+    Examples:
+        >>> import chdb
+        >>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
+        >>> table = to_arrowTable(result)
+        >>> print(table.schema)
+        num: int64
+        text: string
+        >>> print(table.to_pandas())
+           num   text
+        0    1  hello
+    """
     # try import pyarrow and pandas, if failed, raise ImportError with suggestion
     try:
         import pyarrow as pa  # noqa
@@ -30,12 +62,48 @@ def to_arrowTable(res):
         raise ImportError("Failed to import pyarrow or pandas") from None
     if len(res) == 0:
         return pa.Table.from_batches([], schema=pa.schema([]))
-    return pa.RecordBatchFileReader(res.bytes()).read_all()
+
+    memview = res.get_memview()
+    return pa.RecordBatchFileReader(memview.view()).read_all()
 
 
 # return pandas dataframe
 def to_df(r):
-    """convert arrow table to Dataframe"""
+    """Convert query result to Pandas DataFrame.
+
+    This function converts chdb query results to a Pandas DataFrame format
+    by first converting to PyArrow Table and then to DataFrame. This provides
+    convenient data analysis capabilities with Pandas API.
+
+    Args:
+        r: Query result object from chdb containing Arrow format data
+
+    Returns:
+        pandas.DataFrame: DataFrame containing the query results with
+        appropriate column names and data types
+
+    Raises:
+        ImportError: If pyarrow or pandas packages are not installed
+
+    .. note::
+        This function uses multi-threading for the Arrow to Pandas conversion
+        to improve performance on large datasets.
+
+    .. seealso::
+        :func:`to_arrowTable` - For PyArrow Table format conversion
+
+    Examples:
+        >>> import chdb
+        >>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow")
+        >>> df = to_df(result)
+        >>> print(df)
+           num   text
+        0    1  hello
+        >>> print(df.dtypes)
+        num      int64
+        text    object
+        dtype: object
+    """
     t = to_arrowTable(r)
     return t.to_pandas(use_threads=True)
 
@@ -49,7 +117,35 @@ class StreamingResult:
         self._supports_record_batch = supports_record_batch
 
     def fetch(self):
-        """Fetch next chunk of streaming results"""
+        """Fetch the next chunk of streaming results.
+
+        This method retrieves the next available chunk of data from the streaming
+        query result. It automatically handles exhaustion detection and applies
+        the configured result transformation function.
+
+        Returns:
+            The next chunk of results in the format specified during query execution,
+            or None if no more data is available
+
+        Raises:
+            RuntimeError: If the streaming query encounters an error
+
+        .. note::
+            Once the stream is exhausted (returns None), subsequent calls will
+            continue to return None.
+
+        .. warning::
+            This method should be called sequentially. Concurrent calls may
+            result in undefined behavior.
+
+        Examples:
+            >>> conn = Connection(":memory:")
+            >>> stream = conn.send_query("SELECT number FROM numbers(100)")
+            >>> chunk = stream.fetch()
+            >>> while chunk is not None:
+            ...     print(f"Got chunk with {len(chunk)} bytes")
+            ...     chunk = stream.fetch()
+        """
         if self._exhausted:
             return None
 
@@ -84,9 +180,51 @@ class StreamingResult:
         self.cancel()
 
     def close(self):
+        """Close the streaming result and cleanup resources.
+
+        This method is an alias for :meth:`cancel` and provides a more
+        intuitive interface for resource cleanup. It cancels the streaming
+        query and marks the result as exhausted.
+
+        .. seealso::
+            :meth:`cancel` - The underlying cancellation method
+
+        Examples:
+            >>> stream = conn.send_query("SELECT * FROM large_table")
+            >>> # Process some data
+            >>> chunk = stream.fetch()
+            >>> # Close when done
+            >>> stream.close()
+        """
         self.cancel()
 
     def cancel(self):
+        """Cancel the streaming query and cleanup resources.
+
+        This method cancels the streaming query on the server side and marks
+        the StreamingResult as exhausted. After calling this method, no more
+        data can be fetched from this result.
+
+        Raises:
+            RuntimeError: If cancellation fails on the server side
+
+        .. note::
+            This method is idempotent - calling it multiple times is safe
+            and will not cause errors.
+
+        .. warning::
+            Once cancelled, the streaming result cannot be resumed or reset.
+            You must create a new query to get fresh results.
+
+        Examples:
+            >>> stream = conn.send_query("SELECT * FROM huge_table")
+            >>> # Process first few chunks
+            >>> for i, chunk in enumerate(stream):
+            ...     if i >= 5:  # Stop after 5 chunks
+            ...         stream.cancel()
+            ...         break
+            ...     process_chunk(chunk)
+        """
         if not self._exhausted:
             self._exhausted = True
             try:
@@ -266,10 +404,92 @@ class Connection:
         self._conn = _chdb.connect(connection_string)
 
     def cursor(self) -> "Cursor":
+        """Create a cursor object for executing queries.
+
+        This method creates a database cursor that provides the standard
+        DB-API 2.0 interface for executing queries and fetching results.
+        The cursor allows for fine-grained control over query execution
+        and result retrieval.
+
+        Returns:
+            Cursor: A cursor object for database operations
+
+        .. note::
+            Creating a new cursor will replace any existing cursor associated
+            with this connection. Only one cursor per connection is supported.
+
+        Examples:
+            >>> conn = connect(":memory:")
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("CREATE TABLE test (id INT, name String)")
+            >>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
+            >>> cursor.execute("SELECT * FROM test")
+            >>> rows = cursor.fetchall()
+            >>> print(rows)
+            ((1, 'Alice'),)
+
+        .. seealso::
+            :class:`Cursor` - Database cursor implementation
+        """
         self._cursor = Cursor(self._conn)
         return self._cursor
 
     def query(self, query: str, format: str = "CSV") -> Any:
+        """Execute a SQL query and return the complete results.
+
+        This method executes a SQL query synchronously and returns the complete
+        result set. It supports various output formats and automatically applies
+        format-specific post-processing.
+
+        Args:
+            query (str): SQL query string to execute
+            format (str, optional): Output format for results. Defaults to "CSV".
+                Supported formats:
+
+                - "CSV" - Comma-separated values (string)
+                - "JSON" - JSON format (string)
+                - "Arrow" - Apache Arrow format (bytes)
+                - "Dataframe" - Pandas DataFrame (requires pandas)
+                - "Arrowtable" - PyArrow Table (requires pyarrow)
+
+        Returns:
+            Query results in the specified format. Type depends on format:
+
+            - String formats return str
+            - Arrow format returns bytes
+            - dataframe format returns pandas.DataFrame
+            - arrowtable format returns pyarrow.Table
+
+        Raises:
+            RuntimeError: If query execution fails
+            ImportError: If required packages for format are not installed
+
+        .. warning::
+            This method loads the entire result set into memory. For large
+            results, consider using :meth:`send_query` for streaming.
+
+        Examples:
+            >>> conn = connect(":memory:")
+            >>>
+            >>> # Basic CSV query
+            >>> result = conn.query("SELECT 1 as num, 'hello' as text")
+            >>> print(result)
+            num,text
+            1,hello
+
+            >>> # DataFrame format
+            >>> df = conn.query("SELECT number FROM numbers(5)", "dataframe")
+            >>> print(df)
+               number
+            0       0
+            1       1
+            2       2
+            3       3
+            4       4
+
+        .. seealso::
+            :meth:`send_query` - For streaming query execution
+        """
         lower_output_format = format.lower()
         result_func = _process_result_format_funs.get(lower_output_format, lambda x: x)
         if lower_output_format in _arrow_format:
@@ -279,6 +499,64 @@ class Connection:
         return result_func(result)
 
     def send_query(self, query: str, format: str = "CSV") -> StreamingResult:
+        """Execute a SQL query and return a streaming result iterator.
+
+        This method executes a SQL query and returns a StreamingResult object
+        that allows you to iterate over the results without loading everything
+        into memory at once. This is ideal for processing large result sets.
+
+        Args:
+            query (str): SQL query string to execute
+            format (str, optional): Output format for results. Defaults to "CSV".
+                Supported formats:
+
+                - "CSV" - Comma-separated values
+                - "JSON" - JSON format
+                - "Arrow" - Apache Arrow format (enables record_batch() method)
+                - "dataframe" - Pandas DataFrame chunks
+                - "arrowtable" - PyArrow Table chunks
+
+        Returns:
+            StreamingResult: A streaming iterator for query results that supports:
+
+            - Iterator protocol (for loops)
+            - Context manager protocol (with statements)
+            - Manual fetching with fetch() method
+            - PyArrow RecordBatch streaming (Arrow format only)
+
+        Raises:
+            RuntimeError: If query execution fails
+            ImportError: If required packages for format are not installed
+
+        .. note::
+            Only the "Arrow" format supports the record_batch() method on the
+            returned StreamingResult.
+
+        Examples:
+            >>> conn = connect(":memory:")
+            >>>
+            >>> # Basic streaming
+            >>> stream = conn.send_query("SELECT number FROM numbers(1000)")
+            >>> for chunk in stream:
+            ...     print(f"Processing chunk: {len(chunk)} bytes")
+
+            >>> # Using context manager for cleanup
+            >>> with conn.send_query("SELECT * FROM large_table") as stream:
+            ...     chunk = stream.fetch()
+            ...     while chunk:
+            ...         process_data(chunk)
+            ...         chunk = stream.fetch()
+
+            >>> # Arrow format with RecordBatch streaming
+            >>> stream = conn.send_query("SELECT * FROM data", "Arrow")
+            >>> reader = stream.record_batch(rows_per_batch=10000)
+            >>> for batch in reader:
+            ...     print(f"Batch shape: {batch.num_rows} x {batch.num_columns}")
+
+        .. seealso::
+            :meth:`query` - For non-streaming query execution
+            :class:`StreamingResult` - Streaming result iterator
+        """
         lower_output_format = format.lower()
         supports_record_batch = lower_output_format == "arrow"
         result_func = _process_result_format_funs.get(lower_output_format, lambda x: x)
@@ -289,6 +567,31 @@ class Connection:
         return StreamingResult(c_stream_result, self._conn, result_func, supports_record_batch)
 
     def close(self) -> None:
+        """Close the connection and cleanup resources.
+
+        This method closes the database connection and cleans up any associated
+        resources including active cursors. After calling this method, the
+        connection becomes invalid and cannot be used for further operations.
+
+        .. note::
+            This method is idempotent - calling it multiple times is safe.
+
+        .. warning::
+            Any ongoing streaming queries will be cancelled when the connection
+            is closed. Ensure all important data is processed before closing.
+
+        Examples:
+            >>> conn = connect("test.db")
+            >>> # Use connection for queries
+            >>> conn.query("CREATE TABLE test (id INT)")
+            >>> # Close when done
+            >>> conn.close()
+
+            >>> # Using with context manager (automatic cleanup)
+            >>> with connect("test.db") as conn:
+            ...     conn.query("SELECT 1")
+            ...     # Connection automatically closed
+        """
         # print("close")
         if self._cursor:
             self._cursor.close()
@@ -303,6 +606,54 @@ class Cursor:
         self._current_row: int = 0
 
     def execute(self, query: str) -> None:
+        """Execute a SQL query and prepare results for fetching.
+
+        This method executes a SQL query and prepares the results for retrieval
+        using the fetch methods. It handles the parsing of result data and
+        automatic type conversion for ClickHouse data types.
+
+        Args:
+            query (str): SQL query string to execute
+
+        Raises:
+            Exception: If query execution fails or result parsing fails
+
+        .. note::
+            This method follows DB-API 2.0 specifications for cursor.execute().
+            After execution, use fetchone(), fetchmany(), or fetchall() to
+            retrieve results.
+
+        .. note::
+            The method automatically converts ClickHouse data types to appropriate
+            Python types:
+
+            - Int/UInt types → int
+            - Float types → float
+            - String/FixedString → str
+            - DateTime → datetime.datetime
+            - Date → datetime.date
+            - Bool → bool
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>>
+            >>> # Execute DDL
+            >>> cursor.execute("CREATE TABLE test (id INT, name String)")
+            >>>
+            >>> # Execute DML
+            >>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')")
+            >>>
+            >>> # Execute SELECT and fetch results
+            >>> cursor.execute("SELECT * FROM test")
+            >>> rows = cursor.fetchall()
+            >>> print(rows)
+            ((1, 'Alice'),)
+
+        .. seealso::
+            :meth:`fetchone` - Fetch single row
+            :meth:`fetchmany` - Fetch multiple rows
+            :meth:`fetchall` - Fetch all remaining rows
+        """
         self._cursor.execute(query)
         result_mv = self._cursor.get_memview()
         if self._cursor.has_error():
@@ -404,9 +755,53 @@ class Cursor:
             raise Exception(f"Failed to parse JSON data: {e}")
 
     def commit(self) -> None:
+        """Commit any pending transaction.
+
+        This method commits any pending database transaction. In ClickHouse,
+        most operations are auto-committed, but this method is provided for
+        DB-API 2.0 compatibility.
+
+        .. note::
+            ClickHouse typically auto-commits operations, so explicit commits
+            are usually not necessary. This method is provided for compatibility
+            with standard DB-API 2.0 workflow.
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("INSERT INTO test VALUES (1, 'data')")
+            >>> cursor.commit()
+        """
         self._cursor.commit()
 
     def fetchone(self) -> Optional[tuple]:
+        """Fetch the next row from the query result.
+
+        This method retrieves the next available row from the current query
+        result set. It returns a tuple containing the column values with
+        appropriate Python type conversion applied.
+
+        Returns:
+            Optional[tuple]: Next row as a tuple of column values, or None
+            if no more rows are available
+
+        .. note::
+            This method follows DB-API 2.0 specifications. Column values are
+            automatically converted to appropriate Python types based on
+            ClickHouse column types.
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("SELECT id, name FROM users")
+            >>> row = cursor.fetchone()
+            >>> while row is not None:
+            ...     user_id, user_name = row
+            ...     print(f"User {user_id}: {user_name}")
+            ...     row = cursor.fetchone()
+
+        .. seealso::
+            :meth:`fetchmany` - Fetch multiple rows
+            :meth:`fetchall` - Fetch all remaining rows
+        """
         if not self._current_table or self._current_row >= len(self._current_table):
             return None
 
@@ -416,6 +811,38 @@ class Cursor:
         return row
 
     def fetchmany(self, size: int = 1) -> tuple:
+        """Fetch multiple rows from the query result.
+
+        This method retrieves up to 'size' rows from the current query result
+        set. It returns a tuple of row tuples, with each row containing column
+        values with appropriate Python type conversion.
+
+        Args:
+            size (int, optional): Maximum number of rows to fetch. Defaults to 1.
+
+        Returns:
+            tuple: Tuple containing up to 'size' row tuples. May contain fewer
+            rows if the result set is exhausted.
+
+        .. note::
+            This method follows DB-API 2.0 specifications. It will return fewer
+            than 'size' rows if the result set is exhausted.
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("SELECT * FROM large_table")
+            >>>
+            >>> # Process results in batches
+            >>> while True:
+            ...     batch = cursor.fetchmany(100)  # Fetch 100 rows at a time
+            ...     if not batch:
+            ...         break
+            ...     process_batch(batch)
+
+        .. seealso::
+            :meth:`fetchone` - Fetch single row
+            :meth:`fetchall` - Fetch all remaining rows
+        """
         if not self._current_table:
             return tuple()
 
@@ -427,6 +854,32 @@ class Cursor:
         return tuple(rows)
 
     def fetchall(self) -> tuple:
+        """Fetch all remaining rows from the query result.
+
+        This method retrieves all remaining rows from the current query result
+        set starting from the current cursor position. It returns a tuple of
+        row tuples with appropriate Python type conversion applied.
+
+        Returns:
+            tuple: Tuple containing all remaining row tuples from the result set.
+            Returns empty tuple if no rows are available.
+
+        .. warning::
+            This method loads all remaining rows into memory at once. For large
+            result sets, consider using :meth:`fetchmany` to process results
+            in batches.
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("SELECT id, name FROM users")
+            >>> all_users = cursor.fetchall()
+            >>> for user_id, user_name in all_users:
+            ...     print(f"User {user_id}: {user_name}")
+
+        .. seealso::
+            :meth:`fetchone` - Fetch single row
+            :meth:`fetchmany` - Fetch multiple rows in batches
+        """
         if not self._current_table:
             return tuple()
 
@@ -436,6 +889,22 @@ class Cursor:
         return tuple(remaining_rows)
 
     def close(self) -> None:
+        """Close the cursor and cleanup resources.
+
+        This method closes the cursor and cleans up any associated resources.
+        After calling this method, the cursor becomes invalid and cannot be
+        used for further operations.
+
+        .. note::
+            This method is idempotent - calling it multiple times is safe.
+            The cursor is also automatically closed when the connection is closed.
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("SELECT 1")
+            >>> result = cursor.fetchone()
+            >>> cursor.close()  # Cleanup cursor resources
+        """
         self._cursor.close()
 
     def __iter__(self):
@@ -448,20 +917,81 @@ class Cursor:
         return row
 
     def column_names(self) -> list:
-        """Return a list of column names from the last executed query"""
+        """Return a list of column names from the last executed query.
+
+        This method returns the column names from the most recently executed
+        SELECT query. The names are returned in the same order as they appear
+        in the result set.
+
+        Returns:
+            list: List of column name strings, or empty list if no query
+            has been executed or the query returned no columns
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("SELECT id, name, email FROM users LIMIT 1")
+            >>> print(cursor.column_names())
+            ['id', 'name', 'email']
+
+        .. seealso::
+            :meth:`column_types` - Get column type information
+            :attr:`description` - DB-API 2.0 column description
+        """
         return self._column_names if hasattr(self, "_column_names") else []
 
     def column_types(self) -> list:
-        """Return a list of column types from the last executed query"""
+        """Return a list of column types from the last executed query.
+
+        This method returns the ClickHouse column type names from the most
+        recently executed SELECT query. The types are returned in the same
+        order as they appear in the result set.
+
+        Returns:
+            list: List of ClickHouse type name strings, or empty list if no
+            query has been executed or the query returned no columns
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("SELECT toInt32(1), toString('hello')")
+            >>> print(cursor.column_types())
+            ['Int32', 'String']
+
+        .. seealso::
+            :meth:`column_names` - Get column name information
+            :attr:`description` - DB-API 2.0 column description
+        """
         return self._column_types if hasattr(self, "_column_types") else []
 
     @property
     def description(self) -> list:
-        """
-        Return a description of the columns as per DB-API 2.0
-        Returns a list of 7-item tuples, each containing:
+        """Return column description as per DB-API 2.0 specification.
+
+        This property returns a list of 7-item tuples describing each column
+        in the result set of the last executed SELECT query. Each tuple contains:
         (name, type_code, display_size, internal_size, precision, scale, null_ok)
-        where only name and type_code are provided
+
+        Currently, only name and type_code are provided, with other fields set to None.
+
+        Returns:
+            list: List of 7-tuples describing each column, or empty list if no
+            SELECT query has been executed
+
+        .. note::
+            This follows the DB-API 2.0 specification for cursor.description.
+            Only the first two elements (name and type_code) contain meaningful
+            data in this implementation.
+
+        Examples:
+            >>> cursor = conn.cursor()
+            >>> cursor.execute("SELECT id, name FROM users LIMIT 1")
+            >>> for desc in cursor.description:
+            ...     print(f"Column: {desc[0]}, Type: {desc[1]}")
+            Column: id, Type: Int32
+            Column: name, Type: String
+
+        .. seealso::
+            :meth:`column_names` - Get just column names
+            :meth:`column_types` - Get just column types
         """
         if not hasattr(self, "_column_names") or not self._column_names:
             return []
@@ -473,33 +1003,77 @@ class Cursor:
 
 
 def connect(connection_string: str = ":memory:") -> Connection:
-    """
-    Create a connection to chDB backgroud server.
-    Only one open connection is allowed per process. Use `close` to close the connection.
-    If called with the same connection string, the same connection object will be returned.
-    You can use the connection object to create cursor object. `cursor` method will return a cursor object.
+    """Create a connection to chDB background server.
+
+    This function establishes a connection to the chDB (ClickHouse) database engine.
+    Only one open connection is allowed per process. Multiple calls with the same
+    connection string will return the same connection object.
 
     Args:
-        connection_string (str, optional): Connection string. Defaults to ":memory:".
-        Also support file path like:
-          - ":memory:" (for in-memory database)
-          - "test.db" (for relative path)
-          - "file:test.db" (same as above)
-          - "/path/to/test.db" (for absolute path)
-          - "file:/path/to/test.db" (same as above)
-          - "file:test.db?param1=value1&param2=value2" (for relative path with query params)
-          - "file::memory:?verbose&log-level=test" (for in-memory database with query params)
-          - "///path/to/test.db?param1=value1&param2=value2" (for absolute path)
-
-        Connection string args handling:
-          Connection string can contain query params like "file:test.db?param1=value1&param2=value2"
-          "param1=value1" will be passed to ClickHouse engine as start up args.
-
-          For more details, see `clickhouse local --help --verbose`
-          Some special args handling:
-            - "mode=ro" would be "--readonly=1" for clickhouse (read-only mode)
+        connection_string (str, optional): Database connection string. Defaults to ":memory:".
+            Supported connection string formats:
+
+            **Basic formats:**
+
+            - ":memory:" - In-memory database (default)
+            - "test.db" - Relative path database file
+            - "file:test.db" - Same as relative path
+            - "/path/to/test.db" - Absolute path database file
+            - "file:/path/to/test.db" - Same as absolute path
+
+            **With query parameters:**
+
+            - "file:test.db?param1=value1&param2=value2" - Relative path with params
+            - "file::memory:?verbose&log-level=test" - In-memory with params
+            - "///path/to/test.db?param1=value1&param2=value2" - Absolute path with params
+
+            **Query parameter handling:**
+
+            Query parameters are passed to ClickHouse engine as startup arguments.
+            Special parameter handling:
+
+            - "mode=ro" becomes "--readonly=1" (read-only mode)
+            - "verbose" enables verbose logging
+            - "log-level=test" sets logging level
+
+            For complete parameter list, see ``clickhouse local --help --verbose``
 
     Returns:
-        Connection: Connection object
+        Connection: Database connection object that supports:
+
+        - Creating cursors with :meth:`Connection.cursor`
+        - Direct queries with :meth:`Connection.query`
+        - Streaming queries with :meth:`Connection.send_query`
+        - Context manager protocol for automatic cleanup
+
+    Raises:
+        RuntimeError: If connection to database fails
+
+    .. warning::
+        Only one connection per process is supported. Creating a new connection
+        will close any existing connection.
+
+    Examples:
+        >>> # In-memory database
+        >>> conn = connect()
+        >>> conn = connect(":memory:")
+        >>>
+        >>> # File-based database
+        >>> conn = connect("my_data.db")
+        >>> conn = connect("/path/to/data.db")
+        >>>
+        >>> # With parameters
+        >>> conn = connect("data.db?mode=ro")  # Read-only mode
+        >>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
+        >>>
+        >>> # Using context manager for automatic cleanup
+        >>> with connect("data.db") as conn:
+        ...     result = conn.query("SELECT 1")
+        ...     print(result)
+        >>> # Connection automatically closed
+
+    .. seealso::
+        :class:`Connection` - Database connection class
+        :class:`Cursor` - Database cursor for DB-API 2.0 operations
     """
     return Connection(connection_string)