Wizard Making Tools (xonsh.wizard)

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

class xonsh.wizard.FileInserter(prefix, suffix, dump_rules, default_file=None, check=True, ask_filename=True)

Node for inserting the state into a file in between a prefix and suffix. The state is converted according to some dumper rules.

Parameters:

prefix : str

Starting unique string in file to find and begin the insertion at, e.g. ‘# XONSH WIZARD START

‘

suffix : str

Ending unique string to find in the file and end the replacement at, e.g. ‘

# XONSH WIZARD END’

dump_rules : dict of strs to functions

This is a dictionary that maps the path-like match strings to functions that take the flat path and the value as arguments and convert the state value at a path to a string. The keys here may use wildcards (as seen in the standard library fnmatch module). For example:

dump_rules = {
    '/path/to/exact': lambda path, x: str(x),
    '/otherpath/*': lambda path, x: x,
    '*ending': lambda path x: repr(x),
    '/': None,
    }

If a wildcard is not used in a path, then that rule will be used used on an exact match. If wildcards are used, the deepest and longest match is used. If None is given instead of a the function, it means to skip generating that key.

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)

dumps(flat)

Dumps a flat mapping of (string path keys, values) pairs and returns a formatted string.

find_rule(path)

For a path, find the key and conversion function that should be used to dump a value.

attrs = ('prefix', 'suffix', 'dump_rules', 'default_file', 'check', 'ask_filename')

default_file

dump_rules

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

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. Default False.

path : str or sequence of str, optional

A path within the storage object.

attrs = ('prompt', 'converter', 'show_conversion', 'confirm', 'path')

class xonsh.wizard.LoadJSON(default_file=None, check=True, ask_filename=True)

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)

Contains a simple message to report to the user.

attrs = 'message'

class xonsh.wizard.Node

Base type of all nodes.

attrs = ()

class xonsh.wizard.Pass

Simple do-nothing node

attrs = ()

class xonsh.wizard.PrettyFormatter(tree=None, indent=' ')

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)

visit_message(node)

visit_node(node)

visit_question(node)

visit_statefile(node)

visit_while(node)

visit_wizard(node)

class xonsh.wizard.PromptVisitor(tree=None, state=None, **kwargs)

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.

flatten(path='/', value=None, flat=None)

Returns a dict version of the store whose keys are paths. Note that list and dict entries will always end in ‘/’, allowing disambiquation in dump_rules.

store(path, val, indices=None)

Stores a value at the path location.

visit(node=None)

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

visit_fileinserter(node)

visit_input(node)

visit_loadjson(node)

visit_message(node)

visit_pass(node)

visit_question(node)

visit_savejson(node)

visit_while(node)

visit_wizard(node)

class xonsh.wizard.Question(question, responses, converter=None, path=None)

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 responses dict.

path : str or sequence of str, optional

A path within the storage object.

attrs = ('question', 'responses', 'converter', 'path')

class xonsh.wizard.SaveJSON(default_file=None, check=True, ask_filename=True)

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)

Node for representing the state as a 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)

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.

flatten(path='/', value=None, flat=None)

Returns a dict version of the store whose keys are paths. Note that list and dict entries will always end in ‘/’, allowing disambiquation in dump_rules.

store(path, val, indices=None)

Stores a value at the path location.

visit(node=None)

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

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

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)

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)

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

attrs = ('prompt', 'converter', 'show_conversion', 'confirm', 'path')

class xonsh.wizard.UnstorableType

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)

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

visit(node=None)

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)

Computes a body while a condition function evaluates to true.

The condition function has the form cond(visitor=None, node=None) and must return an object that responds to the Python magic method __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.

body : sequence of nodes

A list of node to execute on each iteration. The condition function has the form cond(visitor=None, node=None) and must return an object that responds to the Python magic method __bool__.

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)

Top-level node in the tree.

attrs = ('children', 'path')

class xonsh.wizard.YesNo(question, yes, no, path=None)

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)

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)

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)

Creates a string or int.