Skip to content

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:

Name Type Description
column_defs list[dict[str, Any]]

Serialized column definitions passed to AG Grid.
default_col_def dict[str, Any] | None

Default column definition shared by all columns.
row_data list[dict[str, Any]] | None

Client-side row data when using the client-side row model.
row_model_type RowModelType

AG Grid row model used to render and fetch data.
row_selection dict[str, Any] | bool | None

Row selection configuration passed directly to AG Grid.
cell_selection bool | None

Whether cell-level selection is enabled.
dom_layout DomLayoutType

Layout mode controlling grid sizing behavior.
pagination bool | None

Whether pagination is enabled.
pagination_page_size int

Number of rows shown per page when pagination is active.
pagination_page_size_selector list[int] | bool

Allowed page-size choices shown by AG Grid.
group_display_type str

Group rendering strategy used for grouped rows.
row_group_panel_show str

Visibility mode for the row grouping panel.
group_default_expanded int

Initial expansion depth for grouped rows.
cache_block_size int

Block size used by infinite and server-side row models.
max_concurrent_datasource_requests int

Maximum concurrent requests made by AG Grid data sources.
infinite_initial_row_count int

Placeholder row count shown before infinite data arrives.
single_click_edit bool | None

Whether editing starts on a single click.
undo_redo_cell_editing bool

Whether undo and redo are enabled for cell edits.
undo_redo_cell_editing_limit int

Maximum number of undo history entries retained.
copy_headers_to_clipboard bool

Whether copied ranges include column headers.
animate_rows bool

Whether row changes animate in the grid.
enable_cell_span bool

Whether AG Grid cell spanning is enabled.

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

_coerce_row_selection classmethod 

_coerce_row_selection(v: Any) -> dict[str, Any] | bool | None

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:

Name Type Description
field str | None

Data field backing the column.
col_id str | None

Stable AG Grid column identifier.
header_name str | None

Display name shown in the grid header.
header_tooltip str | None

Tooltip shown when hovering the column header.
hide bool | None

Whether the column starts hidden.
pinned PinnedPosition | None

Pin position used to keep the column fixed on the left or right.
width int | None

Explicit column width in pixels.
min_width int | None

Minimum column width in pixels.
max_width int | None

Maximum column width in pixels.
flex int | None

Flex grow factor when columns share available width.
sortable bool | None

Whether the column supports sorting.
filter bool | str | None

Filter toggle or AG Grid filter type name.
resizable bool | None

Whether the user can resize the column.
editable bool | None

Whether the cell values are editable.
cell_data_type CellDataType | None

AG Grid data type hint for client-side behaviors.
value_getter str | None

JavaScript expression or callback name for derived values.
value_formatter str | None

JavaScript formatter expression or callback name.
value_setter str | None

JavaScript expression or callback name used for edits.
cell_renderer str | None

AG Grid cell renderer name or callback identifier.
cell_class str | list[str] | None

CSS class or classes applied to rendered cells.
cell_style dict[str, str] | None

Inline style mapping applied to rendered cells.
auto_height bool | None

Whether row height grows to fit wrapped content.
wrap_text bool | None

Whether cell text is allowed to wrap.
row_group bool | None

Whether the column participates in active row grouping.
enable_row_group bool | None

Whether the column may be dragged into the row group panel.
agg_func str | None

Aggregation function name for grouped rows.
span_rows bool | str | None

Row-span configuration for repeated values.
lock_position bool | str | None

Prevents the user from moving the column.
lock_pinned bool | None

Prevents changes to the pinned state.
lock_visible bool | None

Prevents the user from hiding the column.

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:

Name Type Description
header_name str

Display label for the group header.
children list[ColDef | ColGroupDef]

Child columns or nested groups contained by this group.
group_id str | None

Stable AG Grid identifier for the group.
marry_children bool | None

Whether child columns must stay together during reordering.
open_by_default bool | None

Whether the group should be expanded initially.

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:

Name Type Description
sortable bool

Whether columns are sortable by default.
filter bool

Whether columns expose filtering by default.
resizable bool

Whether columns are resizable by default.
floating_filter bool

Whether a floating filter row is shown beneath headers.
min_width int

Minimum width applied to columns that do not override it.
flex int

Flex share used when distributing available width.
enable_row_group bool

Whether columns can be used for row grouping.
enable_pivot bool

Whether columns can be used for pivoting.
enable_value bool

Whether columns can be aggregated as values.

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:

Name Type Description
mode RowSelectionMode

Single-row or multi-row selection mode.
checkboxes bool

Whether row selection checkboxes are shown.
header_checkbox bool

Whether the header includes a select-all checkbox.
enable_click_selection bool | str

Click behavior used for selecting and deselecting rows.
hide_disabled_checkboxes bool

Whether disabled checkboxes should be hidden instead of shown inactive.

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

Parameters:

Name Type Description Default
data Any

Input data (DataFrame, list, dict).

 required
column_defs list | None

Custom column definitions. Can be dicts or ColDef objects.

 None
grid_options dict | None

Additional AG Grid options to merge.

 None
row_model_type str

'clientSide' (default), 'infinite', 'serverSide', or 'viewport'.

 'clientSide'
theme str

'dark' or 'light'.

 'dark'
aggrid_theme str

AG Grid theme: 'quartz', 'alpine', 'balham', 'material'.

 'alpine'
grid_id str | None

Custom grid ID (auto-generated if None).

 None
pagination bool

Enable pagination.

 None
pagination_page_size int

Rows per page.

 100
cache_block_size int

Block size for infinite row model.

 500
row_selection RowSelection | dict | bool

Row selection config. True = multiRow with checkboxes. False = disabled. Or pass RowSelection/dict for custom.

 False
enable_cell_span bool | None

Enable row spanning for index columns. None (default) = auto-detect from MultiIndex rows. True = force enable. False = force disable.

 None

Returns:

Type Description
GridConfig

Complete configuration with options and context.
Notes

This function is the main high-level entry point for PyWry AG Grid setup. It normalizes input data, builds column definitions, applies safety limits, and prepares both AG Grid options and PyWry-specific rendering 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.

Parameters:

Name Type Description Default
config GridConfig

Combined grid configuration to serialize.

 required

Returns:

Type Description
dict[str, Any]

JSON-serializable AG Grid configuration for the browser.

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)

Parameters:

Name Type Description Default
data Any

Supported tabular input such as a DataFrame, list of row dictionaries, dict of columns, or single row mapping.

 required

Returns:

Type Description
GridData

Normalized grid payload with rows, columns, and metadata.

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.

Parameters:

Name Type Description Default
columns list[str]

Column names from the data.

 required
column_defs list | None

Custom column definitions (overrides auto-generation).

 None
column_groups list | None

Column group structure from MultiIndex columns.

 None
index_columns list[str] | None

Index columns that were flattened from MultiIndex rows.

 None
enable_cell_span bool

If True, index columns get spanRows=True for automatic row spanning.

 False
column_types dict[str, str] | None

Detected column types from pandas dtypes (e.g., {'timestamp': 'dateString'}).

 None

Returns:

Type Description
list[dict[str, Any]]

Serialized AG Grid column definitions ready for the frontend.

pywry.grid.build_grid_html 

build_grid_html(config: GridConfig) -> str

Generate the standalone HTML and JavaScript snippet for AG Grid.

Parameters:

Name Type Description Default
config GridConfig

Combined grid configuration to embed.

 required

Returns:

Type Description
str

HTML snippet that bootstraps an AG Grid instance when inserted into a page.

Grid Model

pywry.grid.AGGridModel

Bases: BaseModel

Base model for AG Grid objects with camelCase serialization.

The AG Grid Python models accept snake_case field names for ergonomics, then serialize to the camelCase keys expected by the JavaScript API.

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:

Name Type Description
grid_id str

Stable identifier used for IPC and DOM scoping.
theme_class str

CSS class applied to the grid wrapper for theme selection.
total_rows int

Total number of rows in the original dataset.
truncated_rows int

Number of rows omitted when client-side safety truncation is applied.
original_data list[dict[str, Any]]

Full normalized row data retained for PyWry-specific operations.

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:

Name Type Description
options GridOptions

AG Grid options passed to the frontend grid instance.
context PyWryGridContext

PyWry-specific metadata used for rendering and IPC.

Attributes

options instance-attribute 

options: GridOptions

context instance-attribute 

context: PyWryGridContext

Grid Data

pywry.grid.GridData

Bases: BaseModel

Normalized grid data derived from arbitrary Python inputs.

Attributes:

Name Type Description
row_data list[dict[str, Any]]

Normalized row records ready for JSON serialization.
columns list[str]

Flat column names extracted from the input data.
total_rows int

Total number of normalized rows.
column_groups list[dict[str, Any]] | None

Nested column-group structure derived from MultiIndex columns.
index_columns list[str]

Column names created by flattening MultiIndex row indexes.
column_types dict[str, str]

Detected AG Grid cell-data-type hints keyed by column name.

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)