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

chdb/dbapi/err.py

@@ -1,61 +1,300 @@
+"""Exception classes for chdb database operations.
+
+This module provides a complete hierarchy of exception classes for handling
+database-related errors in chdb, following the Python Database API Specification v2.0.
+
+The exception hierarchy is structured as follows::
+
+    StandardError
+    ├── Warning
+    └── Error
+        ├── InterfaceError
+        └── DatabaseError
+            ├── DataError
+            ├── OperationalError
+            ├── IntegrityError
+            ├── InternalError
+            ├── ProgrammingError
+            └── NotSupportedError
+
+Each exception class represents a specific category of database errors:
+
+- **Warning**: Non-fatal warnings during database operations
+- **InterfaceError**: Problems with the database interface itself
+- **DatabaseError**: Base class for all database-related errors
+- **DataError**: Problems with data processing (invalid values, type errors)
+- **OperationalError**: Database operational issues (connectivity, resources)
+- **IntegrityError**: Constraint violations (foreign keys, uniqueness)
+- **InternalError**: Database internal errors and corruption
+- **ProgrammingError**: SQL syntax errors and API misuse
+- **NotSupportedError**: Unsupported features or operations
+
+.. note::
+    These exception classes are compliant with Python DB API 2.0 specification
+    and provide consistent error handling across different database operations.
+
+.. seealso::
+    - `Python Database API Specification v2.0 <https://peps.python.org/pep-0249/>`_
+    - :mod:`chdb.dbapi.connections` - Database connection management
+    - :mod:`chdb.dbapi.cursors` - Database cursor operations
+
+Examples:
+    >>> try:
+    ...     cursor.execute("SELECT * FROM nonexistent_table")
+    ... except ProgrammingError as e:
+    ...     print(f"SQL Error: {e}")
+    ...
+    SQL Error: Table 'nonexistent_table' doesn't exist
+
+    >>> try:
+    ...     cursor.execute("INSERT INTO users (id) VALUES (1), (1)")
+    ... except IntegrityError as e:
+    ...     print(f"Constraint violation: {e}")
+    ...
+    Constraint violation: Duplicate entry '1' for key 'PRIMARY'
+"""
+
+
 class StandardError(Exception):
-    """Exception related to operation with chdb."""
+    """Exception related to operation with chdb.
+
+    This is the base class for all chdb-related exceptions. It inherits from
+    Python's built-in Exception class and serves as the root of the exception
+    hierarchy for database operations.
+
+    .. note::
+        This exception class follows the Python DB API 2.0 specification
+        for database exception handling.
+    """
 
 
 class Warning(StandardError):
-    """Exception raised for important warnings like data truncations
-    while inserting, etc."""
+    """Exception raised for important warnings like data truncations while inserting, etc.
+
+    This exception is raised when the database operation completes but with
+    important warnings that should be brought to the attention of the application.
+    Common scenarios include:
+
+    - Data truncation during insertion
+    - Precision loss in numeric conversions
+    - Character set conversion warnings
+
+    .. note::
+        This follows the Python DB API 2.0 specification for warning exceptions.
+    """
 
 
 class Error(StandardError):
-    """Exception that is the base class of all other error exceptions
-    (not Warning)."""
+    """Exception that is the base class of all other error exceptions (not Warning).
+
+    This is the base class for all error exceptions in chdb, excluding warnings.
+    It serves as the parent class for all database error conditions that prevent
+    successful completion of operations.
+
+    .. note::
+        This exception hierarchy follows the Python DB API 2.0 specification.
+
+    .. seealso::
+        :class:`Warning` - For non-fatal warnings that don't prevent operation completion
+    """
 
 
 class InterfaceError(Error):
-    """Exception raised for errors that are related to the database
-    interface rather than the database itself."""
+    """Exception raised for errors that are related to the database interface rather than the database itself.
+
+    This exception is raised when there are problems with the database interface
+    implementation, such as:
+
+    - Invalid connection parameters
+    - API misuse (calling methods on closed connections)
+    - Interface-level protocol errors
+    - Module import or initialization failures
+
+    :raises InterfaceError: When database interface encounters errors unrelated to database operations
+
+    .. note::
+        These errors are typically programming errors or configuration issues
+        that can be resolved by fixing the client code or configuration.
+    """
 
 
 class DatabaseError(Error):
-    """Exception raised for errors that are related to the
-    database."""
+    """Exception raised for errors that are related to the database.
+
+    This is the base class for all database-related errors. It encompasses
+    all errors that occur during database operations and are related to the
+    database itself rather than the interface.
+
+    Common scenarios include:
+
+    - SQL execution errors
+    - Database connectivity issues
+    - Transaction-related problems
+    - Database-specific constraints violations
+
+    .. note::
+        This serves as the parent class for more specific database error types
+        such as :class:`DataError`, :class:`OperationalError`, etc.
+    """
 
 
 class DataError(DatabaseError):
-    """Exception raised for errors that are due to problems with the
-    processed data like division by zero, numeric value out of range,
-    etc."""
+    """Exception raised for errors that are due to problems with the processed data.
+
+    This exception is raised when database operations fail due to issues with
+    the data being processed, such as:
+
+    - Division by zero operations
+    - Numeric values out of range
+    - Invalid date/time values
+    - String truncation errors
+    - Type conversion failures
+    - Invalid data format for column type
+
+    :raises DataError: When data validation or processing fails
+
+    Examples:
+        >>> # Division by zero in SQL
+        >>> cursor.execute("SELECT 1/0")
+        DataError: Division by zero
+
+        >>> # Invalid date format
+        >>> cursor.execute("INSERT INTO table VALUES ('invalid-date')")
+        DataError: Invalid date format
+    """
 
 
 class OperationalError(DatabaseError):
-    """Exception raised for errors that are related to the database's
-    operation and not necessarily under the control of the programmer,
-    e.g. an unexpected disconnect occurs, the data source name is not
-    found, a transaction could not be processed, a memory allocation
-    error occurred during processing, etc."""
+    """Exception raised for errors that are related to the database's operation.
+
+    This exception is raised for errors that occur during database operation
+    and are not necessarily under the control of the programmer, including:
+
+    - Unexpected disconnection from database
+    - Database server not found or unreachable
+    - Transaction processing failures
+    - Memory allocation errors during processing
+    - Disk space or resource exhaustion
+    - Database server internal errors
+    - Authentication or authorization failures
+
+    :raises OperationalError: When database operations fail due to operational issues
+
+    .. note::
+        These errors are typically transient and may be resolved by retrying
+        the operation or addressing system-level issues.
+
+    .. warning::
+        Some operational errors may indicate serious system problems that
+        require administrative intervention.
+    """
 
 
 class IntegrityError(DatabaseError):
-    """Exception raised when the relational integrity of the database
-    is affected, e.g. a foreign key check fails, duplicate key,
-    etc."""
+    """Exception raised when the relational integrity of the database is affected.
+
+    This exception is raised when database operations violate integrity constraints,
+    including:
+
+    - Foreign key constraint violations
+    - Primary key or unique constraint violations (duplicate keys)
+    - Check constraint violations
+    - NOT NULL constraint violations
+    - Referential integrity violations
+
+    :raises IntegrityError: When database integrity constraints are violated
+
+    Examples:
+        >>> # Duplicate primary key
+        >>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')")
+        >>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')")
+        IntegrityError: Duplicate entry '1' for key 'PRIMARY'
+
+        >>> # Foreign key violation
+        >>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
+        IntegrityError: Cannot add or update a child row: foreign key constraint fails
+    """
 
 
 class InternalError(DatabaseError):
-    """Exception raised when the database encounters an internal
-    error, e.g. the cursor is not valid anymore, the transaction is
-    out of sync, etc."""
+    """Exception raised when the database encounters an internal error.
+
+    This exception is raised when the database system encounters internal
+    errors that are not caused by the application, such as:
+
+    - Invalid cursor state (cursor is not valid anymore)
+    - Transaction state inconsistencies (transaction is out of sync)
+    - Database corruption issues
+    - Internal data structure corruption
+    - System-level database errors
+
+    :raises InternalError: When database encounters internal inconsistencies
+
+    .. warning::
+        Internal errors may indicate serious database problems that require
+        database administrator attention. These errors are typically not
+        recoverable through application-level retry logic.
+
+    .. note::
+        These errors are generally outside the control of the application
+        and may require database restart or repair operations.
+    """
 
 
 class ProgrammingError(DatabaseError):
-    """Exception raised for programming errors, e.g. table not found
-    or already exists, syntax error in the SQL statement, wrong number
-    of parameters specified, etc."""
+    """Exception raised for programming errors in database operations.
+
+    This exception is raised when there are programming errors in the
+    application's database usage, including:
+
+    - Table or column not found
+    - Table or index already exists when creating
+    - SQL syntax errors in statements
+    - Wrong number of parameters specified in prepared statements
+    - Invalid SQL operations (e.g., DROP on non-existent objects)
+    - Incorrect usage of database API methods
+
+    :raises ProgrammingError: When SQL statements or API usage contains errors
+
+    Examples:
+        >>> # Table not found
+        >>> cursor.execute("SELECT * FROM nonexistent_table")
+        ProgrammingError: Table 'nonexistent_table' doesn't exist
+
+        >>> # SQL syntax error
+        >>> cursor.execute("SELCT * FROM users")
+        ProgrammingError: You have an error in your SQL syntax
+
+        >>> # Wrong parameter count
+        >>> cursor.execute("INSERT INTO users (name, age) VALUES (%s)", ('John',))
+        ProgrammingError: Column count doesn't match value count
+    """
 
 
 class NotSupportedError(DatabaseError):
-    """Exception raised in case a method or database API was used
-    which is not supported by the database, e.g. requesting a
-    .rollback() on a connection that does not support transaction or
-    has transactions turned off."""
+    """Exception raised when a method or database API is not supported.
+
+    This exception is raised when the application attempts to use database
+    features or API methods that are not supported by the current database
+    configuration or version, such as:
+
+    - Requesting rollback() on connections without transaction support
+    - Using advanced SQL features not supported by the database version
+    - Calling methods not implemented by the current driver
+    - Attempting to use disabled database features
+
+    :raises NotSupportedError: When unsupported database features are accessed
+
+    Examples:
+        >>> # Transaction rollback on non-transactional connection
+        >>> connection.rollback()
+        NotSupportedError: Transactions are not supported
+
+        >>> # Using unsupported SQL syntax
+        >>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
+        NotSupportedError: WITH clause not supported in this database version
+
+    .. note::
+        Check database documentation and driver capabilities to avoid
+        these errors. Consider graceful fallbacks where possible.
+    """

chdb/dbapi/times.py

@@ -1,20 +1,191 @@
+"""Date and time type constructors for chdb database operations.
+
+This module provides Python DB API 2.0 compliant date and time constructors
+for converting between Unix timestamps and Python datetime objects. These
+functions are essential for handling temporal data in database operations.
+
+The module provides the following type aliases and constructor functions:
+
+Type Aliases:
+    - **Date**: Alias for :class:`datetime.date`
+    - **Time**: Alias for :class:`datetime.time`
+    - **TimeDelta**: Alias for :class:`datetime.timedelta`
+    - **Timestamp**: Alias for :class:`datetime.datetime`
+
+Constructor Functions:
+    - :func:`DateFromTicks`: Convert Unix timestamp to date object
+    - :func:`TimeFromTicks`: Convert Unix timestamp to time object
+    - :func:`TimestampFromTicks`: Convert Unix timestamp to datetime object
+
+These constructors are particularly useful when working with database systems
+that store temporal data as Unix timestamps or when interfacing with APIs
+that use timestamp representations.
+
+.. note::
+    All constructor functions use the local timezone for timestamp conversion.
+    For UTC conversions, consider using :func:`datetime.datetime.utcfromtimestamp`.
+
+.. seealso::
+    - :mod:`datetime` - Core datetime functionality
+    - :mod:`time` - Time access and conversions
+    - `Python DB API Specification v2.0 <https://peps.python.org/pep-0249/>`_
+
+Examples:
+    >>> import time
+    >>> timestamp = time.time()  # Current Unix timestamp
+    >>>
+    >>> # Convert to different temporal types
+    >>> date_obj = DateFromTicks(timestamp)
+    >>> time_obj = TimeFromTicks(timestamp)
+    >>> datetime_obj = TimestampFromTicks(timestamp)
+    >>>
+    >>> print(f"Date: {date_obj}")
+    >>> print(f"Time: {time_obj}")
+    >>> print(f"DateTime: {datetime_obj}")
+    Date: 2023-12-25
+    Time: 14:30:45
+    DateTime: 2023-12-25 14:30:45
+"""
+
 from time import localtime
 from datetime import date, datetime, time, timedelta
 
 
 Date = date
+"""Type alias for :class:`datetime.date`.
+
+This provides a standard DB API 2.0 compliant alias for the date class,
+allowing portable code across different database drivers.
+
+:type: type[datetime.date]
+"""
+
 Time = time
+"""Type alias for :class:`datetime.time`.
+
+This provides a standard DB API 2.0 compliant alias for the time class,
+allowing portable code across different database drivers.
+
+:type: type[datetime.time]
+"""
+
 TimeDelta = timedelta
+"""Type alias for :class:`datetime.timedelta`.
+
+This provides a standard DB API 2.0 compliant alias for the timedelta class,
+useful for representing time intervals and durations in database operations.
+
+:type: type[datetime.timedelta]
+"""
+
 Timestamp = datetime
+"""Type alias for :class:`datetime.datetime`.
+
+This provides a standard DB API 2.0 compliant alias for the datetime class,
+allowing portable code across different database drivers.
+
+:type: type[datetime.datetime]
+"""
 
 
 def DateFromTicks(ticks):
+    """Convert a Unix timestamp to a date object.
+
+    This function takes a Unix timestamp (seconds since epoch) and converts
+    it to a Python date object representing the date in local time.
+
+    Args:
+        ticks (float): Unix timestamp (seconds since January 1, 1970, 00:00 UTC)
+
+    Returns:
+        datetime.date: Date object representing the local date for the given timestamp
+
+    Note:
+        The conversion uses the local timezone. The time component is ignored,
+        only the date portion is extracted.
+
+    Examples:
+        >>> # Convert current timestamp to date
+        >>> import time
+        >>> current_time = time.time()
+        >>> today = DateFromTicks(current_time)
+        >>> print(today)
+        2023-12-25
+
+        >>> # Convert specific timestamp
+        >>> timestamp = 1640995200.0  # 2022-01-01 00:00:00 UTC
+        >>> date_obj = DateFromTicks(timestamp)
+        >>> print(date_obj)
+        2021-12-31  # Local time (assuming UTC-5 timezone)
+    """
     return date(*localtime(ticks)[:3])
 
 
 def TimeFromTicks(ticks):
+    """Convert a Unix timestamp to a time object.
+
+    This function takes a Unix timestamp (seconds since epoch) and converts
+    it to a Python time object representing the time of day in local time.
+
+    Args:
+        ticks (float): Unix timestamp (seconds since January 1, 1970, 00:00 UTC)
+
+    Returns:
+        datetime.time: Time object representing the local time for the given timestamp
+
+    Note:
+        The conversion uses the local timezone. The date component is ignored,
+        only the time-of-day portion is extracted.
+
+    Examples:
+        >>> # Convert timestamp to time
+        >>> timestamp = 1640995200.0  # 2022-01-01 00:00:00 UTC
+        >>> time_obj = TimeFromTicks(timestamp)
+        >>> print(time_obj)
+        19:00:00  # Local time (assuming UTC-5 timezone)
+
+        >>> # Extract current time
+        >>> import time
+        >>> current_time = time.time()
+        >>> now_time = TimeFromTicks(current_time)
+        >>> print(f"Current time: {now_time}")
+    """
     return time(*localtime(ticks)[3:6])
 
 
 def TimestampFromTicks(ticks):
+    """Convert a Unix timestamp to a datetime object.
+
+    This function takes a Unix timestamp (seconds since epoch) and converts
+    it to a Python datetime object representing the complete date and time
+    in local time.
+
+    Args:
+        ticks (float): Unix timestamp (seconds since January 1, 1970, 00:00 UTC)
+
+    Returns:
+        datetime.datetime: DateTime object representing the local datetime for the given timestamp
+
+    Note:
+        The conversion uses the local timezone. This provides both date and time
+        components, making it the most complete temporal conversion function.
+
+    Examples:
+        >>> # Convert timestamp to datetime
+        >>> timestamp = 1640995200.0  # 2022-01-01 00:00:00 UTC
+        >>> dt_obj = TimestampFromTicks(timestamp)
+        >>> print(dt_obj)
+        2021-12-31 19:00:00  # Local time (assuming UTC-5 timezone)
+
+        >>> # Convert current timestamp
+        >>> import time
+        >>> current_time = time.time()
+        >>> now_dt = TimestampFromTicks(current_time)
+        >>> print(f"Current datetime: {now_dt}")
+        Current datetime: 2023-12-25 14:30:45
+
+        >>> # Use in database operations
+        >>> cursor.execute("INSERT INTO events (created_at) VALUES (%s)",
+        ...               (TimestampFromTicks(time.time()),))
+    """
     return datetime(*localtime(ticks)[:6])