buhtzology.report.Report

class documentation

class Report: (source)

Constructor: Report(title, subtitle, heading_level_offset)

Content container for a report like document independent from its output format.

Such a report can have text paragraphs, headings, tables ( pandas.DataFrame), images and figures.

Class	`Control`	An element controlling page breaks, orientation and insertion of auto generated reference lists like table of contents.
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__`	No summary
Method	`auto_tags`	Use temporary default tags for new elements.
Method	`get_filtered_elements`	Generator returning only that elements fitting the tag rules.
Method	`heading`	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: Union[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`	Undocumented

def __len__(self): (source) ¶

@contextlib.contextmanager
def auto_tags(self, tags: Union[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:`Union[list, str]`	One tag or a list of tags.
Returns
`Report`	The instance itself.

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

Generator returning only that elements fitting the tag rules.

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: Union[list, str] = None): (source) ¶

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:`Union[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: Union[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.

def image(self, file_path_or_figure: Union[pathlib.Path, matplotlib.figure.Figure, matplotlib.axes.Axes, seaborn.axisgrid._BaseGrid, bytes], scale_factor: float = None, caption: str = None, tags: Union[list, str] = None): (source) ¶

Image or plotted figure as report element.

Parameters
file_path_or_figure:`Union[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:`Union[list, str]`	One or more tags for that element.

def image_dict(self, image_dict: dict, page_break: bool = False, tags: Union[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:`Union[list, str]`	Tag that element.

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

Add list of figures element.

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

Add list of tables element.

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

Just a page break.

def page_break_landscape(self, tags: Union[list, str] = None): (source) ¶

Page break with landscape orientation.

def page_break_portrait(self, tags: Union[list, str] = None): (source) ¶

Page break with portrait orientation.

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

Add a paragraph element.

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

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

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

Parameters
title:`str`	Heading of the section,
tags:`Union[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: Union[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:`Union[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: Union[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:`Union[list, str]`	One or more tag for that element.

def table_dict(self, dataframe_dict: dict, page_break: bool = False, autofit: bool = True, tags: Union[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:`Union[list, str]`	Tag that element.

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

Generate a table of content element.

def title(self, text: str, tags: Union[list, str] = None): (source) ¶

Title of the report.

The title is a heading of level 0.

Parameters
text:`str`	Title string.
tags:`Union[list, str]`	One or more tags for that title element.

def toggle_orientation(self, tags: Union[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: Union[NamedTuple, Report], tags: Union[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:`Union[NamedTuple, Report]`	The element.
tags:`Union[list, str]`	One or more tags used for that element.

def _page_break_with_orientation(self, orientation: _ControlType, tags: Union[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