Options#
DataTable Options#
ITables is a wrapper for the Javascript DataTables library, which means that you can use more or less directly the DataTables options from within Python.
Since ITables just maps these options to DataTables, you are invited to have a look at DataTable’s great documentation, and to its huge collection of examples. The DataTable forum can be quite useful as well.
A non-exhaustive list of the DataTable options, together with their expected types, is available at itables.typing.DataTableOptions.
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).
import inspect
import itables
print(inspect.getsource(itables.typing.DataTableOptions))
class DataTableOptions(TypedDict):
"""
This structure provides a non-exhaustive list of options that can be passed
to the DataTable constructor. See https://datatables.net/reference/option/
for the corresponding documentation.
"""
# DataTable options
caption: NotRequired[str]
lengthMenu: NotRequired[
Union[list[Union[int, str, Mapping[str, Any]]], list[list[Union[int, str]]]]
]
order: NotRequired[
Union[list[list[Union[int, str]]], Mapping[str, Union[int, str]]]
]
layout: NotRequired[Mapping[str, Union[None, str, Mapping[str, Any]]]]
columnDefs: NotRequired[list[Mapping[str, Any]]]
paging: NotRequired[bool]
autoWidth: NotRequired[bool]
scrollX: NotRequired[bool]
scrollY: NotRequired[str]
scrollCollapse: NotRequired[bool]
language: NotRequired[Mapping[str, str]]
search: NotRequired[Mapping[str, Any]]
searchCols: NotRequired[list[Any]]
initComplete: NotRequired[JavascriptFunction]
fnInfoCallback: NotRequired[JavascriptFunction]
stateSave: NotRequired[bool]
stateDuration: NotRequired[int]
# DataTable options provided by its extensions
buttons: NotRequired[list[Union[str, Mapping[str, Any]]]]
fixedColumns: NotRequired[Mapping[Literal["left", "right", "start", "end"], int]]
searchPanes: NotRequired[Mapping[str, Any]]
searchBuilder: NotRequired[Mapping[str, Any]]
rowGroup: NotRequired[Mapping[str, Any]]
select: NotRequired[Union[bool, str, Mapping[str, str]]]
keys: NotRequired[bool]
ITable Options#
ITables itself adds a few options like connected, maxBytes, allow_html etc.
The ITable options are documented at itables.typing.ITableOptions:
print(inspect.getsource(itables.typing.ITableOptions))
class ITableOptions(DataTableOptions):
"""
A non-exhaustive list of options that can be passed
to the show function and to the ITable Python classes.
"""
classes: NotRequired[Union[str, list[str]]]
style: NotRequired[Union[str, dict[str, str]]]
selected_rows: NotRequired[list[int]]
showIndex: NotRequired[Union[bool, str]]
maxBytes: NotRequired[Union[int, str]]
maxRows: NotRequired[int]
maxColumns: NotRequired[int]
allow_html: NotRequired[bool]
table_id: NotRequired[str]
dt_url: NotRequired[str]
dt_bundle: NotRequired[Union[str, Path]]
connected: NotRequired[bool]
display_logo_when_loading: NotRequired[bool]
footer: NotRequired[bool]
warn_on_unexpected_types: NotRequired[bool]
warn_on_selected_rows_not_rendered: NotRequired[bool]
warn_on_undocumented_option: NotRequired[bool]
text_in_header_can_be_selected: NotRequired[bool]
column_filters: NotRequired[Literal[False, "header", "footer"]]
use_to_html: NotRequired[bool]
Default values#
Some of the options have a default value set in itables.options. You can change these defaults easily, and even set defauts for the options that don’t have one yet with e.g.
import itables
itables.options.maxBytes = "128KB"
print(inspect.getsource(itables.options))
"""Global options for ITables.
These parameters are documented at
https://mwouts.github.io/itables/advanced_parameters.html
"""
from pathlib import Path
from typing import Literal, Union
import itables.typing as typing
import itables.utils as utils
__non_options = set()
__non_options = set(locals())
"""Table layout, see https://datatables.net/reference/option/layout
NB: to remove a control, replace it by None"""
layout: dict[str, Union[str, None]] = {
"topStart": "pageLength",
"topEnd": "search",
"bottomStart": "info",
"bottomEnd": "paging",
}
"""Show the index? Possible values: True, False and 'auto'. In mode 'auto', the index is not shown
if it has no name and its content is range(N)"""
showIndex: Literal[True, False, "auto"] = "auto"
"""Default DataTables classes. See https://datatables.net/manual/styling/classes"""
classes: Union[str, list[str]] = "display nowrap"
"""Default table style. Use
- 'table-layout:auto' to compute the layout automatically
- 'width:auto' to fit the table width to its content
- 'margin:auto' to center the table.
Combine multiple options using ';'.
NB: When scrollX=true, "margin:auto" is replaced with "margin:0"
to avoid an issue with misaligned headers
"""
style: Union[str, dict[str, str]] = (
"table-layout:auto;width:auto;margin:auto;caption-side:bottom"
)
"""Maximum bytes before downsampling a table"""
maxBytes: Union[str, int] = "64KB"
"""Maximum number of rows or columns before downsampling a table"""
maxRows: int = 0
maxColumns: int = 200
"""By default we don't sort the table"""
order: list[str] = []
"""Authorize, or not, the use of HTML in the table content.
Make sure that you trust the content of your tables before
setting this option to True.
NOTE: This option does not apply to Pandas Styler objects.
For the Style objects the HTML generated by Pandas is used as is,
so you need to make sure that you trust their content.
"""
allow_html: bool = False
"""Optional table footer"""
footer: bool = False
"""Column filters"""
column_filters: Literal[False, "header", "footer"] = False
"""Should a warning appear when we have to encode an unexpected type?"""
warn_on_unexpected_types: bool = True
"""Should a warning appear when the selection targets rows that have been
filtered by the downsampling?"""
warn_on_selected_rows_not_rendered: bool = True
"""The DataTables URL for the connected mode"""
dt_url: str = utils.UNPKG_DT_BUNDLE_URL
"""The DataTable bundle for the offline mode
(this option is for 'init_notebook_mode')"""
dt_bundle: Union[str, Path] = utils.find_package_file("html/dt_bundle.js")
"""Display the ITables animated logo when loading"""
display_logo_when_loading: bool = True
"""Make the text in the table header selectable. When False, clicking
on the column header will sort the table. See #227"""
text_in_header_can_be_selected: bool = True
"""Check that all options passed to ITable are valid and have the expected type."""
warn_on_undocumented_option: bool = typing.is_typeguard_available()
if warn_on_undocumented_option:
typing.check_itable_arguments(
{k: v for k, v in locals().items() if k not in __non_options},
typing.ITableOptions,
)