pywry.grid

Configuration models for AG Grid integration.

---

Grid Options

pywry.grid.GridOptions

Bases: AGGridModel

AG Grid options following the official API.

This mirrors AG Grid's GridOptions interface. Includes sensible defaults that make the grid powerful out-of-the-box.

See: https://www.ag-grid.com/javascript-data-grid/grid-options/

Attributes

column_defs class-attribute instance-attribute

column_defs: list[dict[str, Any]] = Field(default_factory=list, alias='columnDefs')

default_col_def class-attribute instance-attribute

default_col_def: dict[str, Any] | None = Field(default=None, alias='defaultColDef')

row_data class-attribute instance-attribute

row_data: list[dict[str, Any]] | None = Field(default=None, alias='rowData')

row_model_type class-attribute instance-attribute

row_model_type: RowModelType = Field(default='clientSide', alias='rowModelType')

row_selection class-attribute instance-attribute

row_selection: dict[str, Any] | bool | None = Field(default=None, alias='rowSelection')

cell_selection class-attribute instance-attribute

cell_selection: bool | None = Field(default=True, alias='cellSelection')

dom_layout class-attribute instance-attribute

dom_layout: DomLayoutType = Field(default='normal', alias='domLayout')

pagination class-attribute instance-attribute

pagination: bool | None = None

pagination_page_size class-attribute instance-attribute

pagination_page_size: int = Field(default=100, alias='paginationPageSize')

pagination_page_size_selector class-attribute instance-attribute

pagination_page_size_selector: list[int] | bool = Field(default_factory=lambda: [25, 50, 100, 250, 500], alias='paginationPageSizeSelector')

group_display_type class-attribute instance-attribute

group_display_type: str = Field(default='singleColumn', alias='groupDisplayType')

row_group_panel_show class-attribute instance-attribute

row_group_panel_show: str = Field(default='always', alias='rowGroupPanelShow')

group_default_expanded class-attribute instance-attribute

group_default_expanded: int = Field(default=1, alias='groupDefaultExpanded')

cache_block_size class-attribute instance-attribute

cache_block_size: int = Field(default=500, alias='cacheBlockSize')

max_concurrent_datasource_requests class-attribute instance-attribute

max_concurrent_datasource_requests: int = Field(default=2, alias='maxConcurrentDatasourceRequests')

infinite_initial_row_count class-attribute instance-attribute

infinite_initial_row_count: int = Field(default=1, alias='infiniteInitialRowCount')

single_click_edit class-attribute instance-attribute

single_click_edit: bool | None = Field(default=None, alias='singleClickEdit')

undo_redo_cell_editing class-attribute instance-attribute

undo_redo_cell_editing: bool = Field(default=True, alias='undoRedoCellEditing')

undo_redo_cell_editing_limit class-attribute instance-attribute

undo_redo_cell_editing_limit: int = Field(default=20, alias='undoRedoCellEditingLimit')

copy_headers_to_clipboard class-attribute instance-attribute

copy_headers_to_clipboard: bool = Field(default=True, alias='copyHeadersToClipboard')

animate_rows class-attribute instance-attribute

animate_rows: bool = Field(default=True, alias='animateRows')

enable_cell_span class-attribute instance-attribute

enable_cell_span: bool = Field(default=False, alias='enableCellSpan')

model_config class-attribute instance-attribute

model_config = ConfigDict(populate_by_name=True, extra='allow')

Functions

to_dict

to_dict() -> dict[str, Any]

Convert to dict for JSON serialization to AG Grid.

Handles conditional inclusion based on row model type.

---

Column Definition

pywry.grid.ColDef

Bases: AGGridModel

AG Grid Column Definition.

See: https://www.ag-grid.com/javascript-data-grid/column-definitions/

Use snake_case in Python, serializes to camelCase for AG Grid.

Example: ColDef(field="name", header_name="Full Name", min_width=100) # Serializes to: {"field": "name", "headerName": "Full Name", "minWidth": 100}

Attributes

field class-attribute instance-attribute

field: str | None = None

col_id class-attribute instance-attribute

col_id: str | None = Field(default=None, alias='colId')

header_name class-attribute instance-attribute

header_name: str | None = Field(default=None, alias='headerName')

header_tooltip class-attribute instance-attribute

header_tooltip: str | None = Field(default=None, alias='headerTooltip')

hide class-attribute instance-attribute

hide: bool | None = None

pinned class-attribute instance-attribute

pinned: PinnedPosition | None = None

width class-attribute instance-attribute

width: int | None = None

min_width class-attribute instance-attribute

min_width: int | None = Field(default=None, alias='minWidth')

max_width class-attribute instance-attribute

max_width: int | None = Field(default=None, alias='maxWidth')

flex class-attribute instance-attribute

flex: int | None = None

sortable class-attribute instance-attribute

sortable: bool | None = None

filter class-attribute instance-attribute

filter: bool | str | None = None

resizable class-attribute instance-attribute

resizable: bool | None = None

editable class-attribute instance-attribute

editable: bool | None = None

cell_data_type class-attribute instance-attribute

cell_data_type: CellDataType | None = Field(default=None, alias='cellDataType')

value_getter class-attribute instance-attribute

value_getter: str | None = Field(default=None, alias='valueGetter')

value_formatter class-attribute instance-attribute

value_formatter: str | None = Field(default=None, alias='valueFormatter')

value_setter class-attribute instance-attribute

value_setter: str | None = Field(default=None, alias='valueSetter')

cell_renderer class-attribute instance-attribute

cell_renderer: str | None = Field(default=None, alias='cellRenderer')

cell_class class-attribute instance-attribute

cell_class: str | list[str] | None = Field(default=None, alias='cellClass')

cell_style class-attribute instance-attribute

cell_style: dict[str, str] | None = Field(default=None, alias='cellStyle')

auto_height class-attribute instance-attribute

auto_height: bool | None = Field(default=None, alias='autoHeight')

wrap_text class-attribute instance-attribute

wrap_text: bool | None = Field(default=None, alias='wrapText')

row_group class-attribute instance-attribute

row_group: bool | None = Field(default=None, alias='rowGroup')

enable_row_group class-attribute instance-attribute

enable_row_group: bool | None = Field(default=None, alias='enableRowGroup')

agg_func class-attribute instance-attribute

agg_func: str | None = Field(default=None, alias='aggFunc')

span_rows class-attribute instance-attribute

span_rows: bool | str | None = Field(default=None, alias='spanRows')

lock_position class-attribute instance-attribute

lock_position: bool | str | None = Field(default=None, alias='lockPosition')

lock_pinned class-attribute instance-attribute

lock_pinned: bool | None = Field(default=None, alias='lockPinned')

lock_visible class-attribute instance-attribute

lock_visible: bool | None = Field(default=None, alias='lockVisible')

model_config class-attribute instance-attribute

model_config = ConfigDict(populate_by_name=True, extra='allow')

Functions

validate_positive_width classmethod

validate_positive_width(v: int | None) -> int | None

Validate width values are positive if set.

to_dict

to_dict() -> dict[str, Any]

Convert to dict with camelCase keys, excluding None values.

Explicitly maps field names to aliases.

---

Column Group Definition

pywry.grid.ColGroupDef

Bases: AGGridModel

AG Grid Column Group Definition.

See: https://www.ag-grid.com/javascript-data-grid/column-groups/

Attributes

header_name class-attribute instance-attribute

header_name: str = Field(alias='headerName')

children class-attribute instance-attribute

children: list[ColDef | ColGroupDef] = Field(default_factory=list)

group_id class-attribute instance-attribute

group_id: str | None = Field(default=None, alias='groupId')

marry_children class-attribute instance-attribute

marry_children: bool | None = Field(default=None, alias='marryChildren')

open_by_default class-attribute instance-attribute

open_by_default: bool | None = Field(default=None, alias='openByDefault')

model_config class-attribute instance-attribute

model_config = ConfigDict(populate_by_name=True, extra='allow')

Functions

to_dict

to_dict() -> dict[str, Any]

Convert to dict, recursively converting children.

---

Default Column Definition

pywry.grid.DefaultColDef

Bases: AGGridModel

Default column definition applied to all columns.

These defaults make the grid useful out-of-the-box.

Attributes

sortable class-attribute instance-attribute

sortable: bool = True

filter class-attribute instance-attribute

filter: bool = True

resizable class-attribute instance-attribute

resizable: bool = True

floating_filter class-attribute instance-attribute

floating_filter: bool = Field(default=False, alias='floatingFilter')

min_width class-attribute instance-attribute

min_width: int = Field(default=80, alias='minWidth')

flex class-attribute instance-attribute

flex: int = 1

enable_row_group class-attribute instance-attribute

enable_row_group: bool = Field(default=True, alias='enableRowGroup')

enable_pivot class-attribute instance-attribute

enable_pivot: bool = Field(default=True, alias='enablePivot')

enable_value class-attribute instance-attribute

enable_value: bool = Field(default=True, alias='enableValue')

model_config class-attribute instance-attribute

model_config = ConfigDict(populate_by_name=True, extra='allow')

Functions

to_dict

to_dict() -> dict[str, Any]

Convert to dict with camelCase keys, excluding None values.

Explicitly maps field names to aliases.

---

Row Selection

pywry.grid.RowSelection

Bases: AGGridModel

AG Grid Row Selection configuration.

See: https://www.ag-grid.com/javascript-data-grid/row-selection-multi-row/

enableClickSelection options: - False: Only checkboxes select rows - 'enableDeselection': Ctrl+click to deselect only - 'enableSelection': Click to select only - True: Click to select, Ctrl+click to deselect (default)

Attributes

mode class-attribute instance-attribute

mode: RowSelectionMode = 'multiRow'

checkboxes class-attribute instance-attribute

checkboxes: bool = True

header_checkbox class-attribute instance-attribute

header_checkbox: bool = Field(default=True, alias='headerCheckbox')

enable_click_selection class-attribute instance-attribute

enable_click_selection: bool | str = Field(default=True, alias='enableClickSelection')

hide_disabled_checkboxes class-attribute instance-attribute

hide_disabled_checkboxes: bool = Field(default=False, alias='hideDisabledCheckboxes')

model_config class-attribute instance-attribute

model_config = ConfigDict(populate_by_name=True, extra='allow')

Functions

to_dict

to_dict() -> dict[str, Any]

Convert to dict with camelCase keys, excluding None values.

Explicitly maps field names to aliases.

---

Utility Functions

pywry.grid.build_grid_config

build_grid_config(data: Any, *, column_defs: list[dict[str, Any] | ColDef] | None = None, grid_options: dict[str, Any] | None = None, row_model_type: RowModelType = 'clientSide', theme: Literal['dark', 'light'] = 'dark', aggrid_theme: Literal['quartz', 'alpine', 'balham', 'material'] = 'alpine', grid_id: str | None = None, pagination: bool | None = None, pagination_page_size: int = 100, cache_block_size: int = 500, row_selection: RowSelection | dict[str, Any] | bool = False, enable_cell_span: bool | None = None) -> GridConfig

Build complete grid configuration from data.

This is the main entry point. Creates a fully-configured grid with sensible defaults that work great out-of-the-box.

Features enabled by default: - Multi-row selection with checkboxes - Sortable, filterable, resizable columns - Floating filter row - Row grouping with drag panel - Cell text selection - Undo/redo for edits - Copy with headers

PARAMETER	DESCRIPTION
data	Input data (DataFrame, list, dict). TYPE: Any
column_defs	Custom column definitions. Can be dicts or ColDef objects. TYPE: list | None DEFAULT: None
grid_options	Additional AG Grid options to merge. TYPE: dict | None DEFAULT: None
row_model_type	'clientSide' (default), 'infinite', 'serverSide', or 'viewport'. TYPE: str DEFAULT: 'clientSide'
theme	'dark' or 'light'. TYPE: str DEFAULT: 'dark'
aggrid_theme	AG Grid theme: 'quartz', 'alpine', 'balham', 'material'. TYPE: str DEFAULT: 'alpine'
grid_id	Custom grid ID (auto-generated if None). TYPE: str | None DEFAULT: None
pagination	Enable pagination. TYPE: bool DEFAULT: None
pagination_page_size	Rows per page. TYPE: int DEFAULT: 100
cache_block_size	Block size for infinite row model. TYPE: int DEFAULT: 500
row_selection	Row selection config. True = multiRow with checkboxes. False = disabled. Or pass RowSelection/dict for custom. TYPE: RowSelection | dict | bool DEFAULT: False
enable_cell_span	Enable row spanning for index columns. None (default) = auto-detect from MultiIndex rows. True = force enable. False = force disable. TYPE: bool | None DEFAULT: None

RETURNS	DESCRIPTION
GridConfig	Complete configuration with options and context.

pywry.grid.to_js_grid_config

to_js_grid_config(config: GridConfig) -> dict[str, Any]

Convert GridConfig to JSON-serializable dict for JS.

Used by anywidget backend which passes config as JSON.

pywry.grid.normalize_data

normalize_data(data: Any) -> GridData

Convert various data formats to normalized GridData.

Handles: - pandas DataFrame (including MultiIndex columns and rows) - list of dicts: [{'a': 1}, {'a': 2}] - dict of lists: {'a': [1, 2], 'b': [3, 4]} - single dict: {'a': 1, 'b': 2}

For pandas MultiIndex: - MultiIndex columns → column_groups for AG Grid ColGroupDef - MultiIndex rows → flattened to regular columns (can use for row spanning)

pywry.grid.build_column_defs

build_column_defs(columns: list[str], column_defs: list[dict[str, Any] | ColDef] | None = None, column_groups: list[dict[str, Any]] | None = None, index_columns: list[str] | None = None, enable_cell_span: bool = False, column_types: dict[str, str] | None = None) -> list[dict[str, Any]]

Build AG Grid column definitions.

If column_defs is provided, use it. Otherwise auto-generate from column names. Supports column groups from MultiIndex and special handling for index columns.

PARAMETER	DESCRIPTION
columns	Column names from the data. TYPE: list[str]
column_defs	Custom column definitions (overrides auto-generation). TYPE: list | None DEFAULT: None
column_groups	Column group structure from MultiIndex columns. TYPE: list | None DEFAULT: None
index_columns	Index columns that were flattened from MultiIndex rows. TYPE: list[str] | None DEFAULT: None
enable_cell_span	If True, index columns get spanRows=True for automatic row spanning. TYPE: bool DEFAULT: False
column_types	Detected column types from pandas dtypes (e.g., {'timestamp': 'dateString'}). TYPE: dict[str, str] | None DEFAULT: None

pywry.grid.build_grid_html

build_grid_html(config: GridConfig) -> str

Generate the HTML/JS snippet for the AG Grid.

---

Grid Model

pywry.grid.AGGridModel

Bases: BaseModel

Base model for AG Grid objects with camelCase serialization.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(populate_by_name=True, extra='allow')

Functions

to_dict

to_dict() -> dict[str, Any]

Convert to dict with camelCase keys, excluding None values.

Explicitly maps field names to aliases.

---

Grid Context

pywry.grid.PyWryGridContext

Bases: BaseModel

PyWry-specific context for grid rendering.

This contains metadata that PyWry needs but AG Grid doesn't care about. Kept separate from GridOptions to maintain clean API boundaries.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

grid_id instance-attribute

grid_id: str

theme_class instance-attribute

theme_class: str

total_rows class-attribute instance-attribute

total_rows: int = 0

truncated_rows class-attribute instance-attribute

truncated_rows: int = 0

original_data class-attribute instance-attribute

original_data: list[dict[str, Any]] = Field(default_factory=list, repr=False)

---

Grid Config

pywry.grid.GridConfig

Bases: BaseModel

Combined configuration: AG Grid options + PyWry context.

This is what rendering functions receive. It cleanly separates: - options: What AG Grid needs (follows their API) - context: What PyWry needs (grid_id, theme, etc.)

Attributes

options instance-attribute

options: GridOptions

context instance-attribute

context: PyWryGridContext

---

Grid Data

pywry.grid.GridData

Bases: BaseModel

Normalized grid data from various input formats.

Attributes

row_data instance-attribute

row_data: list[dict[str, Any]]

columns instance-attribute

columns: list[str]

total_rows instance-attribute

total_rows: int

column_groups class-attribute instance-attribute

column_groups: list[dict[str, Any]] | None = None

index_columns class-attribute instance-attribute

index_columns: list[str] = Field(default_factory=list)

column_types class-attribute instance-attribute

column_types: dict[str, str] = Field(default_factory=dict)