Skip to content

Pagination

Metadata-driven pagination utilities and strategies used by the unified encoder.

RTFPagination

Core pagination settings used to calculate available space on each page.

rtflite.pagination.RTFPagination pydantic-model

Bases: BaseModel

Core pagination logic and calculations for RTF documents

Show JSON schema: 
{
  "description": "Core pagination logic and calculations for RTF documents",
  "properties": {
    "page_width": {
      "description": "Page width in inches",
      "title": "Page Width",
      "type": "number"
    },
    "page_height": {
      "description": "Page height in inches",
      "title": "Page Height",
      "type": "number"
    },
    "margin": {
      "description": "Page margins [left, right, top, bottom, header, footer]",
      "items": {
        "type": "number"
      },
      "title": "Margin",
      "type": "array"
    },
    "nrow": {
      "description": "Maximum rows per page",
      "title": "Nrow",
      "type": "integer"
    },
    "orientation": {
      "description": "Page orientation",
      "title": "Orientation",
      "type": "string"
    }
  },
  "required": [
    "page_width",
    "page_height",
    "margin",
    "nrow",
    "orientation"
  ],
  "title": "RTFPagination",
  "type": "object"
}

Config:

  • arbitrary_types_allowed: True

Fields:

  • page_width (float)
  • page_height (float)
  • margin (Sequence[float])
  • nrow (int)
  • orientation (str)

page_width pydantic-field 

page_width: float

Page width in inches

page_height pydantic-field 

page_height: float

Page height in inches

margin pydantic-field 

margin: Sequence[float]

Page margins [left, right, top, bottom, header, footer]

nrow pydantic-field 

nrow: int

Maximum rows per page

orientation pydantic-field 

orientation: str

Page orientation

calculate_available_space 

calculate_available_space() -> Mapping[str, float]

Calculate available space for content on each page

PageBreakCalculator

Calculates row metadata, page assignments, and optimal break points.

rtflite.pagination.PageBreakCalculator pydantic-model

Bases: BaseModel

Calculates where page breaks should occur based on content and constraints

Show JSON schema: 
{
  "$defs": {
    "RTFPagination": {
      "description": "Core pagination logic and calculations for RTF documents",
      "properties": {
        "page_width": {
          "description": "Page width in inches",
          "title": "Page Width",
          "type": "number"
        },
        "page_height": {
          "description": "Page height in inches",
          "title": "Page Height",
          "type": "number"
        },
        "margin": {
          "description": "Page margins [left, right, top, bottom, header, footer]",
          "items": {
            "type": "number"
          },
          "title": "Margin",
          "type": "array"
        },
        "nrow": {
          "description": "Maximum rows per page",
          "title": "Nrow",
          "type": "integer"
        },
        "orientation": {
          "description": "Page orientation",
          "title": "Orientation",
          "type": "string"
        }
      },
      "required": [
        "page_width",
        "page_height",
        "margin",
        "nrow",
        "orientation"
      ],
      "title": "RTFPagination",
      "type": "object"
    }
  },
  "description": "Calculates where page breaks should occur based on content and constraints",
  "properties": {
    "pagination": {
      "$ref": "#/$defs/RTFPagination",
      "description": "Pagination configuration"
    }
  },
  "required": [
    "pagination"
  ],
  "title": "PageBreakCalculator",
  "type": "object"
}

Config:

  • arbitrary_types_allowed: True

Fields:

  • pagination (RTFPagination)

pagination pydantic-field 

pagination: RTFPagination

Pagination configuration

calculate_content_rows 

calculate_content_rows(df: DataFrame, col_widths: Sequence[float], table_attrs: TableAttributes | None = None, font_size: float = 9, spanning_columns: Sequence[str] | None = None) -> Sequence[int]

Calculate how many rows each content row will occupy when rendered

Parameters:

Name Type Description Default
df DataFrame

DataFrame containing the content

 required
col_widths Sequence[float]

Width of each column in inches

 required
table_attrs TableAttributes | None

Table attributes containing cell height and font size info

 None
font_size float

Default font size in points

 9
spanning_columns Sequence[str] | None

Columns that should be treated as spanning the full width

 None

Returns:

Type Description
Sequence[int]

List of row counts for each data row

find_page_breaks 

find_page_breaks(df: DataFrame, col_widths: Sequence[float], page_by: Sequence[str] | None = None, new_page: bool = False, table_attrs: TableAttributes | None = None, additional_rows_per_page: int = 0) -> Sequence[tuple[int, int]]

Find optimal page break positions (r2rtf compatible)

Parameters:

Name Type Description Default
df DataFrame

DataFrame to paginate

 required
col_widths Sequence[float]

Column widths in inches

 required
page_by Sequence[str] | None

Columns to group by for page breaks

 None
new_page bool

Whether to force new pages between groups

 False
table_attrs TableAttributes | None

Table attributes for accurate row calculation

 None
additional_rows_per_page int

Additional rows per page (headers, footnotes, sources)

 0

Returns:

Type Description
Sequence[tuple[int, int]]

List of (start_row, end_row) tuples for each page

calculate_row_metadata 

calculate_row_metadata(df: DataFrame, col_widths: Sequence[float], page_by: Sequence[str] | None = None, subline_by: Sequence[str] | None = None, table_attrs: TableAttributes | None = None, removed_column_indices: Sequence[int] | None = None, font_size: float = 9, additional_rows_per_page: int = 0, new_page: bool = False) -> DataFrame

Generate complete row metadata for pagination.

Pagination contexts and registry

rtflite.pagination.PaginationContext pydantic-model

Bases: BaseModel

Context passed to the strategy to perform pagination.

Config:

  • arbitrary_types_allowed: True

Fields:

  • df (DataFrame)
  • rtf_body (RTFBody)
  • rtf_page (RTFPage)
  • col_widths (list[float])
  • table_attrs (TableAttributes | None)
  • additional_rows_per_page (int)
  • row_metadata (DataFrame | None)
  • removed_column_indices (list[int] | None)

rtflite.pagination.PageContext pydantic-model

Bases: BaseModel

Holds all data and metadata required to render a single page.

Config:

  • arbitrary_types_allowed: True

Fields:

  • page_number (int)
  • total_pages (int)
  • data (DataFrame)
  • is_first_page (bool)
  • is_last_page (bool)
  • col_widths (list[float])
  • needs_header (bool)
  • table_attrs (TableAttributes | None)
  • subline_header (dict[str, Any] | None)
  • pageby_header_info (dict[str, Any] | None)
  • group_boundaries (list[dict[str, Any]] | None)
  • final_body_attrs (TableAttributes | None)
  • component_borders (dict[str, Any])

rtflite.pagination.StrategyRegistry

Registry for pagination strategies.

register classmethod 

register(name: str, strategy_cls: type[PaginationStrategy]) -> None

Register a new strategy.

get classmethod 

get(name: str) -> type[PaginationStrategy]

Get a strategy by name.

list_strategies classmethod 

list_strategies() -> list[str]

List all registered strategies.

rtflite.pagination.PaginationStrategy

Bases: ABC

Abstract base class for pagination strategies.

paginate abstractmethod 

paginate(context: PaginationContext) -> list[PageContext]

Split the document into pages based on the strategy.

Built-in strategies

rtflite.pagination.strategies.defaults.DefaultPaginationStrategy

Bases: PaginationStrategy

Default pagination strategy based on row counts and page size.

rtflite.pagination.strategies.grouping.PageByStrategy

Bases: PaginationStrategy

Pagination strategy that respects grouping columns (page_by).

rtflite.pagination.strategies.grouping.SublineStrategy

Bases: PageByStrategy

Pagination strategy for subline_by (forces new pages and special headers).

Page feature processing

rtflite.pagination.processor.PageFeatureProcessor

Processes page features like borders, headers, and footers for each page.

process 

process(document: Any, page: PageContext) -> PageContext

Process a single page to apply all feature-specific logic.