xlwings.reports API Reference

xlwings.reports.create_report(template, output, book_settings=None, app=None, **data)

Writes the values of all key word arguments to the output file according to the template and the variables contained in there (Jinja variable syntax). Following variable types are supported:

strings, numbers, lists, simple dicts, NumPy arrays, Pandas DataFrames, PIL Image objects that have a filename and Matplotlib figures.

Parameters
  • template (str) – Path to your Excel template, e.g. r'C:\Path\to\my_template.xlsx'

  • output (str) – Path to your Report, e.g. r'C:\Path\to\my_report.xlsx'

  • book_settings (dict, default None) – A dictionary of xlwings.Book parameters, for details see: xlwings docs. For example: book_settings={'update_links': False}.

  • app (xlwings App, default None) –

    By passing in an xlwings App instance, you can control where your report runs and configure things like hidden=True. For details see: xlwings docs. By default, it creates the report in the currently active instance of Excel.

  • data (kwargs) – All key/value pairs that are used in the template.

Returns

wb

Return type

xlwings Book

Examples

In my_template.xlsx, put the following Jinja variables in two cells: {{ title }} and {{ df }}

>>> from xlwings.reports import create_report
>>> import pandas as pd
>>> df = pd.DataFrame(data=[[1,2],[3,4]])
>>> wb = create_report('my_template.xlsx', 'my_report.xlsx', title='MyTitle', df=df)

With many template variables it may be useful to collect the data first:

>>> data = dict(title='MyTitle', df=df)
>>> wb = create_report('my_template.xlsx', 'my_report.xlsx', **data)

If you need to handle external links or a password, use it like so:

>>> wb = create_report('my_template.xlsx', 'my_report.xlsx',
                       book_settings={'update_links': True, 'password': 'mypassword'},
                       **data)

You can control the Excel instance by passing in an xlwings App instance. For example, to run the report in a separate and hidden instance of Excel, do the following:

>>> import xlwings import xw
>>> from xlwings.reports import create_report
>>> app = xw.App(hidden=True)  # Separate and hidden Excel instance
>>> wb = create_report('my_template.xlsx', 'my_report.xlsx', app=app, **data)
>>> app.quit()  # Close the wb and quit the Excel instance
xlwings.reports.create_pdf(book, output=None, from_=None, to=None)

Creates a PDF report from the Excel workbook. NOTE: This is currently only availalbe on Windows.

Parameters
  • book (xlwings Book) – An xlwings Book, e.g. xw.Book(...) or the object returned by create_report.

  • output (str, optional) – Path to the PDF report, e.g. C:\my_report.pdf. By default, the report will be called the same as the Excel file, but with the .pdf extension.

  • from_ (int, optional) – First sheet that will be included in the PDF report (0 based indexing).

  • to (int, optional) – Last sheet that will be included in the PDF report (0 based indexing).

Returns

output – pdf file name

Return type

str

Examples

>>> from xlwings.reports import create_report, create_pdf
>>> import pandas as pd
>>> df = pd.DataFrame(data=[[1,2],[3,4]])
>>> wb = create_report('my_template.xlsx', 'my_report.xlsx', title='MyTitle', df=df)
>>> create_pdf(wb, from_=0, to=0)