Doc: added documentation on the col_widths parameter (#1310)

docs/Tables.md

@@ -45,6 +45,11 @@ Result:
 * merge cells across columns and rows
 
 ## Setting table & column widths
+The `col_widths` optional parameter can be provided to configure this.
+
+If a **single number** is provided as `col_widths`, it is interpreted as a **fixed column width in document units**.
+
+If an **array of numbers** is provided as `col_widths`, the values are considered to be **fractions of the full effective page width**, meaning that `col_widths=(1, 1, 2)` is strictly equivalent to `col_widths=(25, 25, 50)`.
 
 ```python
 ...

fpdf/table.py

@@ -61,7 +61,10 @@ def __init__(
             cell_fill_color (float, tuple, fpdf.drawing.DeviceGray, fpdf.drawing.DeviceRGB): optional.
                 Defines the cells background color
             cell_fill_mode (str, fpdf.enums.TableCellFillMode): optional. Defines which cells are filled with color in the background
-            col_widths (float, tuple): optional. Sets column width. Can be a single number or a sequence of numbers
+            col_widths (float, tuple): optional. Sets column width. Can be a single number or a sequence of numbers.
+                 When `col_widths` is a single number, it is interpreted as a fixed column width in document units.
+                 When `col_widths` is provided as an array, the values are considered to be fractions of the full effective page width,
+                 meaning that `col_widths=(1, 1, 2)` is strictly equivalent to `col_widths=(25, 25, 50)`.
             first_row_as_headings (bool): optional, default to True. If False, the first row of the table
                 is not styled differently from the others
             gutter_height (float): optional vertical space between rows

test/test_perfs.py

@@ -5,21 +5,22 @@
 from fpdf import FPDF
 
 HERE = Path(__file__).resolve().parent
+PNG_FILE_PATHS = list((HERE / "image/png_images/").glob("*.png"))
+PNG_FILE_PATHS.extend(
+    file_path
+    for file_path in (HERE / "image/png_test_suite/").glob("*.png")
+    if not file_path.name.startswith("x")
+)
 
 
 @ensure_exec_time_below(seconds=9)
 @ensure_rss_memory_below(mib=15)
-def test_intense_image_rendering():
-    png_file_paths = []
-    for png_file_path in (HERE / "image/png_images/").glob("*.png"):
-        png_file_paths.append(str(png_file_path))
-    for png_file_path in (HERE / "image/png_test_suite/").glob("*.png"):
-        if not png_file_path.name.startswith("x"):
-            png_file_paths.append(str(png_file_path))
+def test_intense_image_rendering(tmp_path):
     pdf = FPDF()
     for _ in range(2000):
         pdf.add_page()
-        for i, png_file_path in enumerate(png_file_paths):
+        for i, png_file_path in enumerate(PNG_FILE_PATHS):
             x = (i % 13) * 16
             y = (i // 13) * 16
             pdf.image(png_file_path, x=x, y=y)
+    pdf.output(tmp_path / "out.pdf")