0
# Configuration and Options
1

2
Pandas configuration system for controlling display options, computational behavior, and library-wide settings.
3

4
## Core Imports
5

6
```python
7
import pandas as pd
8
from pandas import get_option, set_option, reset_option, option_context
9
```
10

11
## Capabilities
12

13
### Option Management
14

15
Core functions for getting, setting, and managing pandas configuration options.
16

17
```python { .api }
18
def get_option(pat):
19
    """
20
    Retrieve the value of the specified option.
21
    
22
    Parameters:
23
    - pat: str, regexp pattern for option name
24
    
25
    Returns:
26
    object, option value
27
    """
28

29
def set_option(pat, value):
30
    """
31
    Set the value of the specified option.
32
    
33
    Parameters:
34
    - pat: str, regexp pattern for option name
35
    - value: object, new value for option
36
    """
37

38
def reset_option(pat):
39
    """
40
    Reset one or more options to their default value.
41
    
42
    Parameters:
43
    - pat: str, regexp pattern for option name(s) to reset
44
    """
45

46
def describe_option(pat, _print_desc=False):
47
    """
48
    Print available options and their descriptions.
49
    
50
    Parameters:
51
    - pat: str, regexp pattern for option name(s) to describe
52
    - _print_desc: bool, whether to print descriptions
53
    
54
    Returns:
55
    str or None, option descriptions
56
    """
57

58
def option_context(*args):
59
    """
60
    Context manager to temporarily set options.
61
    
62
    Parameters:
63
    - args: pairs of (option_name, option_value)
64
    
65
    Usage:
66
    with pd.option_context('display.max_rows', 100):
67
        # Temporary setting active here
68
        pass
69
    # Setting reverted after context
70
    """
71

72
# Access options registry directly
73
options: object  # Configuration options registry object
74
```
75

76
### Display Options
77

78
Configuration options controlling how pandas objects are displayed.
79

80
```python { .api }
81
# Display formatting options (accessed via get_option/set_option):
82

83
# General display
84
'display.chop_threshold'  # float, threshold for displaying small numbers as zero
85
'display.colheader_justify'  # str, column header alignment ('left', 'right')
86
'display.date_dayfirst'  # bool, interpret ambiguous dates as dayfirst
87
'display.date_yearfirst'  # bool, interpret ambiguous dates as yearfirst
88
'display.encoding'  # str, character encoding to use for display
89
'display.expand_frame_repr'  # bool, allow DataFrame repr to span multiple lines
90
'display.float_format'  # callable, function to format floats
91
'display.large_repr'  # str, display format for large frames ('truncate' or 'info')
92
'display.latex.escape'  # bool, escape special characters in LaTeX output
93
'display.latex.longtable'  # bool, use longtable format for LaTeX output
94
'display.latex.multicolumn'  # bool, use multicolumn format for LaTeX output
95
'display.latex.multicolumn_format'  # str, alignment for multicolumn LaTeX format
96
'display.latex.multirow'  # bool, use multirow format for LaTeX output
97
'display.latex.repr'  # bool, use LaTeX formatting for repr
98
'display.max_categories'  # int, maximum categories to display for categorical columns
99
'display.max_columns'  # int, maximum columns to display
100
'display.max_colwidth'  # int, maximum column width in characters
101
'display.max_info_columns'  # int, maximum columns for DataFrame.info()
102
'display.max_info_rows'  # int, maximum rows for DataFrame.info()
103
'display.max_rows'  # int, maximum rows to display
104
'display.max_seq_items'  # int, maximum sequence items to display
105
'display.memory_usage'  # str, memory usage display ('deep' or None)
106
'display.min_rows'  # int, minimum rows to display when truncating
107
'display.multi_sparse'  # bool, sparsify multi-index display
108
'display.notebook_repr_html'  # bool, use HTML repr in Jupyter notebooks
109
'display.pprint_nest_depth'  # int, nesting depth for pretty printing
110
'display.precision'  # int, floating point precision for display
111
'display.show_dimensions'  # bool, display DataFrame dimensions
112
'display.unicode.ambiguous_as_wide'  # bool, use ambiguous Unicode characters
113
'display.unicode.east_asian_width'  # bool, use East Asian character widths
114
'display.width'  # int, display width in characters
115

116
# HTML specific options
117
'display.html.border'  # int, border attribute for HTML table tags
118
'display.html.table_schema'  # bool, use table schema extension for HTML
119
'display.html.use_mathjax'  # bool, use MathJax for mathematical notation
120

121
# Styling options  
122
'styler.format.decimal'  # str, decimal separator for Styler formatting
123
'styler.format.escape'  # str, escape method for Styler ('html', 'latex', None)
124
'styler.format.formatter'  # dict, default formatters for Styler
125
'styler.format.na_rep'  # str, representation for missing values in Styler
126
'styler.format.precision'  # int, precision for Styler numeric formatting
127
'styler.format.thousands'  # str, thousands separator for Styler
128
'styler.html.mathjax'  # bool, use MathJax for mathematical notation in Styler
129
'styler.latex.environment'  # str, LaTeX environment for Styler ('longtable', 'tabular')
130
'styler.latex.hrules'  # bool, add horizontal rules in LaTeX Styler
131
'styler.latex.multicol_align'  # str, multicolumn alignment for LaTeX Styler
132
'styler.latex.multirow_align'  # str, multirow alignment for LaTeX Styler
133
'styler.render.encoding'  # str, encoding for Styler rendering
134
'styler.render.max_columns'  # int, maximum columns for Styler rendering
135
'styler.render.max_elements'  # int, maximum elements for Styler rendering
136
'styler.render.max_rows'  # int, maximum rows for Styler rendering
137
'styler.render.repr'  # str, representation method for Styler ('html', 'latex')
138
'styler.sparse.columns'  # bool, sparsify column MultiIndex in Styler
139
'styler.sparse.index'  # bool, sparsify row MultiIndex in Styler
140
```
141

142
### Computational Options
143

144
Configuration options affecting pandas computational behavior.
145

146
```python { .api }
147
# Computational behavior options:
148

149
'compute.use_bottleneck'  # bool, use bottleneck library for numerical operations
150
'compute.use_numexpr'  # bool, use numexpr library for expression evaluation
151
'compute.use_numba'  # bool, use numba library for acceleration
152

153
# Mode options
154
'mode.chained_assignment'  # str, behavior for chained assignment ('raise', 'warn', None)
155
'mode.copy_on_write'  # bool, enable copy-on-write mode
156
'mode.data_manager'  # str, internal data manager to use (deprecated)
157
'mode.sim_interactive'  # bool, simulate interactive mode for testing
158
'mode.string_storage'  # str, default storage for StringDtype ('python', 'pyarrow')
159
'mode.use_inf_as_na'  # bool, treat inf/-inf as NA in computations
160

161
# Future warnings
162
'future.infer_string'  # bool, enable string inference in future pandas version
163
'future.no_silent_downcasting'  # bool, disable silent downcasting in future
164

165
# I/O options
166
'io.common.default_buffer_size'  # int, default buffer size for I/O operations  
167
'io.excel.ods.reader'  # str, default engine for reading ODS files
168
'io.excel.ods.writer'  # str, default engine for writing ODS files
169
'io.excel.xls.reader'  # str, default engine for reading XLS files
170
'io.excel.xls.writer'  # str, default engine for writing XLS files
171
'io.excel.xlsb.reader'  # str, default engine for reading XLSB files
172
'io.excel.xlsm.reader'  # str, default engine for reading XLSM files
173
'io.excel.xlsm.writer'  # str, default engine for writing XLSM files
174
'io.excel.xlsx.reader'  # str, default engine for reading XLSX files
175
'io.excel.xlsx.writer'  # str, default engine for writing XLSX files
176
'io.hdf.default_format'  # str, default HDF5 format ('table' or 'fixed')
177
'io.hdf.dropna_table'  # bool, drop NaN values when writing HDF5 table format
178
'io.parquet.engine'  # str, default engine for parquet ('auto', 'pyarrow', 'fastparquet')
179
'io.sql.engine'  # str, default engine for SQL operations ('auto')
180

181
# Plotting options
182
'plotting.backend'  # str, plotting backend to use ('matplotlib')
183
'plotting.matplotlib.register_converters'  # bool, register pandas converters with matplotlib
184
```
185

186
### Advanced Configuration
187

188
Functions for advanced configuration management and option introspection.
189

190
```python { .api }
191
def show_versions(as_json=False):
192
    """
193
    Provide useful information about pandas and the system.
194
    
195
    Parameters:
196
    - as_json: bool, return information as JSON string
197
    
198
    Returns:
199
    None or str, version information
200
    """
201

202
# Configuration state functions  
203
def using_copy_on_write():
204
    """
205
    Return whether copy-on-write is enabled.
206
    
207
    Returns:
208
    bool, True if copy-on-write mode is enabled
209
    """
210

211
def using_nullable_dtypes():
212
    """
213
    Return whether nullable dtypes are the default.
214
    
215
    Returns:
216
    bool, True if nullable dtypes are default
217
    """
218

219
def using_string_dtype():
220
    """
221
    Return whether string dtype inference is enabled.
222
    
223
    Returns:
224
    bool, True if string dtype inference is enabled
225
    """
226

227
# Custom formatting functions
228
def set_eng_float_format(accuracy=3, use_eng_prefix=False):
229
    """
230
    Format float representation to engineering format.
231
    
232
    Parameters:
233
    - accuracy: int, number of decimal places
234
    - use_eng_prefix: bool, use engineering prefix (k, M, G, etc.)
235
    """
236
```
237

238
### Option Categories
239

240
```python { .api }
241
# Major option categories and their purposes:
242

243
class OptionCategories:
244
    """Documentation of pandas option categories."""
245
    
246
    DISPLAY = "display.*"  # Control visual display of pandas objects
247
    COMPUTE = "compute.*"  # Control computational backends and optimizations  
248
    MODE = "mode.*"  # Control pandas operational behavior modes
249
    IO = "io.*"  # Control input/output operations and engines
250
    PLOTTING = "plotting.*"  # Control plotting behavior and backends
251
    STYLER = "styler.*"  # Control DataFrame.style formatting options
252
    FUTURE = "future.*"  # Control future behavior and deprecation warnings
253
```
254

255
### Context Managers and Temporary Settings
256

257
```python { .api }
258
# Common usage patterns for temporary option changes:
259

260
# Single option change
261
def temp_option_example():
262
    """Example of temporary option change."""
263
    with pd.option_context('display.max_rows', 100):
264
        # Temporarily show more rows
265
        print(large_dataframe)
266
    # Option automatically reverted
267

268
# Multiple option changes  
269
def multi_option_example():
270
    """Example of multiple temporary option changes."""
271
    with pd.option_context('display.max_rows', 50, 
272
                          'display.max_columns', 10,
273
                          'display.precision', 2):
274
        # Multiple temporary settings active
275
        print(dataframe)
276
    # All options automatically reverted
277

278
# Nested contexts
279
def nested_context_example():
280
    """Example of nested option contexts.""" 
281
    with pd.option_context('display.max_rows', 100):
282
        print("Outer context - 100 rows")
283
        with pd.option_context('display.max_rows', 10):
284
            print("Inner context - 10 rows")
285
        print("Back to outer context - 100 rows")
286
    print("Original setting restored")
287
```
288

289
### Commonly Used Options
290

291
```python { .api }
292
# Most frequently modified options with common values:
293

294
COMMON_OPTIONS = {
295
    # Display options
296
    'display.max_rows': [10, 20, 50, 100, None],  # None = show all
297
    'display.max_columns': [10, 20, None],  # None = show all  
298
    'display.width': [80, 120, 160, None],  # None = auto-detect
299
    'display.precision': [2, 3, 4, 6],  # decimal places
300
    'display.float_format': ['{:.2f}'.format, '{:.4f}'.format, None],
301
    'display.expand_frame_repr': [True, False],  # multi-line repr
302
    'display.show_dimensions': [True, False],  # show (rows, cols)
303
    
304
    # Computational options
305
    'mode.chained_assignment': ['warn', 'raise', None],
306
    'mode.copy_on_write': [True, False],
307
    'compute.use_bottleneck': [True, False],
308
    'compute.use_numexpr': [True, False],
309
    
310
    # I/O options
311
    'io.excel.xlsx.reader': ['openpyxl', 'xlrd'],
312
    'io.excel.xlsx.writer': ['openpyxl', 'xlsxwriter'],
313
    'io.parquet.engine': ['auto', 'pyarrow', 'fastparquet'],
314
}
315
```
316

317
## Types
318

319
```python { .api }
320
# Option value types
321
OptionValue = Union[str, int, float, bool, None, callable]
322

323
# Display alignment options
324
DisplayAlign = Literal['left', 'right', 'center']
325

326
# Large representation modes
327
LargeRepr = Literal['truncate', 'info']
328

329
# Chained assignment modes
330
ChainedAssignment = Literal['raise', 'warn', None]
331

332
# String storage modes  
333
StringStorage = Literal['python', 'pyarrow']
334

335
# I/O engine options
336
ExcelEngine = Literal['openpyxl', 'xlrd', 'xlsxwriter', 'odf', 'pyxlsb']
337
ParquetEngine = Literal['auto', 'pyarrow', 'fastparquet']
338
HDFFormat = Literal['table', 'fixed']
339

340
# Plotting backends
341
PlottingBackend = Literal['matplotlib']
342

343
# Memory usage options
344
MemoryUsage = Literal['deep', None]
345

346
# LaTeX environment options
347
LatexEnvironment = Literal['longtable', 'tabular']
348

349
# Styler representation options
350
StylerRepr = Literal['html', 'latex']
351

352
# Float format function type
353
FloatFormatter = Callable[[float], str]
354
```