When we introduced disposable clients, our runner.py got much longer and harder to read. As discussed collectively, we would like to make it easier to navigate in once again. The current proposal is this:

1. move LocalRunner from runner.py to executor.py and rename it to Executor
2. move logic from Runner and RemoteRunner to governor.py and shape it into SSHGovernor and DisposableGovernor. It could follow a similar structure to http://fpaste.org/260063/78548144/ . If you think it's going to be beneficial, introduce also RemoteGovernor, which would be a parent for those two, and would document all shared methods (so that you don't need to have the same docstrings in both classes). OTOH, if their API is not similar enough, or there are just a few methods, it might not be worth it. PS: We think that "governor" is a good name for describing what this does, but more suggestions welcome.
3. rename runner.py to main.py
4. introduce method in main.py which will contain the decision logic whether we run things in local mode or in remote mode (and in which remote mode). Based on the outcome, create the proper class (i.e. Executor or SSHGovernor or DisposableGovernor, alternatively the method in question can return the proper instance right away) and run it.
5. move Tee from remote_exec.py to file_utils.py
6. rename RemoteExec from remote_exec.py to ParamikoHelper or SSHClient (other suggestions welcome)
7. get rid of vm.Image, if not used anywhere

When writing documentation in docstrings, use terms like "executor", "governor", "local mode", "remote mode" (and more concretely "ssh mode" and "disposable mode").