boxcli documentation

BoxFactory

The BoxFactory class can be used to create boxes with a set style. This style can be updated later on so that you don’t have to create multiple instances of this class.

class boxcli.BoxFactory(Px: int, Py: int, style: Union[boxcli.box.BoxStyles, boxcli.styles.RawStyle], **kwargs)

Represents a Box factory.

This class can be used to create terminal boxes with ease.

Parameters:
  • Px (int) – Horizontal padding.
  • Py (int) – Vertical padding.
  • style (Union[BoxStyles, RawStyle]) – The style used to construct boxes. You can pass in a BoxStyles enum for builtin styles. or use boxcli.RawStyle to specify a custom one.
Keyword Arguments:
 
  • alignment (ContentAlignment) – The alignment used to construct boxes. Defaults to ContentAlignment.CENTRE
  • title_pos (TitlePosition) – The position of the title with respect to the box. Defaults to TitlePosition.INSIDE
  • colour (Union[ColourEnum, RGB]) – The colour to be used to construct the box border. Defaults to white colour.
get_box(title: str, content: str) → str

Returns a rendered box in the form of a string.

Parameters:
  • title (str) – The title of the box.
  • content (str) – The content of the box.
Returns:

The rendered box with the title and content provided by the user.

Return type:

str

Raises:
  • TitlePositionError – If the position of the title is not TitlePosition.INSIDE and yet it contains a newline.
  • TitleLengthError – If the length of the title is larger than the length of the largest line in the content.
  • DifferentLengthError – If the length of the top bar is not equal to the length of the bottom bar.
update(**kwargs) → None

Update the settings of the box factory.

Keyword Arguments:
 
  • Px (int) – The horizontal padding.
  • Py (int) – The vertical padding.
  • style (Union[BoxStyles, RawStyle]) – The style used to construct boxes
  • alignment (ContentAlignment) – The alignment of the content and title.
  • title_pos (TitlePosition) – The position of the title relative to the box.
  • colour (Union[ColourEnum, RGB]) – The colour of the box border.

Enumerations

class boxcli.BoxStyles

BoxStyle enumeration, to be used to specify the box style.

To see the box styles for yourself please go to the project README.

CLASSIC

The classic box style, with plus signs at the corners and dashes as the separators.

Type:BoxStyles
INVISIBLE

The invisible box style, with plus signs at the corners but no box outline separators.

Type:BoxStyles
BOLD

The bold box style.

Type:BoxStyles
ROUND

The round box style, with rounded edges.

Type:BoxStyles
SINGLE

The single box style.

Type:BoxStyles
DOUBLE

The double box style, similar to the single box style but has two lines in the separators and corners instead of single line.

Type:BoxStyles
SINGLE_DOUBLE

The single double box style.

Type:BoxStyles
DOUBLE_SINGLE

The double single box style.

Type:BoxStyles
class boxcli.ColourEnum

The colour enumeration, can be used to specify colour of box border.

BLACK

Black Colour.

Type:ColourEnum
RED

Red Colour.

Type:ColourEnum
GREEN

Green Colour.

Type:ColourEnum
BLUE

Blue Colour.

Type:ColourEnum
CYAN

Cyan Colour.

Type:ColourEnum
MAGENTA

Magenta Colour.

Type:ColourEnum
YELLOW

Yellow Colour.

Type:ColourEnum
WHITE

White Colour.

Type:ColourEnum
class boxcli.ContentAlignment

Content alignment enumeration.

To be used to specify the alignment of the content and title in the box.

CENTRE

Centred alignment.

Type:ContentAlignment
LEFT

Left-sided alignment.

Type:ContentAlignment
RIGHT

Right-sided alignment.

Type:ContentAlignment
class boxcli.TitlePosition

Title Position enumeration.

To be used to specify the position of the title relative to the box.

INSIDE

The title position inside the box with the content.

Type:TitlePosition
TOP

The title position on top of the box.

Type:TitlePosition
BOTTOM

The title position underneath the box.

Type:TitlePosition

Custom Styles and Colours

class boxcli.RawStyle(parts: dict)

Represents the raw style of the box.

This can be used to specify a custom style. You need to pass in a dictionary with the keys, horizontal, vertical, top_left, top_right, bottom_left, bottom_right, whose values should be single character strings or single digit ints. If you pass anything else the Box rendering WILL break.

Parameters:parts (dict) – A dictionary with the format described above.
class boxcli.RGB(rgb: Tuple[int, int, int])

Represents a colour in RGB format.

This can be used to specify a custom box colour with preferred RGB colour value.

Parameters:rgb (typing.Tuple[int, int, int]) – A tuple with the (R, G, B) values.
Raises:ValueError: – If the values inside the tuple exceed the RGB range.

Exceptions

exception boxcli.TitleLengthError

Raised when title length is larger than the top and bottom bars.

exception boxcli.TitlePositionError

Raised when the title position is inside and title has multiple lines.