refactor:

- reorganized expressions/values conversions types, improved their doc
- added Literals for sqltypes ids and string conversion, and various type aliases, covering all paths.
- using aformentionned literals in _sqltypes signatures

Author: OutSquareCapital

_duckdb-stubs/_sqltypes.pyi

@@ -1,5 +1,6 @@
 import duckdb
 import typing
+from ._typing import StrIntoDType, DTypeIdentifiers
 
 __all__: list[str] = [
     "BIGINT",
@@ -39,13 +40,13 @@ class DuckDBPyType:
     def __getitem__(self, name: str) -> DuckDBPyType: ...
     def __hash__(self) -> int: ...
     @typing.overload
-    def __init__(self, type_str: str, connection: duckdb.DuckDBPyConnection) -> None: ...
+    def __init__(self, type_str: StrIntoDType, connection: duckdb.DuckDBPyConnection) -> None: ...
     @typing.overload
     def __init__(self, obj: object) -> None: ...
     @property
     def children(self) -> list[tuple[str, DuckDBPyType | int | list[str]]]: ...
     @property
-    def id(self) -> str: ...
+    def id(self) -> DTypeIdentifiers: ...
 
 BIGINT: DuckDBPyType  # value = BIGINT
 BIT: DuckDBPyType  # value = BIT

_duckdb-stubs/_typing.pyi

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-from typing import TypeAlias, TYPE_CHECKING, Protocol, Any, TypeVar, Generic
+from typing import TypeAlias, TYPE_CHECKING, Protocol, Any, TypeVar, Generic, Literal
 from datetime import date, datetime, time, timedelta
 from decimal import Decimal
 from uuid import UUID
-from collections.abc import Mapping, Iterator
+from collections.abc import Mapping, Iterator, Sequence
 
 if TYPE_CHECKING:
     from ._expression import Expression
@@ -52,44 +52,127 @@ class NPArrayLike(NPProtocol, Generic[_S_co, _D_co], Protocol):
     @property
     def size(self) -> int: ...
 
-NumericLiteral: TypeAlias = int | float | Decimal
-"""Python objects that can be converted to a numerical `ConstantExpression` (integer or floating points numbers.)"""
+# Expression and values conversions
+
+NumericLiteral: TypeAlias = int | float
+"""Python objects that can be converted to a numerical `Expression` or `DuckDBPyType` (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`.
+BlobLiteral: TypeAlias = bytes | bytearray
+"""Python objects that can be converted to a `BLOB` `ConstantExpression` or `DuckDBPyType`.
 
 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[NonNestedLiteral, PythonLiteral]
-    | NPArrayLike[Any, Any]
-    | None
-)
+ScalarLiteral: TypeAlias = NumericLiteral | BlobLiteral | str | bool
+NonNestedLiteral: TypeAlias = ScalarLiteral | TemporalLiteral | UUID | Decimal | memoryview
+
+# NOTE:
+# Using `Sequence` and `Mapping` instead of `list | tuple` and `dict` would make the covariance of the element types work.
+# Thus, this would allow to avoid the use of `Any` for them.
+# However, this would also be incorrect at runtime, since only the 3 aformentioned containers types are accepted.
+NestedLiteral: TypeAlias = list[Any] | tuple[Any, ...] | dict[Any, Any] | NPArrayLike[Any, Any]
+"""Containers types that can be converted to a nested `ConstantExpression` (e.g. to `ARRAY` or `STRUCT`).
+
+Those types can be aribtraly nested, as long as their leaf values are `PythonLiteral`."""
+
+PythonLiteral: TypeAlias = NonNestedLiteral | NestedLiteral | None
 """Python objects that can be converted to a `ConstantExpression`."""
+
+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
+"""
+
 # the field_ids argument to to_parquet and write_parquet has a recursive structure
 ParquetFieldIdsType: TypeAlias = Mapping[str, int | ParquetFieldIdsType]
 IntoValues: TypeAlias = list[PythonLiteral] | tuple[Expression, ...] | Expression
 """Types that can be converted to a table."""
-IntoDType: TypeAlias = DuckDBPyType | str
-"""Types that can be converted to a `DuckDBPyType`.
+# Datatypes conversions
 
-Passing `INTEGER` is equivalent to passing `DuckDBPyType("INTEGER")` or `DuckDBPyType.INTEGER`.
+Builtins: TypeAlias = Literal[
+    "bigint",
+    "bit",
+    "bignum",
+    "blob",
+    "boolean",
+    "date",
+    "double",
+    "float",
+    "hugeint",
+    "integer",
+    "interval",
+    "smallint",
+    "null",
+    "time_tz",
+    "time",
+    "timestamp_ms",
+    "timestamp_ns",
+    "timestamp_s",
+    "timestamp_tz",
+    "timestamp",
+    "tinyint",
+    "ubigint",
+    "uhugeint",
+    "uinteger",
+    "usmallint",
+    "utinyint",
+    "uuid",
+    "varchar",
+]
+"""Literals strings convertibles into `DuckDBPyType` instances.
 
 Note:
-    A `StrEnum` will be handled the same way as a `str`.
+    Passing the same values in uppercase is also accepted. 
+    We use lowercase here to be able to reuse this `Literal` in the `DTypeIdentifiers` `Literal`.
 """
-IntoNestedDType: TypeAlias = dict[str, IntoDType] | list[IntoDType]
-"""Types that can be converted to a nested `DuckDBPyType` (e.g. for struct or union types)."""
-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).
+
+NestedIds: TypeAlias = Literal["list", "struct", "array", "enum", "map", "decimal", "union"]
+"""Identifiers for nested types in `DuckDBPyType.id`."""
+
+DTypeIdentifiers: TypeAlias = Builtins | NestedIds
+"""All possible identifiers for `DuckDBPyType.id`."""
+
+StrIntoDType = Builtins | Literal["json"] | str
+"""Any `str` that can be converted into a `DuckDBPyType`. 
+
+The dtypes not present in the literal values are the composed ones, like `STRUCT` or `DECIMAL`
+
+Note:
+    A `StrEnum` will be handled the same way as a `str`."""
+
+# NOTE:
+# the `dict` and `list` types are `Any` due to the same limitation mentionned in `NestedLiteral`.
+IntoDType: TypeAlias = (
+    DuckDBPyType
+    | StrIntoDType
+    | type[NPScalarTypeLike]
+    | type[ScalarLiteral]
+    | type[list[Any]]
+    | type[dict[Any, Any]]
+    | dict[Any, Any]
+)
+"""All types that can be converted to a `DuckDBPyType`.
+
+They can be arbitrarily nested as long as their leaf values are convertible to `DuckDBPyType`.
 
 See Also:
-    https://duckdb.org/docs/stable/clients/python/conversion
+    https://duckdb.org/docs/stable/clients/python/types
+"""
+
+# NOTE: here we keep the covariance "hack" and warn the user in the docstring,
+# because otherwise we can just resort to `Any` for the `dict` and `list` types.
+IntoNestedDType: TypeAlias = Mapping[str, IntoDType] | Sequence[IntoDType]
+"""Types that can be converted either into: 
+
+- a nested `DuckDBPyType` (e.g. `STRUCT` or `UNION`)
+- a schema for file reads
+
+Warning:
+    Only `dict` and `list` containers are accepted at runtime. 
+    We use `Mapping` and `Sequence` here to satisfy the covariance of the element types.
 """