Skip to content
Back to top
View this page
Edit this page

# 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

    ‘
      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:
    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: 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_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: 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:
    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: 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_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: 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_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: 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:
    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: 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:
    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: 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:
    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: 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:
    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: 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:
    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: 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.