Defining Formats of Tables

Headers

class Column(title, name, style=None, cell_format=None, formatter=None, format_rules=None, display_type=None, width=None, max_width=None, horizontal_alignment=None, vertical_alignment=VerticalAlign.TOP)

Column definition. Contains mapping to columns in the output table (name) and defines header and value format.

Parameters:

• title (str) – Header title.

• name (str | bytes | Enum | int | float | complex | bool | None | tuple[str | bytes | Enum | int | float | complex | bool | None, ...]) – Column name to use.

• style (CellStyle | None) – Header style.

• cell_format (Format | None) – Value format.

• formatter (Callable[[Any, Series], Any] | None) – Custom format function.

• format_rules (list[FormatRule] | None) – Conditional formatting rules.

• width (int) – Set specific width of the column. The width should be set as a number of characters that should fit into the column.

• max_width (int) – Maximum width of the column. The width should be set as a number of characters that should fit into the column. If the column is narrower, it is not resized and automatic resizing takes effect. If the width parameter is set, it takes precedence over max_width.

• horizontal_alignment (HorizontalAlign | None) – Horizontal alignment of values.

class ColumnGroup(title, columns, style=None)

Column group.

Parameters:

• title (str) – Group title.

• columns (list[ColumnGroup | Column]) – List of columns or nested column groups (can be mixed).

• style (CellStyle | None) – Header style.

Text Formatting

class HorizontalAlign(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

CENTER = 'center'

Text align center.

LEFT = 'left'

Text align left.

RIGHT = 'right'

Text align right.

class VerticalAlign(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

BOTTOM = 'bottom'

Text align bottom.

MIDDLE = 'middle'

Text align middle.

TOP = 'top'

Text align top.

class Color(red, green=None, blue=None, alpha=None)

Color representation. Can be given either in RGB with individual components:

>>> Color(139, 188, 47)

Or as a single hex number with all components:

>>> Color(0xF6A413)

Parameters:

• red (float) – Red component or hexadecimal , 0 - 255

• green (float | None) – Green component, 0 - 255

• blue (float | None) – Blue component, 0 - 255

• alpha (float | None) – Alpha component, always 0 - 1.

change_luminosity(by)

Darkens the given color by specified value. The color is converted

Parameters:

by (float) – Darken by, should be a float between -1 and 1. If you darken any color by 1, it will become black, if you darken

Returns:

Darkened color.

classmethod from_hex(text)

Creates a color from string with hexadecimal representation of the color. :type text: str :param text: Color as RRGGBB or #RRGGBB hex string. :rtype: Color :return: A Color instance.

get_text_color(keep_alpha=True)

Gets a color that will provide enough contrast when placed on background filled with this color.

Currently returns either black or white. The decision is based on the luma channel from the color in YIQ color space. The alpha channel is not taken into account during the calculation, but the new color can have the same alpha value as the background one.

The method is described in the following article: https://24ways.org/2010/calculating-color-contrast/

Parameters:

keep_alpha (bool) – Whether the text color should have the same value for alpha channel as the background.

Returns:

Color for the text.

class TextFormat(foreground_color=None, size=None, bold=None, italic=None)

Represents a text format.

Parameters:

• foreground_color (Color | None) – Foreground color.

• size (int | None) – Font size.

• bold (bool | None) – Bold?

• italic (bool | None) – Italics?

BOLD: TextFormat = <ppc_robot_lib.utils.types.TextFormat object>

Predefined format for bold text.

ITALIC: TextFormat = <ppc_robot_lib.utils.types.TextFormat object>

Predefined format for italics.

class CellStyle(background_color=None, text_format=None, horizontal_alignment=None, vertical_alignment=None, wrap_strategy=None)

Represents a cell style – contains background color, text format and alignment.

Parameters:

• background_color (Color | None) – Background color.

• text_format (TextFormat | None) – Text format.

• horizontal_alignment (HorizontalAlign | None) – Horizontal text alignment.

• vertical_alignment (VerticalAlign | None) – Vertical text alignment.

• wrap_strategy (WrapStrategy | None) – Text wrapping.

class FormatType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

CURRENCY = 'currency'

Currency.

DATE = 'date'

Date.

DATE_TIME = 'date_time'

Date and time.

NUMBER = 'number'

Format as number.

PERCENT = 'percent'

Format as percents. The value shall be given as double divided by a 100, i.e. 0.1 means 10%.

SCIENTIFIC = 'scientific'

Scientific number format, e.g. 10e3.

TEXT = 'text'

Format as text.

TIME = 'time'

Time without date.

class Format(format_type, pattern=None)

Defines how to format values in the cell.

Parameters:

• format_type (FormatType) – Format type.

• pattern (str | None) – Optional pattern, see Google Sheets Date and Number Formats. The pattern might be replaced with another mechanism if we find that formats are not portable between different output services.

Conditional Formatting

class FormatRule

Abstract class for conditional format rules. Use one of:

• BoolConditionRule, or

• GradientRule.

class BoolConditionOperator(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Operators for the BoolConditionRule.

BETWEEN = 'between'

Value is in the defined range. The reference value must be given as a pair of (a, b).

CUSTOM_FORMULA = 'custom_formula'

Custom formula evaluates to TRUE. The formula should start with the = sign.

EQ = 'eq'

Value equals the reference value.

GT = 'gt'

Value is greater than the reference value.

GTE = 'gte'

Value is greater than or equal to the reference value.

LT = 'lt'

Value is less than the reference value.

LTE = 'lte'

Value is less than or equal to the reference value.

NEQ = 'neq'

Value does not equal the reference value.

NOT_BETWEEN = 'not_between'

Value is not in the defined range. The reference value must be given as a pair of (a, b).

class BoolConditionRule(op, value, style)

Boolean conditional rule. If the value matches the given condition, apply the given style.

Parameters:

• op (BoolConditionOperator) – Operator.

• value (float | list[float] | tuple[float] | str) – Reference value.

• style (CellStyle) – Style to apply if the condition matches.

class GradientPointType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Point type in the gradient for GradientRule.

MAX = 'max'

Determine the maximum value.

MIN = 'min'

Determine the minimum value.

NUMBER = 'number'

Compare to the given number.

PERCENT = 'percent'

Set point at the given percent.

PERCENTILE = 'percentile'

Set point at the given percentile.

class GradientPoint(value_type, value, color)

Point in the gradient for GradientRule.

Parameters:

• value_type (GradientPointType) – Type of the point (reference value).

• value (float | None) – Reference value. Not used for MIN and MAX point types.

• color (Color) – Color to apply.

class GradientRule(point_min, point_mid, point_max)

Gradient conditional format rule. The color of a cell is determined by its position on the scale defined by point_min, point_mid and point_max.

Parameters:

• point_min (GradientPoint) – Minumum point.

• point_mid (GradientPoint) – Middle point.

• point_max (GradientPoint) – Maximum point.