Switching from a boolean value to an enum

docs/Tables.md

@@ -147,10 +147,12 @@ The **repetition** of table headings on every page can also be disabled:
 
 ```python
 ...
-with pdf.table(repeat_headings=False) as table:
+with pdf.table(repeat_headings=1) as table:
     ...
 ```
 
+`"ON_TOP_OF_EVERY_PAGE"` is an equivalent valid value for `repeat_headings`.
+
 ## Style table headings
 
 ```python

fpdf/enums.py

@@ -354,6 +354,16 @@ class TableSpan(CoerciveEnum):
     "Mark this cell as a continuation of the previous column"
 
 
+class TableHeadingsDisplay(CoerciveIntEnum):
+    "Defines how the table headings should be displayed"
+
+    NONE = 0
+    "Only render the table headings at the beginning of the table"
+
+    ON_TOP_OF_EVERY_PAGE = 1
+    "When a page break occurs, repeat the table headings at the top of every table fragment"
+
+
 class RenderStyle(CoerciveEnum):
     "Defines how to render shapes"
 

fpdf/fpdf.py

@@ -4998,7 +4998,7 @@ def table(self, *args, **kwargs):
             num_heading_rows (number): optional. Sets the number of heading rows, default value is 1. If this value is not 1,
                 first_row_as_headings needs to be True if num_heading_rows>1 and False if num_heading_rows=0. For backwards compatibility,
                 first_row_as_headings is used in case num_heading_rows is 1.
-            repeat_headings (bool): optional, indicates whether to print table headings on every page, default to True.
+            repeat_headings (fpdf.enums.TableHeadingsDisplay): optional, indicates whether to print table headings on every page, default to 1.
         """
         table = Table(self, *args, **kwargs)
         yield table

fpdf/table.py

@@ -7,6 +7,7 @@
     MethodReturnValue,
     TableBordersLayout,
     TableCellFillMode,
+    TableHeadingsDisplay,
     WrapMode,
     VAlign,
     TableSpan,
@@ -47,7 +48,7 @@ def __init__(
         padding=None,
         outer_border_width=None,
         num_heading_rows=1,
-        repeat_headings=True,
+        repeat_headings=1,
     ):
         """
         Args:
@@ -80,7 +81,7 @@ def __init__(
             num_heading_rows (number): optional. Sets the number of heading rows, default value is 1. If this value is not 1,
                 first_row_as_headings needs to be True if num_heading_rows>1 and False if num_heading_rows=0. For backwards compatibility,
                 first_row_as_headings is used in case num_heading_rows is 1.
-            repeat_headings (bool): optional, indicates whether to print table headings on every page, default to True.
+            repeat_headings (fpdf.enums.TableHeadingsDisplay): optional, indicates whether to print table headings on every page, default to 1.
         """
         self._fpdf = fpdf
         self._align = align
@@ -100,7 +101,7 @@ def __init__(
         self._width = fpdf.epw if width is None else width
         self._wrapmode = wrapmode
         self._num_heading_rows = num_heading_rows
-        self._repeat_headings = repeat_headings
+        self._repeat_headings = TableHeadingsDisplay.coerce(repeat_headings)
         self._initial_style = None
         self.rows = []
 
@@ -214,13 +215,16 @@ def render(self):
         row_info = list(self._process_rowpans_entries())
 
         # actually render the cells
+        repeat_headings = (
+            self._repeat_headings is TableHeadingsDisplay.ON_TOP_OF_EVERY_PAGE
+        )
         self._fpdf.y += self._outer_border_margin[1]
         for i, row in enumerate(self.rows):
             # pylint: disable=protected-access
             page_break = self._fpdf._perform_page_break_if_need_be(
                 row_info[i].pagebreak_height
             )
-            if page_break and self._repeat_headings and i >= self._num_heading_rows:
+            if page_break and repeat_headings and i >= self._num_heading_rows:
                 # repeat headings on top:
                 self._fpdf.y += self._outer_border_margin[1]
                 for row_idx in range(self._num_heading_rows):

test/table/test_table.py

@@ -356,9 +356,22 @@ def test_table_with_page_break_and_headings_repeated(tmp_path):  # issue 1151
     pdf = FPDF()
     pdf.add_page()
     pdf.set_font("Times", size=16)
+    pdf.cell(text="repeat_headings=1:", new_y="NEXT")
     with pdf.table(
         MULTILINE_TABLE_DATA,
-        repeat_headings=False,
+        repeat_headings=1,
+    ):
+        pass
+    pdf.cell(text='repeat_headings="NONE":', new_y="NEXT")
+    with pdf.table(
+        MULTILINE_TABLE_DATA,
+        repeat_headings="NONE",
+    ):
+        pass
+    pdf.cell(text='repeat_headings="ON_TOP_OF_EVERY_PAGE":', new_y="NEXT")
+    with pdf.table(
+        MULTILINE_TABLE_DATA,
+        repeat_headings="ON_TOP_OF_EVERY_PAGE",
     ):
         pass
     assert_pdf_equal(