Enforce strict type checking on docs

mwouts · mwouts · commit 8fa250a684a6 · 2025-05-31T21:58:13.000+01:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -33,5 +33,5 @@ repos:
     rev: v1.17.1
     hooks:
     - id: jupytext
-      types: ["python"]
-      args: ["--sync", "--quiet"]
+      files: "^docs/"
+      args: ["--sync"]
diff --git a/docs/apps/html.md b/docs/apps/html.md
@@ -12,6 +12,12 @@ kernelspec:
   name: itables
 ---
 
+```{code-cell} ipython3
+:tags: [remove-cell]
+
+# pyright: reportUnknownVariableType=false
+```
+
 # HTML export
 
 To get the HTML representation of a Pandas DataFrame `df` as an interactive [DataTable](https://datatables.net/), you can use `to_html_datatable` as below:
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -5,7 +5,7 @@ ITables ChangeLog
 ----------------------
 
 **Added**
-- We now enforce `pyright` on the ITables documentation
+- We now enforce `pyright` on the ITables documentation ([#395](https://github.com/mwouts/itables/issues/395))
 
 **Changed**
 - The `warn_on_undocumented_option` option now defaults to `True` and only check the option names
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -12,6 +12,12 @@ kernelspec:
   name: itables
 ---
 
+```{code-cell} ipython3
+:tags: [remove-cell]
+
+# pyright: reportUnknownVariableType=false
+```
+
 # Contributing
 
 Thanks for considering making a contribution to ITables. There are
diff --git a/docs/css.md b/docs/css.md
@@ -16,6 +16,7 @@ kernelspec:
 :tags: [remove-cell]
 
 # ruff: noqa: E402
+# pyright: reportUnknownVariableType=false
 ```
 
 # CSS
diff --git a/docs/options/allow_html.md b/docs/options/allow_html.md
@@ -12,6 +12,14 @@ kernelspec:
   name: itables
 ---
 
+```{code-cell} ipython3
+:tags: [remove-cell]
+
+# pyright: reportUnknownVariableType=false
+# pyright: reportUnknownArgumentType=false
+# pyright: reportUnknownMemberType=false
+```
+
 # Allow HTML
 
 Since v2.4.0, the HTML content in your tables is escaped by default. You can change this by passing `allow_html=True`.
diff --git a/docs/options/order.md b/docs/options/order.md
@@ -25,6 +25,6 @@ import itables
 
 itables.init_notebook_mode()
 
-sorted_df = pd.DataFrame({"i": [1, 2], "a": [2, 1]}).set_index(["i"])
+sorted_df = pd.DataFrame({"a": [2, 1]}, index=pd.Index([1, 2], name="i"))
 itables.show(sorted_df, order=[[1, "asc"]])
 ```
diff --git a/docs/options/row_group.md b/docs/options/row_group.md
@@ -12,6 +12,12 @@ kernelspec:
   name: itables
 ---
 
+```{code-cell} ipython3
+:tags: [remove-cell]
+
+# pyright: reportUnknownMemberType=false
+```
+
 # RowGroup
 
 Use the [RowGroup](https://datatables.net/extensions/rowgroup/) extension to group
diff --git a/docs/pandas_style.md b/docs/pandas_style.md
@@ -16,6 +16,7 @@ kernelspec:
 :tags: [remove-cell]
 
 # pyright: reportUnusedExpression=false
+# pyright: reportUnknownMemberType=false
 ```
 
 # Pandas Style
diff --git a/docs/polars_dataframes.md b/docs/polars_dataframes.md
@@ -20,7 +20,7 @@ dataframes are displayed nicely with the default `itables` settings.
 ```{code-cell} ipython3
 import itables
 
-dict_of_test_dfs = itables.sample_dfs.get_dict_of_test_dfs(polars=True)
+dict_of_test_dfs = itables.sample_dfs.get_dict_of_polars_test_dfs()
 itables.init_notebook_mode()
 ```
 
diff --git a/docs/py/apps/html.py b/docs/py/apps/html.py
@@ -14,6 +14,9 @@
 #     name: itables
 # ---
 
+# %% tags=["remove-cell"]
+# pyright: reportUnknownVariableType=false
+
 # %% [markdown]
 # # HTML export
 #
diff --git a/docs/py/contributing.py b/docs/py/contributing.py
@@ -14,6 +14,9 @@
 #     name: itables
 # ---
 
+# %% tags=["remove-cell"]
+# pyright: reportUnknownVariableType=false
+
 # %% [markdown]
 # # Contributing
 #
diff --git a/docs/py/css.py b/docs/py/css.py
@@ -16,6 +16,7 @@
 
 # %% tags=["remove-cell"]
 # ruff: noqa: E402
+# pyright: reportUnknownVariableType=false
 
 # %% [markdown]
 # # CSS
diff --git a/docs/py/options/allow_html.py b/docs/py/options/allow_html.py
@@ -14,6 +14,11 @@
 #     name: itables
 # ---
 
+# %% tags=["remove-cell"]
+# pyright: reportUnknownVariableType=false
+# pyright: reportUnknownArgumentType=false
+# pyright: reportUnknownMemberType=false
+
 # %% [markdown]
 # # Allow HTML
 #
diff --git a/docs/py/options/order.py b/docs/py/options/order.py
@@ -28,5 +28,5 @@
 
 itables.init_notebook_mode()
 
-sorted_df = pd.DataFrame({"i": [1, 2], "a": [2, 1]}).set_index(["i"])
+sorted_df = pd.DataFrame({"a": [2, 1]}, index=pd.Index([1, 2], name="i"))
 itables.show(sorted_df, order=[[1, "asc"]])
diff --git a/docs/py/options/row_group.py b/docs/py/options/row_group.py
@@ -14,6 +14,9 @@
 #     name: itables
 # ---
 
+# %% tags=["remove-cell"]
+# pyright: reportUnknownMemberType=false
+
 # %% [markdown]
 # # RowGroup
 #
diff --git a/docs/py/pandas_style.py b/docs/py/pandas_style.py
@@ -16,6 +16,7 @@
 
 # %% tags=["remove-cell"]
 # pyright: reportUnusedExpression=false
+# pyright: reportUnknownMemberType=false
 
 # %% [markdown]
 # # Pandas Style
diff --git a/docs/py/polars_dataframes.py b/docs/py/polars_dataframes.py
@@ -23,7 +23,7 @@
 # %%
 import itables
 
-dict_of_test_dfs = itables.sample_dfs.get_dict_of_test_dfs(polars=True)
+dict_of_test_dfs = itables.sample_dfs.get_dict_of_polars_test_dfs()
 itables.init_notebook_mode()
 
 # %% [markdown]
diff --git a/docs/py/troubleshooting.py b/docs/py/troubleshooting.py
@@ -17,6 +17,7 @@
 # %% tags=["remove-cell"]
 # ruff: noqa: E402
 # pyright: reportUnusedExpression=false
+# pyright: reportDuplicateImport=false
 
 # %% [markdown]
 # # Troubleshooting
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -17,6 +17,7 @@ kernelspec:
 
 # ruff: noqa: E402
 # pyright: reportUnusedExpression=false
+# pyright: reportDuplicateImport=false
 ```
 
 # Troubleshooting
diff --git a/pyproject.toml b/pyproject.toml
@@ -126,3 +126,4 @@ artifacts = [
 
 [tool.pyright]
 typeCheckingMode = "standard"
+strict = ["docs"]
diff --git a/src/itables/downsample.py b/src/itables/downsample.py
@@ -3,16 +3,18 @@
 
 import pandas as pd
 
+from itables.typing import DataFrameOrSeries
 
-def nbytes(df):
+
+def nbytes(df: DataFrameOrSeries) -> int:
     try:
         return sum(x.values.nbytes for _, x in df.items())
     except AttributeError:
         # Polars DataFrame
         return df.estimated_size()
 
 
-def as_nbytes(mem):
+def as_nbytes(mem: Union[int, float, str]) -> int:
     if isinstance(mem, (int, float)):
         return int(mem)
     assert isinstance(mem, str), mem
diff --git a/src/itables/options.py b/src/itables/options.py
@@ -118,6 +118,7 @@
 searchCols: Optional[Sequence[Any]]
 initComplete: Optional[typing.JavascriptFunction]
 fnInfoCallback: Optional[typing.JavascriptFunction]
+drawCallback: Optional[typing.JavascriptFunction]
 stateSave: Optional[bool]
 stateDuration: Optional[int]
 buttons: Optional[Sequence[Union[str, Mapping[str, Any]]]]
diff --git a/src/itables/sample_dfs.py b/src/itables/sample_dfs.py
@@ -3,7 +3,7 @@
 from datetime import datetime, timedelta
 from functools import lru_cache
 from itertools import cycle
-from typing import cast
+from typing import Any, cast
 
 import numpy as np
 import pandas as pd
@@ -38,7 +38,7 @@
     COLUMN_TYPES = [type for type in COLUMN_TYPES if type != "timedelta"]
 
 
-def get_countries(html: bool = True, climate_zone: bool = False):
+def get_countries(html: bool = True, climate_zone: bool = False) -> pd.DataFrame:
     """A Pandas DataFrame with the world countries (from the world bank data)
     Flags are loaded from https://flagpedia.net/"""
     df = pd.read_csv(find_package_file("samples/countries.csv"))
@@ -116,10 +116,10 @@ def get_df_complex_index():
     return df
 
 
-def get_dict_of_test_dfs(N=100, M=100, polars=False):
+def get_dict_of_test_dfs(N=100, M=100) -> dict[str, pd.DataFrame]:
     NM_values = np.reshape(np.linspace(start=0.0, stop=1.0, num=N * M), (N, M))
 
-    test_dfs = {
+    return {
         "empty": pd.DataFrame(dtype=float),
         "no_rows": pd.DataFrame(dtype=float, columns=["a"]),
         "no_columns": pd.DataFrame(dtype=float, index=["a"]),
@@ -280,28 +280,27 @@ def get_dict_of_test_dfs(N=100, M=100, polars=False):
         ),
     }
 
-    if polars:
-        import polars as pl
-        import pyarrow as pa
 
-        polars_dfs = {}
-        for key, df in test_dfs.items():
-            if key == "multiindex":
-                # Since Polars 1.2, pl.from_pandas fails with this error:
-                # ValueError: Pandas dataframe contains non-unique indices and/or column names.
-                # Polars dataframes require unique string names for columns.
-                # See https://github.com/pola-rs/polars/issues/18130
-                df.index = df.index.tolist()  # type: ignore
-            try:
-                polars_dfs[key] = pl.from_pandas(df)
-            except (pa.ArrowInvalid, ValueError):
-                pass
-        return polars_dfs
+def get_dict_of_polars_test_dfs(N=100, M=100) -> dict[str, Any]:
+    import polars as pl
+    import pyarrow as pa
 
-    return test_dfs
+    polars_dfs = {}
+    for key, df in get_dict_of_test_dfs(N=100, M=100).items():
+        if key == "multiindex":
+            # Since Polars 1.2, pl.from_pandas fails with this error:
+            # ValueError: Pandas dataframe contains non-unique indices and/or column names.
+            # Polars dataframes require unique string names for columns.
+            # See https://github.com/pola-rs/polars/issues/18130
+            df.index = df.index.tolist()  # type: ignore
+        try:
+            polars_dfs[key] = pl.from_pandas(df)
+        except (pa.ArrowInvalid, ValueError):
+            pass
+    return polars_dfs
 
 
-def get_dict_of_test_series(polars=False):
+def get_dict_of_test_series():
     series = {}
     for df_name, df in get_dict_of_test_dfs().items():
         if len(df.columns) > 6:
@@ -311,27 +310,28 @@ def get_dict_of_test_series(polars=False):
             if not isinstance(df[col], pd.Series):
                 continue
             series["{}.{}".format(df_name, col)] = df[col]
+    return series
 
-    if polars:
-        import polars as pl
-        import pyarrow as pa
 
-        polars_series = {}
-        for key in series:
-            try:
-                polars_series[key] = pl.from_pandas(series[key])
-            except (pa.ArrowInvalid, ValueError):
-                pass
+def get_dict_of_polars_test_series():
+    import polars as pl
+    import pyarrow as pa
 
-        # Add a Polar table with unsigned integers
-        # https://github.com/mwouts/itables/issues/192
-        # https://github.com/mwouts/itables/issues/299
-        polars_series["u32"] = pl.Series([1, 2, 5]).cast(pl.UInt32)
-        polars_series["u64"] = pl.Series([1, 2, 2**40]).cast(pl.UInt64)
+    polars_series = {}
+    series = get_dict_of_test_series()
+    for key in series:
+        try:
+            polars_series[key] = pl.from_pandas(series[key])
+        except (pa.ArrowInvalid, ValueError):
+            pass
 
-        return polars_series
+    # Add a Polar table with unsigned integers
+    # https://github.com/mwouts/itables/issues/192
+    # https://github.com/mwouts/itables/issues/299
+    polars_series["u32"] = pl.Series([1, 2, 5]).cast(pl.UInt32)
+    polars_series["u64"] = pl.Series([1, 2, 2**40]).cast(pl.UInt64)
 
-    return series
+    return polars_series
 
 
 @lru_cache()
diff --git a/src/itables/typing.py b/src/itables/typing.py
@@ -69,6 +69,7 @@ class DataTableOptions(TypedDict):
     searchCols: NotRequired[Sequence[Any]]
     initComplete: NotRequired[JavascriptFunction]
     fnInfoCallback: NotRequired[JavascriptFunction]
+    drawCallback: NotRequired[JavascriptFunction]
     stateSave: NotRequired[bool]
     stateDuration: NotRequired[int]
 
diff --git a/tests/test_polars.py b/tests/test_polars.py
@@ -2,7 +2,10 @@
 
 from itables import to_html_datatable
 from itables.javascript import datatables_rows
-from itables.sample_dfs import get_dict_of_test_dfs, get_dict_of_test_series
+from itables.sample_dfs import (
+    get_dict_of_polars_test_dfs,
+    get_dict_of_polars_test_series,
+)
 
 try:
     import polars as pl  # noqa
@@ -11,14 +14,14 @@
 
 
 @pytest.mark.parametrize(
-    "name,x", [(name, x) for name, x in get_dict_of_test_series(polars=True).items()]
+    "name,x", [(name, x) for name, x in get_dict_of_polars_test_series().items()]
 )
 def test_show_polars_series(name, x):
     to_html_datatable(x)
 
 
 @pytest.mark.parametrize(
-    "name,df", [(name, df) for name, df in get_dict_of_test_dfs(polars=True).items()]
+    "name,df", [(name, df) for name, df in get_dict_of_polars_test_dfs().items()]
 )
 def test_show_polars_df(name, df):
     to_html_datatable(df)
