From 1f480361aa7986badf550baa13616621399a4583 Mon Sep 17 00:00:00 2001
From: etrotta <erictrottavolt@gmail.com>
Date: Mon, 7 Oct 2024 15:49:26 -0300
Subject: [PATCH] docs(python): Annotate Config kwarg options (#18988)

---
 py-polars/polars/config.py          | 64 +++++++++++++++++++++++++++--
 py-polars/tests/unit/test_config.py |  2 +-
 2 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/py-polars/polars/config.py b/py-polars/polars/config.py
index 0ad1dfb985f9..d6774cfd126f 100644
--- a/py-polars/polars/config.py
+++ b/py-polars/polars/config.py
@@ -3,7 +3,7 @@
 import contextlib
 import os
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, get_args
+from typing import TYPE_CHECKING, Literal, TypedDict, get_args
 
 from polars._utils.various import normalize_filepath
 from polars.dependencies import json
@@ -20,9 +20,9 @@
         from typing_extensions import TypeAlias
 
     if sys.version_info >= (3, 11):
-        from typing import Self
+        from typing import Self, Unpack
     else:
-        from typing_extensions import Self
+        from typing_extensions import Self, Unpack
 
 
 __all__ = ["Config"]
@@ -87,6 +87,60 @@
     }
 
 
+class ConfigParameters(TypedDict, total=False):
+    """Parameters supported by the polars Config."""
+
+    ascii_tables: bool | None
+    auto_structify: bool | None
+    decimal_separator: str | None
+    thousands_separator: str | bool | None
+    float_precision: int | None
+    fmt_float: FloatFmt | None
+    fmt_str_lengths: int | None
+    fmt_table_cell_list_len: int | None
+    streaming_chunk_size: int | None
+    tbl_cell_alignment: Literal["LEFT", "CENTER", "RIGHT"] | None
+    tbl_cell_numeric_alignment: Literal["LEFT", "CENTER", "RIGHT"] | None
+    tbl_cols: int | None
+    tbl_column_data_type_inline: bool | None
+    tbl_dataframe_shape_below: bool | None
+    tbl_formatting: TableFormatNames | None
+    tbl_hide_column_data_types: bool | None
+    tbl_hide_column_names: bool | None
+    tbl_hide_dtype_separator: bool | None
+    tbl_hide_dataframe_shape: bool | None
+    tbl_rows: int | None
+    tbl_width_chars: int | None
+    trim_decimal_zeros: bool | None
+    verbose: bool | None
+    expr_depth_warning: int
+
+    set_ascii_tables: bool | None
+    set_auto_structify: bool | None
+    set_decimal_separator: str | None
+    set_thousands_separator: str | bool | None
+    set_float_precision: int | None
+    set_fmt_float: FloatFmt | None
+    set_fmt_str_lengths: int | None
+    set_fmt_table_cell_list_len: int | None
+    set_streaming_chunk_size: int | None
+    set_tbl_cell_alignment: Literal["LEFT", "CENTER", "RIGHT"] | None
+    set_tbl_cell_numeric_alignment: Literal["LEFT", "CENTER", "RIGHT"] | None
+    set_tbl_cols: int | None
+    set_tbl_column_data_type_inline: bool | None
+    set_tbl_dataframe_shape_below: bool | None
+    set_tbl_formatting: TableFormatNames | None
+    set_tbl_hide_column_data_types: bool | None
+    set_tbl_hide_column_names: bool | None
+    set_tbl_hide_dtype_separator: bool | None
+    set_tbl_hide_dataframe_shape: bool | None
+    set_tbl_rows: int | None
+    set_tbl_width_chars: int | None
+    set_trim_decimal_zeros: bool | None
+    set_verbose: bool | None
+    set_expr_depth_warning: int
+
+
 class Config(contextlib.ContextDecorator):
     """
     Configure polars; offers options for table formatting and more.
@@ -118,7 +172,9 @@ class Config(contextlib.ContextDecorator):
 
     _original_state: str = ""
 
-    def __init__(self, *, restore_defaults: bool = False, **options: Any) -> None:
+    def __init__(
+        self, *, restore_defaults: bool = False, **options: Unpack[ConfigParameters]
+    ) -> None:
         """
         Initialise a Config object instance for context manager usage.
 
diff --git a/py-polars/tests/unit/test_config.py b/py-polars/tests/unit/test_config.py
index cd0491b5435f..6c74f0693caa 100644
--- a/py-polars/tests/unit/test_config.py
+++ b/py-polars/tests/unit/test_config.py
@@ -739,7 +739,7 @@ def test_config_scope() -> None:
 
 
 def test_config_raise_error_if_not_exist() -> None:
-    with pytest.raises(AttributeError), pl.Config(i_do_not_exist=True):
+    with pytest.raises(AttributeError), pl.Config(i_do_not_exist=True):  # type: ignore[call-arg]
         pass