- new _typing and _expression stub file to centralize type aliases and allow circular imports between files.

- added  nested dtypes, bytesarray, and memoryview as literal, convertible python types
- PythonLiteral is a recursive type, to allow dict of list, list of list, etc...

Author: OutSquareCapital

_duckdb-stubs/_expression.pyi

@@ -0,0 +1,55 @@
+from typing import TYPE_CHECKING, Any, overload
+from duckdb import sqltypes
+
+if TYPE_CHECKING:
+    from ._typing import IntoExpr
+
+class Expression:
+    def __add__(self, other: IntoExpr) -> Expression: ...
+    def __and__(self, other: IntoExpr) -> Expression: ...
+    def __div__(self, other: IntoExpr) -> Expression: ...
+    def __eq__(self, other: IntoExpr) -> Expression: ...  # type: ignore[override]
+    def __floordiv__(self, other: IntoExpr) -> Expression: ...
+    def __ge__(self, other: IntoExpr) -> Expression: ...
+    def __gt__(self, other: IntoExpr) -> Expression: ...
+    @overload
+    def __init__(self, arg0: str) -> None: ...
+    @overload
+    def __init__(self, arg0: Any) -> None: ...
+    def __invert__(self) -> Expression: ...
+    def __le__(self, other: IntoExpr) -> Expression: ...
+    def __lt__(self, other: IntoExpr) -> Expression: ...
+    def __mod__(self, other: IntoExpr) -> Expression: ...
+    def __mul__(self, other: IntoExpr) -> Expression: ...
+    def __ne__(self, other: IntoExpr) -> Expression: ...  # type: ignore[override]
+    def __neg__(self) -> Expression: ...
+    def __or__(self, other: IntoExpr) -> Expression: ...
+    def __pow__(self, other: IntoExpr) -> Expression: ...
+    def __radd__(self, other: IntoExpr) -> Expression: ...
+    def __rand__(self, other: IntoExpr) -> Expression: ...
+    def __rdiv__(self, other: IntoExpr) -> Expression: ...
+    def __rfloordiv__(self, other: IntoExpr) -> Expression: ...
+    def __rmod__(self, other: IntoExpr) -> Expression: ...
+    def __rmul__(self, other: IntoExpr) -> Expression: ...
+    def __ror__(self, other: IntoExpr) -> Expression: ...
+    def __rpow__(self, other: IntoExpr) -> Expression: ...
+    def __rsub__(self, other: IntoExpr) -> Expression: ...
+    def __rtruediv__(self, other: IntoExpr) -> Expression: ...
+    def __sub__(self, other: IntoExpr) -> Expression: ...
+    def __truediv__(self, other: IntoExpr) -> Expression: ...
+    def alias(self, name: str) -> Expression: ...
+    def asc(self) -> Expression: ...
+    def between(self, lower: IntoExpr, upper: IntoExpr) -> Expression: ...
+    def cast(self, type: sqltypes.DuckDBPyType) -> Expression: ...
+    def collate(self, collation: str) -> Expression: ...
+    def desc(self) -> Expression: ...
+    def get_name(self) -> str: ...
+    def isin(self, *args: IntoExpr) -> Expression: ...
+    def isnotin(self, *args: IntoExpr) -> Expression: ...
+    def isnotnull(self) -> Expression: ...
+    def isnull(self) -> Expression: ...
+    def nulls_first(self) -> Expression: ...
+    def nulls_last(self) -> Expression: ...
+    def otherwise(self, value: IntoExpr) -> Expression: ...
+    def show(self) -> None: ...
+    def when(self, condition: IntoExpr, value: IntoExpr) -> Expression: ...

_duckdb-stubs/_typing.pyi

@@ -0,0 +1,35 @@
+from __future__ import annotations
+from typing import TypeAlias, TYPE_CHECKING
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from uuid import UUID
+from collections.abc import Mapping
+
+if TYPE_CHECKING:
+    from ._expression import Expression
+
+NumericLiteral: TypeAlias = int | float | Decimal
+"""Python objects that can be converted to a numerical `ConstantExpression` (integer or floating points numbers.)"""
+TemporalLiteral: TypeAlias = date | datetime | time | timedelta
+BlobLiteral: TypeAlias = bytes | bytearray | memoryview
+"""Python objects that can be converted to a `BLOB` `ConstantExpression`.
+
+Note:
+    `bytes` can also be converted to a `BITSTRING`.
+"""
+NonNestedLiteral: TypeAlias = NumericLiteral | TemporalLiteral | str | bool | BlobLiteral | UUID
+PythonLiteral: TypeAlias = (
+    NonNestedLiteral | list[PythonLiteral] | tuple[PythonLiteral, ...] | dict[PythonLiteral, PythonLiteral] | None
+)
+"""Python objects that can be converted to a `ConstantExpression`."""
+# the field_ids argument to to_parquet and write_parquet has a recursive structure
+ParquetFieldIdsType: TypeAlias = Mapping[str, int | ParquetFieldIdsType]
+
+IntoExprColumn: TypeAlias = Expression | str
+"""Types that are, or can be used as a `ColumnExpression`."""
+IntoExpr: TypeAlias = IntoExprColumn | PythonLiteral
+"""Any type that can be converted to an `Expression` (or is already one).
+
+See Also:
+    https://duckdb.org/docs/stable/clients/python/conversion
+"""