Document the DataTable and ITable options (#372)

* Document the DataTable and the ITable options
* Enforce pyright within the CI
* Pre-commit autoupdate
* Update Ubuntu and Python action versions
* Require Python 3.9+, stop testing Pandas<1
* Update Copyright years
* Set warn_on_undocumented_option=True only when typeguard is available
* Check the type of the default options
* Add tests on type checks
* Type check only works well with typeguard>=4.4.1 on Python 3.10

Author: mwouts

.github/workflows/continuous-integration.yml

@@ -22,6 +22,27 @@ jobs:
         uses: actions/setup-python@v5
       - uses: pre-commit/[email protected]
 
+  pyright:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          cache: 'pip'
+      - run: |
+          python -m venv .venv
+          source .venv/bin/activate
+          pip install pandas-stubs
+          pip install streamlit
+          pip install -e .[test]
+      - run: echo "$PWD/.venv/bin" >> $GITHUB_PATH
+      - name: Run Pyright
+        uses: jakebailey/pyright-action@v2
+        with:
+          pylance-version: latest-release
+
   codeql:
     runs-on: ubuntu-latest
     permissions:
@@ -40,12 +61,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.7, 3.8, 3.9, "3.10", "3.11", "3.12", "3.13"]
+        python-version: [3.9, "3.10", "3.11", "3.12", "3.13"]
         pandas-version: [latest]
         numpy-version: [latest]
+        typeguard-version: [latest]
         include:
-          - python-version: 3.7
-            pandas-version: '<1.0'
           - python-version: 3.9
             pandas-version: '<2.0'
             numpy-version: '<2.0'
@@ -54,7 +74,11 @@ jobs:
             polars: true
           - python-version: "3.13"
             uninstall_jinja2_and_dash: true
-    runs-on: ubuntu-20.04
+          - python-version: "3.10"
+            typeguard-version: "<4.4.1"
+          - python-version: "3.10"
+            typeguard-version: "<4"
+    runs-on: ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -82,13 +106,15 @@ jobs:
       - name: Install numpy ${{ matrix.numpy-version }}
         if: matrix.numpy-version != 'latest'
         run: pip install 'numpy${{ matrix.numpy-version }}'
+      - name: Install typeguard ${{ matrix.typeguard-version }}
+        if: matrix.typeguard-version != 'latest'
+        run: pip install 'typeguard${{ matrix.typeguard-version }}'
 
       - name: Install polars
         if: matrix.polars
         run: pip install -e .[polars]
 
       - name: Install shiny
-        if: matrix.python-version != '3.7'
         run: pip install "shiny>=1.0"
 
       - name: Uninstall jinja2 and dash

.pre-commit-config.yaml

@@ -5,32 +5,32 @@ exclude: ^src/itables_for_dash/ITable.py$  # auto-generated
 repos:
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
     - id: check-json
     - id: check-yaml
     - id: end-of-file-fixer
     - id: trailing-whitespace
 
   - repo: https://github.com/timothycrosley/isort
-    rev: 5.13.2
+    rev: 6.0.1
     hooks:
     - id: isort
       args: ["--profile", "black", "--filter-files"]
 
   - repo: https://github.com/psf/black
-    rev: 24.4.2
+    rev: 25.1.0
     hooks:
     - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.5
+    rev: v0.11.7
     hooks:
       - id: ruff
         args: ["--fix", "--show-fixes"]
 
   - repo: https://github.com/mwouts/jupytext
-    rev: v1.17.0
+    rev: v1.17.1
     hooks:
     - id: jupytext
       exclude: packages/

README.md

@@ -11,7 +11,7 @@
 [![Dash Component](https://img.shields.io/badge/Dash-Plotly-1098F7.svg?style=flat&logo=Plotly)](https://mwouts.github.io/itables/dash.html)
 [![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_red.svg)](https://itables.streamlit.app)
 
-This packages changes how Pandas and Polars DataFrames are rendered in Jupyter Notebooks.
+This packages changes how Pandas and Polars DataFrames are rendered in Python notebooks and applications.
 With `itables` you can display your tables as interactive [DataTables](https://datatables.net/)
 that you can sort, paginate, scroll or filter.
 
@@ -39,7 +39,7 @@ or
 conda install itables -c conda-forge
 ```
 
-Activate the interactive mode for all series and dataframes with
+Activate the interactive mode for all series and dataframes in Jupyter with
 ```python
 import itables
 

docs/_config.yml

@@ -1,6 +1,6 @@
 title: Interactive Tables
 author: Marc Wouts
-copyright: "2019-2024"
+copyright: "2019-2025"
 logo: "../src/itables/logo/logo.svg"
 execute:
   execute_notebooks: force

docs/changelog.md

@@ -1,6 +1,16 @@
 ITables ChangeLog
 =================
 
+2.4.0-dev
+---------
+
+**Added**
+- We have added type hints for the `show` function and for the various app components. A SyntaxWarning is issued if either the argument name or type does not match when `warn_on_undocumented_option=True` (the default when `typeguard>=4.4.1` is installed).
+
+**Changed**
+- ITable now requires Python 3.9, due to the addition of type hints.
+
+
 2.3.0 (2025-04-05)
 ------------------
 

docs/dash.md

@@ -34,7 +34,7 @@ Listening to the selected rows is simply done by adding `select=True` to the `IT
 
 ## Updating the DataFrame
 
-The `ITable` fonction returns an `ITableComponent` that has many properties. These properties (data, columns, selected rows etc) need to be updated in a consistent way. Therefore we recommend that you list the outputs with `ITableOutputs("my_dataframe")` in your callback, and update them with `updated_itable_outputs` which takes the same arguments as `show`, e.g. `df`, `caption`,`selected_rows`, etc, like in the below (extracted from this [example app](https://github.com/mwouts/itables/tree/main/apps/dash/3_update_table.py)):
+The `ITable` component has many properties. These properties (data, columns, selected rows etc) need to be updated in a consistent way. Therefore we recommend that you list the outputs with `ITableOutputs("my_dataframe")` in your callback, and update them with `updated_itable_outputs` which takes the same arguments as `show`, e.g. `df`, `caption`, `selected_rows`, etc, like in the below (extracted from this [example app](https://github.com/mwouts/itables/tree/main/apps/dash/3_update_table.py)):
 
 ```python
 from itables.dash import ITable, ITableOutputs, updated_itable_outputs

docs/quick_start.md

@@ -27,7 +27,7 @@ kernelspec:
 <a class="github-button" href="https://github.com/mwouts/itables" data-icon="octicon-star" data-show-count="true"></a>
 <script src="https://buttons.github.io/buttons.js"></script>
 
-This packages changes how Pandas and Polars DataFrames are rendered in Jupyter Notebooks.
+This packages changes how Pandas and Polars DataFrames are rendered in Python notebooks and applications.
 With `itables` you can display your tables as interactive [DataTables](https://datatables.net/)
 that you can sort, paginate, scroll or filter.
 

environment.yml

@@ -18,6 +18,8 @@ dependencies:
   - pytest-xdist
   - pytest-cov
   - pre-commit
+  - pyright
+  - typeguard
   - pip
   - setuptools
   - twine

packages/dt_for_itables/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Marc Wouts
+Copyright (c) 2024-2025 Marc Wouts
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

pyproject.toml

@@ -18,24 +18,23 @@ classifiers = [
   "Intended Audience :: Science/Research",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.7",
-  "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
 ]
-requires-python = ">= 3.7"
+requires-python = ">= 3.9"
 dependencies = ["IPython", "pandas", "numpy"]
 dynamic = ["version"]
 
 [project.optional-dependencies]
 polars = ["polars", "pyarrow"]
+check_type = ["typeguard>=4.4.1"]
 style = ["matplotlib"]
 samples = ["pytz", "world_bank_data"]
 widget = ["anywidget", "traitlets"]
-all = ["itables[polars,style,samples,widget]"]
+all = ["itables[polars,style,samples,widget,check_type]"]
 test = [
   "itables[all]",
   # Pytest