Reports#

class Image(filename)#

Use this class to provide images to either render_template().

Parameters

filename (str or pathlib.Path object) – The file name or path

class Markdown(text, style=<MarkdownStyle> h1.font: .bold: True paragraph.blank_lines_after: 1 unordered_list.bullet_character: • unordered_list.blank_lines_after: 1 strong.bold: True emphasis.italic: True)#

Markdown objects can be assigned to a single cell or shape via myrange.value or myshape.text. They accept a string in Markdown format which will cause the text in the cell to be formatted accordingly. They can also be used in mysheet.render_template().

Note

On macOS, formatting is currently not supported, but things like bullet points will still work.

Parameters

  • text (str) – The text in Markdown syntax

  • style (MarkdownStyle object, optional) – The MarkdownStyle object defines how the text will be formatted.

Examples

>>> mysheet['A1'].value = Markdown("A text with *emphasis* and **strong** style.")
>>> myshape.text = Markdown("A text with *emphasis* and **strong** style.")

New in version 0.23.0.

class MarkdownStyle#

MarkdownStyle defines how Markdown objects are being rendered in Excel cells or shapes. Start by instantiating a MarkdownStyle object. Printing it will show you the current (default) style:

>>> style = MarkdownStyle()
>>> style
<MarkdownStyle>
h1.font: .bold: True
h1.blank_lines_after: 1
paragraph.blank_lines_after: 1
unordered_list.bullet_character: •
unordered_list.blank_lines_after: 1
strong.bold: True
emphasis.italic: True

You can override the defaults, e.g., to make **strong** text red instead of bold, do this:

>>> style.strong.bold = False
>>> style.strong.color = (255, 0, 0)
>>> style.strong
strong.color: (255, 0, 0)

New in version 0.23.0.

formatter(func)#

Decorator

render_template(template, output, book_settings=None, app=None, **data)#

This function requires xlwings PRO.

This is a convenience wrapper around mysheet.render_template

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, pictures and Matplotlib/Plotly figures.

Parameters

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

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

  • book_settings (dict, default None) – A dict of xlwings.Book parameters, for details see: xlwings.Book. 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 visible=False. For details see xlwings.App. 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

Return type

xlwings Book

Examples

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

>>> from xlwings.reports import render_template
>>> import pandas as pd
>>> df = pd.DataFrame(data=[[1,2],[3,4]])
>>> mybook = render_template('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)
>>> mybook = render_template('my_template.xlsx', 'my_report.xlsx', **data)

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

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