bwk 1.0.0

A simple Python windowing kit module for use with Blessed terminal formatting.

Blessed Window Kit (bwk)

A simple Python windowing kit module for use with Blessed terminal formatting.

• Documentation: https:blessed.readthedocs.io/en/1.20.0/https:blessed.readthedocs.io/en/1.20.0/
• Source Code: https:github.com/jquast/blessedhttps:github.com/jquast/blessed
• Installation: pip3 install blessed==1.20.0

• Use in your project by importing the module:
  • from bwk import Border, Window, echo, flush

bwk.characters.UnicodeChars

A struct-like class which contains Unicode characters commonly used in Text-Based User Interfaces (TUI's).

bwk

Constants:

• DEFAULT_WINDOW_BORDER: a bordercharstring (see Borderobject) which uses the solid line Unicode characters

def echo(str, end='', flush=False):

Parameters:

• str: the string to output
• end: a suffix to append to the string
• flush: whether or not to flush the buffer of the output stream

A convenience method for working with Blessed . This method will use the built-in Python print()method but with the above parameters defaulted differently. It is intended to be used as a way to buffer output for the current outstream without flushing it.

def flush():

A convenience method which flushes the current output stream. Equivalent to print('', end='', flush=True) .

def window_shopper(termstuff, *args, **kwargs):

Parameters:

• termstuff: a function to execute within a Blessed terminal context
• args: arguments to be passed to termstuff
• kwargs: keyword arguments to be passed to termstuff

This method provides a default terminal context to preview window layouts. The terminal context provided is A fullscreen blessed.Terminalwith a hidden cursor. Pressing any key ends the terminal context.

The termstufffunction must receive the Terminalobject as its first argument, it must include *argsand **kwargs, and has no return value.

def mywindowfunc(term, *args, **kwargs):
   # do window layout here

NOTE: The terminal context will automaticaly flush the stream, so you do not need to use the flush()method, only echo().

class Border:

A class for defining the borders of a Windowobject.

Attributes:

• upper_left_corner: ( default: '')
• top_border: ( default: '')
• upper_right_corner: ( default: '')
• right_border: ( default: '')
• lower_right_corner: ( default: '')
• bottom_border: ( default: '')
• lower_left_corner: ( default: '')
• left_border: ( default: '')

def __init__(self, borderchars=''):

Parameters:

• borderchars: a string of characters to use for the border

Creates a new Borderobject. The bordercharsstring must be exactly 8 characters long. If it is not, then no border is used. The characters form the corners and sides starting with the upper left corner and going clockwise.

Example: borderchars='1=2:3+4|'

1=====2
|     :
|     :
4+++++3

You can also directly alter any of the border characters via the object's attributes (see Attributes above)

class Window:

A rectangular container for displaying content.

Constants:

• TITLE_ALIGNS: A set of strings to identify the alignment of the window title

Attributes:

• term: the blessed.Terminalobject used for display
• x: the column of the terminal that the upper left corner is placed
• y: the row of the terminal that the upper left corner is placed
• height: the total height of the window (including the borders)
• width: the total width of the window (including borders)
• border: a Borderobject which defines the border display of the window
• title: the title displayed at the top of the window
• title_align: the alignment of the title
• content: a string of characters to display in the window

NOTE: When a Windowis defined, there must be content added to it, either by setting the contentattribute directly, or by overriding the render_content()method. The window is not buffered to the output stream unless the render()method is called.

def __init__(self, term, x, y, height=None, width=None, fore_color=None, bg_color=None, border=DEFAULT_WINDOW_BORDER, title='', title_align='center'):

Parameters:

• term: the blessed.Terminalobject used for display
• x: the column of the terminal that the upper left corner is placed
• y: the row of the terminal that the upper left corner is placed
• height: the total height of the window (including the borders)
• width: the total width of the window (including borders)
• fore_color: not yet implemented
• bg_color: not yet implemented
• border: a bordercharstring or a Borderobject
• title: the title displayed at the top of the window
• title_align: the alignment of the title

If heightor widthis not provided, then that dimension will stretch all the way to the edge of the terminal. If borderis set to None, then no border will be drawn. The titlewill not be displayed unless there is a borderwith at least the top_borderattribute set. The title_alignstring must be one of the following values: left, center, or right.

def render(self):

Echoes the window to the output stream buffer (via the echo()function). The content of the window is limited by the heightand widthof the window (minus the height and width of the border). Any characters which are beyond the dimensions of the window will not be displayed.

def render_content(self, max_width, max_height):

Parameters:

• max_width: the total width of the window (minus the width of the borders)
• max_height: the total height of the window (minus the height of the borders)

Returns: A string or list of strings which will fit in the dimensions of the window.

This method is provided to be overriden, either by overwriting the instance attrbute render_contentwith a different function, or by overriding this function in a subclass. By default, this method simply returns the window's contentstring.

This method is called by the render()method. If the return value is a string, render()will iterate over the each line (delimited by a n). If the return value is a list of strings, render()will iterate over the list.

Blessed Window Kit Screen Tools (bwk.screen)

An extension of the Blessed Window Kit (BWK) for quickly building Text-Based User Interface (TUI) applications.

• Use in your project by importing the module:
  • import bwk.screen

class Screen:

A barebones implementation for rendering output to a terminal and processing input. This can be used with or without the BWK itself (see the ScreenManagerclasses below).

Attributes:

• man: a ScreenManagerwhich the sceen is associated to.
• name: the name of the screen
• commands: a dictionary of commands. Each value is a function which will execute when input matching its key is received by the screen.

def __init__(self, manager, name, commands={}):

Parameters:

• man: a ScreenManagerwhich the sceen is associated to.
• name: the name of the screen
• commands: a dictionary of commands. Each value is a function which will execute when input matching its key is received by the screen.

def set_commands(self):

Use this method to append commands to the screen. When the process_input()method is called, it checks if the input matches any keys in self.commands. If there is a matching key, the screen will execute the function stored by that key. Typically this method is used to add methods of the class itself ( self.method_name()), as they cannot be accessed easily from outside the class. Therefore, the typical structure of this method looks like the example below.

Example:

def set_commands(self):
  self.commands['d'] = self.method_one
  self.commands['x'] = self.method_two
  self.commands['3'] = self.method_three

def pre_process_input(self, userin):

Parameters:

• userin: the input received to the screen

This method executes after a screen receives input, but before a matching command is executed.

def post_process_input(self, userin):

Parameters:

• userin: the input received to the screen

This method executes after the input has been processed by the screen (which may be a command, or an error).

def process_input(self, userin):

Parameters:

• userin: the input received to the screen

This is the main method which handles input to the screen. It executes the following steps in order:

• self.pre_process_input(userin)
• if userinmatches a key in self.commands,executes the corresponding function
• if userindoes not match a key in self.commands,executes self.process_input_error(userin)
• self.post_process_input(userin)

def process_input_error(self, userin):

Parameters:

• userin: the input received to the screen

This method executes when an input does not match any key in self.commands.

def render(self):

This method will render the screen content to the terminal.

class GenericScreenManager:

A barebones implementation for running an application loop with Screenobjects.

Attributes:

• running: a boolean indicating if the run loop should continue
• curr_screen: the current Screenobject being used to render output and process input

def __init__(self):

Initializes the manager.

def pre_run(self):

This method executes before the run loop begins. Any necessary preparation before the application starts should be done here.

def post_run(self):

This method executes after the run loop ends. Any necessary cleanup after the application has ended should be done here.

def run(self):

This is the main entrypoint for the ScreenManager. Execute this method to begin the application loop, including the pre_run()and post_run()methods.

def run_loop(self):

The actual implementation of the application loop. It executes the follwoing setps in order:

• self.render()
• self.get_user_input()
• self.process_input(userin)

The above steps will continue to execute until self.runningis False or there is no self.curr_screenset (meaning that there is no way to display output or process input).

def render(self):

Renders output to the terminal. This is typically done via self.curr_screen.render().

def get_user_input(self):

Gets input from the user. This can be overriden for specific input types. By default, it uses Python's input()method.

def process_input(self, userin):

Parameters:

• userin: the input received from the user

Processes the input received from the user. This is typically done via self.curr_screen.process_input(userin).

def quit(self):

A convenience method for ending the application loop. By default, this simply sets self.runningto False.

Parameters:

• exc: the Exceptionraised during the application loop

In the event that an exception is not caught during the application loop, the manager will gracefully catch the exception and handle it here. After this method executes, the post_run()method executes, to ensure that all necessary cleanup is still performed despite the program crashing.

class BwkScreenManager(GenericScreenManager):

A screen manager for running specifically for handling screens which utilize the Blessed Window Kit for rendering.

Attributes:

• running: a boolean indicating if the run loop should continue
• curr_screen: the current Screenobject being used to render output and process input
• term: the blessed.Terminalobject used to render screens

def __init__(self, term=None):

Parameters:

• term: the blessed.Terminalobject used to render screens

Initializes the screen manager. If no termis provided, a default Terminal()is used.

def run(self):

Overrides the original run()with special context managers for BWK:

• term.fullscreen
• term.cbreak
• term.hidden_cursor

This ensures that the application behaves similarly to the window_shopper()method provided by the BWK to simplify building and managing screens.

def get_user_input(self):

Overrides this method to use the self.term.inkey()method to get user input, rather than the default Python input()method.

def process_input(self, userin):

Overrides this method to ensure that proper key name is sent to the screen's process_input()method.