Improving docstrings

docs/Maths.md

@@ -128,25 +128,21 @@ columns = [list(df)]  # Get list of dataframe columns
 rows = df.values.tolist()  # Get list of dataframe rows
 data = columns + rows  # Combine columns and rows in one list
 
-# Start pdf creating
 pdf = FPDF()
 pdf.add_page()
 pdf.set_font("Times", size=10)
-line_height = pdf.font_size * 2.5
-col_width = pdf.epw / 4  # distribute content evenly
-
-for row in data:
-    for datum in row:
-        pdf.multi_cell(
-            col_width,
-            line_height,
-            datum,
-            border=1,
-            new_y="TOP",
-            max_line_height=pdf.font_size,
-        )
-    pdf.ln(line_height)
-pdf.output("table_with_cells.pdf")
+with pdf.table() as table:
+    table.borders_layout = "MINIMAL"
+    table.cell_fill_color = 200  # grey
+    table.cell_fill_logic = lambda i, j: i % 2
+    table.line_height = pdf.font_size * 2.5
+    table.text_align = "CENTER"
+    table.width= 160
+    for data_row in data:
+        with table.row() as row:
+            for datum in data_row:
+                row.cell(datum)
+pdf.output("table_from_pandas.pdf")
 ```
 
 Result:

docs/Tables.md

@@ -190,6 +190,10 @@ Result:
 
 ![](table_with_images_and_img_fill_width.jpg)
 
+## Table from pandas DataFrame
+
+_cf._ https://pyfpdf.github.io/fpdf2/Maths.html#using-pandas
+
 ## Using write_html
 
 Tables can also be defined in HTML using [`FPDF.write_html`](HTML.md).

fpdf/enums.py

@@ -190,7 +190,7 @@ def coerce(cls, value):
 class TextEmphasis(CoerciveIntFlag):
     """
     Indicates use of bold / italics / underline.
-    Because values positive integers, enum values can be easily combined:
+    This enum values can be combined with & and | operators:
 
         style = B | I
     """
@@ -227,6 +227,9 @@ class TableBordersLayout(CoerciveEnum):
     ALL = intern("ALL")
     "Draw all table cells borders"
 
+    NONE = intern("NONE")
+    "Draw zero cells border"
+
     INTERNAL = intern("INTERNAL")
     "Draw only internal horizontal & vertical borders"
 
@@ -775,7 +778,3 @@ class EncryptionMethod(Enum):
     NO_ENCRYPTION = 0
     RC4 = 1
     AES_128 = 2
-
-
-# This enum is only used internally:
-__pdoc__ = {"DocumentState": False}

fpdf/fpdf.py

@@ -942,7 +942,7 @@ def footer(self):
         """
         Footer to be implemented in your own inherited class.
 
-        This is automatically called by `FPDF.add_page()` and `FPDF.close()`
+        This is automatically called by `FPDF.add_page()` and `FPDF.output()`
         and should not be called directly by the user application.
         The default implementation performs nothing: you have to override this method
         in a subclass to implement your own rendering logic.
@@ -964,16 +964,7 @@ def set_draw_color(self, r, g=-1, b=-1):
             g (int): green component (between 0 and 255)
             b (int): blue component (between 0 and 255)
         """
-        if isinstance(r, (drawing.DeviceGray, drawing.DeviceRGB)):
-            # Note: in this case, r is also a Sequence
-            self.draw_color = r
-        else:
-            if isinstance(r, Sequence):
-                r, g, b = r
-            if (r, g, b) == (0, 0, 0) or g == -1:
-                self.draw_color = drawing.DeviceGray(r / 255)
-            else:
-                self.draw_color = drawing.DeviceRGB(r / 255, g / 255, b / 255)
+        self.draw_color = _convert_to_drawing_color(r, g, b)
         if self.page > 0:
             self._out(self.draw_color.serialize().upper())
 
@@ -989,16 +980,7 @@ def set_fill_color(self, r, g=-1, b=-1):
             g (int): green component (between 0 and 255)
             b (int): blue component (between 0 and 255)
         """
-        if isinstance(r, (drawing.DeviceGray, drawing.DeviceRGB)):
-            # Note: in this case, r is also a Sequence
-            self.fill_color = r
-        else:
-            if isinstance(r, Sequence):
-                r, g, b = r
-            if (r, g, b) == (0, 0, 0) or g == -1:
-                self.fill_color = drawing.DeviceGray(r / 255)
-            else:
-                self.fill_color = drawing.DeviceRGB(r / 255, g / 255, b / 255)
+        self.fill_color = _convert_to_drawing_color(r, g, b)
         if self.page > 0:
             self._out(self.fill_color.serialize().lower())
 
@@ -1014,16 +996,7 @@ def set_text_color(self, r, g=-1, b=-1):
             g (int): green component (between 0 and 255)
             b (int): blue component (between 0 and 255)
         """
-        if isinstance(r, (drawing.DeviceGray, drawing.DeviceRGB)):
-            # Note: in this case, r is also a Sequence
-            self.text_color = r
-        else:
-            if isinstance(r, Sequence):
-                r, g, b = r
-            if (r, g, b) == (0, 0, 0) or g == -1:
-                self.text_color = drawing.DeviceGray(r / 255)
-            else:
-                self.text_color = drawing.DeviceRGB(r / 255, g / 255, b / 255)
+        self.text_color = _convert_to_drawing_color(r, g, b)
 
     def get_string_width(self, s, normalized=False, markdown=False):
         """
@@ -4570,6 +4543,7 @@ def use_font_style(self, font_style: FontStyle):
     def table(self):
         """
         Inserts a table, that can be built using the `fpdf.table.Table` object yield.
+        Detailed usage documentation: https://pyfpdf.github.io/fpdf2/Tables.html
         """
         table = Table(self)
         yield table
@@ -4625,6 +4599,17 @@ def output(
         return self.buffer
 
 
+def _convert_to_drawing_color(r, g, b):
+    if isinstance(r, (drawing.DeviceGray, drawing.DeviceRGB)):
+        # Note: in this case, r is also a Sequence
+        return r
+    if isinstance(r, Sequence):
+        r, g, b = r
+    if (r, g, b) == (0, 0, 0) or g == -1:
+        return drawing.DeviceGray(r / 255)
+    return drawing.DeviceRGB(r / 255, g / 255, b / 255)
+
+
 def _is_svg(bytes):
     return bytes.startswith(b"<?xml ") or bytes.startswith(b"<svg ")
 

fpdf/image_parsing.py

@@ -25,7 +25,7 @@
 def load_image(filename):
     """
     This method is used to load external resources, such as images.
-    It is automatically called when resource added to document by `FPDF.image()`.
+    It is automatically called when resource added to document by `fpdf.FPDF.image()`.
     It always return a BytesIO buffer.
     """
     # if a bytesio instance is passed in, use it as is.

fpdf/table.py

@@ -10,7 +10,10 @@
 
 
 class Table:
-    "Object that `FPDF.table()` yields, used to build a table in the document"
+    """
+    Object that `fpdf.FPDF.table()` yields, used to build a table in the document.
+    Detailed usage documentation: https://pyfpdf.github.io/fpdf2/Tables.html
+    """
 
     def __init__(self, fpdf):
         self._fpdf = fpdf
@@ -47,7 +50,7 @@ def row(self):
         yield row
 
     def render(self):
-        "This is an internal method called by `FPDF.table()` once the table is finished"
+        "This is an internal method called by `fpdf.FPDF.table()` once the table is finished"
         if self.width > self._fpdf.epw:
             raise ValueError(
                 f"Invalid value provided .width={self.width}: effective page width is {self._fpdf.epw}"
@@ -87,11 +90,13 @@ def get_cell_border(self, i, j):
         """
         Defines which cell borders should be drawn.
         Returns a string containing some or all of the letters L/R/T/B,
-        to be passed to `FPDF.multi_cell()`.
+        to be passed to `fpdf.FPDF.multi_cell()`.
         Can be overriden to customize this logic
         """
         if self.borders_layout == TableBordersLayout.ALL.value:
             return 1
+        if self.borders_layout == TableBordersLayout.NONE.value:
+            return 0
         columns_count = max(len(row.cells) for row in self._rows)
         rows_count = len(self._rows)
         border = list("LRTB")
@@ -190,7 +195,7 @@ def _render_table_cell(
         lines = self._fpdf.multi_cell(
             w=col_width,
             h=row_height,
-            txt=cell.text or "",
+            txt=cell.text,
             max_line_height=cell_line_height,
             border=self.get_cell_border(i, j),
             align=text_align,
@@ -236,15 +241,17 @@ def _get_lines_heights_per_cell(self, i) -> List[List[int]]:
 
 
 class Row:
-    "Object that FPDF.row() yields, used to build a row in a table"
+    "Object that `Table.row()` yields, used to build a row in a table"
 
     def __init__(self):
         self.cells = []
 
-    def cell(self, text=None, img=None, img_fill_width=False):
+    def cell(self, text="", img=None, img_fill_width=False):
         """
+        Adds a cell to the row.
+
         Args:
-            text (str): optional. String content, can contain several lines.
+            text (str): string content, can contain several lines.
                 In that case, the row height will grow proportionally.
             img: optional. Either a string representing a file path to an image,
                 an URL to an image, an io.BytesIO, or a instance of `PIL.Image.Image`.