HTML tables made easy in dominate!

[MarcBresson]

Hello, I wrote a small script to easily create HTML tables. You start by defining your table, the number of columns and rows, then you can put your data progressively!

Example:

doc = dominate.document(title='Dominate your HTML')

with doc:
    # initialize your table
    tab = HTMLTable(n_rows=1, n_cols=4)

    # populate the header row with a list of stringifiable objects or dom tags.
    tab.headers(["hello", strong("bonjour"), "ni hao", [1,2,3]])

    # you can fill a normal row one cell at a time
    tab[0][0] = "oui"
    tab[0][1] = td("comment ça va?", id="how_are_you_doing")
    tab[0][2] = "non"
    tab[0][3] = "si"

    # if you want more rows, you can append as many as you want
    tab.append_rows(1)

    # and you can also fill a row with a list of cells
    tab[1] = ["coucou", "bonjour", "salut", 3.1495]

    # convert your tab to dominate html !
    tab.html()

# print the beautiful result
print(doc.render())

Code:

from typing import TypeAlias

Stringifiable: TypeAlias = str | int | float | list

def ensure_dom_tag_in_list(list_to_check: list[dom_tag | Stringifiable]):
    """
    ensure that all elements of a list are a DOM tag. If one lement is not, it
    will attempt a conversion to a span tag. That way, a list of str can be
    provided without raising any exception.

    Parameters
    ----------
    list_to_check : list
        list of the elements to check.

    Raises
    ------
    TypeError
        raise an error if an element is not a dom_tag and is not stringifiable
        (has no __str__ method).
    """
    for i, ele in enumerate(list_to_check):
        if not isinstance(ele, dom_tag) and not hasattr(ele, "__str__"):
            raise TypeError(
                "All elements should be of type dominate.dom_tag or any object that can ",
                f"be stringified. Got a {type(ele)} at position {i}."
            )

def check_length(cell_list: list, n_cols: int):
    """
    check if cell list has the right number of elements to fit in a row.

    Parameters
    ----------
    cell_list : list
        list of the row cells.
    n_cols : int
        intended number of columns in the row.

    Raises
    ------
    ValueError
        if the number of cells is different from the number of intended columns
    """
    if len(cell_list) != n_cols:
            raise ValueError(f"{len(cell_list)} cells were provided for a row with {n_cols} columns.")

class HTMLTableRow:
    def __init__(self, n_cols: int):
        self.n_cols = n_cols
        self.cells = [None] * n_cols

    def __getitem__(self, idx: int) -> None | dom_tag | Stringifiable:
        return self.cells[idx]

    def __setitem__(self, idx: int, tag: dom_tag | Stringifiable):
        self.cells[idx] = tag

    def set(self, cell_list: list[dom_tag | Stringifiable]):
        """
        set all the cells of a row to the values of a list. If an element of
        the list is not an HTML tag, it will automatically convert it to a span
        """
        ensure_dom_tag_in_list(cell_list)
        check_length(cell_list, self.n_cols)

        self.cells = cell_list
    
    def html(self, default_tag: dom_tag = td) -> dom_tag:
        """
        generate html DOM tree of a row. The cell tag can be changed to adapt
        for header cells (th) and regular cells (td).
        """
        row = tr()

        for cell_value in self.cells:
            if isinstance(cell_value, default_tag):
                # if the cell is already a td tag
                row += cell_value
            else:
                row += default_tag(cell_value)

        return row

class HTMLTable:
    def __init__(self, n_rows: int, n_cols: int):
        self.n_rows = n_rows
        self.n_cols = n_cols

        self._rows = [HTMLTableRow(n_cols) for i in range(n_rows)]
        self._header_row: None | HTMLTableRow = None

    def headers(self, header_list: list[dom_tag | Stringifiable]):
        """
        add a header row to the table.
        """
        self._header_row = HTMLTableRow(self.n_cols)
        self._header_row.set(header_list)

    def __getitem__(self, idx: int):
        return self._rows[idx]

    def __setitem__(self, idx: int, cell_list: list[dom_tag | Stringifiable]):
        self._rows[idx].set(cell_list)

    def append_rows(self, n_new_rows: int = 1):
        """append n new rows at the end of the table.

        Parameters
        ----------
        n_new_rows : int, optional
            number of rows to append, by default 1
        """
        self._rows += [HTMLTableRow(self.n_cols) for i in range(n_new_rows)]

    def html(self, *, table_tag: table = None, thead_tag : thead = None, tbody_tag: tbody = None) -> table:
        """
        Generate the HTML DOM tree of a table.

        Parameters
        ----------
        table_tag : table, optional
            your own `table` tag from dominate.tag, by default None
        thead_tag : thead, optional
            your own `thead` tag from dominate.tag, by default None
        tbody_tag : tbody, optional
            your own `tbody` tag from dominate.tag, by default None

        Returns
        -------
        table
            the populated HTML table
        """
        if table_tag is None:
            table_tag = table()
        if thead_tag is None:
            thead_tag = thead()
        if tbody_tag is None:
            tbody_tag = tbody()

        with table_tag:
            if self._header_row is not None:
                thead_tag.add(self._header_row.html(default_tag=th))

            for row in self._rows:
                tbody_tag.add(row.html())
        
        return table_tag