Skip to content

Locator API

Locators describe which part of a table a style rule should target. Pass a locator to TypTable.tab_style with a text style, cell style, or both:

from narwhals import selectors as ncs

from typ_tables import TypTable, locators, style

table = (
    TypTable(df)
    .tab_style(
        locator=locators.LocBody(columns=ncs.numeric()),
        cell=style.CellStyle(align="right"),
    )
)

Some locators select a single table region and need no arguments, such as LocHeader or LocStubhead. Others can be narrowed to specific columns, rows, or row groups. Column-based locators use ColumnSelector; row-based locators use RowSelector.

Selectors

typ_tables.ColumnSelector module-attribute 

ColumnSelector = (
    Selector | list[str] | str | list[int] | int
)

A Type alias for all the types that can be used to select columns.

A ColumnSelector can be either
  • A Narwhals Selector
  • A list of column names.
  • A column name.
  • A list of column indices.
  • A column index.

typ_tables.RowSelector module-attribute 

RowSelector = Expr | list[int] | int

A Type alias for all the types that can be used to select rows.

A RowSelector can be either

Locators

typ_tables.locators

Public styling locators for targeting table regions.

Loc

Bases: Protocol

Protocol implemented by all public table style locators.

Pass a locator to TypTable.tab_style to choose which table region receives the supplied text and cell styles. Concrete locator classes select regions such as the header, body cells, row stub, or row-group labels.

LocBody dataclass

Select table body cells.

By default, all body cells are selected. Use rows, columns, or both to limit the style rule to a subset of the body.

columns class-attribute instance-attribute 
columns: ColumnSelector | None = None

Columns to select in the body.

Accepts any ColumnSelector. None selects all body columns.

rows class-attribute instance-attribute 
rows: RowSelector | None = None

Rows to select in the body.

Accepts any RowSelector. None selects all body rows.

LocColumnLabels dataclass

Select column-label cells.

Column-label cells are the header cells that display data column names above the body. Use columns to style labels for only some data columns.

columns class-attribute instance-attribute 
columns: ColumnSelector | None = None

Columns whose labels should be selected.

Accepts any ColumnSelector. None selects all column labels.

LocFooter dataclass

Select the footer cell.

LocHeader dataclass

Select the table header title and subtitle region.

This locator targets the heading created by TypTable.tab_header, not the column-label row. Use LocColumnLabels to style column names.

LocRowGroup dataclass

Select row-group label cells.

Row-group labels are created from groupname_col. By default, all row-group labels are selected. Use group to limit styling to one or more group labels.

group class-attribute instance-attribute 
group: str | list[str] | None = None

Row-group label or labels to select.

None selects every row group. A string selects the matching group label. A list selects all matching labels in the list.

LocSpanner dataclass

Select spanners in the table header.

Spanners are the labels above one or more column labels.

spanner_ids class-attribute instance-attribute 
spanner_ids: list[str] | None = None

Spanner IDs to target. The default None means all spanners will be targeted.

LocStub dataclass

Select row-label cells in the table stub.

The stub is the left-hand column created from rowname_col. By default, all stub cells are selected. Use rows to limit the style rule to specific row labels.

rows class-attribute instance-attribute 
rows: RowSelector | None = None

Rows whose stub cells should be selected.

Accepts any RowSelector. None selects all stub rows.

LocStubhead dataclass

Select the stub-head cell.

The stub head is the top-left header cell above the row-label stub column. Its visible label is set with TypTable.tab_stubhead.