Implementation

This is the documentation for the underlying implementing classes. For the most part you don’t need to understand it if you’re just calling into the purdy library.

Animation Cells

A Cell represents an animation used by the purdy.animation.manager.AnimationManager. A Cell is responsible for rendering or undoing work to a purdy.widget.CodeBox. Animating cells can partially render then wait for an alarm provided by the manager to continue rendering.

class purdy.animation.cell.GroupCell

Groups steps together into a bundle that can be rendered or undone together. Implements animation alarms so the manager can do timed call backs into the group and continue rendering.

purdy.animation.cell.group_steps_into_cells(steps)

Actions create multiple steps possibly with cell breaks between them. This method takes a list of steps and returns a list of Cell objects, grouping the steps by break marker

Parameters:

steps – a list of steps

Returns:

a list of Cell objects

Animation Management

This module handles the slide rendering animation in the urwid purdy player

Animation Steps

An animation is created through a series of steps that are executed together. A cell.GroupCell wraps these steps. When the user moves forwards and backwards through the animations each cell is rendered or undone. This module

exception purdy.animation.steps.StopMovieException

Command Line Tools

Several of the command line tools have common arguments and needs. This file defines helper functions so these are defined once.

Colour Module (purdy.colour)

Contains classes to convert tokens to colour according to the various supported renderers and palettes.

Parser

This contains methods and classes to manage parsing of code

class purdy.parser.CodePart(token, text)
text

Alias for field number 1

token

Alias for field number 0

class purdy.parser.PurdyLexer(name, description, pygments_lexer_cls, is_console, palette)

Container for the built-in supported lexers. This class is where the names of the lexers are defined. Current choices are:

  • ‘con’ – Python 3 Console

  • ‘py3’ – Python 3 Source code

  • ‘bash’ – interactive Bash session

  • ‘dbash’ – interactive Bash session using a dollar sign prompt

  • ‘node’ – interactive JavaScript / Node.js session

  • ‘yaml’ – YAML document

  • ‘rst’ – RST document

  • ‘md’ – Markdown document

  • ‘none’ – Use plain text, no lexing

purdy.parser.parse_source(source, lexer)

Parses blocks of source text, returning a list of CodeLine objects.

purdy.parser.token_ancestor(token, ancestor_list)

Tokens are hierarchical, in some situations you need to translate a token into one from a known list, e.g. turning a “Token.Literal.Number.Integer” into a “Number”. This method takes a token and a list of approved ancestors and attempts to make the map. If no ancestor is found then a generic “Token” object is returned

Parameters:

  • token – token to translate into an approved ancestor

  • ancestor_list – list of approved ancestor tokens

purdy.parser.token_is_a(token1, token2)

Returns true if token1 is the same type as or a child type of token2

Scribe Module (purdy.scribe.py)

Methods for transforming code into different representations on stdout.

purdy.scribe.print_html(listing, snippet=True)

Prints the code in an HTML representation.

Parameters:

  • listing – Listing object containing code to print

  • snippet – if True, prints out just the <div> containing the code. Otherwise, prints a full valid HTML file. Defaults to True.

purdy.scribe.print_rtf(listing, background_colour=None)

Prints an RTF document containing the colourized code

Parameters:

listing – Listing object containing code to print

purdy.scribe.print_tokens(listing, colour=True)

Prints each line in a purdy.content.Code object with a coloured background, then prints the parsed tokens inside that line

Parameters:

  • listing – purdy.content.Listing object containing code to print

  • colour – set to True to print out using ANSI colour. Defaults to True

TUI Screen (purdy.tui.iscreen.py)

This module is an Urwid code viewer concrete implementation of a Screen. It is constructed by purdy.ui.Screen depending on its factory.

class purdy.iscreen.tui.iscreen.BaseWindow(iscreen, *args, **kwargs)
keypress(size, key)

Pass the keypress to the widget in focus.

Unhandled ‘up’ and ‘down’ keys may cause a focus change.

class purdy.iscreen.tui.iscreen.ConcreteCodeBox(proxy_code_box)

purdy.ui.CodeBox represents a box of code in the purdy.ui.Screen. This is an Urwid implementation of it.

Parameters:

proxy_code_box – the purdy.ui.CodeBox representing what is to be built.

class purdy.iscreen.tui.iscreen.ConcreteTwinCodeBox(proxy)

purdy.ui.TwinCodeBox represents two boxes of code in the purdy.ui.Screen, this is an Urwid implementation of it.

Parameters:

proxy – the purdy.ui.TwinCodeBox representing what is to be built.

class purdy.iscreen.tui.iscreen.HelpDialog(parent)
keypress(size, key)

Pass the keypress to the widget in focus.

Unhandled ‘up’ and ‘down’ keys may cause a focus change.

class purdy.iscreen.tui.iscreen.TUIScreen(parent_screen)

Concrete, Urwid based implementation of a screen.

Parameters:

parent_screen – purdy.ui.Screen object that is creating this concrete implementation

run()

Calls the main display event loop. Does not return until the UI exits.

Wigets (purdy.wigets.py)

Widgets for displaying. These are called and managed through the Screen classes in purdy.ui.

class purdy.iscreen.tui.widgets.CodeWidget(screen, auto_scroll)

Urwid widget that displays the code. This implements the methods of purdy.content.RenderHook and is registered against a purdy.ui.CodeBox and purdy.content.Listing. As changes are made to the listing they will be rendered this widget.

The widget wraps an urwid ListBox, with each line in the box being a line of code. It also provides indiciators on the right side of the screen as to whether there is content above or below the current screen. If the parent Screen implementation has multiple instances of this class active, the scroll area will also indicate which code box is focused.

The up and down arrows as well as the page-up and page-down buttons are supported. If there are multiple code widgets, tab key will change the focus.

class purdy.iscreen.tui.widgets.DividingLine
class purdy.iscreen.tui.widgets.ScrollingIndicator
class purdy.iscreen.tui.widgets.ScrollingListBox(scroll_indicator, *args, **kwargs)
keypress(size, key)

Move selection through the list elements scrolling when necessary. Keystrokes are first passed to widget in focus in case that widget can handle them.

Keystrokes handled by this widget are:

‘up’ up one line (or widget) ‘down’ down one line (or widget) ‘page up’ move cursor up one listbox length (or widget) ‘page down’ move cursor down one listbox length (or widget)

render(size, focus)

Render ListBox and return canvas.

see Widget.render() for details

class purdy.iscreen.tui.widgets.TwinContainer(widget_list: Iterable[Widget | tuple[Literal['pack', WHSettings.PACK] | int, Widget] | tuple[Literal['given', WHSettings.GIVEN], int, Widget] | tuple[Literal['weight', WHSettings.WEIGHT], int | float, Widget]], dividechars: int = 0, focus_column: int | Widget | None = None, min_width: int = 1, box_columns: Iterable[int] | None = None)

Virtual Screen (purdy.virtual.iscreen.py)

This module mimics a code viewer, running through the requested actions and making the final result available.

class purdy.iscreen.virtual.iscreen.VirtualScreen(parent_screen)

Concrete, Urwid based implementation of a screen.

Parameters:

parent_screen – purdy.ui.Screen object that is creating this concrete implementation

run()

Runs the actions on the code listings.