feat:

- added various new literals for files arguments
- moved join "how" literal in _typing for centralization
- renamed IntoNestedDType -> IntoFields

Author: OutSquareCapital

_duckdb-stubs/__init__.pyi

@@ -19,7 +19,8 @@ if typing.TYPE_CHECKING:
         PythonLiteral,
         IntoValues,
         IntoDType,
-        IntoNestedDType,
+        IntoFields,
+        JoinType,
     )
     from duckdb import sqltypes, func
 
@@ -447,17 +448,17 @@ class DuckDBPyConnection:
     def register_filesystem(self, filesystem: fsspec.AbstractFileSystem) -> None: ...
     def remove_function(self, name: str) -> DuckDBPyConnection: ...
     def rollback(self) -> DuckDBPyConnection: ...
-    def row_type(self, fields: IntoNestedDType) -> sqltypes.DuckDBPyType: ...
+    def row_type(self, fields: IntoFields) -> sqltypes.DuckDBPyType: ...
     def sql(self, query: Statement | str, *, alias: str = "", params: object = None) -> DuckDBPyRelation: ...
     def sqltype(self, type_str: str) -> sqltypes.DuckDBPyType: ...
     def string_type(self, collation: str = "") -> sqltypes.DuckDBPyType: ...
-    def struct_type(self, fields: IntoNestedDType) -> sqltypes.DuckDBPyType: ...
+    def struct_type(self, fields: IntoFields) -> sqltypes.DuckDBPyType: ...
     def table(self, table_name: str) -> DuckDBPyRelation: ...
     def table_function(self, name: str, parameters: object = None) -> DuckDBPyRelation: ...
     def tf(self) -> dict[str, typing.Any]: ...
     def torch(self) -> dict[str, typing.Any]: ...
     def type(self, type_str: str) -> sqltypes.DuckDBPyType: ...
-    def union_type(self, members: IntoNestedDType) -> sqltypes.DuckDBPyType: ...
+    def union_type(self, members: IntoFields) -> sqltypes.DuckDBPyType: ...
     def unregister(self, view_name: str) -> DuckDBPyConnection: ...
     def unregister_filesystem(self, name: str) -> None: ...
     def values(self, *args: IntoValues) -> DuckDBPyRelation: ...
@@ -571,12 +572,7 @@ class DuckDBPyRelation:
     def insert(self, values: lst[object]) -> None: ...
     def insert_into(self, table_name: str) -> None: ...
     def intersect(self, other_rel: Self) -> DuckDBPyRelation: ...
-    def join(
-        self,
-        other_rel: Self,
-        condition: IntoExprColumn,
-        how: typing.Literal["inner", "left", "right", "outer", "semi", "anti"] = "inner",
-    ) -> DuckDBPyRelation: ...
+    def join(self, other_rel: Self, condition: IntoExprColumn, how: JoinType = "inner") -> DuckDBPyRelation: ...
     def lag(
         self,
         expression: str,
@@ -1391,7 +1387,7 @@ def register_filesystem(
 ) -> None: ...
 def remove_function(name: str, *, connection: DuckDBPyConnection | None = None) -> DuckDBPyConnection: ...
 def rollback(*, connection: DuckDBPyConnection | None = None) -> DuckDBPyConnection: ...
-def row_type(fields: IntoNestedDType, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
+def row_type(fields: IntoFields, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
 def rowcount(*, connection: DuckDBPyConnection | None = None) -> int: ...
 def set_default_connection(connection: DuckDBPyConnection) -> None: ...
 def sql(
@@ -1403,7 +1399,7 @@ def sql(
 ) -> DuckDBPyRelation: ...
 def sqltype(type_str: str, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
 def string_type(collation: str = "", *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
-def struct_type(fields: IntoNestedDType, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
+def struct_type(fields: IntoFields, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
 def table(table_name: str, *, connection: DuckDBPyConnection | None = None) -> DuckDBPyRelation: ...
 def table_function(
     name: str,
@@ -1415,7 +1411,7 @@ def tf(*, connection: DuckDBPyConnection | None = None) -> dict[str, typing.Any]
 def tokenize(query: str) -> lst[tuple[int, token_type]]: ...
 def torch(*, connection: DuckDBPyConnection | None = None) -> dict[str, typing.Any]: ...
 def type(type_str: str, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
-def union_type(members: IntoNestedDType, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
+def union_type(members: IntoFields, *, connection: DuckDBPyConnection | None = None) -> sqltypes.DuckDBPyType: ...
 def unregister(view_name: str, *, connection: DuckDBPyConnection | None = None) -> DuckDBPyConnection: ...
 def unregister_filesystem(name: str, *, connection: DuckDBPyConnection | None = None) -> None: ...
 def values(*args: IntoValues, connection: DuckDBPyConnection | None = None) -> DuckDBPyRelation: ...

_duckdb-stubs/_typing.pyi

@@ -88,8 +88,6 @@ 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."""
 # Datatypes conversions
@@ -140,7 +138,7 @@ DTypeIdentifiers: TypeAlias = Builtins | NestedIds
 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`
+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`."""
@@ -166,7 +164,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.
-IntoNestedDType: TypeAlias = Mapping[str, IntoDType] | Sequence[IntoDType]
+IntoFields: TypeAlias = Mapping[str, IntoDType] | Sequence[IntoDType]
 """Types that can be converted either into: 
 
 - a nested `DuckDBPyType` (e.g. `STRUCT` or `UNION`)
@@ -176,3 +174,33 @@ Warning:
     Only `dict` and `list` containers are accepted at runtime. 
     We use `Mapping` and `Sequence` here to satisfy the covariance of the element types.
 """
+
+# Files related
+
+# NOTE: ideally HiveTypes should also be accepted as a Mapping[str, StrIntoDType].
+ColumnsTypes: TypeAlias = Mapping[str, StrIntoDType]
+HiveTypes: TypeAlias = dict[str, StrIntoDType]
+ParquetFieldIdsType: TypeAlias = Mapping[str, int | ParquetFieldIdsType]
+
+_Auto: TypeAlias = Literal["auto"]
+ParquetFieldsOptions: TypeAlias = _Auto | ParquetFieldIdsType
+"""Types accepted for the `field_ids` parameter in parquet writing methods."""
+
+_CompressionOptions: TypeAlias = Literal["none", "gzip", "zstd"]
+"""Generally available compression options."""
+
+CsvCompression: TypeAlias = _Auto | _CompressionOptions
+CsvEncoding: TypeAlias = Literal["utf-8", "utf-16", "latin-1"] | str
+"""Encdoding options.
+
+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"]
+JsonFormat: TypeAlias = _Auto | Literal["unstructured", "newline_delimited", "array"]
+JsonRecordOptions: TypeAlias = _Auto | Literal["true", "false"]
+
+# Other
+
+JoinType = Literal["inner", "left", "right", "outer", "semi", "anti"]
+"""Types of join accepted by `DuckDBPyRelation.join` method."""