buhtzology.report.DocxDocument

class documentation

class DocxDocument(_GenericDocumentOutput): (source)

Constructor: DocxDocument(file_path, margins, autoupdate_fields, tags_allowed, ...)

Export a Report as MS Word docx file.

The docx (known as python-docx) package is used for that.

Method	`__init__`	No summary
Method	`add_paragraph_style`	Add a user-definied paragraph style to the document.
Method	`available_styles`	Return a `dict` of available styles.
Method	`control_to`	Convert `_ControlType` elements into their MS Word document corresponding components.
Method	`dataframe_to_table`	Convert a `pandas.DataFrame` in a MS Word table.
Method	`image`	Embed an image into the document.
Method	`page_numbering`	Set the page numbering behavior.
Method	`save`	Start the export of each element into the `docx` file.
Method	`set_page_orientation_landscape`	Current page/section in landscape orientation.
Method	`set_page_orientation_portrait`	Current page/section in portrait orientation.
Method	`string_to_heading`	Add heading.
Method	`string_to_paragraph`	Add paragraph.
Method	`toggle_page_orientation`	Toggle the current page/section's orientation.
Static Method	`_add_column_labels_one_level`	Used by `_add_row_and_column_labels()`.
Static Method	`_add_column_labels_two_levels`	Used by `_add_row_and_column_labels()`.
Static Method	`_add_field`	Helper adding a _field_ to an existing _run_.
Static Method	`_add_page_number`	Add a page number field to an existing paragraph.
Static Method	`_add_row_and_column_labels`	Format the labels of rows and columns.
Static Method	`_add_row_labels_one_level`	Used by `_add_row_and_column_labels()`.
Static Method	`_add_row_labels_two_levels`	Used by `_add_row_and_column_labels()`.
Static Method	`_cell_value_to_formated_string`	Helper for converting `pandas.DataFrame` cell values to a MS Word table.
Static Method	`_color_to_rgbcolor`	Convert a "color" value into format usable by `docx` (aka `python-docx`).
Static Method	`_element_with_attribute`	Helper to create an XML element with an attribute and its value.
Static Method	`_multiindex_to_dict`	Convert a MultiIndex to dictionary.
Static Method	`_table_autofit`	Helper to autofit table objects.
Method	`_activate_auto_update_fields`	All fields will semi-automatic updated.
Method	`_caption`	Add caption paragraph including name and numbering.
Method	`_init_docx_document_instance`	Initiate and setup the document instance `self._doc`.
Method	`_init_header_and_footer`	Setup header and footer elements of the document.
Method	`_init_styles`	Create some additional styles.
Method	`_set_page_orientation`	Set page orientation if different.
Method	`_setup_language`	Documents language.
Method	`_setup_spell_and_grammar_checking`	Undocumented
Method	`_table_of_something`	Generic method to create a reference list (e.g. TOC).
Instance Variable	`_additional_styles`	List of user defined styles add via `add_paragraph_style()`.
Instance Variable	`_autoupdate_fields`	Activate the auto update field feature.
Instance Variable	`_captions_position_figure`	Position of figure captions on top (0) or bottom of a figure. Bottom is default.
Instance Variable	`_captions_position_table`	Position of table captions on top (0) or bottom of a table. Bottom is default.
Instance Variable	`_doc`	Instance of `docx.document.Document`.
Instance Variable	`_footer_text`	String for the document footer.
Instance Variable	`_header_text`	String for the document header.
Instance Variable	`_language`	The language relevant for spell checking.
Instance Variable	`_margins`	A string indicate the type of margins (`narrow`, `moderate`).
Instance Variable	`_page_numbering`	A `dict` with settings about page numbering.
Instance Variable	`_spell_and_grammar_checking`	Document global checking of spelling and grammar.

Inherited from _GenericDocumentOutput:

Method	`show`	Open the generated document with the file type associated application.
Instance Variable	`file_path`	Path to the file.
Instance Variable	`tags_allowed`	List of tags for elements that are allowed.
Instance Variable	`tags_excluded`	List of tags for elements that are excluded.
Method	`_not_implemented`	Handler for not implemented elements.

def __init__(self, file_path: pathlib.Path, margins: str = 'narrow', autoupdate_fields: bool = True, tags_allowed: Union[List[str], str] = None, tags_excluded: Union[List[str], str] = None, text_header: str = None, text_footer: str = None, spell_and_grammar_checking: bool = False, language: str = None, captions_position_table: int = 1, captions_position_figure: int = 1): (source) ¶

overrides buhtzology.report._GenericDocumentOutput.__init__

Parameters
file_path:`pathlib.Path`	Path to the `docx` file to generate.
margins:`str`	Possible values are `narrow` or `moderate`.
autoupdate_fields:`bool`	Activate auto-updated all fields in the docx.
tags_allowed:`Union[List[str], str]`	See `_GenericDocumentOutput`.
tags_excluded:`Union[List[str], str]`	See `_GenericDocumentOutput`.
text_header:`str`	Text to put in document header.
text_footer:`str`	Text to put in document footer.
spell_and_grammar_checking:`bool`	Undocumented
language:`str`	Undocumented
captions_position_table:`int`	Captions before (0) or after (1, default) a table.
captions_position_figure:`int`	Captions before (0) or after (1, default) a figure.

def add_paragraph_style(self, name: str, based_on: str = None, font_name: str = None, font_pt: int = None, font_color: Union[tuple[int, int, int], str] = None, font_bgcolor: Union[tuple[int, int, int], str] = None): (source) ¶

Add a user-definied paragraph style to the document.

A style can then be used via its name when adding new paragraphs:

doc = DocxDocument(fp)
report = Report()

# Create the style
doc.add_paragraph_style(name='MyStyle', font_name='Fira Code')

# Use the style
report.paragraph('lore ipsum', style='MyStlye')

Parameters
name:`str`	Name of the new style.
based_on:`str`	Parent style that style should inherit from.
font_name:`str`	Font name.
font_pt:`int`	Font size in points.
font_color:`Union[tuple[int, int, int], str]`	Foreground color as name, Hex-value or RGB value tuple.
font_bgcolor:`Union[tuple[int, int, int], str]`	Background color of the font.

def available_styles(self) -> Dict[Hashable, list]: (source) ¶

Return a dict of available styles.

The dict keys are the categories of styles. The values are the style names as list.

Note

Seems to be unused. Also makes not much sense because _doc is None except while calling save().

def control_to(self, control_type: _ControlType): (source) ¶

Convert _ControlType elements into their MS Word document corresponding components.

Such components are page breaks, page orientation, reference lists for headings, figures and tables.

def dataframe_to_table(self, df: pandas.DataFrame, caption: str, note: str, autofit: bool, decimal_places: int = 2): (source) ¶

Convert a pandas.DataFrame in a MS Word table.

Parameters
df:`pandas.DataFrame`	The data frame.
caption:`str`	String for the table caption.
note:`str`	Used as (foot)note.
autofit:`bool`	Auto adjust the width of the table to its content.
decimal_places:`int`	Round of float values.

def image(self, image_bytes: bytes, scale_factor: float = None, caption: str = None): (source) ¶

Embed an image into the document.

The original picture source is not scaled, resized or converted. Scaling is done "dynamic" via MS Word specifying the view-size in Millimeters. That value is calculated based on original pixel size, the DPI and the scaling factor scale_factor.

Plots and figures from matplotlib or derivates are saved in PNG format with DEFAULT_DPI dpi.

Parameters
image_bytes:`bytes`	The image as bytes.
scale_factor:`float`	Factor to scale.
caption:`str`	Image caption string.

def page_numbering(self, pos: Union[int, str], prefix: str = '\tPage ', with_pagenum: bool = True, infix: str = ' of ', suffix: str = None): (source) ¶

Set the page numbering behavior.

Parameters
pos:`Union[int, str]`	Indicates header (`0`/`header`) or footer (`1`/`footer`).
prefix:`str`	String in front of the page number.
with_pagenum:`bool`	Add count of all pages.
infix:`str`	String between current page number and all pages count.
suffix:`str`	String at the end.

def save(self, report: Report) -> _GenericDocumentOutput: (source) ¶

Start the export of each element into the docx file.

Parameters
report:`Report`	The report instance with all elements.
Returns
`_GenericDocumentOutput`	Itself.

def set_page_orientation_landscape(self): (source) ¶

Current page/section in landscape orientation.

def set_page_orientation_portrait(self): (source) ¶

Current page/section in portrait orientation.

def string_to_heading(self, text: str, level: int): (source) ¶

Add heading.

def string_to_paragraph(self, text: str, style: str): (source) ¶

Add paragraph.

def toggle_page_orientation(self, section: docx.section.Section = None): (source) ¶

Toggle the current page/section's orientation.

@staticmethod
def _add_column_labels_one_level(df, tab): (source) ¶

Used by _add_row_and_column_labels().

@staticmethod
def _add_column_labels_two_levels(df, tab): (source) ¶

Used by _add_row_and_column_labels().

@staticmethod
def _add_field(run, field): (source) ¶

Helper adding a _field_ to an existing _run_.

A _run_ is a part of a paragraph. Fields are visible in MS Word as elements with gray background (e.g. for page numbers or citation references).

Credits: https://github.com/python-openxml/python-docx /issues/498#issuecomment-394143566

@staticmethod
def _add_page_number(paragraph: docx.text.paragraph.Paragraph, with_pagenum: bool, prefix: str, infix: str, suffix: str): (source) ¶

Add a page number field to an existing paragraph.

Credits: https://stackoverflow.com/a/62534711/4865723

@staticmethod
def _add_row_and_column_labels(df, tab): (source) ¶

Format the labels of rows and columns.

@staticmethod
def _add_row_labels_one_level(df, tab): (source) ¶

Used by _add_row_and_column_labels().

@staticmethod
def _add_row_labels_two_levels(df, tab): (source) ¶

Used by _add_row_and_column_labels().

@staticmethod
def _cell_value_to_formated_string(cell_value, decimal_places) -> str: (source) ¶

Helper for converting pandas.DataFrame cell values to a MS Word table.

The original cell_value is converted into a string. Decimal point and Thousand delimiter used based on the current locale.LC_NUMERIC. A float is rounded based on decimal_places using round().

@staticmethod
def _color_to_rgbcolor(color: Union[str, tuple[int, int, int]]) -> docx.shared.RGBColor: (source) ¶

Convert a "color" value into format usable by docx (aka python-docx).

The package webcolors is used to do the conversion.

Parameters
color:`Union[str, tuple[int, int, int]]`	Name of a color, Hex Color code as string or an integer tuple with RGB values for red, green and blue.
Returns
`docx.shared.RGBColor`	Undocumented

@staticmethod
def _element_with_attribute(element_name: str, attribute_name: str, attribute_value: str) -> docx.oxml.OxmlElement: (source) ¶

Helper to create an XML element with an attribute and its value.

@staticmethod
def _multiindex_to_dict(idx: pandas.MultiIndex) -> dict: (source) ¶

Convert a MultiIndex to dictionary.

Helper function used by _add_row_labels_two_levels() and _add_column_labels_two_levels().

Parameters
idx:`pandas.MultiIndex`	Index object (columns or rows of a pandas dataframe)
Returns
`dict`	The dictionary indexed by the first level of the multi index.

@staticmethod
def _table_autofit(tab: docx.table.Table): (source) ¶

Helper to autofit table objects.

Credits: https://github.com/python-openxml/python-docx /issues/209#issuecomment-566128709

def _activate_auto_update_fields(self): (source) ¶

All fields will semi-automatic updated.

This includes table of content and numbering in table and figure captions. In practice when opening such a docx file MS Word will ask if all fields should be updated.

Credits: https://stackoverflow.com/a/63799828/4865723

def _caption(self, caption: str, target: str): (source) ¶

Add caption paragraph including name and numbering.

Based on: https://github.com/python-openxml/python-docx/issues/359

Parameters
caption:`str`	The content of the caption.
target:`str`	The prefix name (e.g. _Table_ or _Figure_)

def _init_docx_document_instance(self): (source) ¶

Initiate and setup the document instance self._doc.

The method is not called by __init__() but save().

def _init_header_and_footer(self): (source) ¶

Setup header and footer elements of the document.

The behavior is based on the instance attributes _page_numbering, _header_text and _footer_text.

def _init_styles(self): (source) ¶

Create some additional styles.

def _set_page_orientation(self, orientation): (source) ¶

Set page orientation if different.

def _setup_language(self): (source) ¶

Documents language.

The language is set based on _language for all existing styles.

def _setup_spell_and_grammar_checking(self): (source) ¶

Undocumented

def _table_of_something(self, kind: _ReferenceKind, depth: int): (source) ¶

Generic method to create a reference list (e.g. TOC).

It is used for table_of_contents().

Credits

The code is based on the following sources

- ttps://stackoverflow.com/a/59170642/4865723
- https://github.com/python-openxml/python-docx/issues/36
- https://github.com/xiaominzhaoparadigm/python-docx-add-list-of-tables-figures/blob/master/LOT.py

_additional_styles: list = (source) ¶

List of user defined styles add via add_paragraph_style().

_autoupdate_fields = (source) ¶

Activate the auto update field feature.

_captions_position_figure = (source) ¶

Position of figure captions on top (0) or bottom of a figure. Bottom is default.

_captions_position_table = (source) ¶

Position of table captions on top (0) or bottom of a table. Bottom is default.

_doc = (source) ¶

Instance of docx.document.Document.

_footer_text = (source) ¶

String for the document footer.