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:

prefixstr

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

‘

suffixstr

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

# XONSH WIZARD END’

dump_rulesdict 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_filestr, optional

The default filename to save the file as.

checkbool, 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_filenamebool, 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: tuple[str, ...] = ('prefix', 'suffix', 'dump_rules', 'default_file', 'check', 'ask_filename')

property default_file

property dump_rules

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

Gets input from the user.

Parameters:

promptstr, optional

Prompt string prior to input

convertercallable, optional

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

show_conversionbool, optional

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

confirmbool, optional

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

retrybool, optional

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

pathstr or sequence of str, optional

A path within the storage object.

attrs: tuple[str, ...] = ('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_filestr, optional

The default filename to save the file as.

checkbool, 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_filenamebool, optional

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

attrs: tuple[str, ...] = ('default_file', 'check', 'ask_filename')

property default_file

class xonsh.wizard.Message(message)

Contains a simple message to report to the user.

attrs: tuple[str, ...] | str = 'message'

class xonsh.wizard.Node

Base type of all nodes.

attrs: tuple[str, ...] | str = ()

class xonsh.wizard.Pass

Simple do-nothing node

attrs: tuple[str, ...] | str = ()

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:

treeNode, optional

Tree of nodes to start visitor with.

statedict, optional

Initial state to begin with.

**kwargsoptional

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:

questionstr

The question itself.

responsesdict with str keys and Node values

Mapping from user-input responses to nodes.

convertercallable, optional

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

pathstr or sequence of str, optional

A path within the storage object.

attrs: tuple[str, ...] | str = ('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_filestr, optional

The default filename to save the file as.

checkbool, 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_filenamebool, optional

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

attrs: tuple[str, ...] = ('default_file', 'check', 'ask_filename')

property 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_filestr, optional

The default filename to save the file as.

checkbool, 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_filenamebool, optional

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

attrs: tuple[str, ...] = ('default_file', 'check', 'ask_filename')

property 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.

Parameters:

promptstr, optional

Prompt string prior to input

convertercallable, optional

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

show_conversionbool, optional

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

confirmbool, optional

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

retrybool, optional

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

pathstr or sequence of str, optional

A path within the storage object.

attrs: tuple[str, ...] = ('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.

Parameters:

promptstr, optional

Prompt string prior to input

convertercallable, optional

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

show_conversionbool, optional

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

confirmbool, optional

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

retrybool, optional

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

pathstr or sequence of str, optional

A path within the storage object.

attrs: tuple[str, ...] = ('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.

Parameters:

promptstr, optional

Prompt string prior to input

convertercallable, optional

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

show_conversionbool, optional

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

confirmbool, optional

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

retrybool, optional

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

pathstr or sequence of str, optional

A path within the storage object.

attrs: tuple[str, ...] = ('prompt', 'converter', 'show_conversion', 'confirm', 'path')

class xonsh.wizard.UnstorableType(*args, **kwargs)

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:

condcallable

Function that determines if the next loop iteration should be executed.

bodysequence 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__.

idxnamestr, optional

The variable name for the index.

begint, optional

The first index value when evaluating path format strings.

pathstr or sequence of str, optional

A path within the storage object.

attrs: tuple[str, ...] | str = ('cond', 'body', 'idxname', 'beg', 'path')

class xonsh.wizard.Wizard(children, path=None)

Top-level node in the tree.

attrs: tuple[str, ...] | str = ('children', 'path')

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

Represents a simple yes/no question.

Parameters:

questionstr

The question itself.

yesNode

Node to execute if the response is True.

noNode

Node to execute if the response is False.

pathstr or sequence of str, optional

A path within the storage object.

attrs: tuple[str, ...] | str = ('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.