0
# Configuration Management
1
2
Comprehensive configuration system for ITables supporting both programmatic and file-based configuration. The system provides default values, validation, type checking, and flexible customization options for all table display parameters.
3
4
## Capabilities
5
6
### Global Options Module
7
8
Central configuration module containing all configurable options with sensible defaults. All options can be modified at runtime to affect subsequent table displays.
9
10
```python { .api }
11
# Import options module
12
import itables.options as opts
13
14
# Layout configuration
15
opts.layout: dict # Table layout specification (topStart, topEnd, bottomStart, bottomEnd)
16
17
# Display options
18
opts.showIndex: str | bool # Index display control ("auto", True, False)
19
opts.classes: str | list # CSS classes for table styling
20
opts.style: str | dict # CSS styles for table appearance
21
22
# Data limits and downsampling
23
opts.maxBytes: str | int # Maximum data size before downsampling ("64KB")
24
opts.maxRows: int # Maximum rows before downsampling (0 = unlimited)
25
opts.maxColumns: int # Maximum columns before downsampling (200)
26
27
# Table features
28
opts.column_filters: str | bool # Column filtering location (False, "header", "footer")
29
opts.footer: bool # Show table footer
30
opts.allow_html: bool # Allow HTML content in cells
31
32
# Behavior options
33
opts.warn_on_unexpected_types: bool # Warning for unexpected data types
34
opts.warn_on_selected_rows_not_rendered: bool # Warning for selection issues
35
opts.display_logo_when_loading: bool # Show ITables logo during loading
36
opts.text_in_header_can_be_selected: bool # Make header text selectable
37
38
# DataTables library configuration
39
opts.dt_url: str # DataTables JavaScript bundle URL for connected mode
40
opts.dt_bundle: str | Path # Local DataTables bundle path for offline mode
41
```
42
43
### Configuration File Management
44
45
Functions for loading and managing configuration from TOML files, supporting both dedicated ITables config files and pyproject.toml integration.
46
47
```python { .api }
48
def get_config_file(path=None):
49
"""
50
Find ITables configuration file.
51
52
Parameters:
53
- path (Path, optional): Starting directory for search (default: current directory)
54
55
Returns:
56
Path | None: Path to config file if found, None otherwise
57
58
Search order:
59
1. ITABLES_CONFIG environment variable path
60
2. itables.toml in current/parent directories
61
3. tool.itables section in pyproject.toml
62
4. itables.toml in user config directory
63
"""
64
65
def load_config_file(config_file):
66
"""
67
Load and validate configuration from TOML file.
68
69
Parameters:
70
- config_file (Path): Path to configuration file
71
72
Returns:
73
dict: Validated configuration options
74
75
Raises:
76
ImportError: If tomllib/tomli not available
77
ValueError: If file contains invalid configuration
78
"""
79
80
def set_options_from_config_file(options):
81
"""
82
Apply configuration file settings to options dictionary.
83
84
Parameters:
85
- options (dict): Options dictionary to update
86
87
Returns:
88
None (modifies options in-place)
89
"""
90
```
91
92
### Configuration Display
93
94
Utility for displaying current configuration file location and contents, useful for debugging configuration issues.
95
96
```python { .api }
97
def show_config(path):
98
"""
99
Display ITables configuration file location and content.
100
101
Parameters:
102
- path (Path): Directory to search for config file
103
104
Returns:
105
None (prints configuration information)
106
"""
107
```
108
109
## Configuration Options Reference
110
111
### Layout and Appearance
112
113
```python
114
# Table layout (DataTables layout option)
115
opts.layout = {
116
"topStart": "pageLength", # Page length selector position
117
"topEnd": "search", # Search box position
118
"bottomStart": "info", # Info text position
119
"bottomEnd": "paging" # Pagination controls position
120
}
121
122
# CSS styling
123
opts.classes = "display nowrap" # Space-separated CSS classes
124
opts.style = "table-layout:auto;width:auto;margin:auto;caption-side:bottom"
125
126
# Index display control
127
opts.showIndex = "auto" # "auto": hide if unnamed RangeIndex, True/False: force show/hide
128
```
129
130
### Data Processing
131
132
```python
133
# Size limits for automatic downsampling
134
opts.maxBytes = "64KB" # String format: "64KB", "1MB" or integer bytes
135
opts.maxRows = 0 # 0 = unlimited, positive integer = row limit
136
opts.maxColumns = 200 # Column limit before downsampling
137
138
# Default sorting (empty = no sorting)
139
opts.order = [] # List of [column_index, "asc"/"desc"] pairs
140
```
141
142
### Table Features
143
144
```python
145
# Interactive features
146
opts.column_filters = False # False, "header", or "footer"
147
opts.footer = False # Show table footer
148
opts.allow_html = False # Allow HTML in table cells (security risk)
149
150
# Behavioral options
151
opts.warn_on_unexpected_types = True # Warn about unexpected data types
152
opts.warn_on_selected_rows_not_rendered = True # Warn about selection issues
153
opts.display_logo_when_loading = True # Show ITables logo while loading
154
opts.text_in_header_can_be_selected = True # Allow header text selection
155
```
156
157
### DataTables Integration
158
159
```python
160
# Library loading configuration
161
opts.dt_url = "https://www.unpkg.com/dt_for_itables@2.4.0/dt_bundle.js"
162
opts.dt_bundle = Path("html/dt_bundle.js") # Local bundle for offline mode
163
```
164
165
## Usage Examples
166
167
### Programmatic Configuration
168
169
```python
170
import itables.options as opts
171
172
# Modify global options
173
opts.classes = "display compact stripe"
174
opts.pageLength = 25
175
opts.column_filters = "header"
176
opts.maxRows = 1000
177
178
# These settings affect all subsequent show() calls
179
from itables import show
180
show(df) # Uses updated options
181
```
182
183
### Per-Display Configuration
184
185
```python
186
# Override options for specific display
187
show(df,
188
pageLength=50, # Override global pageLength
189
scrollX=True, # Enable horizontal scrolling
190
classes="display hover") # Override global classes
191
```
192
193
### File-Based Configuration
194
195
Create `itables.toml`:
196
197
```toml
198
classes = "display compact"
199
pageLength = 20
200
column_filters = "header"
201
maxRows = 2000
202
showIndex = false
203
display_logo_when_loading = false
204
```
205
206
Or add to `pyproject.toml`:
207
208
```toml
209
[tool.itables]
210
classes = "display compact"
211
pageLength = 20
212
column_filters = "header"
213
```
214
215
### Environment Variable Configuration
216
217
```bash
218
# Use specific config file
219
export ITABLES_CONFIG="/path/to/custom/itables.toml"
220
221
# Disable config file loading
222
export ITABLES_CONFIG=""
223
```
224
225
### Configuration Inspection
226
227
```python
228
from itables.show_config import show_config
229
from pathlib import Path
230
231
# Display current configuration
232
show_config(Path.cwd())
233
```
234
235
## Advanced Configuration
236
237
### Custom Layout
238
239
```python
240
# Custom DataTables layout
241
opts.layout = {
242
"topStart": "buttons", # Export buttons
243
"topEnd": "search",
244
"bottomStart": None, # Remove info display
245
"bottomEnd": "paging"
246
}
247
```
248
249
### DataTables Extension Options
250
251
```python
252
# DataTables native options can be passed through
253
show(df,
254
buttons=['copy', 'csv', 'excel'], # Export buttons
255
fixedColumns={'left': 1}, # Fix first column
256
searchPanes={'cascadePanes': True}, # Search panes
257
select={'style': 'multi'}) # Multi-row selection
258
```
259
260
### Validation and Type Checking
261
262
```python
263
# Enable strict validation (requires typeguard package)
264
opts.warn_on_undocumented_option = True
265
opts.warn_on_unexpected_option_type = True
266
267
# This will warn about unknown or incorrectly typed options
268
show(df, unknown_option=True) # Triggers warning
269
```