Allowing to set padding in tables and multi_cell + vertical alignment in tables

docs/Tables.md

@@ -67,6 +67,45 @@ Result:
 
 ![](table_align.jpg)
 
+## Setting cell padding
+
+Cell padding (the space between the cells content and the edge of the cell) can be set globally or on a per-cell basis.
+
+Following the CCS standard the padding can be specified using 1,2 3 or 4 values. 
+- When one value is specified, it applies the same padding to all four sides.
+- When two values are specified, the first padding applies to the top and bottom, the second to the left and right.
+- When three values are specified, the first padding applies to the top, the second to the right and left, the third to the bottom.
+- When four values are specified, the paddings apply to the top, right, bottom, and left in that order (clockwise)
+
+```python
+    ...
+    style = FontFace(color=black, fill_color=red)
+    with pdf.table(line_height = pdf.font_size,padding=2) as table:
+        for irow in range(5):
+            row = table.row()
+            for icol in range(5):
+                datum = "Circus"
+                if irow == 3 and icol %2 == 0:
+                    row.cell("custom padding", style=style, padding = (2*icol,8,8,8))
+                else:
+                    row.cell(datum)
+```
+(also an example of coloring individual cells)
+
+![img.png](img_table_padding.png)
+
+## Setting vertical alignment of text in cells
+
+Can be set globally or per cell.
+Works the same way as padding, but with the `v_align` parameter.
+
+```python
+
+    with pdf.table(v_align = AlignV.C) as table:
+        ...
+           row.cell(f"custom v-align" v_align = AlignV.T) # <-- align to top
+```
+
 ## Setting row height
 ```python
 ...

fpdf/enums.py

@@ -198,6 +198,25 @@ def coerce(cls, value):
             return cls.L
         return super(cls, cls).coerce(value)
 
+class AlignV(CoerciveEnum):
+    """Defines how to vertically render text in a cell.
+    Default value is CENTER"""
+
+    C = intern("CENTER")
+    "Center text vertically"
+
+    T = intern("TOP")
+    "Place text at the top of the cell, but obey the cells padding"
+
+    B = intern("BOTTOM")
+    "Place text at the bottom of the cell, but obey the cells padding"
+
+    @classmethod
+    def coerce(cls, value):
+        if value == "":
+            return cls.C
+        return super(cls, cls).coerce(value)
+
 
 class TextEmphasis(CoerciveIntFlag):
     """

fpdf/fpdf.py

@@ -253,6 +253,22 @@ def get_page_format(format, k=None):
         raise FPDFPageFormatException(f"Arguments must be numbers: {args}") from e
 
 
+def get_padding_tuple(padding):
+    """Return a 4-tuple of padding values from a single value or a 2, 3 or 4-tuple according to CSS rules"""
+    if isinstance(padding, (int, float)):
+        return (padding, padding, padding, padding)
+    elif len(padding) == 2:
+        return (padding[0], padding[1], padding[0], padding[1])
+    elif len(padding) == 3:
+        return (padding[0], padding[1], padding[2], padding[1])
+    elif len(padding) == 4:
+        return padding
+
+    raise ValueError(
+        f"padding shall be a number or a sequence of 2, 3 or 4 numbers, got {str(padding)}"
+    )
+
+
 def check_page(fn):
     """Decorator to protect drawing methods"""
 
@@ -1413,6 +1429,42 @@ def _draw_rounded_rect(self, x, y, w, h, style, round_corners, r):
             self.line(point_5[0], point_5[1], point_6[0], point_6[1])
             self.line(point_7[0], point_7[1], point_8[0], point_8[1])
 
+    def _draw_box(self, x1, y1, x2, y2, border, fill):
+        """Draws a box using the current style"""
+
+        sl = []
+
+        k = self.k
+
+        # y top to bottom instead of bottom to top
+        y1 = self.h - y1
+        y2 = self.h - y2
+
+        # scale
+        x1 *= k
+        x2 *= k
+        y2 *= k
+        y1 *= k
+
+        if fill:
+            op = "B" if border == 1 else "f"
+            sl.append(f"{x1:.2f} {y2:.2f} " f"{x2 - x1:.2f} {y1 - y2:.2f} re {op}")
+        elif border == 1:
+            sl.append(f"{x1:.2f} {y2:.2f} " f"{x2 - x1:.2f} {y1 - y2:.2f} re S")
+
+        if isinstance(border, str):
+            if "L" in border:
+                sl.append(f"{x1:.2f} {y2:.2f} m " f"{x1:.2f} {y1:.2f} l S")
+            if "T" in border:
+                sl.append(f"{x1:.2f} {y2:.2f} m " f"{x2:.2f} {y2:.2f} l S")
+            if "R" in border:
+                sl.append(f"{x2:.2f} {y2:.2f} m " f"{x2:.2f} {y1:.2f} l S")
+            if "B" in border:
+                sl.append(f"{x1:.2f} {y1:.2f} m " f"{x2:.2f} {y1:.2f} l S")
+
+        s = " ".join(sl)
+        self._out(s)
+
     @check_page
     def ellipse(self, x, y, w, h, style=None):
         """
@@ -2857,6 +2909,7 @@ def _render_styled_text_line(
         fill: bool = False,
         link: str = "",
         center: bool = False,
+        padding=(0, 0, 0, 0),
     ):
         """
         Prints a cell (rectangular area) with optional borders, background color and
@@ -2931,45 +2984,38 @@ def _render_styled_text_line(
             self.x = self.l_margin + (self.epw - w) / 2
         page_break_triggered = self._perform_page_break_if_need_be(h)
         sl = []
+
         k = self.k
         # pylint: disable=invalid-unary-operand-type
         # "h" can't actually be None
+
+        # pre-calc border edges with padding
+
+        left = (self.x - padding[3]) * k
+        right = (self.x + w + padding[1]) * k
+        top = (self.h - self.y + padding[0]) * k
+        bottom = (self.h - (self.y + h) - padding[2]) * k
+
         if fill:
             op = "B" if border == 1 else "f"
             sl.append(
-                f"{self.x * k:.2f} {(self.h - self.y) * k:.2f} "
-                f"{w * k:.2f} {-h * k:.2f} re {op}"
+                f"{left:.2f} {top:.2f} " f"{right-left:.2f} {bottom-top:.2f} re {op}"
             )
         elif border == 1:
             sl.append(
-                f"{self.x * k:.2f} {(self.h - self.y) * k:.2f} "
-                f"{w * k:.2f} {-h * k:.2f} re S"
+                f"{left:.2f} {top:.2f} " f"{right-left:.2f} {bottom-top:.2f} re S"
             )
         # pylint: enable=invalid-unary-operand-type
 
         if isinstance(border, str):
-            x = self.x
-            y = self.y
             if "L" in border:
-                sl.append(
-                    f"{x * k:.2f} {(self.h - y) * k:.2f} m "
-                    f"{x * k:.2f} {(self.h - (y + h)) * k:.2f} l S"
-                )
+                sl.append(f"{left:.2f} {top:.2f} m " f"{left:.2f} {bottom:.2f} l S")
             if "T" in border:
-                sl.append(
-                    f"{x * k:.2f} {(self.h - y) * k:.2f} m "
-                    f"{(x + w) * k:.2f} {(self.h - y) * k:.2f} l S"
-                )
+                sl.append(f"{left:.2f} {top:.2f} m " f"{right:.2f} {top:.2f} l S")
             if "R" in border:
-                sl.append(
-                    f"{(x + w) * k:.2f} {(self.h - y) * k:.2f} m "
-                    f"{(x + w) * k:.2f} {(self.h - (y + h)) * k:.2f} l S"
-                )
+                sl.append(f"{right:.2f} {top:.2f} m " f"{right:.2f} {bottom:.2f} l S")
             if "B" in border:
-                sl.append(
-                    f"{x * k:.2f} {(self.h - (y + h)) * k:.2f} m "
-                    f"{(x + w) * k:.2f} {(self.h - (y + h)) * k:.2f} l S"
-                )
+                sl.append(f"{left:.2f} {bottom:.2f} m " f"{right:.2f} {bottom:.2f} l S")
 
         if self._record_text_quad_points:
             self._add_quad_points(self.x, self.y, w, h)
@@ -3419,6 +3465,8 @@ def multi_cell(
         wrapmode: WrapMode = WrapMode.WORD,
         dry_run=False,
         output=MethodReturnValue.PAGE_BREAK,
+        padding=0,
+        # cell_height = None,
     ):
         """
         This method allows printing text with line breaks. They can be automatic
@@ -3430,7 +3478,7 @@ def multi_cell(
 
         Args:
             w (float): cell width. If 0, they extend up to the right margin of the page.
-            h (float): cell height. Default value: None, meaning to use the current font size.
+            h (float): row height. Default value: None, meaning to use the current font size.
             txt (str): string to print.
             border: Indicates if borders must be drawn around the cell.
                 The value can be either a number (`0`: no border ; `1`: frame)
@@ -3461,12 +3509,21 @@ def multi_cell(
                 Can be useful when combined with `output`.
             output (fpdf.enums.MethodReturnValue): defines what this method returns.
                 If several enum values are joined, the result will be a tuple.
+            padding (float or Sequence): padding to apply around the text. Default value: 0.
+                When one value is specified, it applies the same padding to all four sides.
+                When two values are specified, the first padding applies to the top and bottom, the second to the left and right.
+                When three values are specified, the first padding applies to the top, the second to the right and left, the third to the bottom.
+                When four values are specified, the paddings apply to the top, right, bottom, and left in that order (clockwise)
+
 
         Using `new_x=XPos.RIGHT, new_y=XPos.TOP, maximum height=pdf.font_size` is
         useful to build tables with multiline text in cells.
 
         Returns: a single value or a tuple, depending on the `output` parameter value
         """
+
+        padding = get_padding_tuple(padding)
+
         if split_only:
             warnings.warn(
                 # pylint: disable=implicit-str-concat
@@ -3495,6 +3552,7 @@ def multi_cell(
                     dry_run=False,
                     split_only=False,
                     output=MethodReturnValue.LINES if split_only else output,
+                    padding=padding,
                 )
         wrapmode = WrapMode.coerce(wrapmode)
         if isinstance(w, str) or isinstance(h, str):
@@ -3538,18 +3596,27 @@ def multi_cell(
 
         if h is None:
             h = self.font_size
+
         # If width is 0, set width to available width between margins
         if w == 0:
             w = self.w - self.r_margin - self.x
+
+        prev_x, prev_y = self.x, self.y
+
+        # Apply padding to contents
+        # decrease maximum allowed width by padding
+        # shift the starting point by padding
+        w = w - padding[1] - padding[3]
         maximum_allowed_width = w - 2 * self.c_margin
+        self.x += padding[3]
+        self.y += padding[0]
 
         # Calculate text length
         txt = self.normalize_text(txt)
         normalized_string = txt.replace("\r", "")
         styled_text_fragments = self._preload_font_styles(normalized_string, markdown)
 
         prev_font_style, prev_underline = self.font_style, self.underline
-        prev_x, prev_y = self.x, self.y
         total_height = 0
 
         if not border:
@@ -3612,12 +3679,13 @@ def multi_cell(
                 align=Align.L if (align == Align.J and is_last_line) else align,
                 fill=fill,
                 link=link,
+                padding=padding,
             )
             page_break_triggered = page_break_triggered or new_page
             total_height += current_cell_height
             if not is_last_line and align == Align.X:
                 # prevent cumulative shift to the left
-                self.x = prev_x
+                self.x = prev_x + padding[3]
         if should_render_bottom_blank_cell:
             new_page = self._render_styled_text_line(
                 TextLine(
@@ -3640,6 +3708,7 @@ def multi_cell(
                 new_y=new_y,
                 fill=fill,
                 link=link,
+                padding=padding,
             )
             page_break_triggered = page_break_triggered or new_page
         if new_page and new_y == YPos.TOP:
@@ -3654,13 +3723,18 @@ def multi_cell(
 
         if new_y == YPos.TOP:  # We may have jumped a few lines -> reset
             self.y = prev_y
+        elif new_y == YPos.NEXT:  # move down by bottom padding
+            self.y += padding[2]
 
         if markdown:
             if self.font_style != prev_font_style:
                 self.font_style = prev_font_style
                 self.current_font = self.fonts[self.font_family + self.font_style]
             self.underline = prev_underline
 
+        # move right by right padding
+        self.x += padding[1]
+
         output = MethodReturnValue.coerce(output)
         return_value = ()
         if output & MethodReturnValue.PAGE_BREAK:
@@ -3674,7 +3748,7 @@ def multi_cell(
                 output_lines.append("".join(characters))
             return_value += (output_lines,)
         if output & MethodReturnValue.HEIGHT:
-            return_value += (total_height,)
+            return_value += (total_height + padding[0] + padding[2],)
         if len(return_value) == 1:
             return return_value[0]
         return return_value
@@ -4814,6 +4888,7 @@ def table(self, *args, **kwargs):
             width (number): optional. Sets the table width
             wrapmode (fpdf.enums.WrapMode): "WORD" for word based line wrapping (default),
                 "CHAR" for character based line wrapping.
+            padding (number, tuple): optional. Sets the cell padding. Can be a single number or a sequence of numbers (top, right, bottom, left) using CSS convention
         """
         table = Table(self, *args, **kwargs)
         yield table