reportng

reportng is a python module to build on the fly reports. It leverages Bootstrap 4 to automatically create using user defined bootswatch themes. reportng is capable of handling any python out including but not limited to api output, stdio output, sql queries etc.

Some example use cases of reportng are

  • Create a report for a tool
  • Create a report of a test
  • Create a report of debugging
  • etc…

reportng is designed to be stackable. This means that it follows the following convention

  • section
  • footer

Social

Installation

pip install reportng

Documentation

Reportng

class reportng.Reportng(report_name: str, brand: str, use_asciinema: bool = False, show_progress_bar: bool = True, show_search: bool = True, highlight_code: bool = True, theme_preview: bool = False, user_javascript: str = None, user_css: str = None, theme: str = 'lux', use_bootstrap: bool = False, search_highlight_color: str = '#f1c40f', navbar_background: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary')
__init__(report_name: str, brand: str, use_asciinema: bool = False, show_progress_bar: bool = True, show_search: bool = True, highlight_code: bool = True, theme_preview: bool = False, user_javascript: str = None, user_css: str = None, theme: str = 'lux', use_bootstrap: bool = False, search_highlight_color: str = '#f1c40f', navbar_background: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary')

The __init__ method for the Reportng class. The init method is used to set the brand and report_name for the report, along with optional arguments that can control custom css, js, and other built in features of Reportng. Features that can be enabled or disabled includes asciinema, progress bar, search, highlight etc.

Parameters:
  • report_name (str) – The name of the report
  • brand (str) – The author/brand of the report.
  • use_asciinema (bool, optional) – If asciinema player should be used. Defaults to False.
  • show_progress_bar (bool, optional) – Enable a top scrolling progress bar. Defaults to True.
  • show_search (bool, optional) – Enable search. Defaults to True.
  • highlight_code (bool, optional) – Enable code highlight. Defaults to True.
  • theme_preview (bool, optional) – Preview themes. Defaults to False.
  • user_javascript (str, optional) – Custom Javascript to inject in the header. Defaults to None.
  • user_css (str, optional) – Custom CSS to inject in the header. Defaults to None.
  • theme (str, optional) – A valid Bootstrap 4 theme. Defaults to “lux”.
  • use_bootstrap (bool, optional) – Base Bootstrap 4 theme. Defaults to False.
  • search_highlight_color (str, optional) – Highlight color for matching search results. Defaults to “#f1c40f”.
  • navbar_background (Literal[, optional) – Color for navbar. Defaults to “primary”.
asciinema(asciinema_link: str, title: str = '', is_section: bool = False, add_reference: reportng.rngtypes.Reference = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None, add_modal: reportng.rngtypes.Modal = None)

Add an asciinema section

Parameters:
  • asciinema_link (str) – Link to asciinema
  • title (str, optional) – Title for asciinema. Defaults to “”.
  • is_section (bool, optional) – Add as extra data to previous section. Defaults to False.
  • add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
  • add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
  • add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
  • add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns:

The Reportng object.

Return type:

Reportng

captions(content: str, text_color: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary', is_section: bool = True, raw_html: str = None)

Add captions to the previous section

Parameters:
  • content (str) – Caption content
  • text_color (Literal[, optional) – Color of caption. Defaults to “primary”.
  • is_section (bool, optional) – Add as extra data to previous section. Defaults to True.
  • raw_html (str, optional) – Add raw html. Defaults to None.
Returns:

The Reportng object.

Return type:

Reportng

cards(cards: List[reportng.rngtypes.Cards], is_section: bool = False, border_only: bool = False, section_title: str = None, add_alert: reportng.rngtypes.Alert = None, add_modal: reportng.rngtypes.Modal = None)

Add a cards section

Parameters:
  • cards (List[Cards]) – List of cards. Each card is a dictionary
  • is_section (bool, optional) – Add as data to previous section. Defaults to False.
  • border_only (bool, optional) – Show cards with borders only. Defaults to False.
  • section_title (str, optional) – Card title. Defaults to None.
  • add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
  • add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Raises:

TypeError – Cards should be a list of cards

Returns:

The Reportng object.

Return type:

Reportng

code(title: str, content: str, is_section: bool = True, add_reference: reportng.rngtypes.Reference = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None, add_modal: reportng.rngtypes.Modal = None)

Add a code section with highlighting

Parameters:
  • title (str) – Title of section
  • content (str) – Section content
  • is_section (bool, optional) – Add as extra data to previous section. Defaults to False.
  • add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
  • add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
  • add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
  • add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns:

The Reportng object.

Return type:

Reportng

custom_html(html: str)

Add a custom section with raw html inside a jumbotron

Parameters:html (str) – Raw html
Returns:The Reportng object.
Return type:Reportng
footer(message: str = '', twitter: str = None, linkedin: str = None, github: str = None, email: str = None, raw_html: str = None)

Add a footer section

Parameters:
  • message (str, optional) – Footer message. Defaults to “”.
  • twitter (str, optional) – Twitter link. Defaults to None.
  • linkedin (str, optional) – Linkedin link. Defaults to None.
  • github (str, optional) – Github link. Defaults to None.
  • email (str, optional) – Email address. Defaults to None.
  • raw_html (str, optional) – Add raw html. Defaults to None.
Returns:

The Reportng object.

Return type:

Reportng

Create an image carousel

Parameters:images (List[ImageCarouselType]) – List of image paths
Returns:The Reportng object.
Return type:Reportng
list_group(section_title: str, items: List[str], is_section: bool = False, raw_html: str = None, add_reference: reportng.rngtypes.Reference = None, add_modal: reportng.rngtypes.Modal = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None)

Add a list group section. A list group is a collection of strings presented as a list

Parameters:
  • section_title (str) – Section title
  • items (List[str]) – An array of list items as strings
  • is_section (bool, optional) – Add as data to previous section. Defaults to False.
  • raw_html (str, optional) – Add raw html. Defaults to None.
  • add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
  • add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
  • add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
  • add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns:

The Reportng object.

Return type:

Reportng

save(path: str) → None

Save the report

Parameters:path (str) – Path to save the report.
section(title: str, content: str, raw_html_content: Optional[str] = None, keep_formatting: bool = True, section_color: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary', title_background: bool = False, overflow_control: str = 'max-height: 70%; overflow: auto; margin-bottom: 20', text_color: typing_extensions.Literal['primary', 'red', 'green', 'yellow', 'blue', 'light'][primary, red, green, yellow, blue, light] = 'primary', use_h2_title: bool = False, is_section: bool = False, add_reference: reportng.rngtypes.Reference = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None, add_modal: reportng.rngtypes.Modal = None)

A section is considered the main container used by Reportng to hold values. Any string type value can be passed into a section.

Parameters:
  • title (str) – Title of the section
  • content (str) – Content for the section
  • raw_html_content (Union[str, None], optional) – Raw html content to include. Defaults to None.
  • keep_formatting (bool, optional) – Use a pre tag for the content to keep formatting. Defaults to True.
  • section_color (Literal[, optional) – Color of the section title bar. Defaults to “primary”.
  • title_background (bool, optional) – If true, background color is applied. Else, text color is changed. Defaults to False.
  • overflow_control (str, optional) – Uses valid CSS to control overflow of data. Defaults to rng.CSSControl.css_overflow.
  • text_color (Literal[, optional) – Text color of section. Defaults to “primary”.
  • use_h2_title (bool, optional) – Use h2 as title instead of h1. If h2, it will not allow jumping from navbar. Defaults to False.
  • is_section (bool, optional) – Add as extra data to the previous container. Defaults to False.
  • add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
  • add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
  • add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
  • add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns:

The Reportng object

Return type:

Reportng

section_collapsible(title: str, content: str = '', section_color: str = 'default', raw_html_content: str = '', keep_formatting: bool = True, **kwargs)

Create a collapsed section.

Parameters:
  • title (str) – Title for section
  • content (str, optional) – Section Content. Defaults to “”.
  • section_color (str, optional) – Section color. Defaults to “default”.
  • raw_html_content (str, optional) – Raw html content. Defaults to “”.
  • keep_formatting (bool, optional) – Preserve formatting. Defaults to True.
Returns:

The Reportng object.

Return type:

Reportng

table(table_header: List[str], data: List[List[str]], is_section: bool = False, section_title: str = '', header_color: typing_extensions.Literal['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark', 'default', 'red', 'green', 'blue', 'yellow', 'light'][primary, secondary, success, danger, warning, info, light, dark, default, red, green, blue, yellow, light] = 'dark', show_index: bool = False, add_reference: reportng.rngtypes.Reference = None, add_alert: reportng.rngtypes.Alert = None, add_badge: List[reportng.rngtypes.Badge] = None, add_modal: reportng.rngtypes.Modal = None)

Add a table section

Parameters:
  • table_header (List[str]) – Table header. Should be a list of strings corresponding to the number of data points.
  • data (List[List[str]]) – Table data. Should be a list of list of strings. For example [[1,2,3], [‘a’, ‘b’, ‘c’]].
  • is_section (bool, optional) – Add extra data to previous section. Defaults to False.
  • section_title (str, optional) – Title for section. Defaults to “”.
  • header_color (Literal[, optional) – Title header color. Defaults to “dark”.
  • show_index (bool, optional) – Show the table index. Defaults to False.
  • add_reference (Reference, optional) – Add a reference link. Argument is a dictionary with keys color and link Defaults to None.
  • add_alert (Alert, optional) – Add an alert. Argument is a dictionary with keys color and message Defaults to None.
  • add_badge (List[Badge], optional) – Add a reference link. Argument is a list of dictionaries with keys color and message Defaults to None.
  • add_modal (Modal, optional) – Add a modal message box. Argument is a dictionary with keys button, title and message Defaults to None.
Returns:

The Reportng object.

Return type:

Reportng

Helpers

JSCSS

class reportng.rnghelpers.JSCSS

This class controls constants that can be modified by the user and can be pointed to local files to host them locally. Can be used with DownloadAssets(download_path, rel_path) class to save all files locally and point them correctly

asciinema_css = 'https://cdnjs.cloudflare.com/ajax/libs/asciinema-player/2.4.1/asciinema-player.min.css'

Constant that handles asciinema-player.min.js

Type:asciinema_css
asciinema_js = 'https://cdnjs.cloudflare.com/ajax/libs/asciinema-player/2.4.1/asciinema-player.min.js'

Constant that handles asciinema-player.min.js

Type:asciinema_js
bootswatch = 'https://bootswatch.com/4/lux/bootstrap.min.css'

bootswatch theme

bs4_js = 'https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js'

Constant that handles bootstrap.min.js

Type:bs4_js
font_awesome = 'https://use.fontawesome.com/releases/v5.0.6/css/all.css'

Constant that handles font awesomes all.min.js

Type:font_awesome
highlightjs_css = 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css'

Constant that handles highlight.js default.min.js

Type:highlighjs_css
highlightjs_js = 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js'

Constant that handles highlight.min.js

Type:highlight_js
jquery = 'https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js'

Constant that handles jqery.min.js

Type:jquery
mark_js = 'https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js'

Constant that handles mark.js

Type:mark_js
popper_js = 'https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.0/umd/popper.min.js'

popper_js = Constant that handles popper.js

progressbar_js = 'https://cdn.rawgit.com/securisec/reportng/master/js/progressbar.js'

Constant that handles progressbar.js

Type:progressbar

CSSControl

class reportng.rnghelpers.CSSControl

CSS control

css_overflow = 'max-height: 70%; overflow: auto; margin-bottom: 20'

This value can be modified globally so that all containers are the same size similar to the output report_code_section. Can be modified directly, or using overflow option in report_section

Type:css_overflow
jumbotron_style = 'padding-bottom:3; padding-top:40'

Style attribute values of jumbotron

Type:jumbotron_style
not_sticky_section = 'padding-bottom:3; padding-top:40;'

Controls if the section is not a sticky

Type:not_stick_section
sticky_section_css = 'padding:0; margin-top:-2rem;'

Controls if section should sticky with preceeding section

Type:sticky_section_css

JSCustom

class reportng.rnghelpers.JSCustom

Class that handles all the custom JS code. It is best not to modify any of this code.

HelperFunctions

class reportng.rnghelpers.HelperFunctions

Some helper functions that does not impact how enduser uses reportng

static accordian_collapse(color, title, content, pre, raw_html, **kwargs)

Creates a collapsible accordian

static color_to_tag(s)

Maps colors to their appropriate tags

static convert_to_string(s)

Converts an object to string

static create_badges(b)

Creates badges at the bottom of a section

static make_alert(data)

Helper function that creates dismissable alerts

static make_cards(b_only, k, h, v)

Helper function that helps making cards

static ref_button(data)

Places a button with href on it.

static slide_indicator(num)

Helper function that controls how image slide count works

valid_tags = ['primary', 'secondary', 'success', 'danger', 'warning', 'info', 'light', 'dark', 'default', 'red', 'green', 'blue', 'yellow', 'light']

Valid options for colors/cards etc

Exceptions

exception reportng.rnghelpers.NotValidTag

Exception to handle invalid tag for background color control

exception reportng.rnghelpers.ObjectNotInitiated

Exception when a method is called but not initiated

exception reportng.rnghelpers.TooManyValues

Exception when too many args are passed

exception reportng.rnghelpers.TableError

Exception when there are problems with creating a table

Example

import reportng
from subprocess import Popen, PIPE
import requests

r = reportng.Reportng(report_name='Demo report',
                          brand='securisec')

# Multiline support
report.section(
'Multiline Demo',
"""
One line
Two line
""")

# Example stdio reporting
output = Popen('ls /tmp', shell=True, stdout=PIPE).stdout.read()
report += r.section('Output of ls', output,
                            tag_color='success')


# Example using web requests
req = requests.get('https://httpbin.org/status/418').text
report += r.section('Output of requests',
                            req, tag_color='info')


# Add an image carousel
report += r.image_carousel(
    'foo.jpg',
    'bar.jpg',
    'baz.jpg')


# Add description for image carousel
report += r.caption('Nice pictures!')


# Add a footer
report += r.footer(message='Hello from securisec!',
                          twitter='https://twitter.com/securisec',
                          github='https://github.com/securisec')


# Save the report!
r.save('demo_report.html')

Contents

Indices and tables