buhtzology.report.Report

class documentation

class Report: (source)

Constructor: Report(title, subtitle, heading_level_offset)

Content container for a report like document.

The report container is independent from its output format. It can have text paragraphs, headings, tables (pandas.DataFrame), images and figures.

Class	`Control`	Control several page layout aspects.
Class	`Enumeration`	Ordered or unordered enumeration.
Class	`Heading`	Content element representing a heading element.
Class	`Image`	An image content element.
Class	`Paragraph`	Content element representing a text paragraph.
Class	`References`	Reference list, e.g. TOC, Figure, Tables.
Class	`Table`	Content element representing a data table.
Static Method	`image_to_bytes`	Create a bytes object from an image file or a plotted figure.
Method	`__getitem__`	Use the report with a `[]` operator like a list.
Method	`__init__`	Initiate a report instance.
Method	`__len__`	Return the number of elements.
Method	`auto_tags`	Use temporary default tags for new elements.
Method	`enumeration`	Enumeration element.
Method	`get_filtered_elements`	Return only elements that fit the tag rules.
Method	`heading`	Add a heading element.
Method	`heading_level`	Modify the current heading level.
Method	`heading_temporary`	Create headings on a none persistent level.
Method	`image`	Image or plotted figure as report element.
Method	`image_dict`	Add a bunch of images at once via (nested) dictionary.
Method	`list_of_figures`	Add list of figures element.
Method	`list_of_tables`	Add list of tables element.
Method	`page_break`	Just a page break.
Method	`page_break_landscape`	Page break with landscape orientation.
Method	`page_break_portrait`	Page break with portrait orientation.
Method	`paragraph`	Add a paragraph element.
Method	`section`	Open a section and return it as a child report object.
Method	`subtitle`	Subtitle for the document.
Method	`table`	Table element as `pandas.DataFrame`.
Method	`table_dict`	Add a bunch of tables at once via (nested) dictionary.
Method	`table_of_contents`	Generate a table of content element.
Method	`title`	Title of the report.
Method	`toggle_orientation`	Toggle the current existing page orientation.
Method	`_add_element`	Add a report element to the list and taking care of (auto) tags.
Method	`_page_break_with_orientation`	Page break including specific page orientation.
Instance Variable	`_current_auto_tags`	These tags are added by default to new elements.
Instance Variable	`_current_heading_level`	The current activate heading level.
Instance Variable	`_element_tags`	Tags for each element in `_elements` with the same index.
Instance Variable	`_elements`	List of all elements of that report.
Instance Variable	`_heading_level_offset`	Internally used with child-reports.
Instance Variable	`_xlsx_writer`	Undocumented

@staticmethod
def image_to_bytes(file_path_or_figure: pathlib.Path | matplotlib.figure.Figure | matplotlib.axes.Axes | seaborn.axisgrid._BaseGrid) -> bytes: (source) ¶

Create a bytes object from an image file or a plotted figure.

def __getitem__(self, idx: int): (source) ¶

Use the report with a [] operator like a list.

def __init__(self, title: str = None, subtitle: str = None, heading_level_offset: int = 0): (source) ¶

Initiate a report instance.

Parameters
title:`str`	The title element.
subtitle:`str`	The subtitle.
heading_level_offset:`int`	Heading level to start with.

def __len__(self): (source) ¶

Return the number of elements.

@contextlib.contextmanager
def auto_tags(self, tags: list | str) -> Report: (source) ¶

Use temporary default tags for new elements.

Example

import report

r = report.Report()
r.paragraph('Paragraph without a tag')

with r.auto_tags(['short', 'boss']):
    r.paragraph('Paragraph with tags "short" and "boss".')
    r.table(pandas.DataFrame())  # tagged table

r.paragraph('Another paragraph without a tag.')

Parameters
tags:`list \| str`	One tag or a list of tags.
Returns
`Report`	The instance itself.

def enumeration(self, items: Iterable[str], ordered: bool, style: str = None, tags: list | str = None): (source) ¶

Enumeration element.

When used with DocxDocument the visual result is sligthely different from the regular MS Words enumeration. For example the idention is missing. Another limitation is that nested enumerations are not supported.

Parameters
items:`Iterable[str]`	List of enumeration items as strings.
ordered:`bool`	Use bullet points (`False`) or numbers (`True`).
style:`str`	If used this overwrites `ordered` argument.
tags:`list \| str`	One or more tags for that element.

def get_filtered_elements(self, tags_allowed: Iterable[str] = None, tags_excluded: Iterable[str] = None) -> NamedTuple: (source) ¶

Return only elements that fit the tag rules.

It is a generator. Exclusion tags have higher priority then allowed tags. In practice it means that if an element have tag from tag_allowed and tags_excluded it is excluded from that generator.

Parameters
tags_allowed:`Iterable[str]`	Allowed tags.
tags_excluded:`Iterable[str]`	Tags to exclude.
Returns
`NamedTuple`	Undocumented
Yields
Elements that fitting the tag rules.

def heading(self, text: str, *, level: int = None, up: bool = None, down: bool = None, persistent: bool = True, tags: list | str = None): (source) ¶

Add a heading element.

Parameters
text:`str`	The heading string.
level:`int`	The level (starting with 1).
up:`bool`	Decrease current level and use that for this heading.
down:`bool`	Increase current level and use that for this heading.
persistent:`bool`	Stay on the level if `True` (default).
tags:`list \| str`	One or more tags for that element.

def heading_level(self, up: bool = None, down: bool = None, level: int = None) -> int: (source) ¶

Modify the current heading level.

The arguments are not mutually exclusive.

Parameters
up:`bool`	One level up (decrement).
down:`bool`	One level down (increment).
level:`int`	Explicit value.
Returns
`int`	Current heading level.

def heading_temporary(self, text: str, *, level: int = None, up: bool = None, down: bool = None, tags: list | str = None): (source) ¶

Create headings on a none persistent level.

It is a wrapper for heading(). None persistent means that the used level is set back to the previous level before that method was called.

Image or plotted figure as report element.

Parameters
file_path_or_figure:`pathlib.Path \| matplotlib.figure.Figure \| matplotlib.axes.Axes \| seaborn.axisgrid._BaseGrid \| bytes`	File or plot instance.
scale_factor:`float`	Float scaling factor from 0.0 to 1.0.
caption:`str`	String used as image caption.
tags:`list \| str`	One or more tags for that element.

def image_dict(self, image_dict: dict, page_break: bool = False, tags: list | str = None): (source) ¶

Add a bunch of images at once via (nested) dictionary.

The keys in that dictionary are used as heading or caption.

Parameters
image_dict:`dict`	(Nested) dictionary of image like instances.
page_break:`bool`	New page after each image?
tags:`list \| str`	Tag that element.

def list_of_figures(self, heading_text: str = 'List of Figures', tags: list | str = None): (source) ¶

Add list of figures element.

def list_of_tables(self, heading_text: str = 'List of Tables', tags: list | str = None): (source) ¶

Add list of tables element.

def page_break(self, toggle_orientation: bool = False, tags: list | str = None): (source) ¶

Just a page break.

def page_break_landscape(self, tags: list | str = None): (source) ¶

Page break with landscape orientation.

def page_break_portrait(self, tags: list | str = None): (source) ¶

Page break with portrait orientation.

def paragraph(self, text: str = '', style: str = None, tags: list | str = None): (source) ¶

Add a paragraph element.

Parameters
text:`str`	The paragraph content.
style:`str`	Style name (relevant for `docx` output).
tags:`list \| str`	One or more tags for that element.

def section(self, title: str = None, tags: list | str = None) -> Report: (source) ¶

Open a section and return it as a child report object.

Parameters
title:`str`	Heading of the section,
tags:`list \| str`	On eor more tags for that section.
Returns
`Report`	A report object as a child of the current report.

def subtitle(self, text: str, tags: list | str = None): (source) ¶

Subtitle for the document.

The subtitle is realized via a paragraph of style _Subtitle_.

Parameters
text:`str`	The subtitle string.
tags:`list \| str`	One or more tags for that subtitle element.

def table(self, dataframe: pandas.DataFrame, caption: str = None, *, note: str = None, autofit: bool = True, tags: list | str = None): (source) ¶

Table element as pandas.DataFrame.

Parameters
dataframe:`pandas.DataFrame`	The data object.
caption:`str`	String used as table caption.
note:`str`	String used as (foot)note.
autofit:`bool`	Adjust table width via autofit?
tags:`list \| str`	One or more tag for that element.

def table_dict(self, dataframe_dict: dict, page_break: bool = False, autofit: bool = True, tags: list | str = None): (source) ¶

Add a bunch of tables at once via (nested) dictionary.

The keys in that dictionary are used as heading or caption.

Parameters
dataframe_dict:`dict`	(Nested) dictionary of `pandas.DataFrame`'s.
page_break:`bool`	New page after each table?
autofit:`bool`	Set autofit to each the table.
tags:`list \| str`	Tag that element.

def table_of_contents(self, depth: int = 6, tags: list | str = None): (source) ¶

Generate a table of content element.

def title(self, text: str, tags: list | str = None): (source) ¶

Title of the report.

The title is a heading of level 0.

Parameters
text:`str`	Title string.
tags:`list \| str`	One or more tags for that title element.

def toggle_orientation(self, tags: list | str = None): (source) ¶

Toggle the current existing page orientation.

This will effect all past elements until the last page break.

def _add_element(self, element: NamedTuple | Report, tags: list | str = None): (source) ¶

Add a report element to the list and taking care of (auto) tags.

The instance attribute _current_auto_tags is taken into account.

Parameters
element:`NamedTuple \| Report`	The element.
tags:`list \| str`	One or more tags used for that element.

def _page_break_with_orientation(self, orientation: _ControlType, tags: list | str = None): (source) ¶

Page break including specific page orientation.

_current_auto_tags = (source) ¶

These tags are added by default to new elements.

_current_heading_level = (source) ¶

The current activate heading level.

_element_tags: list = (source) ¶

Tags for each element in _elements with the same index.

_elements: list = (source) ¶

List of all elements of that report.

_heading_level_offset = (source) ¶

Internally used with child-reports.

_xlsx_writer = (source) ¶

Undocumented