codeflash-agent/.tessl/tiles/tessl/pypi-pandas/docs/configuration.md

Configuration and Options

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

Core Imports

import pandas as pd
from pandas import get_option, set_option, reset_option, option_context

Capabilities

Option Management

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

def get_option(pat):
    """
    Retrieve the value of the specified option.
    
    Parameters:
    - pat: str, regexp pattern for option name
    
    Returns:
    object, option value
    """

def set_option(pat, value):
    """
    Set the value of the specified option.
    
    Parameters:
    - pat: str, regexp pattern for option name
    - value: object, new value for option
    """

def reset_option(pat):
    """
    Reset one or more options to their default value.
    
    Parameters:
    - pat: str, regexp pattern for option name(s) to reset
    """

def describe_option(pat, _print_desc=False):
    """
    Print available options and their descriptions.
    
    Parameters:
    - pat: str, regexp pattern for option name(s) to describe
    - _print_desc: bool, whether to print descriptions
    
    Returns:
    str or None, option descriptions
    """

def option_context(*args):
    """
    Context manager to temporarily set options.
    
    Parameters:
    - args: pairs of (option_name, option_value)
    
    Usage:
    with pd.option_context('display.max_rows', 100):
        # Temporary setting active here
        pass
    # Setting reverted after context
    """

# Access options registry directly
options: object  # Configuration options registry object

Display Options

Configuration options controlling how pandas objects are displayed.

# Display formatting options (accessed via get_option/set_option):

# General display
'display.chop_threshold'  # float, threshold for displaying small numbers as zero
'display.colheader_justify'  # str, column header alignment ('left', 'right')
'display.date_dayfirst'  # bool, interpret ambiguous dates as dayfirst
'display.date_yearfirst'  # bool, interpret ambiguous dates as yearfirst
'display.encoding'  # str, character encoding to use for display
'display.expand_frame_repr'  # bool, allow DataFrame repr to span multiple lines
'display.float_format'  # callable, function to format floats
'display.large_repr'  # str, display format for large frames ('truncate' or 'info')
'display.latex.escape'  # bool, escape special characters in LaTeX output
'display.latex.longtable'  # bool, use longtable format for LaTeX output
'display.latex.multicolumn'  # bool, use multicolumn format for LaTeX output
'display.latex.multicolumn_format'  # str, alignment for multicolumn LaTeX format
'display.latex.multirow'  # bool, use multirow format for LaTeX output
'display.latex.repr'  # bool, use LaTeX formatting for repr
'display.max_categories'  # int, maximum categories to display for categorical columns
'display.max_columns'  # int, maximum columns to display
'display.max_colwidth'  # int, maximum column width in characters
'display.max_info_columns'  # int, maximum columns for DataFrame.info()
'display.max_info_rows'  # int, maximum rows for DataFrame.info()
'display.max_rows'  # int, maximum rows to display
'display.max_seq_items'  # int, maximum sequence items to display
'display.memory_usage'  # str, memory usage display ('deep' or None)
'display.min_rows'  # int, minimum rows to display when truncating
'display.multi_sparse'  # bool, sparsify multi-index display
'display.notebook_repr_html'  # bool, use HTML repr in Jupyter notebooks
'display.pprint_nest_depth'  # int, nesting depth for pretty printing
'display.precision'  # int, floating point precision for display
'display.show_dimensions'  # bool, display DataFrame dimensions
'display.unicode.ambiguous_as_wide'  # bool, use ambiguous Unicode characters
'display.unicode.east_asian_width'  # bool, use East Asian character widths
'display.width'  # int, display width in characters

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

# Styling options  
'styler.format.decimal'  # str, decimal separator for Styler formatting
'styler.format.escape'  # str, escape method for Styler ('html', 'latex', None)
'styler.format.formatter'  # dict, default formatters for Styler
'styler.format.na_rep'  # str, representation for missing values in Styler
'styler.format.precision'  # int, precision for Styler numeric formatting
'styler.format.thousands'  # str, thousands separator for Styler
'styler.html.mathjax'  # bool, use MathJax for mathematical notation in Styler
'styler.latex.environment'  # str, LaTeX environment for Styler ('longtable', 'tabular')
'styler.latex.hrules'  # bool, add horizontal rules in LaTeX Styler
'styler.latex.multicol_align'  # str, multicolumn alignment for LaTeX Styler
'styler.latex.multirow_align'  # str, multirow alignment for LaTeX Styler
'styler.render.encoding'  # str, encoding for Styler rendering
'styler.render.max_columns'  # int, maximum columns for Styler rendering
'styler.render.max_elements'  # int, maximum elements for Styler rendering
'styler.render.max_rows'  # int, maximum rows for Styler rendering
'styler.render.repr'  # str, representation method for Styler ('html', 'latex')
'styler.sparse.columns'  # bool, sparsify column MultiIndex in Styler
'styler.sparse.index'  # bool, sparsify row MultiIndex in Styler

Computational Options

Configuration options affecting pandas computational behavior.

# Computational behavior options:

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

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

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

# I/O options
'io.common.default_buffer_size'  # int, default buffer size for I/O operations  
'io.excel.ods.reader'  # str, default engine for reading ODS files
'io.excel.ods.writer'  # str, default engine for writing ODS files
'io.excel.xls.reader'  # str, default engine for reading XLS files
'io.excel.xls.writer'  # str, default engine for writing XLS files
'io.excel.xlsb.reader'  # str, default engine for reading XLSB files
'io.excel.xlsm.reader'  # str, default engine for reading XLSM files
'io.excel.xlsm.writer'  # str, default engine for writing XLSM files
'io.excel.xlsx.reader'  # str, default engine for reading XLSX files
'io.excel.xlsx.writer'  # str, default engine for writing XLSX files
'io.hdf.default_format'  # str, default HDF5 format ('table' or 'fixed')
'io.hdf.dropna_table'  # bool, drop NaN values when writing HDF5 table format
'io.parquet.engine'  # str, default engine for parquet ('auto', 'pyarrow', 'fastparquet')
'io.sql.engine'  # str, default engine for SQL operations ('auto')

# Plotting options
'plotting.backend'  # str, plotting backend to use ('matplotlib')
'plotting.matplotlib.register_converters'  # bool, register pandas converters with matplotlib

Advanced Configuration

Functions for advanced configuration management and option introspection.

def show_versions(as_json=False):
    """
    Provide useful information about pandas and the system.
    
    Parameters:
    - as_json: bool, return information as JSON string
    
    Returns:
    None or str, version information
    """

# Configuration state functions  
def using_copy_on_write():
    """
    Return whether copy-on-write is enabled.
    
    Returns:
    bool, True if copy-on-write mode is enabled
    """

def using_nullable_dtypes():
    """
    Return whether nullable dtypes are the default.
    
    Returns:
    bool, True if nullable dtypes are default
    """

def using_string_dtype():
    """
    Return whether string dtype inference is enabled.
    
    Returns:
    bool, True if string dtype inference is enabled
    """

# Custom formatting functions
def set_eng_float_format(accuracy=3, use_eng_prefix=False):
    """
    Format float representation to engineering format.
    
    Parameters:
    - accuracy: int, number of decimal places
    - use_eng_prefix: bool, use engineering prefix (k, M, G, etc.)
    """

Option Categories

# Major option categories and their purposes:

class OptionCategories:
    """Documentation of pandas option categories."""
    
    DISPLAY = "display.*"  # Control visual display of pandas objects
    COMPUTE = "compute.*"  # Control computational backends and optimizations  
    MODE = "mode.*"  # Control pandas operational behavior modes
    IO = "io.*"  # Control input/output operations and engines
    PLOTTING = "plotting.*"  # Control plotting behavior and backends
    STYLER = "styler.*"  # Control DataFrame.style formatting options
    FUTURE = "future.*"  # Control future behavior and deprecation warnings

Context Managers and Temporary Settings

# Common usage patterns for temporary option changes:

# Single option change
def temp_option_example():
    """Example of temporary option change."""
    with pd.option_context('display.max_rows', 100):
        # Temporarily show more rows
        print(large_dataframe)
    # Option automatically reverted

# Multiple option changes  
def multi_option_example():
    """Example of multiple temporary option changes."""
    with pd.option_context('display.max_rows', 50, 
                          'display.max_columns', 10,
                          'display.precision', 2):
        # Multiple temporary settings active
        print(dataframe)
    # All options automatically reverted

# Nested contexts
def nested_context_example():
    """Example of nested option contexts.""" 
    with pd.option_context('display.max_rows', 100):
        print("Outer context - 100 rows")
        with pd.option_context('display.max_rows', 10):
            print("Inner context - 10 rows")
        print("Back to outer context - 100 rows")
    print("Original setting restored")

Commonly Used Options

# Most frequently modified options with common values:

COMMON_OPTIONS = {
    # Display options
    'display.max_rows': [10, 20, 50, 100, None],  # None = show all
    'display.max_columns': [10, 20, None],  # None = show all  
    'display.width': [80, 120, 160, None],  # None = auto-detect
    'display.precision': [2, 3, 4, 6],  # decimal places
    'display.float_format': ['{:.2f}'.format, '{:.4f}'.format, None],
    'display.expand_frame_repr': [True, False],  # multi-line repr
    'display.show_dimensions': [True, False],  # show (rows, cols)
    
    # Computational options
    'mode.chained_assignment': ['warn', 'raise', None],
    'mode.copy_on_write': [True, False],
    'compute.use_bottleneck': [True, False],
    'compute.use_numexpr': [True, False],
    
    # I/O options
    'io.excel.xlsx.reader': ['openpyxl', 'xlrd'],
    'io.excel.xlsx.writer': ['openpyxl', 'xlsxwriter'],
    'io.parquet.engine': ['auto', 'pyarrow', 'fastparquet'],
}

Types

# Option value types
OptionValue = Union[str, int, float, bool, None, callable]

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

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

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

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

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

# Plotting backends
PlottingBackend = Literal['matplotlib']

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

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

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

# Float format function type
FloatFormatter = Callable[[float], str]