Panels¶

Panels format and display data in a terminal. If you are used to working with graphical user interfaces, you can think of them like windows. They are how the application puts data on the screen.

Common Interfaces¶

In thurible, a panel is a subclass of thurible.panel.Panel. That class and a couple additional protocols define much of the common behavior of panel objects.

For more details on how panels are sized within the terminal, see Sizing Panels.

For more details on how to define how panels react to user input, see Active Keys.

Create a new Panel object. This class serves as a parent class for all panels, providing the core code relating to the area the panel fills in the terminal window.

Parameters:

height – (Optional.) The height of the pane.
width – (Optional.) The width of the pane.
term – (Optional.) A blessed.Terminal instance for formatting text for terminal display.
origin_y – (Optional.) The terminal row for the top of the panel.
origin_x – (Optional.) The terminal column for the left side of the panel.
fg – (Optional.) A string describing the foreground color of the pane. See the documentation for blessed for more detail on the available options.
bg – (Optional.) A string describing the background color of the pane. See the documentation for blessed for more detail on the available options.
panel_pad_top – (Optional.) Distance between the Y origin of the panel and the top of the interior of the panel. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. See Sizing Panels for more information.
panel_relative_height – (Optional.) The height of the interior of the panel in comparison of the full height of the panel. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. See Sizing Panels for more information.
panel_pad_bottom – (Optional.) Distance between the full height of the panel and the interior of the panel. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. See Sizing Panels for more information.
panel_pad_left – (Optional.) Distance between the X origin of the panel and the left side of the interior of the panel. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. See Sizing Panels for more information.
panel_relative_width – (Optional.) The width of the interior of the panel in comparison of the full width of the panel. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. See Sizing Panels for more information.
panel_pad_right – (Optional.) Distance between the full width of the panel and the right side of the interior of the panel. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. See Sizing Panels for more information.
panel_align_h – (Optional.) If the interior of the panel is smaller than the full width of the panel, this sets how the interior of the panel is aligned within the full height. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. See Sizing Panels for more information.
panel_align_v – (Optional.) If the interior of the panel is smaller than the full width of the panel, this sets how the interior of the panel is aligned within the full height. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. See Sizing Panels for more information.

Returns:

A Panel object.

Return type:

thurible.panel.Panel

Usage:

To create a new thurible.panel.Panel subclass:

from thurible import panel

class Spam(panel.Panel):
     def wobble(self):
         pass

spam = Spam(height=10, width=10)

Information on the sizing of thurible.panel.Panel objects can be found in the Sizing Panels section below.

action(key: Keystroke) → tuple[str, str][source]¶

Act on a keystroke typed by the user.

Parameters:: key – A blessed.keyboard.Keystroke object representing the key pressed by the user.
Returns:: A tuple object containing two str objects. The first string is any data that needs to be sent to the application. The second string contains any updates needed to be made to the terminal display.
Return type:: tuple

property active_keys: dict[str, Callable]¶

The key presses the class will react to and the handler that acts on that key press.

Returns:: A dict object where the keys are the representation of the blessed.keyboard.Keystroke object emitted when the key is pressed and the values are the action handler methods called when the key is pressed.
Return type:: dict

clear_contents() → str[source]¶

Clear the interior area of the panel.

Returns:: A str object containing the update needed to be made to the terminal display.
Return type:: str

property inner_height: int¶

The number of rows in the terminal contained within the interior of the panel.

Returns:: An int object.
Return type:: int

property inner_width: int¶

The number of columns in the terminal contained within the interior of the panel.

Returns:: An int object.
Return type:: int

property inner_x: int¶

The left-most column in the terminal of the interior of the panel.

Returns:: An int object.
Return type:: int

property inner_y: int¶

The top-most row in the terminal of the interior of the panel.

Returns:: An int object.
Return type:: int

register_key(key: str, handler: Callable) → None[source]¶

Declare the key presses the class will react to, and define the action the class will take when that key is pressed.

Parameters:

key – The name of the key pressed as returned by the representation of the blessed.keyboard.Keystroke emitted by the key press.
handler – And action handler to invoke when the key is pressed. An action handler is a function that takes an optional blessed.keyboard.Keystroke object and returns a string that contains any changes that need to be made to the terminal display as a result of the key press.

Returns:

None.

Return type:

NoneType

update(msg: Message) → str[source]¶

Act on a message sent by the application.

Parameters:: msg – A message sent by the application.
Returns:: A str object containing any updates needed to be made to the terminal display.
Return type:: str

class thurible.panel.Frame(frame_type: str | None = None, frame_bg: str = '', frame_fg: str = '', *args, **kwargs)[source]¶

Create a new thurible.panel.Frame object. This class serves as a parent class for all panels that can have a frame surrounding the interior of the panel. As a subclass of thurible.panel.Panel, it can also take those parameters and has those public methods.

Parameters:

frame_type – (Optional.) If a string, the string determines the frame used for the pane. If None, the pane doesn’t have a frame.
frame_fg – (Optional.) A string describing the foreground color of the frame. See the documentation for blessed for more detail on the available options. If fg is set and this is not, the frame will have the fg color.
frame_bg – (Optional.) A string describing the background color of the frame. See the documentation for blessed for more detail on the available options. If bg is set and this is not, the frame will have the bg color.

Returns:

A Frame object.

Return type:

thurible.panel.Frame

Usage:

To create a new thurible.panel.Frame subclass:

from thurible import panel

class Spam(panel.Frame):
     def wobble(self):
         pass

spam = Spam(height=10, width=10)

Information on the sizing of thurible.panel.Frame objects can be found in the Sizing Panels section below.

property frame: str¶

A string that will print panel’s frame in a terminal.

Returns:: A str object.
Return type:: str

property frame_height: int¶

The height in rows of the frame in the terminal.

Returns:: A str object.
Return type:: str

property frame_origin_x: int¶

The left-most column of the frame in the terminal.

Returns:: A str object.
Return type:: str

property frame_origin_y: int¶

The top-most row of the frame in the terminal.

Returns:: A str object.
Return type:: str

property frame_width: int¶

The width in columns of the frame in the terminal.

Returns:: A str object.
Return type:: str

property inner_height: int¶

The number of rows in the terminal contained within the interior of the panel.

Returns:: An int object.
Return type:: int

property inner_width: int¶

The number of columns in the terminal contained within the interior of the panel.

Returns:: An int object.
Return type:: int

property inner_x: int¶

The left-most column in the terminal of the interior of the panel.

Returns:: An int object.
Return type:: int

property inner_y: int¶

The top-most row in the terminal of the interior of the panel.

Returns:: An int object.
Return type:: int

class thurible.panel.Content(content_align_h: str | None = None, content_align_v: str = 'middle', content_pad_left: float | None = None, content_pad_right: float | None = None, content_relative_width: float | None = None, *args, **kwargs)[source]¶

Create a new thurible.panel.Content object. This class serves as a parent class for all panels that allow padding between the frame surrounding the interior of the panel and the content contained by the panel. The nature of that content is defined by the subclass. As a subclass of thurible.panel.Frame, it can also take those parameters and has those public methods.

Parameters:

content_align_h – (Optional.) The horizontal alignment of the contents of the panel. It defaults to center.
content_align_v – (Optional.) The vertical alignment of the contents of the penal. It defaults to middle.
content_pad_left – (Optional.) The amount of padding between the left inner margin of the panel and the content. It is measured as a float between 0.0 and 1.0, where 0.0 is no padding and 1.0 is the entire width of the panel is padding. The default is 0.0.
content_pad_right – (Optional.) The amount of padding between the right inner margin of the panel and the content. It is measured as a float between 0.0 and 1.0, where 0.0 is no padding and 1.0 is the entire width of the panel is padding. The default is 0.0.
panel_relative_width – (Optional.) The width of the content of the panel in comparison of the full width of the panel. It is a percentage expressed as a float between 0.0 and 1.0, inclusive. The default is 1.0.

Returns:

A Content object.

Return type:

thurible.panel.Content

Usage:

To create a new thurible.panel.Content subclass:

from thurible import panel

class Spam(panel.Content):
     def wobble(self):
         pass

spam = Spam(height=10, width=10)

Information on the sizing of thurible.panel.Content objects can be found in the Sizing Panels section below.

property content_width: int¶

The width available to content within the panel after padding has been taken into account.

Returns:: A int object.
Return type:: int

property content_x: int¶

The left-most column available to content within the panel after padding has been taken into account.

Returns:: A int object.
Return type:: int

property lines: list[str]¶

The lines available to be displayed in the panel.

Returns:: A list object containing each line as a str.
Return type:: list

class thurible.panel.Scroll(*args, **kwargs)[source]¶

Create a new thurible.panel.Scroll object. This class serves as a parent class for all panels that allow the user to scroll through content that overflows the interior of the panel. As a subclass of thurible.panel.Content, it can also take those parameters and has those public methods.

Returns:

A Panel object.

Return type:

thurible.panel.Panel

Usage:

To create a new thurible.panel.Content subclass:

from thurible import panel

class Spam(panel.Content):
     def wobble(self):
         pass

spam = Spam(height=10, width=10)

Information on the sizing of thurible.panel.Content objects can be found in the Sizing Panels section below.

Active keys:

This class defines the following active keys:

KEY_END: Scroll to the end of the content.

KEY_DOWN: Scroll down in the content.

KEY_HOME: Scroll to the top of the content.

KEY_PGDOWN: Scroll one screen down in the content.

KEY_PGUP: Scroll one page up in the content.

KEY_UP: Scroll one line up in the content.

action(key: Keystroke) → tuple[str, str][source]¶

Act on a keystroke typed by the user.

Parameters:: key – A blessed.keyboard.Keystroke object representing the key pressed by the user.
Returns:: A tuple object containing two str objects. The first string is any data that needs to be sent to the application. The second string contains any updates needed to be made to the terminal display.
Return type:: tuple

property inner_height: int¶

The number of rows in the terminal contained within the interior of the panel.

Returns:: An int object.
Return type:: int

property inner_y: int¶

The top-most row in the terminal of the interior of the panel.

Returns:: An int object.
Return type:: int

class thurible.panel.Title(footer_align: str = 'left', footer_frame: bool = False, footer_text: str = '', title_align: str = 'left', title_bg: str = '', title_fg: str = '', title_frame: bool = False, title_text: str = '', *args, **kwargs)[source]¶

Create a new thurible.panel.Title object. This class serves as a parent class for all panels that all the user to put a title on the top of the panel and a footer on the bottom of the frame. As a subclass of thurible.panel.Frame, it can alse take those parameters and has those public methods and properties.

Parameters:

footer_align – (Optional.) The horizontal alignment of the footer. The available options are “left”, “center”, and “right”.
footer_frame – (Optional.) Whether the frame should be capped on either side of the footer.
footer_text – (Optional.) The text contained within the footer.
title_align – (Optional.) The horizontal alignment of the title. The available options are “left”, “center”, and “right”.
title_bg – (Optional.) The background color of the title and footer. See the documentation for blessed for more detail on the available options.
title_fg – (Optional.) The foreground color of the title and footer. See the documentation for blessed for more detail on the available options.
title_frame – (Optional.) Whether the frame should be capped on either side of the title.
title_text – (Optional.) The text contained within the title.

Returns:

A Title object.

Return type:

thurible.panel.Title

Usage:

To create a new thurible.panel.Title subclass:

from thurible import panel

class Spam(panel.Title):
     def wobble(self):
         pass

spam = Spam(height=10, width=10)

Information on the sizing of thurible.panel.Title objects can be found in the Sizing Panels section below.

property footer: str¶

The footer as a string that could be used to update the terminal.

Returns:: A str object.
Return type:: str

property frame: str¶

A string that will print panel’s frame in a terminal.

Returns:: A str object.
Return type:: str

property inner_height: int¶

The number of rows in the terminal contained within the interior of the panel.

Returns:: An int object.
Return type:: int

property inner_y: int¶

The top-most row in the terminal of the interior of the panel.

Returns:: An int object.
Return type:: int

property title: str¶

The title as a string that could be used to update the terminal.

Returns:: A str object.
Return type:: str

Sizing Panels¶

Panels attempt to allow for the relative sizing of an element within a terminal. What does that mean?

A terminal window has a size in rows and columns. These rows and columns are measured in relation to a fixed-width character. A row is the height of one character. A column is the width of one character. For reasons that go back to the era of punch cards and hardware terminals, the common default size of a terminal window is 24 rows by 80 columns.

However, terminal widows do not have to be that standard size. Most terminal emulators that I’ve used allow you to set any size you want for the size of the terminal window, and you can resize the window after you open it. That creates a problem if you are trying to create a consistent interface for a terminal application. Sure, you can usually assume that a terminal is going to be 24×80, but if you run into a terminal that is 48×132, things might get weird.

Panel tries to solve that by allowing you to set the size of a panel relative to the terminal window, no matter what size that terminal window is. Now, there are some limitations to that. If the terminal window is 1×1, there isn’t much that can be shown in that terminal. However, it still should be useful for most terminal sizes you are going to run into.

The Positioning Onion¶

While it varies a little depending upon what classes a panel inherits, there are generally four layers of positioning that can happen within a panel:

Absolute
Frame (requires inheriting from thurible.panel.Frame)
Inner
Content (requires inheriting from thurible.panel.Content)

The Absolute Layer¶

The absolute layer is the first layer, and it is tracked in the following attributes:

height: The number of rows from the top of the panel to the bottom. If you don’t specify a height, it will default to the total number of rows in the current terminal window.
width: The number of columns from the left side of the panel to the right side. If you don’t specify a width, it will default to the number of columns in the current terminal window.
origin_x: The left-most column of the panel. If you don’t specify an origin_x, it will default to the left-most row of the terminal window.
origin_y: The top-most row of the panel. If you don’t specify an origin_y, it will default to the top-most row of the terminal window.

Note

While you can set these manually, doing so will prevent the panel from being resized when the terminal is resized. The only intended use case for setting these is to simplify the writing of unit tests. In all other cases, it’s recommended to allow these to default to the full size of the terminal window and use other parameters to position the panel.

The Frame Layer¶

For subclasses of thurible.panel.Frame, the next layer in positions the panel’s frame. It’s tracked by the following properties:

frame_height: The number of rows from the top of the panel’s frame to the bottom.
frame_width: The number of columns from the left side of the panel’s frame to the right side.
frame_x: The left-most column of the panel’s frame.
frame_y: The top-most row of the panel’s frame.

These are properties, so they cannot be set directly. You have to use relative positioning attributes to affect these. That is done with the attributes described in the The Inner Layer below.

The Inner Layer¶

The next positioning layer is the inner layer. It’s tracked by the following properties:

inner_height: The number of rows from the top of the panel’s interior to the bottom.
inner_width: The number of columns from the left side of the panel’s interior to the right side.
inner_x: The left-most column of the panel’s interior.
inner_y: The top-most row of the panel’s interior.

These are properties, so they cannot be set directly. You have to use the following attributes to set their value:

panel_relative_height: The proportional height of the interior of the panel as compared to the absoute height of the panel. The proportion is given a float with a value between 0.0 and 1.0, inclusive.
panel_relative_width: The proportional width of the interior of the panel as compared to the absoute width of the panel. The proportion is given a float with a value between 0.0 and 1.0, inclusive.
panel_align_h: The horizontal alignment of the interior of the panel within the absolute width of the panel. The alignment is given as one of the following strings: “left”, “center”, or “right”.
panel_align_v: The vertical alignment of the interior of the panel within the absolute height of the panel. The alignment is given as one of the following strings: “top”, “middle”, “bottom”.

Note

There are two additional attributes that are involved: panel_pad_left and panel_pad_right. While it is currently possible to set these yourself, that ability will likely be removed in future versions. It is recommended to avoid using these two attributes.

So how does this actually work? Let’s say we have the following panel in a standard 80 character wide terminal:

import thurible

panel = thurible.panel.Panel(
    origin_x=0,
    panel_relative_width=0.8,
    panel_align_h='right'
)

The width of the interior of the panel, as given by panel.inner_width is:

panel.width == 80
panel.panel_relative_width == 0.8
int(panel.width * panel.panel_relative_width) == 64

Since the interior is aligned “right”, the starting point of the interior, as given by panel.inner_x is:

panel.origin_x == 0
panel.width == 80
panel.inner_width == 16
panel.origin_x + (panel.width - panel.inner_width) == 16

Had the alignment been “center”, it would have been:

panel.origin_x == 0
panel.width == 80
panel.inner_width == 16
panel.origin_x + (panel.width - panel.inner_width) // 2 == 8

Had the alignment been “left”, it would have been:

panel.origin_x == 0

Warning

The above is not completely accurate for the current version of thurible. Instead, the panel uses panel.panel_relative_width to calculate the values of panel.panel_pad_left and panel.panel_pad_right. It then uses those values to determine the values for the inner_* attributes. However, the explanation above should be close to the results provided by the actual method, and future versions of thurible should move to the model described above.

Note

In subclasses of thurible.panel.Frame, adding a frame will affect the values of the inner_* attributes. The frame shrinks the interior by one character on each side of the interior. Therefore, if there had been a frame in the example above, panel.inner_width would have been 62 and the panel.inner_x would’ve been 17.

The Content Layer¶

For subclasses of thurible.panel.Content, the next layer in positions the panel’s content. It’s tracked by the following properties:

content_width: The number of columns from the left side of the panel’s content to the right side.
content_x: The left-most column of the panel’s content.

These are properties, so they cannot be set directly. You have to use the following attributes to set their value:

content_relative_width: The proportional width of the content of the panel as compared to the inner width of the panel. The proportion is given a float with a value between 0.0 and 1.0, inclusive.
content_align_h: The horizontal alignment of the content of the panel within the inner width of the panel. The alignment is given as one of the following strings: “left”, “center”, or “right”.

Note

There are two additional attributes that are involved: content_pad_left and content_pad_right. While it is currently possible to set these yourself, that ability will likely be removed in future versions. It is recommended to avoid using these two attributes.

These attributes work similar to the relative width and alignment attributes in The Inner Layer above.

Active Keys¶

An active key is a keyboard key that, when pressed by the user, will be intercepted and handled by the panel rather than passed on to the application.

An action handler is a method that accepts a key press, as represented by a blessed.keyboard.Keystroke object returned by blessed.Terminal.inkey.() It defines the behavior of the panel when the key is pressed, and it returns a str with any updates that need to be made to the terminal display.

The thurible library displays data to the user of a terminal application. In some cases, the user needs to navigate within that data. For example, the text displayed by a panel may be longer than the number of rows in the current terminal window, so the user needs to scroll down in the text to read all of it. Given a menu of options the user needs to select the option they want. Thurible panels will handle this sort of navigation for you through these active keys and action handlers.

Note

Active keys do not send any data back to your application. It’s not intended for your application to even be aware they were pressed. Any input that needs to go back to your application should be handled in Panel.action() and returned as the data str.

Defined Panels¶

The following panels are made available by thurible to cover common use cases.

class thurible.Dialog(message_text: str, options: Sequence[Option] = (Option(name='Yes', hotkey='y'), Option(name='No', hotkey='n')), *args, **kwargs)[source]¶

Create a new thurible.Dialog object. This class displays a message to the user and offers pre-defined options for the user to chose from. As a subclass of thurible.panel.Content and thurible.panel.Title, it can also take those parameters and has those public methods and properties.

Parameters:

message_text – The text of the prompt to be displayed to the user.
options – The options the user can chose from. This is a sequence of thurible.Option objects.

Returns:

A Dialog object.

Return type:

thurible.Dialog

Usage:

To create a new thurible.Dialog object with the message text spam and default yes/no options:

import thurible

dialog = thurible.Dialog('spam')

Information on the sizing of thurible.Dialog objects can be found in the Sizing Panels section below.

Active keys:

This class defines the following active keys:

KEY_ENTER: Select current option.

KEY_LEFT: Move to next option.

KEY_RIGHT: Move to previous option.

<hotkey>: Move to the defined option.

action(key: Keystroke) → tuple[str, str][source]¶

Act on a keystroke typed by the user.

Parameters:: key – A blessed.keyboard.Keystroke object representing the key pressed by the user.
Returns:: A tuple object containing two str objects. The first string is any data that needs to be sent to the application. The second string contains any updates needed to be made to the terminal display.
Return type:: tuple

property message: str¶

The message as a string that could be used to update the terminal.

Returns:: A str object.
Return type:: str

class thurible.Log(content: Sequence[str] | None = None, maxlen: int = 50, *args, **kwargs)[source]¶

Create a new thurible.Log object. This class displays messages from the application in “last in first out” (LIFO) format. It’s intended for situations were you want to provide the user a rolling display of status messages. As a subclass of thurible.panel.Content and thurible.panel.Title, it can also take those parameters and has those public methods and properties.

Parameters:

content – (Optional.) A sequence of strings to display in the panel when it is first displayed in the terminal. The first item in the sequence is considered the most recent.
maxlen – (Optional.) The total number of entries the thurible.Log will store. This is used to allow the terminal window to be resized without causing the loss of any messages. It’s not intended for the user to be able to scroll to view messages that have rolled off the terminal.

Returns:

A Log object.

Return type:

thurible.Log

Usage:

To create a new thurible.Log object:

import thurible

dialog = thurible.Log()

To create a new thurible.Log object that will show a maximum of three messages at a time and starts with a welcome message:

log = thurible.Log(['Welcome!',], maxlen=3)

To update the messages in a log use a thurible.Update message:

update = thurible.Update('spam')
log.update(update)

Information on the sizing of thurible.Log objects can be found in the Sizing Panels section below.

property lines: list[str]¶

The lines of text available to be displayed in the panel after they have been wrapped to fit the width of the interior of the panel. A message from the application may be split into multiple lines.

Returns:: A list object containing each line of text as a str.
Return type:: list

update(msg: Message) → str[source]¶

Act on a message sent by the application.

Parameters:: msg – A message sent by the application.
Returns:: A str object containing any updates needed to be made to the terminal display.
Return type:: str

class thurible.Menu(options: tuple[Option], option_align_h: str = 'left', select_bg: str = '', select_fg: str = '', content_align_v: str = 'top', *args, **kwargs)[source]¶

Create a new thurible.Menu object. This class provides a list of options the user can select. As a subclass of thurible.panel.Scroll and thurible.panel.Title, it can also take those parameters and has those public methods, properties, and active keys.

Parameters:

options – A sequence of thurible.Option objects defining the options available to the user.
option_align_h – (Optional.) The horizontal alignment of the options within the area that would be highlighted when the option is highlighted. If you think of each option as a button, it’s how the text is aligned on the face of the button. It defaults to “left”.
select_bg – (Optional.) The background color used to highlight an option.
select_fg – (Optional.) The foreground color used to highlight an option.
content_align_h – (Optional.) The horizontal alignment of the contents of the panel. It defaults to “left”. See thurible.panel.Content for more information.
content_align_v – (Optional.) The vertical alignment of the contents of the panel. It defaults to “top”.

Returns:

A thurible.Menu object.

Return type:

thurible.Menu

Usage:

To create a minimal new thurible.Menu object with two options:

import thurible

opt1 = thurible.Option('spam', hotkey='s')
opt2 = thurible.Option('eggs', hotkey='e')
menu = thurible.Menu([opt1, opt2])

Information on the sizing of thurible.Menu objects can be found in the Sizing Panels section below.

Active keys:

thurible.Menu adds the additional active key:

KEY_ENTER: Select the highlighted option.

Optional hot keys to highlight the options, as defined in the thurible.Option object for the option.

thurible.Menu modifies the behavior of the following active keys:

KEY_END: Highlight the last option, scrolling if needed.

KEY_DOWN: Highlight the next option, scrolling if needed.

KEY_HOME: Highlight the first option, scrolling if needed.

KEY_PGDOWN: Scroll to and highlight the option one screen down.

KEY_PGUP: Scroll to and highlight the option one screen up.

KEY_UP: Highlight the previous option, scrolling if needed.

For more information on active keys, see Active Keys.

action(key: Keystroke) → tuple[str, str][source]¶

Act on a keystroke typed by the user.

Parameters:: key – A blessed.keyboard.Keystroke object representing the key pressed by the user.
Returns:: A tuple object containing two str objects. The first string is any data that needs to be sent to the application. The second string contains any updates needed to be made to the terminal display.
Return type:: tuple

property field_width: int¶

The width of the highlightable area of each option as determined by the option with the most characters.

Returns:: A int object.
Return type:: int

property lines: list[str]¶

A list of str objects used to display the panel in the terminal.

Returns:: A list object of str objects.
Return type:: list

class thurible.Progress(steps: int, progress: int = 0, bar_bg: str = '', bar_fg: str = '', max_messages: int = 0, messages: Sequence[str] | None = None, timestamp: bool = False, *args, **kwargs)[source]¶

Create a new thurible.Progress object. This object displays a bar representing how much progress has been achieved towards a goal. As a subclass of thurible.panel.Content and thurible.panel.Title, it can also take those parameters and has those public methods and properties.

Parameters:

steps – The number of steps required to achieve the goal.
progress – (Optional.) The number of steps that have been completed.
bar_bg – (Optional.) A string describing the background color of the bar. See the documentation for blessed for more detail on the available options.
bar_fg – (Optional.) A string describing the foreground color of the bar. See the documentation for blessed for more detail on the available options.
max_messages – (Optional.) How many status messages should be stored to be displayed.
messages – (Optional.) Any status messages to start in the display. Since new messages are added to the display at the top, the messages passed in this sequence should be stored in reverse chronological order.
timestamp – (Optional.) Add a timestamp to the messages when they are displayed.

Returns:

A thurible.Progress object.

Return type:

thurible.Progress

Usage:

To create a thurible.Progress object with six steps:

import thurible

progress = thurible.Progress(6)

To send an update message to a thurible.Progress object that advances the bar use a thurible.Tick message:

tick = thurible.Tick('First step complete.')
progress.update(tick)

To send an update message to a thurible.Progress object that does not advance the bar use a thurible.NoTick message:

notick = thurible.NoTick('A thing happened.')
progress.update(notick)

Information on the sizing of thurible.Progress objects can be found in the Sizing Panels section below.

property lines: list[str]¶

The lines of text available to be displayed in the panel after they have been wrapped to fit the width of the interior of the panel. A message from the application may be split into multiple lines.

Returns:: A list object containing each line of text as a str.
Return type:: list

property progress_bar: str¶

The progress bar as a string.

Returns:: A str object.
Return type:: str

update(msg: Message) → str[source]¶

Act on a message sent by the application.

thurible.Progress responds to the following update messages:

thurible.progress.Tick: Advance the progress bar and display any message passed.
thurible.progress.NoTick: Do not advance the progress bar but display the message passed as a temporary message. The temporary message will be replaced by the next message received.

Parameters:: msg – A message sent by the application.
Returns:: A str object containing any updates needed to be made to the terminal display.
Return type:: str

class thurible.Splash(content: str = '', *args, **kwargs)[source]¶

Create a new thurible.Splash object. This class creates a splash screen that can be displayed in the terminal. As a subclass of thurible.panel.Content and thurible.panel.Title, it can also take those parameters and has those public methods and properties.

Parameters:

content – (Optional.) The text to display within the interior of the panel.

Returns:

A thurible.Splash object.

Return type:

thurible.Splash

Usage:

To create a minimal thurible.Splash object:

import thurible

splash = thurible.Splash()

To create a splash screen with the word “spam” in the middle of the screen:

splash = thurible.Splash('spam')

Information on the sizing of thurible.Splash objects can be found in the Sizing Panels section below.

property lines: list[str]¶

The lines of text available to be displayed in the panel after they have been wrapped to fit the width of the interior of the panel.

Returns:: A list object containing each line of text as a str.
Return type:: list

class thurible.Table(records: Sequence[DataclassInstance], inner_frame: bool = False, content_align_h: str = 'left', content_align_v: str = 'top', *args, **kwargs)[source]¶

Create a new thurible.Table object. This class displays a table of data to the user. As a subclass of thurible.panel.Scroll and thurible.panel.Title, it can also take those parameters and has those public methods, properties, and active keys.

Parameters:

records – A sequence of dataclasses that will be displayed within the panel. The data held by the dataclass can be of any type, but it must be able to be coerced into a :class:str.
inner_frame – (Optional.) Whether there should be a visible frame around each cell in the panel.
content_align_h – (Optional.) The horizontal alignment of the contents of the panel. It defaults to “left”.
content_align_v – (Optional.) The vertical alignment of the contents of the panel. It defaults to “top”.

Returns:

A thurible.Table object.

Return type:

thurible.Table

Usage:

To create a new thurible.Table object:

from dataclasses import dataclass
import thurible

@dataclass
class Record:
    name: str
    count: int

record_1 = Record('Graham', 1)
record_2 = Record('Michael', 2)
record_3 = Record('John', 3)
records = [record_1, record_2, record_3,]
table = thurible.Table(records)

Information on the sizing of thurible.Table objects can be found in the Sizing Panels section below.

property field_names: list[str]¶

The names of each field of data contained within the records being displayed.

Returns:: A list object containing each name as a str object.
Return type:: list

property field_widths: list[int]¶

The width in characters of each field in the table, as determined by the longest value for this field found in the dataclasses.

Returns:: A list object containing each width as an int.
Return type:: list

property lines: list[str]¶

The lines of text available to be displayed in the panel after they have been wrapped to fit the width of the interior of the panel.

Returns:: A list object containing each line of text as a str.
Return type:: list

class thurible.Text(content: str = '', content_align_h: str = 'left', content_align_v: str = 'top', *args, **kwargs)[source]¶

Create a new thurible.Text object. This class displays text to the document and allows the user to scroll through that text if it is too long to fit in the terminal window. As a subclass of thurible.panel.Scroll and thurible.panel.Title, it can also take those parameters and has those public methods, properties, and active keys.

Parameters:

content – (Optional.) The text to display in the interior of the panel.
content_align_h – (Optional.) The horizontal alignment of the contents of the panel. It defaults to “left”.
content_align_v – (Optional.) The vertical alignment of the contents of the panel. It defaults to “top”.

Returns:

A thurible.Text object.

Return type:

thurible.Text

Usage:

To create a new minimal thurible.Text object:

import thurible

text = thurible.Text()

To create a thurible.Text object containing the text “spam”.:

text = thurible.Text('spam')

Information on the sizing of thurible.Text objects can be found in the Sizing Panels section below.

Active keys:

This class defines the following active keys:

KEY_END: Scroll to the end of the content.

KEY_DOWN: Scroll down in the content.

KEY_HOME: Scroll to the top of the content.

KEY_PGDOWN: Scroll one screen down in the content.

KEY_PGUP: Scroll one page up in the content.

KEY_UP: Scroll one line up in the content.

property lines: list[str]¶

The lines of text available to be displayed in the panel after they have been wrapped to fit the width of the interior of the panel.

Returns:: A list object containing each line of text as a str.
Return type:: list

class thurible.TextDialog(message_text: str, *args, **kwargs)[source]¶

Create a new thurible.TextDialog object. This class displays a message to the user and allows them to input a string, which is send to the application. As a subclass of thurible.panel.Content and thurible.panel.Title, it can also take those parameters and has those public methods, properties, and active keys.

Parameters:

message_text – The text of the prompt to be displayed to the user.

Returns:

A thurible.TextDialog object.

Return type:

thurible.Text

Usage:

To create a thurible.TextDialog object containing the text “spam”.:

import thurible

text = thurible.TextDialog('spam')

Information on the sizing of thurible.TextDialog objects can be found in the Sizing Panels section below.

Active keys:

This class defines the following active keys:

KEY_BACKSPACE: Delete the previous character.

KEY_DELETE: Delete the next character.

KEY_END: Move the cursor to after the last character.

KEY_HOME: Move the cursor to the first character.

KEY_ENTER: Finish text entry and send input to the application.

KEY_LEFT: Move the cursor to the next character.

KEY_RIGHT: Move the cursor to the previous character.

While not registered as active keys, all other key presses that do not result in key sequences as defined by blessed or control characters as defined by the Unicode specification are intercepted by the panel. The str value of that key press is inserted into the text field at the position of the cursor.

For more information on active keys, see Active Keys.

action(key: Keystroke) → tuple[str, str][source]¶

Act on a keystroke typed by the user.

Parameters:: key – A blessed.keyboard.Keystroke object representing the key pressed by the user.
Returns:: A tuple object containing two str objects. The first string is any data that needs to be sent to the application. The second string contains any updates needed to be made to the terminal display.
Return type:: tuple