fixs:

- Builtins Literal had incorrect values for time/timestamp with time zone
- typos fixes
- renamed `DType` for Literals to `PyType` to keep the naming conventions consistent

Author: OutSquareCapital

_duckdb-stubs/__init__.pyi

@@ -18,9 +18,9 @@ if typing.TYPE_CHECKING:
         IntoExprColumn,
         PythonLiteral,
         IntoValues,
-        IntoDType,
+        IntoPyType,
         IntoFields,
-        StrIntoDType,
+        StrIntoPyType,
         JoinType,
         JsonCompression,
         JsonFormat,
@@ -210,7 +210,7 @@ class DuckDBPyConnection:
     def __enter__(self) -> Self: ...
     def __exit__(self, exc_type: object, exc: object, traceback: object) -> None: ...
     def append(self, table_name: str, df: pandas.DataFrame, *, by_name: bool = False) -> DuckDBPyConnection: ...
-    def array_type(self, type: IntoDType, size: typing.SupportsInt) -> sqltypes.DuckDBPyType: ...
+    def array_type(self, type: IntoPyType, size: typing.SupportsInt) -> sqltypes.DuckDBPyType: ...
     def arrow(self, rows_per_batch: typing.SupportsInt = 1000000) -> pyarrow.lib.RecordBatchReader:
         """Alias of to_arrow_reader(). We recommend using to_arrow_reader() instead."""
         ...
@@ -224,8 +224,8 @@ class DuckDBPyConnection:
         self,
         name: str,
         function: Callable[..., PythonLiteral],
-        parameters: lst[IntoDType] | None = None,
-        return_type: IntoDType | None = None,
+        parameters: lst[IntoPyType] | None = None,
+        return_type: IntoPyType | None = None,
         *,
         type: func.PythonUDFType = ...,
         null_handling: func.FunctionNullHandling = ...,
@@ -235,7 +235,7 @@ class DuckDBPyConnection:
     def cursor(self) -> DuckDBPyConnection: ...
     def decimal_type(self, width: typing.SupportsInt, scale: typing.SupportsInt) -> sqltypes.DuckDBPyType: ...
     def df(self, *, date_as_object: bool = False) -> pandas.DataFrame: ...
-    def dtype(self, type_str: StrIntoDType) -> sqltypes.DuckDBPyType: ...
+    def dtype(self, type_str: StrIntoPyType) -> sqltypes.DuckDBPyType: ...
     def duplicate(self) -> DuckDBPyConnection: ...
     def enum_type(self, name: str, type: sqltypes.DuckDBPyType, values: lst[typing.Any]) -> sqltypes.DuckDBPyType: ...
     def execute(self, query: Statement | str, parameters: object = None) -> DuckDBPyConnection: ...
@@ -285,7 +285,7 @@ class DuckDBPyConnection:
         names: lst[str] | None = None,
         lineterminator: str | None = None,
         columns: ColumnsTypes | None = None,
-        auto_type_candidates: lst[StrIntoDType] | None = None,
+        auto_type_candidates: lst[StrIntoPyType] | None = None,
         max_line_size: int | None = None,
         ignore_errors: bool | None = None,
         store_rejects: bool | None = None,
@@ -344,9 +344,9 @@ class DuckDBPyConnection:
     def disable_profiling(self) -> None: ...
     def interrupt(self) -> None: ...
     def list_filesystems(self) -> lst[str]: ...
-    def list_type(self, type: IntoDType) -> sqltypes.DuckDBPyType: ...
+    def list_type(self, type: IntoPyType) -> sqltypes.DuckDBPyType: ...
     def load_extension(self, extension: str) -> None: ...
-    def map_type(self, key: IntoDType, value: IntoDType) -> sqltypes.DuckDBPyType: ...
+    def map_type(self, key: IntoPyType, value: IntoPyType) -> sqltypes.DuckDBPyType: ...
     @typing.overload
     def pl(
         self, rows_per_batch: typing.SupportsInt = 1000000, *, lazy: typing.Literal[False] = ...
@@ -386,7 +386,7 @@ class DuckDBPyConnection:
         names: lst[str] | None = None,
         lineterminator: str | None = None,
         columns: ColumnsTypes | None = None,
-        auto_type_candidates: lst[StrIntoDType] | None = None,
+        auto_type_candidates: lst[StrIntoPyType] | None = None,
         max_line_size: int | None = None,
         ignore_errors: bool | None = None,
         store_rejects: bool | None = None,
@@ -679,8 +679,8 @@ class DuckDBPyRelation:
     def rank_dense(self, window_spec: str, projected_columns: str = "") -> DuckDBPyRelation: ...
     def row_number(self, window_spec: str, projected_columns: str = "") -> DuckDBPyRelation: ...
     def select(self, *args: IntoExpr, groups: str = "") -> DuckDBPyRelation: ...
-    def select_dtypes(self, types: lst[sqltypes.DuckDBPyType | StrIntoDType]) -> DuckDBPyRelation: ...
-    def select_types(self, types: lst[sqltypes.DuckDBPyType | StrIntoDType]) -> DuckDBPyRelation: ...
+    def select_dtypes(self, types: lst[sqltypes.DuckDBPyType | StrIntoPyType]) -> DuckDBPyRelation: ...
+    def select_types(self, types: lst[sqltypes.DuckDBPyType | StrIntoPyType]) -> DuckDBPyRelation: ...
     def set_alias(self, alias: str) -> DuckDBPyRelation: ...
     def show(
         self,
@@ -1033,7 +1033,7 @@ def append(
     table_name: str, df: pandas.DataFrame, *, by_name: bool = False, connection: DuckDBPyConnection | None = None
 ) -> DuckDBPyConnection: ...
 def array_type(
-    type: IntoDType, size: typing.SupportsInt, *, connection: DuckDBPyConnection | None = None
+    type: IntoPyType, size: typing.SupportsInt, *, connection: DuckDBPyConnection | None = None
 ) -> sqltypes.DuckDBPyType: ...
 @typing.overload
 def arrow(
@@ -1062,8 +1062,8 @@ def connect(
 def create_function(
     name: str,
     function: Callable[..., PythonLiteral],
-    parameters: lst[IntoDType] | None = None,
-    return_type: IntoDType | None = None,
+    parameters: lst[IntoPyType] | None = None,
+    return_type: IntoPyType | None = None,
     *,
     type: func.PythonUDFType = ...,
     null_handling: func.FunctionNullHandling = ...,
@@ -1084,7 +1084,7 @@ def df(*, date_as_object: bool = False, connection: DuckDBPyConnection | None =
 @typing.overload
 def df(df: pandas.DataFrame, *, connection: DuckDBPyConnection | None = None) -> DuckDBPyRelation: ...
 def distinct(df: pandas.DataFrame, *, connection: DuckDBPyConnection | None = None) -> DuckDBPyRelation: ...
-def dtype(type_str: StrIntoDType, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
+def dtype(type_str: StrIntoPyType, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
 def duplicate(*, connection: DuckDBPyConnection | None = None) -> DuckDBPyConnection: ...
 def enum_type(
     name: str,
@@ -1172,7 +1172,7 @@ def from_csv_auto(
     names: lst[str] | None = None,
     lineterminator: str | None = None,
     columns: ColumnsTypes | None = None,
-    auto_type_candidates: lst[StrIntoDType] | None = None,
+    auto_type_candidates: lst[StrIntoPyType] | None = None,
     max_line_size: int | None = None,
     ignore_errors: bool | None = None,
     store_rejects: bool | None = None,
@@ -1246,10 +1246,10 @@ def get_profiling_information(*, connection: DuckDBPyConnection | None = None, f
 def enable_profiling(*, connection: DuckDBPyConnection | None = None) -> None: ...
 def disable_profiling(*, connection: DuckDBPyConnection | None = None) -> None: ...
 def list_filesystems(*, connection: DuckDBPyConnection | None = None) -> lst[str]: ...
-def list_type(type: IntoDType, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
+def list_type(type: IntoPyType, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
 def load_extension(extension: str, *, connection: DuckDBPyConnection | None = None) -> None: ...
 def map_type(
-    key: IntoDType, value: IntoDType, *, connection: DuckDBPyConnection | None = None
+    key: IntoPyType, value: IntoPyType, *, connection: DuckDBPyConnection | None = None
 ) -> sqltypes.DuckDBPyType: ...
 def order(
     df: pandas.DataFrame, order_expr: str, *, connection: DuckDBPyConnection | None = None
@@ -1319,7 +1319,7 @@ def read_csv(
     names: lst[str] | None = None,
     lineterminator: str | None = None,
     columns: ColumnsTypes | None = None,
-    auto_type_candidates: lst[StrIntoDType] | None = None,
+    auto_type_candidates: lst[StrIntoPyType] | None = None,
     max_line_size: int | None = None,
     ignore_errors: bool | None = None,
     store_rejects: bool | None = None,

_duckdb-stubs/_expression.pyi

@@ -1,7 +1,7 @@
 from typing import TYPE_CHECKING, Any, overload
 
 if TYPE_CHECKING:
-    from ._typing import IntoExpr, IntoDType
+    from ._typing import IntoExpr, IntoPyType
 
 class Expression:
     def __add__(self, other: IntoExpr) -> Expression: ...
@@ -39,7 +39,7 @@ class Expression:
     def alias(self, name: str) -> Expression: ...
     def asc(self) -> Expression: ...
     def between(self, lower: IntoExpr, upper: IntoExpr) -> Expression: ...
-    def cast(self, type: IntoDType) -> Expression: ...
+    def cast(self, type: IntoPyType) -> Expression: ...
     def collate(self, collation: str) -> Expression: ...
     def desc(self) -> Expression: ...
     def get_name(self) -> str: ...

_duckdb-stubs/_sqltypes.pyi

@@ -1,6 +1,6 @@
 import duckdb
 import typing
-from ._typing import StrIntoDType, DTypeIdentifiers
+from ._typing import StrIntoPyType, PyTypeIds
 
 __all__: list[str] = [
     "BIGINT",
@@ -40,13 +40,13 @@ class DuckDBPyType:
     def __getitem__(self, name: str) -> DuckDBPyType: ...
     def __hash__(self) -> int: ...
     @typing.overload
-    def __init__(self, type_str: StrIntoDType, connection: duckdb.DuckDBPyConnection) -> None: ...
+    def __init__(self, type_str: StrIntoPyType, 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) -> DTypeIdentifiers: ...
+    def id(self) -> PyTypeIds: ...
 
 BIGINT: DuckDBPyType  # value = BIGINT
 BIT: DuckDBPyType  # value = BIT

_duckdb-stubs/_typing.pyi

@@ -36,7 +36,7 @@ class NPScalarTypeLike(NPProtocol, Protocol):
 class NPArrayLike(NPProtocol, Generic[_S_co, _D_co], Protocol):
     """`numpy.ndarray` Protocol.
 
-    This is needed to accept numpy arrays as literals in expressions, without emitting type checker errors about unknown symbol if the user doesn't have numpy installed.
+    This is needed to accept numpy arrays as literals in expressions, without emitting type checker errors about unknown symbol if the user doesn't have `numpy` installed.
 
     Note:
         Using `np.typing.NDArray` is still the best option for return types.
@@ -73,7 +73,7 @@ NonNestedLiteral: TypeAlias = ScalarLiteral | TemporalLiteral | UUID | Decimal |
 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`."""
+Those types can be arbitrarily nested, as long as their leaf values are `PythonLiteral`."""
 
 PythonLiteral: TypeAlias = NonNestedLiteral | NestedLiteral | None
 """Python objects that can be converted to a `ConstantExpression`."""
@@ -89,8 +89,9 @@ See Also:
 """
 
 IntoValues: TypeAlias = list[PythonLiteral] | tuple[Expression, ...] | Expression
-"""Types that can be converted to a table."""
-# Datatypes conversions
+"""Types that can be converted to a table of values."""
+
+# PyType conversions
 
 Builtins: TypeAlias = Literal[
     "bigint",
@@ -106,12 +107,12 @@ Builtins: TypeAlias = Literal[
     "interval",
     "smallint",
     "null",
-    "time_tz",
+    "time with time zone",
     "time",
     "timestamp_ms",
     "timestamp_ns",
     "timestamp_s",
-    "timestamp_tz",
+    "timestamp with time zone",
     "timestamp",
     "tinyint",
     "ubigint",
@@ -122,7 +123,7 @@ Builtins: TypeAlias = Literal[
     "uuid",
     "varchar",
 ]
-"""Literals strings convertibles into `DuckDBPyType` instances.
+"""Literals `str` that can be converted into `DuckDBPyType` instances.
 
 Note:
     Passing the same values in uppercase is also accepted. 
@@ -132,22 +133,22 @@ Note:
 NestedIds: TypeAlias = Literal["list", "struct", "array", "enum", "map", "decimal", "union"]
 """Identifiers for nested types in `DuckDBPyType.id`."""
 
-DTypeIdentifiers: TypeAlias = Builtins | NestedIds
+PyTypeIds: TypeAlias = Builtins | NestedIds
 """All possible identifiers for `DuckDBPyType.id`."""
 
-StrIntoDType = Builtins | Literal["json"] | str
+StrIntoPyType = 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`.
+The pytypes 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 = (
+IntoPyType: TypeAlias = (
     DuckDBPyType
-    | StrIntoDType
+    | StrIntoPyType
     | type[NPScalarTypeLike]
     | type[ScalarLiteral]
     | type[list[Any]]
@@ -164,7 +165,7 @@ See Also:
 
 # 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.
-IntoFields: TypeAlias = Mapping[str, IntoDType] | Sequence[IntoDType]
+IntoFields: TypeAlias = Mapping[str, IntoPyType] | Sequence[IntoPyType]
 """Types that can be converted either into: 
 
 - a nested `DuckDBPyType` (e.g. `STRUCT` or `UNION`)
@@ -177,9 +178,9 @@ Warning:
 
 # Files related
 
-# NOTE: ideally HiveTypes should also be accepted as a Mapping[str, StrIntoDType].
-ColumnsTypes: TypeAlias = Mapping[str, StrIntoDType]
-HiveTypes: TypeAlias = dict[str, StrIntoDType]
+# NOTE: ideally HiveTypes should also be accepted as a Mapping[str, StrIntoPyType].
+ColumnsTypes: TypeAlias = Mapping[str, StrIntoPyType]
+HiveTypes: TypeAlias = dict[str, StrIntoPyType]
 ParquetFieldIdsType: TypeAlias = Mapping[str, int | ParquetFieldIdsType]
 
 _Auto: TypeAlias = Literal["auto"]
@@ -196,7 +197,7 @@ CsvEncoding: TypeAlias = Literal["utf-8", "utf-16", "latin-1"] | str
 All availables options not in the literal values can be seen here:
     https://duckdb.org/docs/stable/core_extensions/encodings
 """
-JsonCompression: TypeAlias = _CompressionOptions | Literal["auto_detect"]
+JsonCompression: TypeAlias = Literal["auto_detect"] | _CompressionOptions
 JsonFormat: TypeAlias = _Auto | Literal["unstructured", "newline_delimited", "array"]
 JsonRecordOptions: TypeAlias = _Auto | Literal["true", "false"]