duckdb 0.8.2.dev3007__cp311-cp311-win_amd64.whl → 1.4.3.dev8__cp311-cp311-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__})"

{pyduckdb → 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

duckdb/experimental/__init__.py

@@ -0,0 +1,5 @@
+from . import spark  # noqa: D104
+
+__all__ = [
+    "spark",
+]

duckdb/experimental/spark/__init__.py

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

{pyduckdb → 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 pyduckdb.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

@@ -0,0 +1,46 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from collections.abc import Iterable, Sized
+from typing import Callable, TypeVar, Union
+
+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)
+
+PrimitiveType = Union[bool, float, int, str]
+
+NonUDFType = Literal[0]
+
+
+class SupportsIAdd(Protocol):
+    def __iadd__(self, other: "SupportsIAdd") -> Self: ...
+
+
+class SupportsOrdering(Protocol):
+    def __lt__(self, other: "SupportsOrdering") -> bool: ...
+
+
+class SizedIterable(Protocol, Sized, Iterable[T_co]): ...
+
+
+S = TypeVar("S", bound=SupportsOrdering)
+
+NumberOrArray = TypeVar("NumberOrArray", float, int, complex, int32, int64, float32, float64, ndarray)

duckdb/experimental/spark/conf.py

@@ -0,0 +1,46 @@
+from typing import Optional  # noqa: D100
+
+from duckdb.experimental.spark.exception import ContributionsAcceptedError
+
+
+class SparkConf:  # noqa: D101
+    def __init__(self) -> None:  # noqa: D107
+        raise NotImplementedError
+
+    def contains(self, key: str) -> bool:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def get(self, key: str, defaultValue: Optional[str] = None) -> Optional[str]:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def getAll(self) -> list[tuple[str, str]]:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def set(self, key: str, value: str) -> "SparkConf":  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def setAll(self, pairs: list[tuple[str, str]]) -> "SparkConf":  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def setAppName(self, value: str) -> "SparkConf":  # noqa: D102
+        raise ContributionsAcceptedError
+
+    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":  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def setMaster(self, value: str) -> "SparkConf":  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def setSparkHome(self, value: str) -> "SparkConf":  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def toDebugString(self) -> str:  # noqa: D102
+        raise ContributionsAcceptedError
+
+
+__all__ = ["SparkConf"]

duckdb/experimental/spark/context.py

@@ -0,0 +1,180 @@
+from typing import Optional  # noqa: D100
+
+import duckdb
+from duckdb import DuckDBPyConnection
+from duckdb.experimental.spark.conf import SparkConf
+from duckdb.experimental.spark.exception import ContributionsAcceptedError
+
+
+class SparkContext:  # noqa: D101
+    def __init__(self, master: str) -> None:  # noqa: D107
+        self._connection = duckdb.connect(":memory:")
+        # This aligns the null ordering with Spark.
+        self._connection.execute("set default_null_order='nulls_first_on_asc_last_on_desc'")
+
+    @property
+    def connection(self) -> DuckDBPyConnection:  # noqa: D102
+        return self._connection
+
+    def stop(self) -> None:  # noqa: D102
+        self._connection.close()
+
+    @classmethod
+    def getOrCreate(cls, conf: Optional[SparkConf] = None) -> "SparkContext":  # noqa: D102
+        raise ContributionsAcceptedError
+
+    @classmethod
+    def setSystemProperty(cls, key: str, value: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    @property
+    def applicationId(self) -> str:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    @property
+    def defaultMinPartitions(self) -> int:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    @property
+    def defaultParallelism(self) -> int:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    # @property
+    # def resources(self) -> Dict[str, ResourceInformation]:
+    # 	raise ContributionsAcceptedError
+
+    @property
+    def startTime(self) -> str:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    @property
+    def uiWebUrl(self) -> str:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    @property
+    def version(self) -> str:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def __repr__(self) -> str:  # noqa: D105
+        raise ContributionsAcceptedError
+
+    # def accumulator(self, value: ~T, accum_param: Optional[ForwardRef('AccumulatorParam[T]')] = None
+    #     ) -> 'Accumulator[T]':
+    # 	pass
+
+    def addArchive(self, path: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def addFile(self, path: str, recursive: bool = False) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def addPyFile(self, path: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    # def binaryFiles(self, path: str, minPartitions: Optional[int] = None
+    #     ) -> duckdb.experimental.spark.rdd.RDD[typing.Tuple[str, bytes]]:
+    # 	pass
+
+    # def binaryRecords(self, path: str, recordLength: int) -> duckdb.experimental.spark.rdd.RDD[bytes]:
+    # 	pass
+
+    # def broadcast(self, value: ~T) -> 'Broadcast[T]':
+    # 	pass
+
+    def cancelAllJobs(self) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def cancelJobGroup(self, groupId: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def dump_profiles(self, path: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    # def emptyRDD(self) -> duckdb.experimental.spark.rdd.RDD[typing.Any]:
+    # 	pass
+
+    def getCheckpointDir(self) -> Optional[str]:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def getConf(self) -> SparkConf:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def getLocalProperty(self, key: str) -> Optional[str]:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    # def hadoopFile(self, path: str, inputFormatClass: str, keyClass: str, valueClass: str,
+    #     keyConverter: Optional[str] = None, valueConverter: Optional[str] = None,
+    #     conf: Optional[Dict[str, str]] = None, batchSize: int = 0) -> pyspark.rdd.RDD[typing.Tuple[~T, ~U]]:
+    # 	pass
+
+    # def hadoopRDD(self, inputFormatClass: str, keyClass: str, valueClass: str, keyConverter: Optional[str] = None,
+    #     valueConverter: Optional[str] = None, conf: Optional[Dict[str, str]] = None, batchSize: int = 0
+    #     ) -> pyspark.rdd.RDD[typing.Tuple[~T, ~U]]:
+    # 	pass
+
+    # def newAPIHadoopFile(self, path: str, inputFormatClass: str, keyClass: str, valueClass: str,
+    #     keyConverter: Optional[str] = None, valueConverter: Optional[str] = None,
+    #     conf: Optional[Dict[str, str]] = None, batchSize: int = 0) -> pyspark.rdd.RDD[typing.Tuple[~T, ~U]]:
+    # 	pass
+
+    # def newAPIHadoopRDD(self, inputFormatClass: str, keyClass: str, valueClass: str,
+    #     keyConverter: Optional[str] = None, valueConverter: Optional[str] = None,
+    #     conf: Optional[Dict[str, str]] = None, batchSize: int = 0) -> pyspark.rdd.RDD[typing.Tuple[~T, ~U]]:
+    # 	pass
+
+    # def parallelize(self, c: Iterable[~T], numSlices: Optional[int] = None) -> pyspark.rdd.RDD[~T]:
+    # 	pass
+
+    # def pickleFile(self, name: str, minPartitions: Optional[int] = None) -> pyspark.rdd.RDD[typing.Any]:
+    # 	pass
+
+    # def range(self, start: int, end: Optional[int] = None, step: int = 1, numSlices: Optional[int] = None
+    #     ) -> pyspark.rdd.RDD[int]:
+    # 	pass
+
+    # def runJob(self, rdd: pyspark.rdd.RDD[~T], partitionFunc: Callable[[Iterable[~T]], Iterable[~U]],
+    #     partitions: Optional[Sequence[int]] = None, allowLocal: bool = False) -> List[~U]:
+    # 	pass
+
+    # def sequenceFile(self, path: str, keyClass: Optional[str] = None, valueClass: Optional[str] = None,
+    #     keyConverter: Optional[str] = None, valueConverter: Optional[str] = None, minSplits: Optional[int] = None,
+    #     batchSize: int = 0) -> pyspark.rdd.RDD[typing.Tuple[~T, ~U]]:
+    # 	pass
+
+    def setCheckpointDir(self, dirName: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def setJobDescription(self, value: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def setJobGroup(self, groupId: str, description: str, interruptOnCancel: bool = False) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def setLocalProperty(self, key: str, value: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def setLogLevel(self, logLevel: str) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def show_profiles(self) -> None:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    def sparkUser(self) -> str:  # noqa: D102
+        raise ContributionsAcceptedError
+
+    # def statusTracker(self) -> duckdb.experimental.spark.status.StatusTracker:
+    # 	raise ContributionsAcceptedError
+
+    # def textFile(self, name: str, minPartitions: Optional[int] = None, use_unicode: bool = True
+    #     ) -> pyspark.rdd.RDD[str]:
+    # 	pass
+
+    # def union(self, rdds: List[pyspark.rdd.RDD[~T]]) -> pyspark.rdd.RDD[~T]:
+    # 	pass
+
+    # def wholeTextFiles(self, path: str, minPartitions: Optional[int] = None, use_unicode: bool = True
+    #     ) -> pyspark.rdd.RDD[typing.Tuple[str, str]]:
+    # 	pass
+
+
+__all__ = ["SparkContext"]