Wizard Making Tools (xonsh.wizard)

Tools for creating command-line and web-based wizards from a tree of nodes.

class xonsh.wizard.Input(prompt='>>> ', converter=None, show_conversion=False, confirm=False, retry=False, path=None)[source]

Gets input from the user.

Parameters:

prompt : str, optional

Prompt string prior to input

converter : callable, optional

Converts the string the user typed into another object prior to storage.

show_conversion : bool, optional

Flag for whether or not to show the results of the conversion function if the conversion function was meaningfully executed. Default False.

confirm : bool, optional

Whether the input should be confirmed until true or broken, default False.

retry : bool, optional

In the event that the conversion operation fails, should users be re-prompted until they provide valid input. Deafult False.

path : str or sequence of str, optional

A path within the storage object.

attrs = ('prompt', 'converter', 'show_conversion', 'confirm', 'path')
class xonsh.wizard.Load(default_file=None, check=True, ask_filename=True)[source]

Node for loading the state as a JSON file under a default or user given file name.

Parameters:

default_file : str, optional

The default filename to save the file as.

check : bool, optional

Whether to print the current state and ask if it should be saved/loaded prior to asking for the file name and saving the file, default=True.

ask_filename : bool, optional

Whether to ask for the filename (if False, always use the default filename)

attrs = ('default_file', 'check', 'ask_filename')
default_file
class xonsh.wizard.Message(message)[source]

Contains a simple message to report to the user.

attrs = 'message'
class xonsh.wizard.Node[source]

Base type of all nodes.

attrs = ()
class xonsh.wizard.Pass[source]

Simple do-nothing node

attrs = ()
class xonsh.wizard.PrettyFormatter(tree=None, indent=' ')[source]

Formats a tree of nodes into a pretty string

visit(node=None)

Walks over a node. If no node is provided, the tree is used.

visit_input(node)[source]
visit_message(node)[source]
visit_node(node)[source]
visit_question(node)[source]
visit_statefile(node)[source]
visit_while(node)[source]
visit_wizard(node)[source]
class xonsh.wizard.PromptVisitor(tree=None, state=None, **kwargs)[source]

Visits the nodes in the tree via the a command-line prompt.

Parameters:

tree : Node, optional

Tree of nodes to start visitor with.

state : dict, optional

Initial state to begin with.

kwargs : optional

Options that are passed through to the prompt via the shell’s singleline() method. See BaseShell for mor details.

store(path, val, indices=None)

Stores a value at the path location.

visit(node=None)
visit_input(node)[source]
visit_load(node)[source]
visit_message(node)[source]
visit_pass(node)[source]
visit_question(node)[source]
visit_save(node)[source]
visit_while(node)[source]
visit_wizard(node)[source]
class xonsh.wizard.Question(question, responses, converter=None, path=None)[source]

Asks a question and then chooses the next node based on the response.

Parameters:

question : str

The question itself.

responses : dict with str keys and Node values

Mapping from user-input responses to nodes.

converter : callable, optional

Converts the string the user typed into another object that serves as a key to the reponses dict.

path : str or sequence of str, optional

A path within the storage object.

attrs = ('question', 'responses', 'converter', 'path')
class xonsh.wizard.Save(default_file=None, check=True, ask_filename=True)[source]

Node for saving the state as a JSON file under a default or user given file name.

Parameters:

default_file : str, optional

The default filename to save the file as.

check : bool, optional

Whether to print the current state and ask if it should be saved/loaded prior to asking for the file name and saving the file, default=True.

ask_filename : bool, optional

Whether to ask for the filename (if False, always use the default filename)

attrs = ('default_file', 'check', 'ask_filename')
default_file
class xonsh.wizard.StateFile(default_file=None, check=True, ask_filename=True)[source]

Node for repesenting the state as a JSON file under a default or user given file name. This node type is likely not useful on its own.

Parameters:

default_file : str, optional

The default filename to save the file as.

check : bool, optional

Whether to print the current state and ask if it should be saved/loaded prior to asking for the file name and saving the file, default=True.

ask_filename : bool, optional

Whether to ask for the filename (if False, always use the default filename)

attrs = ('default_file', 'check', 'ask_filename')
default_file
class xonsh.wizard.StateVisitor(tree=None, state=None, indices=None)[source]

This class visits the nodes and stores the results in a top-level dict of data according to the state path of the node. The the node does not have a path or the path does not exist, the storage is skipped. This class can be optionally initialized with an existing state.

store(path, val, indices=None)[source]

Stores a value at the path location.

visit(node=None)[source]
class xonsh.wizard.StoreNonEmpty(prompt='>>> ', converter=None, show_conversion=False, confirm=False, retry=False, path=None, store_raw=False)[source]

Stores the user input only if the input was not an empty string. This works by wrapping the converter function.

attrs = ('prompt', 'converter', 'show_conversion', 'confirm', 'path')
class xonsh.wizard.TrueFalse(prompt='yes or no [default: no]? ', path=None)[source]

Input node the returns a True or False value.

attrs = ('prompt', 'converter', 'show_conversion', 'confirm', 'path')
class xonsh.wizard.TrueFalseBreak(prompt='yes, no, or break [default: no]? ', path=None)[source]

Input node the returns a True, False, or ‘break’ value.

attrs = ('prompt', 'converter', 'show_conversion', 'confirm', 'path')
class xonsh.wizard.UnstorableType[source]

Represents an unstorable return value for when no input was given or such input was skipped. Typically represented by the Unstorable singleton.

class xonsh.wizard.Visitor(tree=None)[source]

Super-class for all classes that should walk over a tree of nodes. This implements the visit() method.

visit(node=None)[source]

Walks over a node. If no node is provided, the tree is used.

class xonsh.wizard.While(cond, body, idxname='idx', beg=0, path=None)[source]

Computes a body while a condition function evaluates to true. The condition function has the form cond(visitor=None, node=None) and should return an object that is convertable to a bool. The beg attribute specifies the number to start the loop iteration at.

Parameters:

cond : callable

Function that determines if the next loop iteration should be executed. The condition function has the form cond(visitor=None, node=None) and should return an object that is convertable to a bool.

body : sequence of nodes

A list of node to execute on each iteration.

idxname : str, optional

The variable name for the index.

beg : int, optional

The first index value when evaluating path format strings.

path : str or sequence of str, optional

A path within the storage object.

attrs = ('cond', 'body', 'idxname', 'beg', 'path')
class xonsh.wizard.Wizard(children, path=None)[source]

Top-level node in the tree.

attrs = ('children', 'path')
class xonsh.wizard.YesNo(question, yes, no, path=None)[source]

Represents a simple yes/no question.

Parameters:

question : str

The question itself.

yes : Node

Node to execute if the response is True.

no : Node

Node to execute if the response is False.

path : str or sequence of str, optional

A path within the storage object.

attrs = ('question', 'responses', 'converter', 'path')
xonsh.wizard.canon_path(path, indices=None)[source]

Returns the canonical form of a path, which is a tuple of str or ints. Indices may be optionally passed in.

xonsh.wizard.create_truefalse_cond(prompt='yes or no [default: no]? ', path=None)[source]

This creates a basic condition function for use with nodes like While or other conditions. The condition function creates and visits a TrueFalse node and returns the result. This TrueFalse node takes the prompt and path that is passed in here.

xonsh.wizard.ensure_str_or_int(x)[source]

Creates a string or int.