deprecate typing and functional

Author: evertlammerts

_duckdb-stubs/__init__.pyi

@@ -25,7 +25,7 @@
     - DuckDB Type System: https://duckdb.org/docs/sql/data_types/overview
 """
 
-import duckdb.typing as duckdb_typing
+from duckdb import sqltypes
 
 
 class DBAPITypeObject:
@@ -42,16 +42,16 @@ class DBAPITypeObject:
         types: A list of DuckDBPyType instances that belong to this type category.
 
     Example:
-        >>> string_types = DBAPITypeObject([duckdb_typing.VARCHAR, duckdb_typing.CHAR])
-        >>> result = duckdb_typing.VARCHAR == string_types  # True
-        >>> result = duckdb_typing.INTEGER == string_types  # False
+        >>> 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[duckdb_typing.DuckDBPyType]) -> None:
+    def __init__(self, types: list[sqltypes.DuckDBPyType]) -> None:
         """Initialize a DB API type object.
 
         Args:
@@ -73,10 +73,10 @@ def __eq__(self, other: object) -> bool:
             True if other is a DuckDBPyType in this category, False otherwise.
 
         Example:
-            >>> NUMBER == duckdb_typing.INTEGER  # True
-            >>> NUMBER == duckdb_typing.VARCHAR  # False
+            >>> NUMBER == sqltypes.INTEGER  # True
+            >>> NUMBER == sqltypes.VARCHAR  # False
         """
-        if isinstance(other, duckdb_typing.DuckDBPyType):
+        if isinstance(other, sqltypes.DuckDBPyType):
             return other in self.types
         return False
 
@@ -95,7 +95,7 @@ def __repr__(self) -> str:
 
 # Define the standard DB API 2.0 type objects for DuckDB
 
-STRING = DBAPITypeObject([duckdb_typing.VARCHAR])
+STRING = DBAPITypeObject([sqltypes.VARCHAR])
 """
 STRING type object for text-based database columns.
 
@@ -114,20 +114,20 @@ def __repr__(self) -> str:
 
 NUMBER = DBAPITypeObject(
     [
-        duckdb_typing.TINYINT,
-        duckdb_typing.UTINYINT,
-        duckdb_typing.SMALLINT,
-        duckdb_typing.USMALLINT,
-        duckdb_typing.INTEGER,
-        duckdb_typing.UINTEGER,
-        duckdb_typing.BIGINT,
-        duckdb_typing.UBIGINT,
-        duckdb_typing.HUGEINT,
-        duckdb_typing.UHUGEINT,
-        duckdb_typing.DuckDBPyType("BIGNUM"),
-        duckdb_typing.DuckDBPyType("DECIMAL"),
-        duckdb_typing.FLOAT,
-        duckdb_typing.DOUBLE,
+        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,
     ]
 )
 """
@@ -162,14 +162,14 @@ def __repr__(self) -> str:
 
 DATETIME = DBAPITypeObject(
     [
-        duckdb_typing.DATE,
-        duckdb_typing.TIME,
-        duckdb_typing.TIME_TZ,
-        duckdb_typing.TIMESTAMP,
-        duckdb_typing.TIMESTAMP_TZ,
-        duckdb_typing.TIMESTAMP_NS,
-        duckdb_typing.TIMESTAMP_MS,
-        duckdb_typing.TIMESTAMP_S,
+        sqltypes.DATE,
+        sqltypes.TIME,
+        sqltypes.TIME_TZ,
+        sqltypes.TIMESTAMP,
+        sqltypes.TIMESTAMP_TZ,
+        sqltypes.TIMESTAMP_NS,
+        sqltypes.TIMESTAMP_MS,
+        sqltypes.TIMESTAMP_S,
     ]
 )
 """
@@ -201,7 +201,7 @@ def __repr__(self) -> str:
     >>> cursor.description[2][1] == DATETIME  # Check if third column is date/time
 """
 
-BINARY = DBAPITypeObject([duckdb_typing.BLOB])
+BINARY = DBAPITypeObject([sqltypes.BLOB])
 """
 BINARY type object for binary data database columns.
 

_duckdb-stubs/functional.pyi renamed to _duckdb-stubs/_func.pyi

@@ -1,7 +1,5 @@
-from io import StringIO, TextIOBase  # noqa: D100
-from typing import Any, Union
+"""StringIO buffer wrapper.
 
-"""
 BSD 3-Clause License
 
 Copyright (c) 2008-2011, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData Development Team
@@ -35,10 +33,16 @@
 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.
+    """
 
-class BytesIOWrapper:  # noqa: D101
-    # 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

_duckdb-stubs/typing.pyi renamed to _duckdb-stubs/_sqltypes.pyi

@@ -8,7 +8,7 @@
     from ._typing import DateTimeLiteral, DecimalLiteral, LiteralType
 
 from duckdb import ColumnExpression, ConstantExpression, Expression, FunctionExpression
-from duckdb.typing import DuckDBPyType
+from duckdb.sqltypes import DuckDBPyType
 
 __all__ = ["Column"]
 

duckdb/_dbapi_type_object.py

@@ -1,6 +1,6 @@
 from typing import cast  # noqa: D100
 
-from duckdb.typing import DuckDBPyType
+from duckdb.sqltypes import DuckDBPyType
 
 from .types import (
     ArrayType,

duckdb/bytes_io_wrapper.py

@@ -22,7 +22,7 @@
 )
 
 import duckdb
-from duckdb.typing import DuckDBPyType
+from duckdb.sqltypes import DuckDBPyType
 
 from ..exception import ContributionsAcceptedError
 

duckdb/experimental/spark/sql/column.py

@@ -0,0 +1,3 @@
+from _duckdb._func import ARROW, DEFAULT, NATIVE, SPECIAL, FunctionNullHandling, PythonUDFType  # noqa: D104
+
+__all__ = ["ARROW", "DEFAULT", "NATIVE", "SPECIAL", "FunctionNullHandling", "PythonUDFType"]

duckdb/experimental/spark/sql/type_utils.py

@@ -1,3 +1,13 @@
-from _duckdb.functional import ARROW, DEFAULT, NATIVE, SPECIAL, FunctionNullHandling, PythonUDFType  # noqa: D104
+"""DuckDB function constants and types. DEPRECATED: please use `duckdb.func` instead."""
+
+import warnings
+
+from duckdb.func import ARROW, DEFAULT, NATIVE, SPECIAL, FunctionNullHandling, PythonUDFType
 
 __all__ = ["ARROW", "DEFAULT", "NATIVE", "SPECIAL", "FunctionNullHandling", "PythonUDFType"]
+
+warnings.warn(
+    "`duckdb.functional` is deprecated and will be removed in a future version. Please use `duckdb.func` instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)