pyreball.html

Main functions that serve as building blocks of the final html file.

Reference

Reference(default_text=None)

Class for creating references, i.e. anchors in HTML.

Parameters:

Name	Type	Description	Default
default_text	Optional[str]	Default text of the link. This text can be overriden by parameter of __call__ method. If not provided, Pyreball automatically inserts a text. For tables, images and code blocks, their number is used. For headings, their text is used.	None

__call__

__call__(text)

Create a link string with given text.

Parameters:

Name	Type	Description	Default
text	str	Text of the link.	required

Returns:

Type	Description
str	Link string.

__str__

__str__()

Create a link string with default text.

Returns:

Type	Description
str	Link string.

print

print(*values, sep='', end='\n')

Print values as strings to HTML file.

Parameters:

Name	Type	Description	Default
*values	Any	Zero or more values to be printed. Each value is converted to a string first.	()
sep	str	Separator string to concatenate the values with. Defaults to an empty space.	''
end	str	String appended after the values. Defaults to a newline.	'\n'

print_code_block

print_code_block(*values, caption=None, reference=None, align=None, caption_position=None, numbered=None, cl=None, attrs=None, pre_cl=None, pre_attrs=None, sep='', end='\n', syntax_highlight='python')

Print values as a source code into a preformatted block.

This element is used to display a source code in a block. It is possible to highlight the code syntax by setting syntax_highlight parameter to an appropriate string.

Parameters:

Name	Type	Description	Default
*values	Any	Zero or more values to be enclosed in the tag. All values are converted to strings.	()
caption	Optional[str]	Text caption.	None
reference	Optional[Reference]	Reference object.	None
align	Optional[str]	How to align the code block horizontally. Acceptable values are 'left', 'center', and 'right'. Defaults to settings from config or CLI arguments if None.	None
caption_position	Optional[str]	Where to place the caption. Acceptable values are 'top', and 'bottom'. Defaults to settings from config or CLI arguments if None.	None
numbered	Optional[bool]	Whether the caption should be numbered. Defaults to settings from config or CLI arguments if None.	None
cl	ClParameter	One or more class names to be added to the <code> tag. If a string is provided, it is used as it is. If a list of strings is provided, the strings are joined with space. If None, no class is added. If an empty list is provided, class attribute is added with an empty string.	None
attrs	AttrsParameter	Additional attributes to be added to the <code> tag. Dictionary {"key1": "value1", ..., "keyN": "valueN"} is converted to key1="value1" ... keyN="valueN". To construct boolean HTML attributes, set None for given key. Any quotes in values are not escaped.	None
pre_cl	ClParameter	The same as cl parameter, but for the <pre> tag.	None
pre_attrs	AttrsParameter	The same as attrs parameter, but for the <pre> tag.	None
sep	str	String separator of the values inside the tag. Defaults to an empty string.	''
end	str	String appended after the tag. Defaults to a newline.	'\n'
syntax_highlight	Optional[str]	Syntax highlighting language. Supported values can be obtained from highlight.js table https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md - see column "Aliases". If None, no highlighting is applied. When highlight is turned on, language name and 'block-highlight' are added to the <code> element as classes.	'python'

print_div

print_div(*values, cl=None, attrs=None, sep='', end='\n')

Print values into a div element.

Any value that is not a string is converted to a string first.

Parameters:

Name	Type	Description	Default
*values	Any	Zero or more values to be printed into the div.	()
cl	ClParameter	One or more class names to be added to the <div> tag. If a string is provided, it is used as it is. If a list of strings is provided, the strings are joined with space. If None, no class is added. If an empty list is provided, class attribute is added with an empty string.	None
attrs	AttrsParameter	Additional attributes to be added to the <div> tag. Dictionary {"key1": "value1", ..., "keyN": "valueN"} is converted to key1="value1" ... keyN="valueN". To construct boolean HTML attributes, set None for given key. Any quotes in values are not escaped.	None
sep	str	String separator of the values inside the tag. Defaults to an empty string.	''
end	str	String appended after the tag. Defaults to a newline.	'\n'

print_figure

print_figure(fig, caption=None, reference=None, align=None, caption_position=None, numbered=None, matplotlib_format=None, embedded=None)

Print a figure.

Parameters:

Name	Type	Description	Default
fig	FigType	A figure object.	required
caption	Optional[str]	Caption of the figure.	None
reference	Optional[Reference]	Reference object for link creation.	None
align	Optional[str]	How to align the graph horizontally. Acceptable values are 'left', 'center', and 'right'. Defaults to settings from config or CLI arguments if None.	None
caption_position	Optional[str]	Where to place the caption. Acceptable values are 'top', and 'bottom'. Defaults to settings from config or CLI arguments if None.	None
numbered	Optional[bool]	Whether the caption should be numbered. Defaults to settings from config or CLI arguments if None.	None
matplotlib_format	Optional[str]	Format for matplotlib figures. Acceptable values are 'svg', and 'png'. Defaults to settings from config or CLI arguments if None.	None
embedded	Optional[bool]	Whether to embed the figure directly into HTML; Only applicable for matplotlib svg images. Defaults to settings from config or CLI arguments if None.	None

print_h1

print_h1(string, reference=None)

Print h1 heading.

Parameters:

Name	Type	Description	Default
string	str	Content of the heading.	required
reference	Optional[Reference]	Reference object.	None

print_h2

print_h2(string, reference=None)

Print h2 heading.

Parameters:

Name	Type	Description	Default
string	str	Content of the heading.	required
reference	Optional[Reference]	Reference object.	None

print_h3

print_h3(string, reference=None)

Print h3 heading.

Parameters:

Name	Type	Description	Default
string	str	Content of the heading.	required
reference	Optional[Reference]	Reference object.	None

print_h4

print_h4(string, reference=None)

Print h4 heading.

Parameters:

Name	Type	Description	Default
string	str	Content of the heading.	required
reference	Optional[Reference]	Reference object.	None

print_h5

print_h5(string, reference=None)

Print h5 heading.

Parameters:

Name	Type	Description	Default
string	str	Content of the heading.	required
reference	Optional[Reference]	Reference object.	None

print_h6

print_h6(string, reference=None)

Print h6 heading.

Parameters:

Name	Type	Description	Default
string	str	Content of the heading.	required
reference	Optional[Reference]	Reference object.	None

print_table

print_table(df, caption=None, reference=None, align=None, caption_position=None, numbered=None, col_align=None, display_option=None, paging_sizes=None, scroll_y_height=None, scroll_x=None, sortable=None, sorting_definition=None, search_box=None, datatables_style=None, datatables_definition=None, **kwargs)

Print pandas DataFrame into HTML.

It uses DataTables JavaScript library to display the table.

Parameters:

Name	Type	Description	Default
df	DataFrame	Data frame to be printed.	required
caption	Optional[str]	Text caption.	None
reference	Optional[Reference]	Reference object.	None
align	Optional[str]	How to align the table horizontally. Acceptable values are 'left', 'center', and 'right'. Defaults to settings from config or CLI arguments if None.	None
caption_position	Optional[str]	Where to place the caption. Acceptable values are 'top', and 'bottom'. Defaults to settings from config or CLI arguments if None.	None
numbered	Optional[bool]	Whether the caption should be numbered. Defaults to settings from config or CLI arguments if None.	None
col_align	Optional[Union[str, List[str]]]	Alignment of individual columns. Can be provided as a list of values 'left', 'center', and 'right'. The list must match the number of columns, including the index when displayed. When provided as a simple string, this value is used for all columns. When None, default Pyreball alignment is used, i.e. numeric columns are right-aligned and all other columns left-aligned.	None
display_option	Optional[str]	How to display the table. This option is useful for long tables, which should not be displayed fully. Acceptable values are: 'full' (show the full table), 'scrolling' (show the table in scrolling mode on y-axis), 'paging' (show the table in paging mode). Defaults to settings from config or CLI arguments if None.	None
paging_sizes	Optional[List[Union[int, str]]]	A list of page sizes to display in paging mode. Allowed values in the list are integer values and string 'All' (the case is not important). When display_option is not 'paging', the value is ignored. Defaults to settings from config or CLI arguments if None. If it still remains None, values [10, 25, 100, "All"] are used.	None
scroll_y_height	Optional[str]	Height of the tables when display_option is set to 'scrolling'. Any string compatible with CSS sizing can be used, e.g. '300px', '20em', etc. Ignored with other display options. Defaults to settings from config or CLI arguments if None.	None
scroll_x	Optional[bool]	Whether to allow scrolling on the x-axis. If set to False, a wide table is allowed to overflow the main container. It is recommended to set this to True, especially with display_option='scrolling', because otherwise the table header won't interact properly when scrolling horizontally.	None
sortable	Optional[bool]	Whether to allow sortable columns. Defaults to settings from config or CLI arguments if None.	None
sorting_definition	Optional[List[Tuple[int, str]]]	How to sort the table columns initially, in the form of a list of tuples (<column_index>, <sorting>), where <sorting> is either 'asc' or 'desc'. When None, the columns are not pre-sorted.	None
search_box	Optional[bool]	Whether to show the search box for the table. Defaults to settings from config or CLI arguments if None.	None
datatables_style	Optional[Union[str, List[str]]]	One or more class names for styling tables using Datatables styling. See https://datatables.net/manual/styling/classes for possible values. Can be either a string with the class name, or a list of class name strings.	None
datatables_definition	Optional[Dict[str, Any]]	Custom setup for datatables in the form of a dictionary. This dictionary is serialized to json and passed to DataTable JavaScript object as it is. If set (i.e. not None), values of parameters col_align, display_option, paging_sizes, scroll_y_height, scroll_x, sortable, sorting_definition, and search_box are ignored. Note that datatables_style is independent of this parameter.	None
**kwargs	Any	Other parameters to pandas to_html() method. Note that parameter sparsify is explicitly set to False by Pyreball, because tables with multi-index would not be displayed correctly using DataTables library.	{}

set_title

set_title(title)

Set page title.

Note that this function does not have to be called at the beginning of the script. If this function is not called via pyreball and parameter keep_stdout is set to True, it just prints the title to stdout.

Parameters:

Name	Type	Description	Default
title	str	Title string.	required