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)[source]¶ 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)[source]¶ Dumps a flat mapping of (string path keys, values) pairs and returns a formatted string.
-
find_rule
(path)[source]¶ 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')¶
-
property
default_file
¶
-
property
dump_rules
¶
-
class
xonsh.wizard.
Input
(prompt='>>> ', converter=None, show_conversion=False, confirm=False, retry=False, path=None)[source]¶ 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
= ('prompt', 'converter', 'show_conversion', 'confirm', 'path')¶
-
class
xonsh.wizard.
LoadJSON
(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_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
= ('default_file', 'check', 'ask_filename')¶
-
property
default_file
¶
-
class
xonsh.wizard.
Message
(message)[source]¶ Contains a simple message to report to the user.
-
attrs
= 'message'¶
-
-
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.
-
-
class
xonsh.wizard.
PromptVisitor
(tree=None, state=None, **kwargs)[source]¶ 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.
-
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
- 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
= ('question', 'responses', 'converter', 'path')¶
-
class
xonsh.wizard.
SaveJSON
(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_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
= ('default_file', 'check', 'ask_filename')¶
-
property
default_file
¶
-
class
xonsh.wizard.
StateFile
(default_file=None, check=True, ask_filename=True)[source]¶ 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
= ('default_file', 'check', 'ask_filename')¶
-
property
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.
-
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.
- 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
= ('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.
- 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
= ('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.
- 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
= ('prompt', 'converter', 'show_conversion', 'confirm', 'path')¶
-
class
xonsh.wizard.
UnstorableType
(*args, **kwargs)[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.
-
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 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
= ('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
- 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
= ('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.