ITables can use an itables.toml configuration file

Author: mwouts

.github/workflows/continuous-integration.yml

@@ -30,6 +30,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
+          python-version: '3.13'
           cache: 'pip'
       - run: |
           python -m venv .venv

docs/changelog.md

@@ -9,6 +9,7 @@ ITables ChangeLog
 
 **Added**
 - We have added the `columnControl` extension that was recently added to DataTables ([blog post](https://datatables.net/blog/2025/columncontrol)) ([#403](https://github.com/mwouts/itables/issues/403))
+- The default options can be set through an `itables.toml` configuration file, either in the current or in a parent folder ([#429](https://github.com/mwouts/itables/issues/429))
 
 **Changed**
 - We have changed the default value of the `html` argument in `itables.sample_dfs.get_countries`. It now defaults to `False`, in which case the example dataframes contains no HTML code.

docs/options/buttons.md

@@ -35,10 +35,16 @@ the location of the buttons (the default is `layout={"topStart": "buttons"}`). A
 
 As always, it is possible to set default values for these parameters by setting these on `itables.options`. For instance, set
 ```python
-itables.options.buttons = ["copyHtml5", "csvHtml5", "excelHtml5"]
+itables.options.buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"]
 ```
 to get the buttons for all your tables.
 
+You can also add
+```
+buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"]
+```
+to your `itables.toml` configuration file.
+
 
 By default, the exported file name is the name of the HTML page. To change it, set a
 [`title` option](https://datatables.net/extensions/buttons/examples/html5/filename.html) on the buttons, like

docs/options/classes.md

@@ -45,3 +45,10 @@ itables.show(df, classes="display")
 
 itables.show(df, classes="display nowrap cell-border")
 ```
+
+```tip
+You can change the default for all your notebooks and apps by creating an `itables.toml` file in the current or a parent directory, with e.g. this content:
+~~~
+classes = ["display", "nowrap", "compact"]
+~~~
+```

docs/options/column_control.md

@@ -72,3 +72,17 @@ itables.show(
     ordering={"indicators": False, "handler": False},
 )
 ```
+
+As usual, you can make this the default by either setting `itables.options.columnControl` in your notebook or application, or by adding this to your `itables.toml` configuration file:
+```
+[[columnControl]]
+target = 0
+content = ["order"]
+[[columnControl]]
+target = "tfoot"
+content = ["search"]
+
+[ordering]
+indicators = false
+handler = false
+```

docs/options/options.md

@@ -16,50 +16,61 @@ kernelspec:
 
 ## DataTable Options
 
-ITables is a wrapper for the Javascript DataTables library, which means that you can use more or less directly the DataTables [options](https://datatables.net/options) from within Python.
+ITables is a wrapper for the JavaScript DataTables library, which means you can often use DataTables [options](https://datatables.net/options) directly within ITables.
 
-Since ITables just maps these options to DataTables, you are invited to have a look at DataTable's great [documentation](https://datatables.net/), and to its huge collection of [examples](https://datatables.net/examples/index). The DataTable [forum](https://datatables.net/forums/) can be quite useful as well.
+Since ITables simply maps these options to DataTables, we encourage you to consult DataTables’ excellent [documentation](https://datatables.net/) and its extensive collection of [examples](https://datatables.net/examples/index). The DataTables [forum](https://datatables.net/forums/) can also be quite helpful.
 
-A non-exhaustive list of the DataTable options, together with their expected types, is available at [`itables.typing.DataTableOptions`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py).
+A non-exhaustive list of DataTables options, along with their expected types, is provided by `DataTableOptions` in [`itables.typing`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py).
 
-Option names and types are checked by default at run time when `typeguard>=4.4.1` is installed - you can deactivate this by setting `warn_on_undocumented_option=False`.
+## ITable Options
+
+ITables adds a few options of its own, such as `connected`, `maxBytes`, `allow_html`, and others. An exhaustive list of these additional options is provided by `ITableOptions` in [`itables.typing`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py).
+
+## Default Values
 
-If you see an option that you find useful and is not documented, or a type hint that is incorrect, please make a PR (and add an example to the documentation, too).
+The default values for these options are set in [`itables.options`](https://github.com/mwouts/itables/blob/main/src/itables/options.py). These defaults are used in each call to `to_html_datatable`, `show`, or `ITable`, unless a corresponding option is set locally—in which case, the local value takes precedence.
 
-```{code-cell} ipython3
-:tags: [scroll-output]
+## Changing the Defaults
 
-import inspect
+You can change the default options in your notebook or application with:
 
+```python
 import itables
 
-print(inspect.getsource(itables.typing.DataTableOptions))
+itables.options.maxBytes = "128KB"
 ```
 
-## ITable Options
-
-ITables itself adds a few options like `connected`, `maxBytes`, `allow_html` etc.
+## Configuration File
 
-The ITable options are documented at [`itables.typing.ITableOptions`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py):
+Since v2.5.0, ITable can load its default options from a configuration file. The configuration file is identified using `get_config_file` from [`itables.config`](https://github.com/mwouts/itables/blob/main/src/itables/config.py). It can be:
 
-```{code-cell} ipython3
-:tags: [scroll-output]
+- The file pointed to by the environment variable `ITABLES_CONFIG`, if set and non-empty (if the variable is an empty string, no configuration file is used)
+- An `itables.toml` file in the current or a parent directory
+- A `tool.itables` section in a `pyproject.toml` file in the current or a parent directory
 
-print(inspect.getsource(itables.typing.ITableOptions))
+A sample configuration file could look like this:
+```
+# itables.toml
+classes = ["display", "nowrap", "compact"]
+buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"]
 ```
 
-## Default values
-
-Some of the options have a default value set in [`itables.options`](https://github.com/mwouts/itables/blob/main/src/itables/options.py). You can change these defaults easily, and even set defauts for the options that don't have one yet with e.g.
-
-```python
-import itables
-
-itables.options.maxBytes = "128KB"
+Add this to use the [column control](column_control.md) extension:
+```
+[[columnControl]]
+target = 0
+content = ["order"]
+[[columnControl]]
+target = "tfoot"
+content = ["search"]
+
+[ordering]
+indicators = false
+handler = false
 ```
 
-```{code-cell} ipython3
-:tags: [scroll-output]
+## Option Names and Type Checks
 
-print(inspect.getsource(itables.options))
-```
+Option names and types are checked by default at runtime when `typeguard>=4.4.1` is installed. You can disable this by setting `warn_on_undocumented_option=False`.
+
+If you find an option that is useful but undocumented, or if you notice an incorrect type hint, please submit a PR (and consider adding an example to the documentation, too).

docs/py/options/buttons.py

@@ -36,10 +36,16 @@
 #
 # As always, it is possible to set default values for these parameters by setting these on `itables.options`. For instance, set
 # ```python
-# itables.options.buttons = ["copyHtml5", "csvHtml5", "excelHtml5"]
+# itables.options.buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"]
 # ```
 # to get the buttons for all your tables.
 #
+# You can also add
+# ```
+# buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"]
+# ```
+# to your `itables.toml` configuration file.
+#
 #
 # By default, the exported file name is the name of the HTML page. To change it, set a
 # [`title` option](https://datatables.net/extensions/buttons/examples/html5/filename.html) on the buttons, like

docs/py/options/classes.py

@@ -41,3 +41,11 @@
 
 # %% tags=["full-width"]
 itables.show(df, classes="display nowrap cell-border")
+
+# %% [markdown]
+# ```tip
+# You can change the default for all your notebooks and apps by creating an `itables.toml` file in the current or a parent directory, with e.g. this content:
+# ~~~
+# classes = ["display", "nowrap", "compact"]
+# ~~~
+# ```

docs/py/options/column_control.py

@@ -72,3 +72,18 @@
     ],
     ordering={"indicators": False, "handler": False},
 )
+
+# %% [markdown]
+# As usual, you can make this the default by either setting `itables.options.columnControl` in your notebook or application, or by adding this to your `itables.toml` configuration file:
+# ```
+# [[columnControl]]
+# target = 0
+# content = ["order"]
+# [[columnControl]]
+# target = "tfoot"
+# content = ["search"]
+#
+# [ordering]
+# indicators = false
+# handler = false
+# ```

docs/py/options/options.py

@@ -1,7 +1,6 @@
 # ---
 # jupyter:
 #   jupytext:
-#     default_lexer: ipython3
 #     formats: docs///md:myst,docs/py///py:percent
 #     notebook_metadata_filter: -jupytext.text_representation.jupytext_version
 #     text_representation:
@@ -19,43 +18,61 @@
 #
 # ## DataTable Options
 #
-# ITables is a wrapper for the Javascript DataTables library, which means that you can use more or less directly the DataTables [options](https://datatables.net/options) from within Python.
+# ITables is a wrapper for the JavaScript DataTables library, which means you can often use DataTables [options](https://datatables.net/options) directly within ITables.
 #
-# Since ITables just maps these options to DataTables, you are invited to have a look at DataTable's great [documentation](https://datatables.net/), and to its huge collection of [examples](https://datatables.net/examples/index). The DataTable [forum](https://datatables.net/forums/) can be quite useful as well.
+# Since ITables simply maps these options to DataTables, we encourage you to consult DataTables’ excellent [documentation](https://datatables.net/) and its extensive collection of [examples](https://datatables.net/examples/index). The DataTables [forum](https://datatables.net/forums/) can also be quite helpful.
 #
-# A non-exhaustive list of the DataTable options, together with their expected types, is available at [`itables.typing.DataTableOptions`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py).
+# A non-exhaustive list of DataTables options, along with their expected types, is provided by `DataTableOptions` in [`itables.typing`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py).
 #
-# Option names and types are checked by default at run time when `typeguard>=4.4.1` is installed - you can deactivate this by setting `warn_on_undocumented_option=False`.
-#
-# If you see an option that you find useful and is not documented, or a type hint that is incorrect, please make a PR (and add an example to the documentation, too).
-
-# %% tags=["scroll-output"]
-import inspect
-
-import itables
-
-print(inspect.getsource(itables.typing.DataTableOptions))
-
-# %% [markdown]
 # ## ITable Options
 #
-# ITables itself adds a few options like `connected`, `maxBytes`, `allow_html` etc.
+# ITables adds a few options of its own, such as `connected`, `maxBytes`, `allow_html`, and others. An exhaustive list of these additional options is provided by `ITableOptions` in [`itables.typing`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py).
 #
-# The ITable options are documented at [`itables.typing.ITableOptions`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py):
-
-# %% tags=["scroll-output"]
-print(inspect.getsource(itables.typing.ITableOptions))
-
-# %% [markdown]
-# ## Default values
+# ## Default Values
+#
+# The default values for these options are set in [`itables.options`](https://github.com/mwouts/itables/blob/main/src/itables/options.py). These defaults are used in each call to `to_html_datatable`, `show`, or `ITable`, unless a corresponding option is set locally—in which case, the local value takes precedence.
 #
-# Some of the options have a default value set in [`itables.options`](https://github.com/mwouts/itables/blob/main/src/itables/options.py). You can change these defaults easily, and even set defauts for the options that don't have one yet with e.g.
+# ## Changing the Defaults
+#
+# You can change the default options in your notebook or application with:
 #
 # ```python
 # import itables
 #
 # itables.options.maxBytes = "128KB"
 # ```
-
-# %% tags=["scroll-output"]
-print(inspect.getsource(itables.options))
+#
+# ## Configuration File
+#
+# Since v2.5.0, ITable can load its default options from a configuration file. The configuration file is identified using `get_config_file` from [`itables.config`](https://github.com/mwouts/itables/blob/main/src/itables/config.py). It can be:
+#
+# - The file pointed to by the environment variable `ITABLES_CONFIG`, if set and non-empty (if the variable is an empty string, no configuration file is used)
+# - An `itables.toml` file in the current or a parent directory
+# - A `tool.itables` section in a `pyproject.toml` file in the current or a parent directory
+#
+# A sample configuration file could look like this:
+# ```
+# # itables.toml
+# classes = ["display", "nowrap", "compact"]
+# buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"]
+# ```
+#
+# Add this to use the [column control](column_control.md) extension:
+# ```
+# [[columnControl]]
+# target = 0
+# content = ["order"]
+# [[columnControl]]
+# target = "tfoot"
+# content = ["search"]
+#
+# [ordering]
+# indicators = false
+# handler = false
+# ```
+#
+# ## Option Names and Type Checks
+#
+# Option names and types are checked by default at runtime when `typeguard>=4.4.1` is installed. You can disable this by setting `warn_on_undocumented_option=False`.
+#
+# If you find an option that is useful but undocumented, or if you notice an incorrect type hint, please submit a PR (and consider adding an example to the documentation, too).