0
# ITables
1

2
ITables is a Python library that transforms Pandas and Polars DataFrames into interactive DataTables with sorting, pagination, scrolling, and filtering capabilities. It provides a minimal-dependency solution that works across all major Jupyter environments and extends to multiple application frameworks including Dash, Streamlit, Shiny, and Jupyter Widgets.
3

4
## Package Information
5

6
- **Package Name**: itables
7
- **Language**: Python
8
- **Installation**: `pip install itables`
9
- **Dependencies**: IPython, pandas, numpy (core)
10
- **Optional Dependencies**: polars, streamlit, dash, shiny, anywidget (for specific features)
11

12
## Core Imports
13

14
```python
15
import itables
16
```
17

18
Common usage patterns:
19

20
```python
21
from itables import show, init_notebook_mode
22
import itables.options as opts
23
```
24

25
For specific framework integrations:
26

27
```python
28
from itables.streamlit import interactive_table
29
from itables.shiny import DT, init_itables
30
from itables.dash import ITable
31
from itables.widget import ITable as WidgetITable
32
```
33

34
## Basic Usage
35

36
```python
37
import pandas as pd
38
from itables import show, init_notebook_mode
39

40
# Initialize interactive mode for all DataFrames
41
init_notebook_mode()
42

43
# Create sample data
44
df = pd.DataFrame({
45
    'Name': ['Alice', 'Bob', 'Charlie', 'David'],
46
    'Age': [25, 30, 35, 28],
47
    'City': ['New York', 'London', 'Tokyo', 'Paris']
48
})
49

50
# Display as interactive table
51
show(df)
52

53
# Or get HTML representation
54
html = itables.to_html_datatable(df, caption="Sample Data")
55
```
56

57
Configuration example:
58

59
```python
60
import itables.options as opts
61

62
# Configure global options
63
opts.classes = "display compact"
64
opts.maxRows = 1000
65
opts.column_filters = "header"
66

67
# Show DataFrame with custom options
68
show(df, pageLength=25, scrollX=True)
69
```
70

71
## Architecture
72

73
ITables follows a modular architecture with clear separation of concerns:
74

75
- **Core Engine**: HTML/JavaScript generation for DataTables integration
76
- **Framework Extensions**: Specialized components for different application frameworks
77
- **Configuration System**: Flexible options management with file-based configuration support
78
- **Data Processing**: Automatic downsampling and type handling for large datasets
79

80
The library serves as an adapter between Python DataFrame libraries (Pandas/Polars) and the DataTables.net JavaScript library, providing seamless interactive table functionality without requiring JavaScript knowledge.
81

82
## Capabilities
83

84
### Core Display Functions
85

86
Primary functions for rendering DataFrames as interactive tables in Jupyter environments, with support for both connected (online) and offline modes.
87

88
```python { .api }
89
def show(df, caption=None, **kwargs):
90
    """Render DataFrame as interactive datatable in Jupyter environments"""
91

92
def to_html_datatable(df, caption=None, **kwargs):
93
    """Return HTML representation of DataFrame as interactive datatable"""
94

95
def init_notebook_mode(all_interactive=True, connected=False, dt_bundle=None):
96
    """Load DataTables library and activate interactive mode for all DataFrames"""
97
```
98

99
[Core Display Functions](./core-display.md)
100

101
### Configuration Management
102

103
Comprehensive configuration system supporting both programmatic and file-based configuration, with validation and type checking capabilities.
104

105
```python { .api }
106
# Configuration variables (all configurable)
107
layout: dict  # Table layout configuration
108
showIndex: str | bool  # Whether to show DataFrame index
109
classes: str | list  # CSS classes for styling
110
maxBytes: str | int  # Maximum bytes before downsampling
111
maxRows: int  # Maximum rows before downsampling
112
column_filters: str | bool  # Column filtering UI location
113
```
114

115
[Configuration Management](./configuration.md)
116

117
### Framework Extensions
118

119
Specialized components and functions for integrating interactive tables into various Python application frameworks.
120

121
```python { .api }
122
# Streamlit integration
123
def interactive_table(df, key=None, caption=None, **kwargs):
124
    """Render DataFrame as interactive table in Streamlit applications"""
125

126
# Shiny integration  
127
def DT(df, caption=None, **kwargs):
128
    """Render DataFrame as interactive table in Shiny applications"""
129

130
# Dash component
131
class ITable:
132
    """Dash component for interactive tables"""
133

134
# Jupyter Widget
135
class ITable:
136
    """AnyWidget-based interactive table widget"""
137
```
138

139
[Framework Extensions](./framework-extensions.md)
140

141
### Data Processing and Utilities
142

143
Utilities for data handling, downsampling, sample data generation, and type processing to ensure optimal table performance.
144

145
```python { .api }
146
def downsample(df, max_rows=0, max_columns=0, max_bytes=0):
147
    """Downsample DataFrame to fit size limits"""
148

149
# Sample data functions
150
def get_countries(html=False, climate_zone=False):
151
    """Return DataFrame with world countries data"""
152

153
def generate_random_df(rows, columns, column_types=None):
154
    """Generate random DataFrame with specified dimensions"""
155
```
156

157
[Data Processing and Utilities](./data-utilities.md)
158

159
### Type System
160

161
Comprehensive type definitions for configuration options, JavaScript integration, and DataFrame compatibility across Pandas and Polars.
162

163
```python { .api }
164
# Type aliases and classes
165
DataFrameOrSeries = Any  # Union of supported DataFrame/Series types
166
class JavascriptFunction(str):  # JavaScript function wrapper
167
class JavascriptCode(str):  # JavaScript code wrapper
168
class ITableOptions(TypedDict):  # Configuration options
169
```
170

171
[Type System](./type-system.md)