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

CHANGELOG.md

@@ -20,12 +20,21 @@ This can also be enabled programmatically with `warnings.simplefilter('default',
 This release is the first performed from the [@py-pdf GitHub org](https://github.com/py-pdf), where `fpdf2` migrated.
 ### Added
 * [`FPDF.write_html()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.write_html) now supports heading colors defined as attributes (_e.g._ `<h2 color="#00ff00">...`)
-- documentation on how to use `livereload` to enable a "watch" mode with PDF generation: [Combine with livereload](https://py-pdf.github.io/fpdf2/CombineWithLivereload.html)
+* [`FPDF.table()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.table): Now supports padding in cells
+* [`FPDF.table()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.table): Now supports vertical alignment in cells 
+* [`FPDF.table()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.table): Now supports outer border width for rendering the outer border of the table with a different line-width.
+
+### Changed
+* [`FPDF.table()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.table): If the height of a row is governed by an image, then the default vertical alignment of the other cells is "center". This was "top". 
+This change was made for consistency between row-height governed by text or images. The old behaviour can be enforced using the new vertical alignment parameter.  
+
 ### Fixed
 * [`FPDF.image()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.image), when provided a `BytesIO` instance, does not close it anymore - _cf._ issue [#881](https://github.com/py-pdf/fpdf2/issues/881)
 * Invalid characters were being generated when a string contains parentheses - _cf._ issue [#884](https://github.com/py-pdf/fpdf2/issues/884)
 * Frozen Glyph dataclass was causing problems for FPDFRecorder with TTF fonts - _cf._ issue [#890](https://github.com/py-pdf/fpdf2/issues/890)
 * Edge case when parsing a Markdown link followed by a newline - _cf._ issue [#916](https://github.com/py-pdf/fpdf2/issues/916), and when bold/italics/underline markers are repeated
+- [`FPDF.table()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.table): images no longer overlap with cell borders - _cf._ issue [#892](https://github.com/py-pdf/fpdf2/issues/892)
+
 
 ## [2.7.5] - 2023-08-04
 ### Added

docs/Tables.md

@@ -67,6 +67,52 @@ Result:
 
 ![](table_align.jpg)
 
+## Setting cell padding
+
+_New in [:octicons-tag-24: 2.7.5](https://github.com/PyFPDF/fpdf2/blob/master/CHANGELOG.md)_
+
+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)
+
+Note: the `c_margin` parameter (default 1.0) also controls the horizontal margins in a cell. If a non-zero padding for left and right is supplied then c_margin is ignored.
+
+
+## Setting vertical alignment of text in cells
+
+_New in [:octicons-tag-24: 2.7.5](https://github.com/PyFPDF/fpdf2/blob/master/CHANGELOG.md)_
+
+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=VAlign.C) as table:
+        ...
+           row.cell(f"custom v-align", v_align=VAlign.T)  # <-- align to top
+```
+
 ## Setting row height
 ```python
 ...
@@ -77,7 +123,7 @@ with pdf.table(line_height=2.5 * pdf.font_size) as table:
 ## Disable table headings
 ```python
 ...
-with pdf.table(first_row_as_headings=False) as table:y
+with pdf.table(first_row_as_headings=False) as table:
     ...
 ```
 
@@ -229,9 +275,7 @@ Result:
 
 ## Column span
 Cells spanning multiple columns can be defined by passing a `colspan` argument to `.cell()`.
-The cells that are overwritten by the spanned cell are not rendered but must be added to the table.
-
-Result:
+Only the cells with data in them need to be defined. This means that the number of cells on each row can be different.
 
 ```python
     ...
@@ -245,17 +289,17 @@ Result:
         row = table.row()
         row.cell("A1")
         row.cell("A2", colspan=2)
-        row.cell("void") # <--- this cell is not rendered
         row.cell("A4")
 
         row = table.row()
         row.cell("B1", colspan=2)
-        row.cell("void")  # <--- this cell is not rendered
         row.cell("B3")
         row.cell("B4")
     ... 
 ```
 
+result:
+
 ![](image-colspan.png)
 
 ## Table from pandas DataFrame

docs/Text.md

@@ -2,13 +2,13 @@
 
 There are several ways in fpdf to add text to a PDF document, each of which comes with its own special features and its own set of advantages and disadvantages. You will need to pick the right one for your specific task.
 
-| method | lines | markdown support | HTML support | accepts new current position | details |
-| -- | :--: | :--: | :--: | :--: | -- |
-| [`.text()`](#text)  | one | no | no | fixed | Inserts a single-line text string with a precise location on the base line of the font.|
-| [`.cell()`](#cell)  | one | yes | no | yes | Inserts a single-line text string within the boundaries of a given box, optionally with background and border. |
-| [`.multi_cell()`](#multi_cell) | several | yes | no | yes | Inserts a multi-line text string within the boundaries of a given box, optionally with background and border. |
+| method | lines | markdown support | HTML support | accepts new current position | details                                                                                                                                                         |
+| -- | :--: | :--: | :--: | :--: |-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`.text()`](#text)  | one | no | no | fixed | Inserts a single-line text string with a precise location on the base line of the font.                                                                         |
+| [`.cell()`](#cell)  | one | yes | no | yes | Inserts a single-line text string within the boundaries of a given box, optionally with background and border.                                                  |
+| [`.multi_cell()`](#multi_cell) | several | yes | no | yes | Inserts a multi-line text string within the boundaries of a given box, optionally with background, border and padding.                                          |
 | [`.write()`](#write) | several | no | no | auto | Inserts a multi-line text string within the boundaries of the page margins, starting at the current x/y location (typically the end of the last inserted text). |
-| [`.write_html()`](#write_html) | several | no | yes | auto |  An extension to `.write()`, with additional parsing of basic HTML tags.
+| [`.write_html()`](#write_html) | several | no | yes | auto | An extension to `.write()`, with additional parsing of basic HTML tags.                                                                                         
 
 ## Typography and Language Specific Concepts 
 ### Supported Features
@@ -77,7 +77,7 @@ Allows printing text with word or character based line breaks. Those can be auto
 reaches the right border of the cell, or explicit (via the `\\n` character).
 As many cells as necessary are stacked, one below the other.
 Text can be aligned, centered or justified. The cell block can be framed and
-the background painted.
+the background painted. Padding between text and the cell edge can be specified in the same way as for tables.
 
 Using `new_x="RIGHT", new_y="TOP", maximum height=pdf.font_size` can be
 useful to build tables with multiline text in cells.

fpdf/enums.py

@@ -199,6 +199,26 @@ def coerce(cls, value):
         return super(cls, cls).coerce(value)
 
 
+class VAlign(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):
     """
     Indicates use of bold / italics / underline.