Add add_table_from_df method to Document class

[jairuspace]

In our usage of this package, we find ourselves wanting to dump a pandas dataframe to a table. We thought this would be generally useful and might be a good addition to the package.

[scanny]

Hmm, yes, I can see the appeal, but the domain coupling seems undesireable to me, like some part of python-docx understanding the pandas domain.

I'd be inclined to consider this a "bridging" function most appropriate to keep outside the library, for these and other reasons:

• There could be any number of sources for table contents and we could not support all of them.
• It expands the domain knowledge required to maintain the library and the docx domain is plenty-big already.
• It adds a dependency on the pandas API to python-docx that is outside our control and could break part of our API without notice.
• ... I'm sure others if I reflected on it a while longer ...

This could easily be encapsulated in a function like so (just changing self to document:

def add_table_from_df(document, df, width, header):
    """Return a table with the data from the dataframe along with the column headings."""
    idx_shift = 1 if header else 0
    tbl = document.add_table(
        rows=df.shape[0] + idx_shift, cols=df.shape[1], width=width
    )

    if header:
        # Add the column headings
        for j in range(df.shape[1]):
            tbl.cell(0, j).text = df.columns[j]

    # Add the body of the data frame
    for i in range(df.shape[0]):
        for j in range(df.shape[1]):
            cell = df.iat[i, j]
            tbl.cell(i + idx_shift, j).text = str(cell)

    return tbl

That could go in a project.util module and could be posted on SO questions and so forth that ask about this sort of thing in order to help others working with pandas.

I think that would be a better solution for everyone and not increase the maintenance burden on python-docx.

[jairuspace]

I had a similar set of thoughts but thought it would be worth submitting a PR to see what the community thought. Thanks for the prompt feedback!

[jairuspace]

@scanny Heres a thought. We could abstract away pandas and expect a dictionary as input. Something like

{"column_1":["value_1","value_2","value_3"], "column_2"...}

This would still make building tables in python-docx a lot easier while still retaining the independence from the source of the table (i.e. pandas). Thoughts?

[scanny]

Yeah, you know, I was thinking that too, but didn't want to go on too long. The basic idea being to identify a "standard"-ish interchange format and then just support the one.

I guess I think that would be just as hard as building your own for a specific project. Tables are notoriously complicated things to describe when you get into merged cell (both horizontal and vertical merges), column and cell widths and so forth. So I'm not sure what a full-function interchange format would be and whether writing a function to write your data in that format would be any easier that a utility function.

Could be a little adapter package or something I suppose, like docx-table-adapters or something that took tabular objects from various places like pandas, numpy, maybe SQLAlchemy, etc. and blew them into tables.

At the same time, I wouldn't discount the value of a snippet that you publicize on SO and other places folks are likely to search. You can put it into a GitHub gist or wherever and make it easily snippable and I'm sure you'd see some uptake on that (if you can manage to measure it). You can see from this SO search that plenty of people ask about that sort of thing :)

[scanny]

I think if you make the title: "python-docx table from pandas dataframe" you'd soon become the top Google search hit for this :)

Nothing stopping you from asking and answering your own question on SO by the way, I've don't that plenty of times for FAQ types of topics and gotten plenty of upvotes on those.