Filters, sorts, and pivot tables

Filter and sort a table’s rows, and find the types the format reserves for categorized and pivot tables.

TransformationInfo

class creator_studio_doc_format.core.TransformationInfo(*, preset_identifier='', base_table=None, structure=None, filter_set=None, sort=None, **extra_data)[source]

Information about how the reader derives a table.

In version 1.0, it holds the filter and sort rules applied to the table, in filter_set and sort, and the table’s content holds the result. base_table and structure are reserved for categorized and pivot tables, which version 1.0 doesn’t support.

field base_table : Table | None = None

The source data this table was derived from. It’s reserved for categorized and pivot tables, which version 1.0 doesn’t support. Its rows and columns carry their own identifiers, independent of the ones this table’s content, column_headers, and merges use.

field structure : Structure | None = None

The structural shape of this table, reserved for categorized and pivot tables, which version 1.0 doesn’t support. Without it, the table is a plain grid of rows and columns, which may still have filter_set or sort.

field filter_set : FilterSet | None = None

The filter configuration applied to this table, grouped by column. When it’s present, rows whose Table.Row.visibility_state is filtered didn’t pass the set.

field sort : Sort | None = None

The sort rules applied to this table, independent of filter_set. The rows in content are already in sorted order.

Structure

class creator_studio_doc_format.core.Structure(*, preset_identifier='', categorized=None, pivot=None, **extra_data)[source]

The structural transformation of a table.

It’s reserved for categorized and pivot tables, which version 1.0 doesn’t support. filter_set and sort are separate settings, and apply to a plain table without it.

field categorized : CategoryRules | None = None

A categorized table, which version 1.0 doesn’t support.

CategoryRules is reserved to describe how its rows are grouped.

field pivot : PivotRules | None = None

A pivot table, which version 1.0 doesn’t support.

PivotRules is reserved to describe its row, column, and value axes.

PivotRules

class creator_studio_doc_format.core.PivotRules(*, preset_identifier='', **extra_data)[source]

A placeholder for a pivot table’s rules, which version 1.0 doesn’t support.

It’s the value of Table.TransformationInfo.Structure.pivot, so that a later version can describe how rows, columns, and values map to the pivot’s row axis, column axis, and value cells. It has no properties yet.

CategoryRules

class creator_studio_doc_format.core.CategoryRules(*, preset_identifier='', **extra_data)[source]

An empty object for a categorized table’s rules, which version 1.0 doesn’t support.

It’s the value of the Table.TransformationInfo.Structure.categorized case, so that a later version can describe the grouping columns, subtotal aggregations, and group-sort settings. It has no properties yet.

FilterSet

class creator_studio_doc_format.core.FilterSet(*, preset_identifier='', is_enabled=True, combine_mode=CombineMode.AND, filters, **extra_data)[source]

The complete filter configuration for a table.

It holds the per-column filters and how they combine. Rows that don’t pass the set stay in content, with Table.Row.visibility_state set to filtered.

field is_enabled : bool = True

Whether the filter set is enabled. When it’s false, the filter set is preserved but every row passes, and no row has Table.Row.visibility_state set to filtered.

field combine_mode : CombineMode = CombineMode.AND

The way the per-column filters combine to decide whether a row passes the set. With and, the row must pass every column’s filter; with or, the row passes if it passes any one column’s filter. Within a single column’s filter, the rules are always combined with OR: a row passes that column’s filter when any of its rules match.

field filters : list[Filter] [Required]

The column filters, with at most one entry for each column. Each entry carries the rules that apply to its column. The order isn’t significant.

CombineMode

class creator_studio_doc_format.core.CombineMode(str, Enum)[source]

The rule for combining the per-column filters in a filter set to decide whether a row passes.

A field accepts a member or its value, so CombineMode.AND and 'and' are the same. The member’s name as a string isn’t accepted.

AND = 'and'

Logical AND: a row passes only if it passes every column’s filter.

OR = 'or'

Logical OR: a row passes if it passes any column’s filter.

Filter

class creator_studio_doc_format.core.Filter(*, preset_identifier='', column_identifier, rules, **extra_data)[source]

The filter for a single column.

It names the column being filtered and holds the ordered rules applied to its values. A row passes the filter when at least one of rules matches; the rules within a single-column filter are always combined with OR.

field column_identifier : str [Required]

The stable identifier of the column whose values every rule in this filter is evaluated against. It matches a Table.ColumnHeader.column_identifier.

field rules : list[TableFilterSetFilterRule] [Required]

The ordered list of predicates applied to the column’s values. A row passes this filter when at least one rule’s predicate matches; within a single-column filter, rules are implicitly combined with OR.

TableFilterSetFilterRule

class creator_studio_doc_format.core.TableFilterSetFilterRule(*, preset_identifier='', predicate, **extra_data)[source]

A single predicate evaluated against a row’s value in the enclosing filter’s column.

field predicate : Predicate [Required]

The predicate evaluated against the row’s value in the enclosing filter’s column. It can use any predicate type, including filter-specific cases such as in_list and duplicates.

Sort

class creator_studio_doc_format.core.Sort(*, preset_identifier='', scope=Scope.ENTIRE_TABLE, rules, **extra_data)[source]

The sort rules that the reader applies to the rows of a table’s content.

Those rows are already in sorted order. Header and footer rows are never sorted, regardless of scope.

field scope : Scope = Scope.ENTIRE_TABLE

The scope the user originally configured the sort with. It affects how the sort is applied if it’s run again. It doesn’t change the rendered content, which is already in sorted order.

field rules : list[TableSortRule] [Required]

The ordered list of sort rules. A rule’s position in the array determines its precedence: index 0 is the primary sort key, index 1 is the tiebreaker, and so on.

Scope

class creator_studio_doc_format.core.Scope(str, Enum)[source]

The scope of a sort, as the user originally configured it.

A field accepts a member or its value, so Scope.ENTIRE_TABLE and 'entire_table' are the same. The member’s name as a string isn’t accepted.

ENTIRE_TABLE = 'entire_table'

Sort applied to all body rows of the table.

SELECTED_ROWS = 'selected_rows'

Sort applied only to the rows that were selected when the sort was created.

TableSortRule

class creator_studio_doc_format.core.TableSortRule(*, preset_identifier='', column_identifier, direction=Direction.ASCENDING, **extra_data)[source]

A single sort key.

field column_identifier : str [Required]

The stable identifier of the column the rule sorts by. It matches a Table.ColumnHeader.column_identifier.

field direction : Direction = Direction.ASCENDING

The sort direction for this key.

Direction

class creator_studio_doc_format.core.Direction(str, Enum)[source]

A sort direction.

A field accepts a member or its value, so Direction.ASCENDING and 'ascending' are the same. The member’s name as a string isn’t accepted.

ASCENDING = 'ascending'

Smallest or earliest first.

DESCENDING = 'descending'

Largest or latest first.