fix(DONT MERGE): duckdb>=1.4.1 typing & warnings

narwhals/_duckdb/dataframe.py

@@ -102,7 +102,7 @@ def to_narwhals(
         if self._version is Version.V1:
             from narwhals.stable.v1 import DataFrame as DataFrameV1
 
-            return DataFrameV1(self, level="interchange")  # type: ignore[no-any-return]
+            return DataFrameV1(self, level="interchange")
         return self._version.lazyframe(self, level="lazy")
 
     def __narwhals_dataframe__(self) -> Self:  # pragma: no cover
@@ -116,7 +116,7 @@ def __narwhals_lazyframe__(self) -> Self:
         return self
 
     def __native_namespace__(self) -> ModuleType:
-        return get_duckdb()  # type: ignore[no-any-return]
+        return get_duckdb()
 
     def __narwhals_namespace__(self) -> DuckDBNamespace:
         from narwhals._duckdb.namespace import DuckDBNamespace
@@ -138,12 +138,8 @@ def collect(
         if backend is None or backend is Implementation.PYARROW:
             from narwhals._arrow.dataframe import ArrowDataFrame
 
-            if self._backend_version < (1, 4):
-                ret = self.native.arrow()
-            else:  # pragma: no cover
-                ret = self.native.fetch_arrow_table()
             return ArrowDataFrame(
-                ret,
+                self.native.fetch_arrow_table(),
                 validate_backend_version=True,
                 version=self._version,
                 validate_column_names=True,
@@ -260,7 +256,7 @@ def to_pandas(self) -> pd.DataFrame:
 
     def to_arrow(self) -> pa.Table:
         # only if version is v1, keep around for backcompat
-        return self.lazy().collect(Implementation.PYARROW).native  # type: ignore[no-any-return]
+        return self.lazy().collect(Implementation.PYARROW).native
 
     def _with_version(self, version: Version) -> Self:
         return self.__class__(self.native, version=version)

narwhals/_duckdb/expr.py

@@ -256,7 +256,8 @@ def is_finite(self) -> Self:
         return self._with_elementwise(lambda expr: F("isfinite", expr))
 
     def is_in(self, other: Sequence[Any]) -> Self:
-        return self._with_elementwise(lambda expr: F("contains", lit(other), expr))
+        other_ = tuple(other) if not isinstance(other, (tuple, list)) else other
+        return self._with_elementwise(lambda expr: F("contains", lit(other_), expr))
 
     def fill_null(
         self,

narwhals/_duckdb/namespace.py

@@ -37,6 +37,7 @@
     from narwhals._utils import Version
     from narwhals.typing import ConcatMethod, IntoDType, NonNestedLiteral
 
+BIGINT = duckdb_dtypes.BIGINT
 VARCHAR = duckdb_dtypes.VARCHAR
 
 
@@ -123,9 +124,7 @@ def mean_horizontal(self, *exprs: DuckDBExpr) -> DuckDBExpr:
         def func(cols: Iterable[Expression]) -> Expression:
             cols = tuple(cols)
             total = reduce(operator.add, (CoalesceOperator(col, lit(0)) for col in cols))
-            count = reduce(
-                operator.add, (col.isnotnull().cast(duckdb_dtypes.BIGINT) for col in cols)
-            )
+            count = reduce(operator.add, (col.isnotnull().cast(BIGINT) for col in cols))
             return total / count
 
         return self._expr._from_elementwise_horizontal_op(func, *exprs)

narwhals/_duckdb/series.py

@@ -24,7 +24,7 @@ def __narwhals_series__(self) -> Self:
         return self
 
     def __native_namespace__(self) -> ModuleType:
-        return get_duckdb()  # type: ignore[no-any-return]
+        return get_duckdb()
 
     @property
     def dtype(self) -> DType:

narwhals/_duckdb/typing.py

@@ -1,11 +1,44 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, TypedDict
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, Literal, Protocol, TypedDict, Union, overload
+
+import duckdb
+from duckdb import Expression
+
+from narwhals._typing_compat import TypeVar
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    import uuid
+
+    import numpy as np
+    import pandas as pd
+    from duckdb import DuckDBPyConnection
+    from typing_extensions import TypeAlias, TypeIs
+
+    from narwhals.typing import Into1DArray, PythonLiteral
 
-    from duckdb import Expression
+
+__all__ = [
+    "BaseType",
+    "IntoColumnExpr",
+    "WindowExpressionKwargs",
+    "has_children",
+    "is_dtype",
+]
+
+IntoDuckDBLiteral: TypeAlias = """
+    PythonLiteral
+    | dict[Any, Any]
+    | uuid.UUID
+    | bytearray
+    | memoryview
+    | Into1DArray
+    | pd.api.typing.NaTType
+    | pd.api.typing.NAType
+    | np.ma.MaskedArray
+    | duckdb.Value
+    """
 
 
 class WindowExpressionKwargs(TypedDict, total=False):
@@ -16,3 +49,102 @@ class WindowExpressionKwargs(TypedDict, total=False):
     descending: Sequence[bool]
     nulls_last: Sequence[bool]
     ignore_nulls: bool
+
+
+_Children_co = TypeVar(
+    "_Children_co",
+    covariant=True,
+    bound=Sequence[tuple[str, Any]],
+    default=Sequence[tuple[str, Any]],
+)
+DTypeT_co = TypeVar("DTypeT_co", covariant=True, bound="BaseType", default="BaseType")
+_Child: TypeAlias = tuple[Literal["child"], DTypeT_co]
+_Size: TypeAlias = tuple[Literal["size"], int]
+_ID_co = TypeVar("_ID_co", bound=str, default=str, covariant=True)
+_Array: TypeAlias = Literal["array"]
+_Struct: TypeAlias = Literal["struct"]
+_List: TypeAlias = Literal["list"]
+_Enum: TypeAlias = Literal["enum"]
+_Decimal: TypeAlias = Literal["decimal"]
+_TimestampTZ: TypeAlias = Literal["timestamp with time zone"]
+IntoColumnExpr: TypeAlias = Union[str, Expression]
+"""A column name, or the result of calling `duckdb.ColumnExpression`."""
+
+
+class BaseType(Protocol[_ID_co]):
+    """Structural equivalent to [`DuckDBPyType`].
+
+    Excludes attributes which are unsafe to use on most types.
+
+    [`DuckDBPyType`]: https://github.com/duckdb/duckdb-python/blob/df7789cbd31b2d2b8d03d012f14331bc3297fb2d/_duckdb-stubs/_sqltypes.pyi#L35-L75
+    """
+
+    def __eq__(self, other: object) -> bool: ...
+    def __hash__(self) -> int: ...
+    @overload
+    def __init__(self, type_str: str, connection: DuckDBPyConnection) -> None: ...
+    @overload
+    def __init__(self, obj: object) -> None: ...
+    @property
+    def id(self) -> _ID_co: ...
+
+
+def has_children(
+    dtype: BaseType | _ParentType[_ID_co, _Children_co],
+) -> TypeIs[_ParentType[_ID_co, _Children_co]]:
+    """Return True if `dtype.children` can be accessed safely.
+
+    `_hasattr_static` returns True on *any* [`DuckDBPyType`], so the only way to be sure is by forcing an exception.
+
+    [`DuckDBPyType`]: https://github.com/duckdb/duckdb-python/blob/df7789cbd31b2d2b8d03d012f14331bc3297fb2d/_duckdb-stubs/_sqltypes.pyi#L35-L75
+    """
+    try:
+        return hasattr(dtype, "children")
+    except duckdb.InvalidInputException:
+        return False
+
+
+@overload
+def is_dtype(obj: BaseType, type_id: _Array, /) -> TypeIs[ArrayType]: ...
+@overload
+def is_dtype(obj: BaseType, type_id: _Struct, /) -> TypeIs[StructType]: ...
+@overload
+def is_dtype(obj: BaseType, type_id: _List, /) -> TypeIs[ListType]: ...
+@overload
+def is_dtype(obj: BaseType, type_id: _Enum, /) -> TypeIs[EnumType]: ...
+@overload
+def is_dtype(obj: BaseType, type_id: _Decimal, /) -> TypeIs[DecimalType]: ...
+@overload
+def is_dtype(
+    obj: BaseType, type_id: _TimestampTZ, /
+) -> TypeIs[BaseType[_TimestampTZ]]: ...
+def is_dtype(
+    obj: BaseType, type_id: _Array | _Struct | _List | _Enum | _Decimal | _TimestampTZ, /
+) -> bool:
+    """Return True if `obj` is the [`DuckDBPyType`] corresponding with `type_id`.
+
+    [`DuckDBPyType`]: https://github.com/duckdb/duckdb-python/blob/df7789cbd31b2d2b8d03d012f14331bc3297fb2d/_duckdb-stubs/_sqltypes.pyi#L35-L75
+    """
+    return obj.id == type_id
+
+
+class _ParentType(BaseType[_ID_co], Protocol[_ID_co, _Children_co]):
+    @property
+    def children(self) -> _Children_co: ...
+
+
+ArrayType: TypeAlias = _ParentType[_Array, tuple[_Child[DTypeT_co], _Size]]
+EnumType: TypeAlias = _ParentType[_Enum, tuple[tuple[Literal["values"], list[str]]]]
+DecimalType: TypeAlias = _ParentType[
+    _Decimal, tuple[tuple[Literal["precision"], int], tuple[Literal["scale"], int]]
+]
+
+
+class ListType(_ParentType[_List, tuple[_Child[DTypeT_co]]], Protocol[DTypeT_co]):
+    @property
+    def child(self) -> DTypeT_co: ...
+
+
+class StructType(_ParentType[_Struct, Sequence[tuple[str, BaseType]]], Protocol):
+    def __getattr__(self, name: str) -> BaseType: ...
+    def __getitem__(self, name: str) -> BaseType: ...