Integrating cmd2 with external tools¶
Throughout this documentation we have focused on the 90% use case, that is the use case we believe around 90+% of
our user base is looking for. This focuses on ease of use and the best out-of-the-box experience where developers get
the most functionality for the least amount of effort. We are talking about running cmd2 applications with the
from cmd2 import Cmd class App(Cmd): # customized attributes and methods here app = App() app.cmdloop()
However, there are some limitations to this way of using
cmd2, mainly that
cmd2 owns the inner loop of a program. This can be unnecessarily restrictive and can prevent
using libraries which depend on controlling their own event loop.
Integrating cmd2 with event loops¶
cmd2 applications can be executed in a fashion where
cmd2 doesn’t own the main loop for the program by using
code like the following:
import cmd2 class Cmd2EventBased(cmd2.Cmd): def __init__(self): cmd2.Cmd.__init__(self) # ... your class code here ... if __name__ == '__main__': app = Cmd2EventBased() app.preloop() # Do this within whatever event loop mechanism you wish to run a single command cmd_line_text = "help history" app.runcmds_plus_hooks([cmd_line_text]) app.postloop()
The runcmds_plus_hooks() method is a convenience method to run multiple commands via onecmd_plus_hooks(). It
properly deals with
load commands which under the hood put commands in a FIFO queue as it reads them in from a
The onecmd_plus_hooks() method will do the following to execute a single
cmd2 command in a normal fashion:
- Parse the command line text
- Execute postparsing_precmd()
- Add the command to the history
- Apply output redirection, if present
- Execute precmd()
- Execute onecmd() - this is what actually runs the command
- Execute postcmd()
- Undo output rediriection (if present) and perform piping, if present
- Execute postparsing_postcmd()
Running in this fashion enables the ability to integrate with an external event loop. However, how to integrate with any specific event loop is beyond the scope of this documentation. Please note that running in this fashion comes with several disadvantages, including:
- Requires the developer to write more code
- Does not support transcript testing
- Does not allow commands at invocation via command-line arguments
Here is a little more info on
runcmds_plus_hooks(cmds: List[str]) → bool¶
Convenience method to run multiple commands by onecmd_plus_hooks.
This method adds the given cmds to the command queue and processes the queue until completion or an error causes it to abort. Scripts that are loaded will have their commands added to the queue. Scripts may even load other scripts recursively. This means, however, that you should not use this method if there is a running cmdloop or some other event-loop. This method is only intended to be used in “one-off” scenarios.
NOTE: You may need this method even if you only have one command. If that command is a load, then you will need this command to fully process all the subsequent commands that are loaded from the script file. This is an improvement over onecmd_plus_hooks, which expects to be used inside of a command loop which does the processing of loaded commands.
Example: cmd_obj.runcmds_plus_hooks([‘load myscript.txt’])
Parameters: cmds – command strings suitable for onecmd_plus_hooks. Returns: True implies the entire application should exit.