duckdb 1.5.0.dev44__cp313-cp313-win_amd64.whl → 1.5.0.dev94__cp313-cp313-win_amd64.whl

duckdb/_dbapi_type_object.py

@@ -0,0 +1,231 @@
+"""DuckDB DB API 2.0 Type Objects Module.
+
+This module provides DB API 2.0 compliant type objects for DuckDB, allowing applications
+to check column types returned by queries against standard database API categories.
+
+Example:
+    >>> import duckdb
+    >>>
+    >>> conn = duckdb.connect()
+    >>> cursor = conn.cursor()
+    >>> cursor.execute("SELECT 'hello' as text_col, 42 as num_col, CURRENT_DATE as date_col")
+    >>>
+    >>> # Check column types using DB API type objects
+    >>> for i, desc in enumerate(cursor.description):
+    >>>     col_name, col_type = desc[0], desc[1]
+    >>>     if col_type == duckdb.STRING:
+    >>>         print(f"{col_name} is a string type")
+    >>>     elif col_type == duckdb.NUMBER:
+    >>>         print(f"{col_name} is a numeric type")
+    >>>     elif col_type == duckdb.DATETIME:
+    >>>         print(f"{col_name} is a date/time type")
+
+See Also:
+    - PEP 249: https://peps.python.org/pep-0249/
+    - DuckDB Type System: https://duckdb.org/docs/sql/data_types/overview
+"""
+
+from duckdb import sqltypes
+
+
+class DBAPITypeObject:
+    """DB API 2.0 type object for categorizing database column types.
+
+    This class implements the type objects defined in PEP 249 (DB API 2.0).
+    It allows checking whether a specific DuckDB type belongs to a broader
+    category like STRING, NUMBER, DATETIME, etc.
+
+    The type object supports equality comparison with DuckDBPyType instances,
+    returning True if the type belongs to this category.
+
+    Args:
+        types: A list of DuckDBPyType instances that belong to this type category.
+
+    Example:
+        >>> string_types = DBAPITypeObject([sqltypes.VARCHAR, sqltypes.CHAR])
+        >>> result = sqltypes.VARCHAR == string_types  # True
+        >>> result = sqltypes.INTEGER == string_types  # False
+
+    Note:
+        This follows the DB API 2.0 specification where type objects are compared
+        using equality operators rather than isinstance() checks.
+    """
+
+    def __init__(self, types: list[sqltypes.DuckDBPyType]) -> None:
+        """Initialize a DB API type object.
+
+        Args:
+            types: List of DuckDB types that belong to this category.
+        """
+        self.types = types
+
+    def __eq__(self, other: object) -> bool:
+        """Check if a DuckDB type belongs to this type category.
+
+        This method implements the DB API 2.0 type checking mechanism.
+        It returns True if the other object is a DuckDBPyType that
+        is contained in this type category.
+
+        Args:
+            other: The object to compare, typically a DuckDBPyType instance.
+
+        Returns:
+            True if other is a DuckDBPyType in this category, False otherwise.
+
+        Example:
+            >>> NUMBER == sqltypes.INTEGER  # True
+            >>> NUMBER == sqltypes.VARCHAR  # False
+        """
+        if isinstance(other, sqltypes.DuckDBPyType):
+            return other in self.types
+        return False
+
+    def __repr__(self) -> str:
+        """Return a string representation of this type object.
+
+        Returns:
+            A string showing the type object and its contained DuckDB types.
+
+        Example:
+            >>> repr(STRING)
+            '<DBAPITypeObject [VARCHAR]>'
+        """
+        return f"<DBAPITypeObject [{','.join(str(x) for x in self.types)}]>"
+
+
+# Define the standard DB API 2.0 type objects for DuckDB
+
+STRING = DBAPITypeObject([sqltypes.VARCHAR])
+"""
+STRING type object for text-based database columns.
+
+This type object represents all string/text types in DuckDB. Currently includes:
+- VARCHAR: Variable-length character strings
+
+Use this to check if a column contains textual data that should be handled
+as Python strings.
+
+DB API 2.0 Reference:
+    https://peps.python.org/pep-0249/#string
+
+Example:
+    >>> cursor.description[0][1] == STRING  # Check if first column is text
+"""
+
+NUMBER = DBAPITypeObject(
+    [
+        sqltypes.TINYINT,
+        sqltypes.UTINYINT,
+        sqltypes.SMALLINT,
+        sqltypes.USMALLINT,
+        sqltypes.INTEGER,
+        sqltypes.UINTEGER,
+        sqltypes.BIGINT,
+        sqltypes.UBIGINT,
+        sqltypes.HUGEINT,
+        sqltypes.UHUGEINT,
+        sqltypes.DuckDBPyType("BIGNUM"),
+        sqltypes.DuckDBPyType("DECIMAL"),
+        sqltypes.FLOAT,
+        sqltypes.DOUBLE,
+    ]
+)
+"""
+NUMBER type object for numeric database columns.
+
+This type object represents all numeric types in DuckDB, including:
+
+Integer Types:
+- TINYINT, UTINYINT: 8-bit signed/unsigned integers
+- SMALLINT, USMALLINT: 16-bit signed/unsigned integers
+- INTEGER, UINTEGER: 32-bit signed/unsigned integers
+- BIGINT, UBIGINT: 64-bit signed/unsigned integers
+- HUGEINT, UHUGEINT: 128-bit signed/unsigned integers
+
+Decimal Types:
+- BIGNUM: Arbitrary precision integers
+- DECIMAL: Fixed-point decimal numbers
+
+Floating Point Types:
+- FLOAT: 32-bit floating point
+- DOUBLE: 64-bit floating point
+
+Use this to check if a column contains numeric data that should be handled
+as Python int, float, or Decimal objects.
+
+DB API 2.0 Reference:
+    https://peps.python.org/pep-0249/#number
+
+Example:
+    >>> cursor.description[1][1] == NUMBER  # Check if second column is numeric
+"""
+
+DATETIME = DBAPITypeObject(
+    [
+        sqltypes.DATE,
+        sqltypes.TIME,
+        sqltypes.TIME_TZ,
+        sqltypes.TIMESTAMP,
+        sqltypes.TIMESTAMP_TZ,
+        sqltypes.TIMESTAMP_NS,
+        sqltypes.TIMESTAMP_MS,
+        sqltypes.TIMESTAMP_S,
+    ]
+)
+"""
+DATETIME type object for date and time database columns.
+
+This type object represents all date/time types in DuckDB, including:
+
+Date Types:
+- DATE: Calendar dates (year, month, day)
+
+Time Types:
+- TIME: Time of day without timezone
+- TIME_TZ: Time of day with timezone
+
+Timestamp Types:
+- TIMESTAMP: Date and time without timezone (microsecond precision)
+- TIMESTAMP_TZ: Date and time with timezone
+- TIMESTAMP_NS: Nanosecond precision timestamps
+- TIMESTAMP_MS: Millisecond precision timestamps
+- TIMESTAMP_S: Second precision timestamps
+
+Use this to check if a column contains temporal data that should be handled
+as Python datetime, date, or time objects.
+
+DB API 2.0 Reference:
+    https://peps.python.org/pep-0249/#datetime
+
+Example:
+    >>> cursor.description[2][1] == DATETIME  # Check if third column is date/time
+"""
+
+BINARY = DBAPITypeObject([sqltypes.BLOB])
+"""
+BINARY type object for binary data database columns.
+
+This type object represents binary data types in DuckDB:
+- BLOB: Binary Large Objects for storing arbitrary binary data
+
+Use this to check if a column contains binary data that should be handled
+as Python bytes objects.
+
+DB API 2.0 Reference:
+    https://peps.python.org/pep-0249/#binary
+
+Example:
+    >>> cursor.description[3][1] == BINARY  # Check if fourth column is binary
+"""
+
+ROWID = None
+"""
+ROWID type object for row identifier columns.
+
+DB API 2.0 Reference:
+    https://peps.python.org/pep-0249/#rowid
+
+Note:
+    This will always be None for DuckDB connections. Applications should not
+    rely on ROWID functionality when using DuckDB.
+"""

duckdb/_version.py

@@ -0,0 +1,22 @@
+# ----------------------------------------------------------------------
+# Version API
+#
+# We provide three symbols:
+# - duckdb.__version__: The version of this package
+# - duckdb.__duckdb_version__: The version of duckdb that is bundled
+# - duckdb.version(): A human-readable version string containing both of the above
+# ----------------------------------------------------------------------
+from importlib.metadata import version as _dist_version
+
+import _duckdb
+
+__version__: str = _dist_version("duckdb")
+"""Version of the DuckDB Python Package."""
+
+__duckdb_version__: str = _duckdb.__version__
+"""Version of DuckDB that is bundled."""
+
+
+def version() -> str:
+    """Human-friendly formatted version string of both the distribution package and the bundled DuckDB engine."""
+    return f"{__version__} (with duckdb {_duckdb.__version__})"

duckdb/bytes_io_wrapper.py

@@ -1,7 +1,5 @@
-from io import StringIO, TextIOBase
-from typing import Union
+"""StringIO buffer wrapper.
 
-"""
 BSD 3-Clause License
 
 Copyright (c) 2008-2011, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData Development Team
@@ -35,11 +33,17 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 """
 
+from io import StringIO, TextIOBase
+from typing import Any, Union
+
 
 class BytesIOWrapper:
-    # Wrapper that wraps a StringIO buffer and reads bytes from it
-    # Created for compat with pyarrow read_csv
-    def __init__(self, buffer: Union[StringIO, TextIOBase], encoding: str = "utf-8") -> None:
+    """Wrapper that wraps a StringIO buffer and reads bytes from it.
+
+    Created for compat with pyarrow read_csv.
+    """
+
+    def __init__(self, buffer: Union[StringIO, TextIOBase], encoding: str = "utf-8") -> None:  # noqa: D107
         self.buffer = buffer
         self.encoding = encoding
         # Because a character can be represented by more than 1 byte,
@@ -48,10 +52,10 @@ class BytesIOWrapper:
         # overflow to the front of the bytestring the next time reading is performed
         self.overflow = b""
 
-    def __getattr__(self, attr: str):
+    def __getattr__(self, attr: str) -> Any:  # noqa: D105, ANN401
         return getattr(self.buffer, attr)
 
-    def read(self, n: Union[int, None] = -1) -> bytes:
+    def read(self, n: Union[int, None] = -1) -> bytes:  # noqa: D102
         assert self.buffer is not None
         bytestring = self.buffer.read(n).encode(self.encoding)
         # When n=-1/n greater than remaining bytes: Read entire file/rest of file
@@ -63,4 +67,3 @@ class BytesIOWrapper:
             to_return = combined_bytestring[:n]
             self.overflow = combined_bytestring[n:]
             return to_return
-

duckdb/experimental/__init__.py

@@ -1,2 +1,3 @@
-from . import spark
+from . import spark  # noqa: D104
+
 __all__ = spark.__all__

duckdb/experimental/spark/__init__.py

@@ -1,7 +1,6 @@
-from .sql import SparkSession, DataFrame
-from .conf import SparkConf
+from .conf import SparkConf  # noqa: D104
 from .context import SparkContext
-from ._globals import _NoValue
 from .exception import ContributionsAcceptedError
+from .sql import DataFrame, SparkSession
 
-__all__ = ["SparkSession", "DataFrame", "SparkConf", "SparkContext", "ContributionsAcceptedError"]
+__all__ = ["ContributionsAcceptedError", "DataFrame", "SparkConf", "SparkContext", "SparkSession"]

duckdb/experimental/spark/_globals.py

@@ -15,8 +15,7 @@
 # limitations under the License.
 #
 
-"""
-Module defining global singleton classes.
+"""Module defining global singleton classes.
 
 This module raises a RuntimeError if an attempt to reload it is made. In that
 way the identities of the classes defined here are fixed and will remain so
@@ -38,7 +37,8 @@ __ALL__ = ["_NoValue"]
 # Disallow reloading this module so as to preserve the identities of the
 # classes defined here.
 if "_is_loaded" in globals():
-    raise RuntimeError("Reloading duckdb.experimental.spark._globals is not allowed")
+    msg = "Reloading duckdb.experimental.spark._globals is not allowed"
+    raise RuntimeError(msg)
 _is_loaded = True
 
 
@@ -54,23 +54,23 @@ class _NoValueType:
 
     __instance = None
 
-    def __new__(cls):
+    def __new__(cls) -> "_NoValueType":
         # ensure that only one instance exists
         if not cls.__instance:
-            cls.__instance = super(_NoValueType, cls).__new__(cls)
+            cls.__instance = super().__new__(cls)
         return cls.__instance
 
     # Make the _NoValue instance falsey
-    def __nonzero__(self):
+    def __nonzero__(self) -> bool:
         return False
 
     __bool__ = __nonzero__
 
     # needed for python 2 to preserve identity through a pickle
-    def __reduce__(self):
+    def __reduce__(self) -> tuple[type, tuple]:
         return (self.__class__, ())
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<no value>"
 
 

duckdb/experimental/spark/_typing.py

@@ -16,10 +16,11 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Callable, Iterable, Sized, TypeVar, Union
-from typing_extensions import Literal, Protocol
+from collections.abc import Iterable, Sized
+from typing import Callable, TypeVar, Union
 
-from numpy import int32, int64, float32, float64, ndarray
+from numpy import float32, float64, int32, int64, ndarray
+from typing_extensions import Literal, Protocol, Self
 
 F = TypeVar("F", bound=Callable)
 T_co = TypeVar("T_co", covariant=True)
@@ -30,17 +31,14 @@ NonUDFType = Literal[0]
 
 
 class SupportsIAdd(Protocol):
-    def __iadd__(self, other: "SupportsIAdd") -> "SupportsIAdd":
-        ...
+    def __iadd__(self, other: "SupportsIAdd") -> Self: ...
 
 
 class SupportsOrdering(Protocol):
-    def __lt__(self, other: "SupportsOrdering") -> bool:
-        ...
+    def __lt__(self, other: "SupportsOrdering") -> bool: ...
 
 
-class SizedIterable(Protocol, Sized, Iterable[T_co]):
-    ...
+class SizedIterable(Protocol, Sized, Iterable[T_co]): ...
 
 
 S = TypeVar("S", bound=SupportsOrdering)

duckdb/experimental/spark/conf.py

@@ -1,44 +1,45 @@
-from typing import Optional, List, Tuple
+from typing import Optional  # noqa: D100
+
 from duckdb.experimental.spark.exception import ContributionsAcceptedError
 
 
-class SparkConf:
-    def __init__(self):
+class SparkConf:  # noqa: D101
+    def __init__(self) -> None:  # noqa: D107
         raise NotImplementedError
 
-    def contains(self, key: str) -> bool:
+    def contains(self, key: str) -> bool:  # noqa: D102
         raise ContributionsAcceptedError
 
-    def get(self, key: str, defaultValue: Optional[str] = None) -> Optional[str]:
+    def get(self, key: str, defaultValue: Optional[str] = None) -> Optional[str]:  # noqa: D102
         raise ContributionsAcceptedError
 
-    def getAll(self) -> List[Tuple[str, str]]:
+    def getAll(self) -> list[tuple[str, str]]:  # noqa: D102
         raise ContributionsAcceptedError
 
-    def set(self, key: str, value: str) -> "SparkConf":
+    def set(self, key: str, value: str) -> "SparkConf":  # noqa: D102
         raise ContributionsAcceptedError
 
-    def setAll(self, pairs: List[Tuple[str, str]]) -> "SparkConf":
+    def setAll(self, pairs: list[tuple[str, str]]) -> "SparkConf":  # noqa: D102
         raise ContributionsAcceptedError
 
-    def setAppName(self, value: str) -> "SparkConf":
+    def setAppName(self, value: str) -> "SparkConf":  # noqa: D102
         raise ContributionsAcceptedError
 
-    def setExecutorEnv(
-        self, key: Optional[str] = None, value: Optional[str] = None, pairs: Optional[List[Tuple[str, str]]] = None
+    def setExecutorEnv(  # noqa: D102
+        self, key: Optional[str] = None, value: Optional[str] = None, pairs: Optional[list[tuple[str, str]]] = None
     ) -> "SparkConf":
         raise ContributionsAcceptedError
 
-    def setIfMissing(self, key: str, value: str) -> "SparkConf":
+    def setIfMissing(self, key: str, value: str) -> "SparkConf":  # noqa: D102
         raise ContributionsAcceptedError
 
-    def setMaster(self, value: str) -> "SparkConf":
+    def setMaster(self, value: str) -> "SparkConf":  # noqa: D102
         raise ContributionsAcceptedError
 
-    def setSparkHome(self, value: str) -> "SparkConf":
+    def setSparkHome(self, value: str) -> "SparkConf":  # noqa: D102
         raise ContributionsAcceptedError
 
-    def toDebugString(self) -> str:
+    def toDebugString(self) -> str:  # noqa: D102
         raise ContributionsAcceptedError