Python module to run commands from CLI

Wed 2026/01/28 Python python / utilities

./doit 
WARN no command chosen, nothing to do
     py-runner-base: v0.1.0
     Choose one of these:
        task1               : run task1
        task2a              : run task2 step-a
        task2b              : run task2 step-b
        task3               : run task3
        task4               : run task4

$ ./doit task1 arg1
==== doit: starting...
     running Task1 args:['arg1']
     doit: run_it rc=0

./doit task1
==== doit: starting...
     running Task1 args:[]
     doit: run_it rc=0

./doit task2b
==== doit: starting...
     running Task2 step-a
     running Task2 step-b
     doit: run_it rc=0

    # --------------------
    def register(self, runner):
        self._runner = runner
        self._runner.add_cmd('task2a', self._run_step_a, 'run task2 step-a')
        self._runner.add_cmd('task2b', self._run_step_b, 'run task2 step-b', prereqs=['task2a'])

# import task class(es) here

class ToolboxApp:
    def __init__(self):
        # any initialization here

        # create an instance of parent of RunnerBase 
        self._runner = ToolboxRunner()

        # build toolbox from the base and the mixins wanted
        tasks = (
            Task1,  # _ do Task1
            Task2,  # _ do Task2
        )

        # register() all the tasks.
        # register() can take a tuple, a list, or an individual class
        # Each tasks is class name, the register() instantiates it.
        self._runner.register(tasks)
        self._runner.register([Task3])
        self._runner.register(Task4)

    # the main.py invokes this function
    def run(self):
        # parse the CLI commands the user typed in
        self._runner.get_cli_info()
        # if there's any problems return
        if self._runner.rc != 0:
            return

        # do a double-check. Your version may or may not need this.
        self._runner.check()
        if self._runner.rc != 0:
            return

        # all is well, so run any/all the commands specified by the user
        # note that you can specify that only one command be called, or N, whatever is needed
        self._runner.run_all()

        # note that main.py will use svc.rc to ensure sys.exit() returns with the right rc. 
        svc.rc += self._runner.rc

class Task1:
    def __init__(self):
        # needed to access any CLI args (or can use sys.argv[])
        self._runner = None

    def register(self, runner):
        # save the runner parent instance
        self._runner = runner

        # register a command "task1", the function to run and some help text
        self._runner.add_cmd('task1', self._run, 'run task1')

    def _run(self):
        # the command to run when task1 is declared
        # must return an rc so the sys.exit() can be set correctly
        errs = 0
        svc.log.line(f'running Task1 args:{self._runner.args}')
        return errs

from src.py_runner_base.runner_base import RunnerBase


# other imports as needed

class ToolboxRunner(RunnerBase):
    def __init__(self):
        super().__init__()
        # initialize the base runner and share the same logger
        self.init_runner_base(svc.log)

    def handle_unknown_arg(self, arg):
        # not a recognized command/task/step so assume it is an arg
        self._args.append(arg)
        return True

    def check(self):
        if self.nothing_chosen():
            svc.rc += 1
            svc.log.warn('no command chosen, nothing to do')
            self.report_err_msg()