Interpreters

A base class for custom command interpreters.

Kmd Class

class kmd.Kmd(completekey='TAB', stdin=None, stdout=None, stderr=None)

Interpreter base class.

This is a subclass of the standard library’s cmd.Cmd class, using the new rl bindings for GNU Readline. The standard library documentation applies unless noted otherwise. Changes include:

  1. The Kmd constructor accepts an additional stderr argument.

  2. preloop() and postloop() are not stubs but contain important code bits. Subclasses must make sure to call their parents’ implementations.

  3. New methods: input(), word_break_hook(), comment(), help(), and run().

  4. Incomplete command names are automatically expanded if they are unique.

  5. Command aliases can be defined by extending the aliases dictionary.

  6. help_*() methods optionally receive the help topic as argument.

  7. complete_*() methods may return any kind of iterable, not just lists.

Example:

import kmd

class MyShell(kmd.Kmd):
    prompt = 'myshell> '

    def do_quit(self, args):
        return True

MyShell().run()
Kmd.alias_header = 'Command aliases (type help <topic>):'

Header for the aliases section of the default help screen. If set to the empty string, the aliases section is omitted.

Kmd.shell_escape_chars = '!'

Special, single-character aliases for do_shell().

Kmd.history_file = ''

If a history filename is set, Kmd loads and saves the history in preloop() and postloop().

Kmd.history_max_entries = -1

A non-negative value limits the history size.

Kmd.cmdloop(intro=None)

Repeatedly issue a prompt, accept input, parse an initial prefix off the received input, and dispatch to action methods, passing them the remainder of the line as argument.

Kmd.preloop()

Called when the cmdloop() method is entered. Configures the readline completer and loads the history file.

Kmd.postloop()

Called when the cmdloop() method is exited. Resets the readline completer and saves the history file. Note that postloop() is called even if cmdloop() exits with an exception!

Kmd.input(prompt)

Read a line from the keyboard using input() (or raw_input() in Python 2). When the user presses the TAB key, invoke the readline completer.

Kmd.word_break_hook(begidx, endidx)

When completing ?<topic> make sure ? is a word break character.

Ditto for !<command> and !. Installed as rl.completer.word_break_hook.

Kmd.complete(text, state)

Return the next possible completion for text.

If a command has not been entered, complete against the command list. Otherwise try to call complete_<command>() to get a list of completions. Installed as rl.completer.completer.

Kmd.onecmd(line)

Interpret a command line.

This may be overridden, but should not normally need to be; see the precmd() and postcmd() methods for useful execution hooks. The return value is a flag indicating whether interpretation of commands by the interpreter should stop.

If there is a do_<command>() method for the command prefix, that method is called, with the remainder of the line as argument, and its return value is returned. Otherwise the return value of the default() method is returned.

Kmd.parseline(line)

Parse the line into a command name and a string containing the arguments. Returns a tuple containing (command, args, line); command and args may be None if the line could not be parsed.

Kmd.emptyline()

Called when the input line is empty. By default repeats the lastcmd.

Kmd.comment(line)

Called when the input line starts with a #. By default clears the lastcmd.

Kmd.default(line)

Called when the command prefix is not recognized. By default prints an error message.

Kmd.do_help(topic='')

Print the help screen for topic.

If there is a help_<topic>() method, that method is called, with the unexpanded topic as argument. Otherwise, and if topic is a command, the docstring of the do_<command>() method is printed to stdout. If topic is empty the help() method is invoked.

Kmd.help()

Print the default help screen. Empty sections and sections with empty headers are omitted.

Kmd.run(args=None)

Run the Kmd.

If args is None it defaults to sys.argv[1:]. If arguments are present they are executed via onecmd(). Without arguments, enters the cmdloop().