opencos-eda 0.2.47__py3-none-any.whl → 0.2.49__py3-none-any.whl

opencos/eda_base.py

@@ -1,22 +1,36 @@
+'''opencos.eda_base holds base classes for opencos.tools and opencos.commands
+
+Note that opencos.Command.process_tokens (on a derived class) is the main entrypoint
+from eda.py, it will find a command handler class for a command + tool, and call
+its obj.process_tokens(args)
+'''
+
+# TODO(drew): Clean up the following pylint
+# pylint: disable=too-many-lines
+
 import argparse
 import copy
-import glob
 import subprocess
 import os
 import queue
 import re
 import shutil
-import shlex
 import signal
 import sys
 import threading
 import time
 from pathlib import Path
 
-import opencos
-from opencos import seed, deps_helpers, util, files
+from opencos import seed, util, files
 from opencos import eda_config
-from opencos.deps_helpers import get_deps_markup_file, deps_markup_safe_load
+
+from opencos.util import Colors
+from opencos.utils.str_helpers import sprint_time, strip_outer_quotes, string_or_space, \
+    indent_wrap_long_text
+from opencos.utils.subprocess_helpers import subprocess_run_background
+
+from opencos.deps.deps_file import DepsFile, deps_data_get_all_targets
+from opencos.deps.deps_processor import DepsProcessor
 
 
 def print_base_help() -> None:
@@ -28,9 +42,12 @@ def print_base_help() -> None:
 
 
 def get_argparser() -> argparse.ArgumentParser:
+    '''Returns the ArgumentParser for general eda CLI'''
     parser = argparse.ArgumentParser(prog='eda options', add_help=False, allow_abbrev=False)
     parser.add_argument('-q', '--quit', action='store_true',
-                        help='For interactive mode (eda called with no options, command, or targets)')
+                        help=(
+                            'For interactive mode (eda called with no options, command, or'
+                            ' targets)'))
     parser.add_argument('--exit', action='store_true', help='same as --quit')
     parser.add_argument('-h', '--help', action='store_true')
 
@@ -40,22 +57,25 @@ def get_argparser() -> argparse.ArgumentParser:
                         help='Tool to use for this command, such as: modelsim_ase, verilator,' \
                         + ' modelsim_ase=/path/to/bin/vsim, verilator=/path/to/bin/verilator')
     parser.add_argument('--eda-safe', action='store_true',
-                        help='disable all DEPS file deps shell commands, overrides values from --config-yml')
+                        help=('disable all DEPS file deps shell commands, overrides values from'
+                              ' --config-yml'))
     return parser
 
 
 def get_argparser_short_help() -> str:
+    '''Returns str for the eda_base argparser (--help, --tool, etc)'''
     return util.get_argparser_short_help(parser=get_argparser())
 
 
-def get_eda_exec(command:str=''):
+def get_eda_exec(command: str = '') -> str:
+    '''Returns the full path of `eda` executable to be used for a given eda <command>'''
     # NOTE(drew): This is kind of flaky. 'eda multi' reinvokes 'eda'. But the executable for 'eda'
     # is one of:
     # 1. pip3 install opencos-eda
     #    -- script 'eda', installed from PyPi
     # 2. pip3 uninstall .; python3 -m build; pip3 install
     #    -- script 'eda' but installed from local.
-    # 2. (opencos repo)/bin/eda - a python wrapper to link to (opencos repo)/opencos/eda.py (package)
+    # 2. (opencos repo)/bin/eda - a python wrapper to link to (opencos repo)/opencos/eda.py, but
     #    packages cannot be run standalone, they need to be called as: python3 -m opencos.eda,
     #    and do not work with relative paths. This only works if env OC_ROOT is set or can be found.
     # 3. If you ran 'source bin/addpath' then you are always using the local (opencos repo)/bin/eda
@@ -64,11 +84,13 @@ def get_eda_exec(command:str=''):
         # Can we run from OC_ROOT/bin/eda?
         oc_root = util.get_oc_root()
         if not oc_root:
-            util.error(f"Need 'eda' in our path to run 'eda {command}', could not find env OC_ROOT, {eda_path=}, {oc_root=}")
+            util.error(f"Need 'eda' in our path to run 'eda {command}', could not find env",
+                       f"OC_ROOT, {eda_path=}, {oc_root=}")
         else:
             bin_eda = os.path.join(oc_root, 'bin', 'eda')
             if not os.path.exists(bin_eda):
-                util.error(f"Need 'eda' in our path to run 'eda {command}', cound not find bin/, {eda_path=}, {oc_root=}, {bin_eda=}")
+                util.error(f"Need 'eda' in our path to run 'eda {command}', cound not find",
+                           f"bin/, {eda_path=}, {oc_root=}, {bin_eda=}")
             else:
                 util.info(f"'eda' not in path, using {bin_eda=} for 'eda' {command} executable")
                 eda_path = os.path.abspath(bin_eda)
@@ -76,9 +98,10 @@ def get_eda_exec(command:str=''):
     return eda_path
 
 
-def which_tool(command, config):
-    '''Returns which tool will be used for a command, given the command_handlers in config dict.'''
-    from opencos import eda_tool_helper
+def which_tool(command: str, config: dict) -> str:
+    '''Returns which tool (str) will be used for a command, given the command_handlers in
+
+    config dict.'''
     if config is None:
         util.error(f'which_tool({command=}) called w/out config')
     if not command in config.get('command_handler', {}):
@@ -136,9 +159,10 @@ class Tool:
             self.set_tool_config_from_config()
 
     def set_exe(self, config: dict) -> None:
+        '''Sets self._EXE based on config'''
         if self._TOOL and self._TOOL in config.get('auto_tools_order', [{}])[0]:
             exe = config.get('auto_tools_order', [{}])[0][self._TOOL].get('exe', '')
-            if exe and type(exe) is list:
+            if exe and isinstance(exe, list):
                 exe = exe[0] # pick first
             if exe and exe != self._EXE:
                 util.info(f'Override for {self._TOOL} using exe {exe}')
@@ -155,9 +179,16 @@ class Tool:
         return self._VERSION
 
     def set_tool_defines(self) -> None:
-        pass
+        '''Derived classes may override, sets any additional defines based on tool.'''
+        return
+
 
 class Command:
+    '''Base class for all: eda <command>
+
+    The Command class should be used when you don't require files, otherwise consider
+    CommandDesign.
+    '''
 
     command_name: str = ''
 
@@ -170,20 +201,20 @@ class Command:
             "keep" : False,
             "force" : False,
             "fake" : False,
-            "stop-before-compile": False,   # Usually in the self.do_it() method, stop prior to compile/elaborate/simulate
+            "stop-before-compile": False,
             "stop-after-compile": False,
-            "stop-after-elaborate": False,  # Set to True to only run compile + elaboration (aka compile + lint)
+            "stop-after-elaborate": False,
             "lint": False, # Same as stop-after-elaborate
             "eda-dir" : "eda.work", # all eda jobs go in here
             "job-name" : "", # this is used to create a certain dir under "eda_dir"
-            "work-dir" : "", # this can be used to run the job in a certain dir, else it will be <eda-dir>/<job-name> else <eda-dir>/<target>_<command>
-            "sub-work-dir" : "", # this can be used to name the dir built under <eda-dir>, which seems to be same function as job-name??
+            "work-dir" : "", # default is usually <eda-dir>/<job-name> or <eda-dir>/<target>.<cmd>
+            "sub-work-dir" : "", # this can be used to name the dir built under <eda-dir>
             "work-dir-use-target-dir": False,
             "suffix" : "",
             "design" : "", # not sure how this relates to top
             'export':     False,
-            'export-run': False,       # run from the exported location if possible, if not possible run the command in usual place.
-            'export-json': False,      # generates an export.json suitable for a testrunner, if possible for self.command.
+            'export-run': False,  # run from the exported location if possible
+            'export-json': False, # generates an export.json suitable for a testrunner
             'enable-tags': [],
             'disable-tags': [],
             'test-mode': False,
@@ -212,12 +243,32 @@ class Command:
         self.target = ""
         self.target_path = ""
         self.status = 0
+        self.errors_log_f = None
+
 
-    def error(self, *args, **kwargs):
-        '''Returns None, child classes can call self.error(..) instead of util.error, which updates their self.status.
+    def error(self, *args, **kwargs) -> None:
+        '''Returns None, child classes can call self.error(..) instead of util.error,
 
-        Please consider using Command.error(..) (or self.error(..)) in place of util.error so self.status is updated.
+        which updates their self.status. Also will write out to eda.errors.log if the work-dir
+        exists. Please consider using Command.error(..) (or self.error(..)) in place of util.error
+        so self.status is updated.
         '''
+
+        if self.args['work-dir']:
+            if not self.errors_log_f:
+                try:
+                    self.errors_log_f = open( # pylint: disable=consider-using-with
+                        os.path.join(self.args['work-dir'], 'eda.errors.log'), 'w',
+                        encoding='utf-8'
+                    )
+                except FileNotFoundError:
+                    pass
+            if self.errors_log_f:
+                print(
+                    f'ERROR: [eda] ({self.command_name}) {" ".join(list(args))}',
+                    file=self.errors_log_f
+                )
+
         self.status = util.error(*args, **kwargs)
 
     def status_any_error(self, report=True) -> bool:
@@ -227,17 +278,29 @@ class Command:
             util.error(f"command '{self.command_name}' has previous errors")
         return self.status > 0
 
-    def which_tool(self, command:str):
+    def which_tool(self, command:str) -> str:
+        '''Returns a str for the tool name used for the requested command'''
         return which_tool(command, config=self.config)
 
-    def create_work_dir(self):
+    def create_work_dir( # pylint: disable=too-many-branches,too-many-statements
+            self
+    ) -> str:
+        '''Creates the working directory and populates self.args['work-dir']
+
+        Generally uses ./ self.args['eda-dir'] / <target-name>.<command> /
+        however, self.args['job-name'] or ['sub-work-dir'] can override that.
+
+        Additionally, the work-dir is attempted to be deleted if it already exists
+        AND it is beneath the caller's original working directory. We also will
+        not delete 'work-dir' that is ./ or $PWD.
+        '''
         util.debug(f"create_work_dir: {self.args['eda-dir']=} {self.args['work-dir']=}")
         if self.args['work-dir-use-target-dir']:
             if not self.target_path:
                 self.target_path = '.'
-            util.info(f"create_work_dir: --work-dir-use-target-dir: using:",
-                       f"{os.path.abspath(self.target_path)}",
-                       f'target={self.target}')
+            util.info("create_work_dir: --work-dir-use-target-dir: using:",
+                      f"{os.path.abspath(self.target_path)}",
+                      f'target={self.target}')
             self.args['work-dir'] = self.target_path
             self.args['sub-work-dir'] = ''
             return self.args['work-dir']
@@ -245,28 +308,37 @@ class Command:
         if not os.path.exists(self.args['eda-dir']):
             util.safe_mkdir(self.args['eda-dir'])
             util.info(f"create_work_dir: created {self.args['eda-dir']}")
+
         if self.args['design'] == "":
             if ('top' in self.args) and (self.args['top'] != ""):
                 self.args['design'] = self.args['top']
-                util.debug(f"create_work_dir: set {self.args['design']=} from {self.args['top']=}, since it was empty")
+                util.debug(f"create_work_dir: set {self.args['design']=} from",
+                           f"{self.args['top']=}, since it was empty")
             else:
                 self.args['design'] = "design" # generic, i.e. to create work dir "design_upload"
-                util.debug(f"create_work_dir: set {self.args['design']=} to 'design', since it was empty and we have no top")
+                util.debug(f"create_work_dir: set {self.args['design']=} to 'design', since it",
+                           "was empty and we have no top")
+
         if self.target == "":
             self.target = self.args['design']
             util.debug(f"create_work_dir: set {self.target=} from design name, since it was empty")
+
         if self.args['work-dir'] == '':
             if self.args['sub-work-dir'] == '':
                 if self.args['job-name'] != '':
                     self.args['sub-work-dir'] = self.args['job-name']
-                    util.debug(f"create_work_dir: set {self.args['sub-work-dir']=} from {self.args['job-name']=}, since it was empty")
+                    util.debug(f"create_work_dir: set {self.args['sub-work-dir']=} from",
+                               f"{self.args['job-name']=}, since it was empty")
                 else:
                     self.args['sub-work-dir'] = f'{self.target}.{self.command_name}'
-                    util.debug(f"create_work_dir: set {self.args['sub-work-dir']=} from {self.target=} and {self.command_name=}, since it was empty and we have no job-name")
+                    util.debug(f"create_work_dir: set {self.args['sub-work-dir']=} from",
+                               f"{self.target=} and {self.command_name=}, since it was empty and",
+                               "we have no job-name")
             self.args['work-dir'] = os.path.join(self.args['eda-dir'], self.args['sub-work-dir'])
             util.debug(f"create_work_dir: set {self.args['work-dir']=}")
+
         keep_file = os.path.join(self.args['work-dir'], "eda.keep")
-        if (os.path.exists(self.args['work-dir'])):
+        if os.path.exists(self.args['work-dir']):
             if os.path.exists(keep_file) and not self.args['force']:
                 self.error(f"Cannot remove old work dir due to '{keep_file}'")
             elif os.path.abspath(self.args['work-dir']) in os.getcwd():
@@ -275,16 +347,19 @@ class Command:
                 # --work-dir=$PWD
                 # --work-dir=/some/path/almost/here
                 # Allow it, but preserve the existing directory, we don't want to blow away
-                # files up-heir from us.
+                # files up-hier from us.
                 # Enables support for --work-dir=.
-                util.info(f"Not removing existing work-dir: '{self.args['work-dir']}' is within {os.getcwd()=}")
+                util.info(f"Not removing existing work-dir: '{self.args['work-dir']}' is within",
+                          f"{os.getcwd()=}")
             elif str(Path(self.args['work-dir'])).startswith(str(Path('/'))):
                 # Do not allow other absolute path work dirs if it already exists.
                 # This prevents you from --work-dir=~ and eda wipes out your home dir.
-                self.error(f'Cannot use work-dir={self.args["work-dir"]} starting with absolute path "/"')
+                self.error(f'Cannot use work-dir={self.args["work-dir"]} starting with',
+                           'fabsolute path "/"')
             elif str(Path('..')) in str(Path(self.args['work-dir'])):
                 # Do not allow other ../ work dirs if it already exists.
-                self.error(f'Cannot use work-dir={self.args["work-dir"]} with up-hierarchy ../ paths')
+                self.error(f'Cannot use work-dir={self.args["work-dir"]} with up-hierarchy'
+                           '../ paths')
             else:
                 # If we made it this far, on a directory that exists, that appears safe
                 # to delete and re-create:
@@ -295,22 +370,32 @@ class Command:
         else:
             util.safe_mkdir(self.args['work-dir'])
             util.debug(f'create_work_dir: created {self.args["work-dir"]}')
-        if (self.args['keep']):
-            open(keep_file, 'w').close()
+
+        if self.args['keep']:
+            open(keep_file, 'w', encoding='utf-8').close() # pylint: disable=consider-using-with
             util.debug(f'create_work_dir: created {keep_file=}')
         return self.args['work-dir']
 
-    def exec(self, work_dir, command_list, background=False, stop_on_error=True,
-             quiet=False, tee_fpath=None, shell=False):
+
+    def exec(self, work_dir: str, command_list: list, background: bool = False,
+             stop_on_error: bool = True, quiet: bool = False, tee_fpath: str = '',
+             shell: bool = False) -> (str, str, int):
+        '''Runs a command via subprocess and returns a tuple of (stderr, stdout, rc)
+
+        - work_dir: is passed to the subprocess call, so os.chdir(..) is not invoked.
+        - command_list: should be a list of individual strings w/out spaces.
+        - background: if False, does not print to stdout (but will print to any
+                      tee_fpath or the global log
+        - shell: arg passed to subprocess, defaults to False.
+        '''
+
         if not tee_fpath and getattr(command_list, 'tee_fpath', None):
             tee_fpath = getattr(command_list, 'tee_fpath', '')
         if not quiet:
             util.info(f"exec: {' '.join(command_list)} (in {work_dir}, {tee_fpath=})")
-        original_cwd = util.getcwd()
-        os.chdir(work_dir)
 
-        stdout, stderr, return_code = util.subprocess_run_background(
-            work_dir=None, # we've already called os.chdir(work_dir).
+        stdout, stderr, return_code = subprocess_run_background(
+            work_dir=work_dir,
             command_list=command_list,
             background=background,
             fake=self.args.get('fake', False),
@@ -318,16 +403,23 @@ class Command:
             shell=shell
         )
 
-        os.chdir(original_cwd)
         if return_code:
             self.status += return_code
-            if stop_on_error: self.error(f"exec: returned with error (return code: {return_code})")
-            else            : util.debug(f"exec: returned with error (return code: {return_code})")
+            if stop_on_error:
+                self.error(f"exec: returned with error (return code: {return_code})")
+            else:
+                util.debug(f"exec: returned with error (return code: {return_code})")
         else:
             util.debug(f"exec: returned without error (return code: {return_code})")
         return stderr, stdout, return_code
 
-    def set_arg(self, key, value):
+    def set_arg( # pylint: disable=too-many-branches
+            self, key, value
+    ) -> None:
+        '''Sets self.args[key] with value, and self.modified_args[key]=True
+
+        Does type checking, handles list type append
+        '''
 
         # Do some minimal type handling, preserving the type(self.args[key])
         if key not in self.args:
@@ -360,14 +452,14 @@ class Command:
                 else:
                     self.args[key] = True
             else:
-                raise Exception(f'set_arg({key=}, {value=}) bool, {type(cur_value)=} {type(value)=}')
+                assert False, f'set_arg({key=}, {value=}) bool {type(cur_value)=} {type(value)=}'
 
         elif isinstance(cur_value, int):
             # if int, attempt to convert string or bool --> int
             if isinstance(value, (bool, int, str)):
                 self.args[key] = int(value)
             else:
-                raise Exception(f'set_arg({key=}, {value=}) int, {type(cur_value)=} {type(value)=}')
+                assert False, f'set_arg({key=}, {value=}) int {type(cur_value)=} {type(value)=}'
 
 
         else:
@@ -378,7 +470,9 @@ class Command:
         util.debug(f'Set arg["{key}"]="{self.args[key]}"')
 
 
-    def get_argparser(self, parser_arg_list=None) -> argparse.ArgumentParser:
+    def get_argparser( # pylint: disable=too-many-branches
+            self, parser_arg_list=None
+    ) -> argparse.ArgumentParser:
         ''' Returns an argparse.ArgumentParser() based on self.args (dict)
 
         If parser_arg_list is not None, the ArgumentParser() is created using only the keys in
@@ -386,8 +480,8 @@ class Command:
         '''
 
         # Preference is --args-with-dashes, which then become parsed.args_with_dashes, b/c
-        # parsed.args-with-dashes is not legal python. Some of self.args.keys() still have - or _, so
-        # this will handle both.
+        # parsed.args-with-dashes is not legal python. Some of self.args.keys() still have - or _,
+        # so this will handle both.
         # Also, preference is for self.args.keys(), to be str with - dashes
         parser = argparse.ArgumentParser(prog='eda', add_help=False, allow_abbrev=False)
         bool_action_kwargs = util.get_argparse_bool_action_kwargs()
@@ -421,19 +515,19 @@ class Command:
                 help_kwargs = {'help': f'{type(value).__name__} default={value}'}
 
 
-            # It's important to set the default=None on these, except for list types where default is []
-            # If the parsed Namespace has values set to None or [], we do not update. This means that as deps
-            # are processed that have args set, they cannot override the top level args that were already set.
-            # nor be overriden by defaults.
-            if type(value) is bool:
-                # For bool, support --key and --no-key with this action=argparse.BooleanOptionalAction.
-                # Note, this means you cannot use --some-bool=True, or --some-bool=False, has to be --some-bool
-                # or --no-some-bool.
+            # It's important to set the default=None on these, except for list types where default
+            # is []. If the parsed Namespace has values set to None or [], we do not update. This
+            # means that as deps are processed that have args set, they cannot override the top
+            # level args that were already set, nor be overriden by defaults.
+            if isinstance(value, bool):
+                # For bool, support --key and --no-key with action=argparse.BooleanOptionalAction.
+                # Note, this means you cannot use --some-bool=True, or --some-bool=False, has to
+                # be --some-bool or --no-some-bool.
                 parser.add_argument(
                     *arguments, default=None, **bool_action_kwargs, **help_kwargs)
-            elif type(value) is list:
+            elif isinstance(value, list):
                 parser.add_argument(*arguments, default=value, action='append', **help_kwargs)
-            elif type(value) in [int, str]:
+            elif isinstance(value, (int, str)):
                 parser.add_argument(*arguments, default=value, type=type(value), **help_kwargs)
             elif value is None:
                 parser.add_argument(*arguments, default=None, **help_kwargs)
@@ -444,10 +538,10 @@ class Command:
 
 
     def run_argparser_on_list(
-            self, tokens: list, parser_arg_list=None, apply_parsed_args:bool=True
+            self, tokens: list, parser_arg_list=None, apply_parsed_args: bool = True
     ) -> (dict, list):
-        ''' Creates an argparse.ArgumentParser() for all the keys in self.args, and attempts to parse
-        from the provided list. Parsed args are applied to self.args.
+        ''' Creates an argparse.ArgumentParser() for all the keys in self.args, and attempts to
+        parse from the provided list. Parsed args are applied to self.args.
 
         Returns a tuple of (parsed argparse.Namespace obj, list of unparsed args)
 
@@ -461,17 +555,16 @@ class Command:
             parsed, unparsed = parser.parse_known_args(tokens + [''])
             unparsed = list(filter(None, unparsed))
         except argparse.ArgumentError:
-            self.error(f'problem {command_name=} attempting to parse_known_args for {tokens=}')
+            self.error(f'problem {self.command_name=} attempting to parse_known_args for {tokens=}')
 
         parsed_as_dict = vars(parsed)
 
         args_to_be_applied = {}
 
-        for key,value in parsed_as_dict.items():
-            # key should have _ instead of POSIX dashes, but we still support dashes like self.args['build-file'],
-            # etc.
+        for key, value in parsed_as_dict.items():
+            # key currently has _ instead of POSIX dashes, so we convert to dashes, for
+            # most self.args, like self.args['build-file'], etc.
             if key not in self.args and '_' in key:
-                # try with dashes instead of _
                 key = key.replace('_', '-')
             assert key in self.args, f'{key=} not in {self.args=}'
 
@@ -483,7 +576,8 @@ class Command:
         return parsed, unparsed
 
 
-    def apply_args_from_dict(self, args_to_be_applied:dict) -> list:
+    def apply_args_from_dict(self, args_to_be_applied: dict) -> list:
+        '''Given a dict of key/value for self.args, apply them to self.args'''
         util.debug('apply_args_from_dict() -- called by:',
                    f'{self.command_name=}, {self.__class__.__name__=},',
                    f'{args_to_be_applied=}')
@@ -505,7 +599,7 @@ class Command:
                              f"with different cur value (cur value={self.args.get(key, None)})")
                 continue
             if self.args[key] != value:
-                util.debug(f"Command.run_argparser_on_list - setting set_arg b/c",
+                util.debug("Command.run_argparser_on_list - setting set_arg b/c",
                            f" argparse -- {key=} {value=} (cur value={self.args[key]})")
                 self.set_arg(key, value) # Note this has special handling for lists already.
                 self.modified_args[key] = True
@@ -523,7 +617,7 @@ class Command:
         _, unparsed = self.run_argparser_on_list(tokens)
         if process_all and len(unparsed) > 0:
             self.error(f"Didn't understand argument: '{unparsed=}' in",
-                       f" {self.command_name=} context")
+                       f" {self.command_name=} context, {pwd=}")
 
         return unparsed
 
@@ -556,27 +650,33 @@ class Command:
 
         Allows command handlers to make thier own customizations from --config-yaml=YAML.
         '''
-        pass
+        return
 
     def update_tool_config(self) -> None:
         '''Returns None. Hook for classes like CommandSim to make tool specific overrides.'''
-        pass
+        return
 
     def write_eda_config_and_args(self):
+        '''Attempts to write eda_output_config.yml to our work-dir'''
         if not self.args.get('work-dir', None):
             util.warning(f'Ouput work-dir not set, saving ouput eda_config to {os.getcwd()}')
-        util.write_eda_config_and_args(dirpath=self.args.get('work-dir', os.getcwd()),
-                                       command_obj_ref=self)
+        eda_config.write_eda_config_and_args(
+            dirpath=self.args.get('work-dir', os.getcwd()), command_obj_ref=self
+        )
 
     def is_export_enabled(self) -> bool:
-        # check if any self.args['export'] is set in any way (but not set to False
-        # or empty list)
-        return any([arg.startswith('export') and v for arg,v in self.args.items()])
+        '''Returns True if any self.args['export'] is set in any way (but not set to False
+        or empty list)'''
+        return any(arg.startswith('export') and v for arg,v in self.args.items())
 
     def run(self) -> None:
+        '''Alias for do_it(self)'''
         self.do_it()
 
     def do_it(self) -> None:
+        '''Main entrypoint of running a command, usually called by process_tokens.
+
+        process_tokens(..) is the starting entrypoint from eda.py'''
         self.write_eda_config_and_args()
         self.error(f"No tool bound to command '{self.command_name}', you",
                    " probably need to setup tool, or use '--tool <name>'")
@@ -592,7 +692,9 @@ class Command:
             self.set_tool_defines()
 
 
-    def help(self, tokens: list = []) -> None:
+    def help( # pylint: disable=dangerous-default-value,too-many-branches
+            self, tokens: list = []
+    ) -> None:
         '''Since we don't quite follow standard argparger help()/usage(), we'll format our own
 
         if self.args_help has additional help information.
@@ -600,7 +702,7 @@ class Command:
 
         # Indent long lines (>100) to indent=56 (this is where we leave off w/ {vstr:12} below.
         def indent_me(text:str):
-            return util.indent_wrap_long_text(text, width=100, indent=56)
+            return indent_wrap_long_text(text, width=100, indent=56)
 
         util.info('Help:')
         # using bare 'print' here, since help was requested, avoids --color and --quiet
@@ -619,14 +721,14 @@ class Command:
             lines.append(f"Generic help for command='{self.command_name}'"
                          f" (using '{self.__class__.__name__}')")
         else:
-            lines.append(f"Generic help (from class Command):")
+            lines.append("Generic help (from class Command):")
 
         # Attempt to run argparser on args, but don't error if it fails.
         unparsed = []
         if tokens:
             try:
                 _, unparsed = self.run_argparser_on_list(tokens=tokens)
-            except:
+            except Exception:
                 pass
 
         for k in sorted(self.args.keys()):
@@ -635,13 +737,13 @@ class Command:
             khelp = self.args_help.get(k, '')
             if khelp:
                 khelp = f'  - {khelp}'
-            if type(v) == bool :
+            if isinstance(v, bool):
                 lines.append(indent_me(f"  --{k:20} : boolean    : {vstr:12}{khelp}"))
-            elif type(v) == int:
+            elif isinstance(v, int):
                 lines.append(indent_me(f"  --{k:20} : integer    : {vstr:12}{khelp}"))
-            elif type(v) == list:
+            elif isinstance(v, list):
                 lines.append(indent_me(f"  --{k:20} : list       : {vstr:12}{khelp}"))
-            elif type(v) == str:
+            elif isinstance(v, str):
                 vstr = "'" + v + "'"
                 lines.append(indent_me(f"  --{k:20} : string     : {vstr:12}{khelp}"))
             else:
@@ -654,7 +756,10 @@ class Command:
             print(f'Unparsed args: {unparsed}')
 
 
-class CommandDesign(Command):
+class CommandDesign(Command): # pylint: disable=too-many-instance-attributes
+    '''CommandDesign is the eda base class for command handlers that need to track files.
+
+    This is the base class for CommandSim, CommandSynth, and others.'''
 
     # Used by for DEPS work_dir_add_srcs@ commands, by class methods:
     #   update_file_lists_for_work_dir(..), and resolve_target(..)
@@ -675,11 +780,16 @@ class CommandDesign(Command):
         self.args_help.update({
             'seed':   'design seed, default is 31-bit non-zero urandom',
             'top':    'TOP level verilog/SV module or VHDL entity for this target',
-            'all-sv': ('Maintain .sv and .v in single file list.'
-                       ' False: .sv flist separate from .v flist and separate compile(s)'
-                       ' True: .sv and .v files compiled together if possible'),
-            'unprocessed-plusargs': 'Args that began with +, but were not +define+ or +incdir+, +<name>, ' \
-            + ' or +<name>=<value>. These become tool dependent, for example "sim" commands will treat as sim-plusargs',
+            'all-sv': (
+                'Maintain .sv and .v in single file list.'
+                ' False: .sv flist separate from .v flist and separate compile(s)'
+                ' True: .sv and .v files compiled together if possible'
+            ),
+            'unprocessed-plusargs': (
+                'Args that began with +, but were not +define+ or +incdir+, +<name>, '
+                ' or +<name>=<value>. These become tool dependent, for example "sim" commands will'
+                ' treat as sim-plusargs'
+            ),
         })
         self.defines = {}
         self.incdirs = []
@@ -697,12 +807,18 @@ class CommandDesign(Command):
         for (d,v) in self.config.get('defines', {}).items():
             self.defines[d] = v
 
-        self.cached_deps = {} # key = abspath of DEPS markup file, has sub-dicts for 'data' and 'line_numbers'.
+        # cached_deps: key = abspath of DEPS markup file, value is a dict with
+        # keys 'data' and 'line_numbers'
+        self.cached_deps = {}
         self.targets_dict = {} # key = targets that we've already processed in DEPS files
         self.last_added_source_file_inferred_top = ''
 
-    def run_dep_commands(self):
-        # Run any shell@ commands from DEPS files
+
+    def run_dep_commands(self) -> None:
+        '''Run shell/peakrdl style commands from DEPS files
+
+        These are deferred to maintain the deps ordering, and run in that order.
+        '''
         self.run_dep_shell_commands()
         # Update any work_dir_add_srcs@ in our self.files, self.files_v, etc, b/c
         # self.args['work-dir'] now exists.
@@ -710,7 +826,10 @@ class CommandDesign(Command):
         # Link any non-sources to our work-dir:
         self.update_non_source_files_in_work_dir()
 
-    def run_dep_shell_commands(self):
+
+    def run_dep_shell_commands(self) -> None:
+        '''Specifically runs shell command from DEPS files'''
+
         # Runs from self.args['work-dir']
         all_cmds_lists = []
 
@@ -729,7 +848,8 @@ class CommandDesign(Command):
                 log_fnames_count.update({target_node: lognum + 1})
             all_cmds_lists += [
                 [], # blank line
-                # comment, where it came from, log to {node}__shell_{lognum}.log (or tee name from DEPS.yml)
+                # comment, where it came from, log to {node}__shell_{lognum}.log
+                # (or tee name from DEPS.yml)
                 [f'# command {i}: target: {d["target_path"]} : {target_node} --> {log}'],
             ]
             if not run_from_work_dir:
@@ -743,10 +863,12 @@ class CommandDesign(Command):
 
             d['exec_list'] = clist # update to tee_fpath is set.
 
-        util.write_shell_command_file(dirpath=self.args['work-dir'], filename='pre_compile_dep_shell_commands.sh',
-                                      command_lists=all_cmds_lists)
+        util.write_shell_command_file(
+            dirpath=self.args['work-dir'], filename='pre_compile_dep_shell_commands.sh',
+            command_lists=all_cmds_lists
+        )
 
-        for i,d in enumerate(self.dep_shell_commands):
+        for i, d in enumerate(self.dep_shell_commands):
             util.info(f'run_dep_shell_commands {i=}: {d=}')
             clist = util.ShellCommandList(d['exec_list'])
             tee_fpath=clist.tee_fpath
@@ -764,16 +886,23 @@ class CommandDesign(Command):
                 self.exec(run_from_dir, clist, tee_fpath=tee_fpath,
                           shell=self.config.get('deps_subprocess_shell', False))
 
-    def update_file_lists_for_work_dir(self):
-        if len(self.dep_work_dir_add_srcs) == 0:
+
+    def update_file_lists_for_work_dir(self) -> None:
+        '''Handles any source files that were creating by "shell" style commands in the
+
+        work-dir, these need to be added via self.add_file(..) in the correct order
+        of the dependencies. Basically, any files that were left with @EDA-WORK-DIR@ prefix
+        need to be patched and added.
+        '''
+        if not self.dep_work_dir_add_srcs:
             return
 
-        # If we encounter any @EDA-WORK_DIR@some_file.v in self.files, self.files_v, etc, then replace it with:
-        # self.args['work-dir'] / some_file.v:
+        # If we encounter any @EDA-WORK_DIR@some_file.v in self.files, self.files_v, etc,
+        # then replace it with: self.args['work-dir'] / some_file.v:
         _work_dir_add_srcs_path_string_len = len(self._work_dir_add_srcs_path_string)
         work_dir_abspath = os.path.abspath(self.args['work-dir'])
-        for key in list(self.files.keys()): # list so it's not an iterator, we're updating self.files.
-            if type(key) is str and key.startswith(self._work_dir_add_srcs_path_string):
+        for key in list(self.files.keys()): # list so it's not an iterator, updates self.files.
+            if isinstance(key, str) and key.startswith(self._work_dir_add_srcs_path_string):
                 new_key = os.path.join(work_dir_abspath, key[_work_dir_add_srcs_path_string_len :])
                 self.files.pop(key)
                 self.files[new_key] = True
@@ -782,12 +911,23 @@ class CommandDesign(Command):
                               self.files_sdc]
         for my_file_list in my_file_lists_list:
             for i,value in enumerate(my_file_list):
-                if value and type(value) is str and value.startswith(self._work_dir_add_srcs_path_string):
-                    new_value = os.path.join(work_dir_abspath, value[_work_dir_add_srcs_path_string_len :])
+                if value and isinstance(value, str) and \
+                   value.startswith(self._work_dir_add_srcs_path_string):
+                    new_value = os.path.join(
+                        work_dir_abspath, value[_work_dir_add_srcs_path_string_len :]
+                    )
                     my_file_list[i] = new_value
                     util.debug(f"file lists: replaced {value} with {new_value}")
 
-    def update_non_source_files_in_work_dir(self):
+
+    def update_non_source_files_in_work_dir(self) -> None:
+        '''For non-source files (that are tracked as 'reqs' in DEPS markup files) these
+
+        need to be copied or linked to the work-dir. For example, if some SV assumes it
+        can $readmemh('file_that_is_here.txt') but we're running out of work-dir. Linking
+        is the easy work-around vs trying to run-in-place of all SV files.
+        '''
+
         for fname in self.files_non_source:
             _, leaf_fname = os.path.split(fname)
             destfile = os.path.join(self.args['work-dir'], leaf_fname)
@@ -797,16 +937,25 @@ class CommandDesign(Command):
                 util.info(f'{fname=} {self.files_caller_info=}')
                 self.error(f'Non-source file (reqs?) {relfname=} does not exist from {caller_info}')
             elif not os.path.exists(destfile):
-                util.debug(f'updating non-source file to work-dir: Linked {fname=} to {destfile=}, from {caller_info}')
+                util.debug(f'updating non-source file to work-dir: Linked {fname=} to {destfile=},',
+                           f'from {caller_info}')
                 if sys.platform == "win32":
                     shutil.copyfile(fname, destfile) # On Windows, fall back to copying
                 else:
                     os.symlink(src=fname, dst=destfile)
 
-    def get_top_name(self, name):
+    @staticmethod
+    def get_top_name(name: str) -> str:
+        '''Attempt to get the 'top' module name from a file, such as path/to/mine.sv will
+
+        return "mine"'''
+        # TODO(drew): Use the helper method in util for this instead to peek in file contents?
         return os.path.splitext(os.path.basename(name))[0]
 
-    def process_plusarg(self, plusarg: str, pwd: str = os.getcwd()):
+
+    def process_plusarg( # pylint: disable=too-many-branches
+            self, plusarg: str, pwd: str = os.getcwd()
+    ) -> None:
         '''Retuns str, parses a +define+, +incdir+, +key=value str; adds to internal.
 
         Adds to self.defines, self.incdirs,
@@ -818,12 +967,12 @@ class CommandDesign(Command):
         # args that come from shlex.quote(token), such as:
         #   token = '\'+define+OC_ROOT="/foo/bar/opencos"\''
         # So we strip all outer ' or " on the plusarg:
-        plusarg = util.strip_outer_quotes(plusarg)
+        plusarg = strip_outer_quotes(plusarg)
         if not pwd:
             pwd = ''
 
         if plusarg.startswith('+define+'):
-            plusarg = plusarg.lstrip('+define+')
+            plusarg = plusarg[len('+define+'):]
             m = re.match(r'^(\w+)$', plusarg)
             if m:
                 k = m.group(1)
@@ -831,11 +980,12 @@ class CommandDesign(Command):
                 util.debug(f"Defined {k}")
                 return None
             m = re.match(r'^(\w+)\=(\S+)$', plusarg)
-            if not m: m = re.match(r'^(\w+)\=(\"[^\"]*\")$', plusarg)
+            if not m:
+                m = re.match(r'^(\w+)\=(\"[^\"]*\")$', plusarg)
             if m:
                 k = m.group(1)
                 v = m.group(2)
-                if v and type(v) is str:
+                if v and isinstance(v, str):
                     if v.startswith('%PWD%/'):
                         v = v.replace('%PWD%', os.path.abspath(pwd))
                     if v.startswith('%SEED%'):
@@ -847,7 +997,7 @@ class CommandDesign(Command):
             return None
 
         if plusarg.startswith('+incdir+'):
-            plusarg = plusarg.lstrip('+incdir+')
+            plusarg = plusarg[len('+incdir+'):]
             m = re.match(r'^(\S+)$', plusarg)
             if m:
                 incdir = m.group(1)
@@ -863,40 +1013,59 @@ class CommandDesign(Command):
             if not self.config.get('bare_plusarg_supported', False):
                 self.error(f"bare plusarg(s) are not supported: {plusarg}'")
                 return None
-            elif plusarg not in self.args['unprocessed-plusargs']:
+            if plusarg not in self.args['unprocessed-plusargs']:
                 self.args['unprocessed-plusargs'].append(plusarg)
                 # For anything added to unprocessed-plusarg, we have to return it, to let
                 # derived classes have the option to handle it
                 return plusarg
-        else:
-            self.error(f"Didn't understand +plusarg: '{plusarg}'")
+
+        self.error(f"Didn't understand +plusarg: '{plusarg}'")
         return None
 
 
-    def append_shell_commands(self, cmds : list):
-        # Each entry in cmds (list) should be a dict with keys ['target_node', 'target_path', 'exec_list']
+    def append_shell_commands(self, cmds : list) -> None:
+        ''' Given a cmds (list), where each item is a dict with:
+
+        { 'target_node': str,
+          'target_path': str,
+          'exec_list': list
+        }
+        add to this class's dep_shell_commands for deferred processing
+        '''
+
         for entry in cmds:
-            if entry is None or type(entry) is not dict:
+            if entry is None or not isinstance(entry, dict):
                 continue
             if entry in self.dep_shell_commands:
-                # we've already run this exact command (target node, target path, exec list), don't run it
-                # again
+                # we've already run this exact command (target node, target path, exec list),
+                # don't run it again
                 continue
 
             assert 'exec_list' in entry, f'{entry=}'
             util.debug(f'adding - dep_shell_command: {entry=}')
             self.dep_shell_commands.append(entry)
 
-    def append_work_dir_add_srcs(self, add_srcs: list, caller_info: str):
-        # Each entry in add_srcs (list) should be a dict with keys ['target_node', 'target_path', 'file_list']
+
+    def append_work_dir_add_srcs(self, add_srcs: list, caller_info: str) -> None:
+        '''Given add_srcs (list), where each item is a dict with:
+
+        { 'target_node': str,
+          'target_path': str,
+          'file_list': list
+        }
+
+        adds files to set self.dep_work_dir_add_src, and call add_file on it, basically
+        resolving adding source files that were generated and residing in the work-dir.
+        '''
         for entry in add_srcs:
-            if entry is None or type(entry) is not dict:
+            if entry is None or not isinstance(entry, dict):
                 continue
 
             work_dir_files = entry['file_list']
             for filename in work_dir_files:
-                # Unfortunately, self.args['work-dir'] doesn't exist yet and hasn't been set, so we'll add these
-                # files as '@EDA-WORK_DIR@' + filename, and have to replace the EDA-WORK_DIR@ string later in our flow.
+                # Unfortunately, self.args['work-dir'] doesn't exist yet and hasn't been set,
+                # so we'll add these files as '@EDA-WORK_DIR@' + filename, and have to replace
+                # the EDA-WORK_DIR@ string later in our flow.
                 filename_use = self._work_dir_add_srcs_path_string + filename
                 dep_key_tuple = (
                     entry['target_path'],
@@ -911,14 +1080,25 @@ class CommandDesign(Command):
                     self.dep_work_dir_add_srcs.add(dep_key_tuple) # add to set()
                 elif dep_key_tuple not in self.dep_work_dir_add_srcs:
                     # we've already added the file so this dep was skipped for this one file.
-                    util.warning(f'work_dir_add_srcs@ {dep_key_tuple=} but {filename_use=}' \
-                                 + 'is already in self.files (duplicate dependency on generated file?)')
+                    util.warning(f'work_dir_add_srcs@ {dep_key_tuple=} but {filename_use=}',
+                                 'is already in self.files (duplicate dependency on generated',
+                                 'file?)')
+
 
+    def resolve_target(
+            self, target: str, no_recursion: bool = False, caller_info: str = ''
+    ) -> bool:
+        '''Returns True if target is found. Entry point for resolving a CLI path based target name.
 
-    def resolve_target(self, target, no_recursion=False, caller_info=''):
-        util.debug("Entered resolve_target(%s)" % (target))
-        # self.target is a name we grab for the job (i.e. for naming work dir etc).  we don't want the path prefix.
-        # TODO: too messy -- there's also a self.target, args['job-name'], args['work-dir'], args['design'], args['top'], args['sub-work-dir'] ...
+        Will recursively call resolve_target_core, looking for a filename existing
+        or DEPS markup file in that path and a target (key) in the markup table.
+
+        This will populate all source file dependencies, commands, and other DEPS markup
+        features as the target is resolved.
+        '''
+        util.debug(f"Entered resolve_target({target})")
+        # self.target is a name we grab for the job (i.e. for naming work dir etc).  we don't want
+        # the path prefix.
 
         self.target_path, self.target = os.path.split(target)
 
@@ -932,7 +1112,7 @@ class CommandDesign(Command):
             # If the target is a file (we're at the root here processing CLI arg tokens)
             # and that file exists and has an extension, then there's no reason to go looking
             # in DEPS files, add the file and return True.
-            file_base, file_ext = os.path.splitext(fpath)
+            _, file_ext = os.path.splitext(fpath)
             if forced_extension or file_ext:
                 self.add_file(fpath, caller_info=caller_info,
                               forced_extension=forced_extension)
@@ -940,23 +1120,25 @@ class CommandDesign(Command):
 
         return self.resolve_target_core(target, no_recursion, caller_info)
 
-    def resolve_target_core(self, target, no_recursion, caller_info=''):
-        util.debug("Entered resolve_target_core(%s)" % (target))
+    def resolve_target_core( # pylint: disable=too-many-locals,too-many-branches
+            self, target: str, no_recursion: bool, caller_info: str = ''
+    ) -> bool:
+        '''Returns True if target is found. recursive point for resolving path or DEPS markup
+        target names.'''
+
+        util.debug(f"Entered resolve_target_core({target=})")
         found_target = False
-        util.debug("Starting to resolve target '%s'" % (target))
         target_path, target_node = os.path.split(target)
 
-        deps = None
-        data = None
+        deps, data, deps_file = None, None, None
         found_deps_file = False
 
         if self.config['deps_markup_supported']:
-            deps = deps_helpers.DepsFile(
+            deps = DepsFile(
                 command_design_ref=self, target_path=target_path, cache=self.cached_deps
             )
             deps_file = deps.deps_file
             data = deps.data
-            data_only_lines = deps.line_numbers
 
         # Continue if we have data, otherwise look for files other than DEPS.<yml|yaml>
         if data is not None:
@@ -969,7 +1151,7 @@ class CommandDesign(Command):
 
             # For convenience, use an external class for this DEPS.yml table/dict
             # This could be re-used for any markup DEPS.json, DEPS.toml, DEPS.py, etc.
-            deps_processor = deps_helpers.DepsProcessor(
+            deps_processor = DepsProcessor(
                 command_design_ref = self,
                 deps_entry = entry,
                 target = target,
@@ -990,10 +1172,11 @@ class CommandDesign(Command):
             # Recurse on the returned deps (ordered list), if they haven't already been traversed.
             for x in deps_targets_to_resolve:
                 caller_info = deps.gen_caller_info(target_node)
-                if x and type(x) is tuple:
+                if x and isinstance(x, tuple):
                     # if deps_processor.process_deps_entry() gave us a tuple, it's an
                     # unprocessed 'command' that we kept in order until now. Append it.
-                    assert len(x) == 2, f'command tuple {x=} must be len 2, {target_node=} {deps_file=}'
+                    assert len(x) == 2, \
+                        f'command tuple {x=} must be len 2, {target_node=} {deps_file=}'
                     shell_commands_list, work_dir_add_srcs_list = x
                     self.append_shell_commands( cmds=shell_commands_list )
                     self.append_work_dir_add_srcs( add_srcs=work_dir_add_srcs_list,
@@ -1007,32 +1190,40 @@ class CommandDesign(Command):
                                       forced_extension=forced_extension)
                     else:
                         util.debug(f'   ... Calling resolve_target_core({x=})')
-                        found_target |= self.resolve_target_core( x, no_recursion, caller_info=caller_info)
+                        found_target |= self.resolve_target_core(
+                            x, no_recursion, caller_info=caller_info
+                        )
 
 
         # Done with DEPS.yml if it existed.
 
         if not found_target:
-            util.debug("Haven't been able to resolve %s via DEPS" % (target))
+            util.debug(f"Haven't been able to resolve {target=} via DEPS")
             known_file_extensions_for_source = []
-            for x in ['verilog', 'systemverilog', 'vhdl', 'cpp']:
-                known_file_extensions_for_source += self.config.get('file_extensions', {}).get(x, [])
+            for x in ('verilog', 'systemverilog', 'vhdl', 'cpp'):
+                known_file_extensions_for_source += self.config.get(
+                    'file_extensions', {}).get(x, [])
             for e in known_file_extensions_for_source:
                 try_file = target + e
-                util.debug("Looking for %s" % (try_file))
+                util.debug(f"Looking for file {try_file}")
                 if os.path.exists(try_file):
-                    self.add_file(try_file, caller_info=str('n/a::' + target + '::n/a'))
+                    self.add_file(try_file, caller_info=f'n/a::{target}::n/a')
                     found_target = True
                     break # move on to the next target
             if not found_target: # if STILL not found_this_target...
-                self.error("Unable to resolve target '%s'" % (target))
+                self.error(f"Unable to resolve {target=}")
 
         # if we've found any target since being called, it means we found the one we were called for
         return found_target
 
-    def add_file(self, filename, use_abspath=True, add_to_non_sources=False,
-                 caller_info:str='', forced_extension:str=''):
-        file_base, file_ext = os.path.splitext(filename)
+    def add_file(
+            self, filename: str, use_abspath: bool = True, add_to_non_sources: bool = False,
+            caller_info: str = '', forced_extension: str = ''
+    ) -> str:
+        '''Given a filename, add it to one of self.files_sv or similar lists
+
+        based on file extension or prefix directive.'''
+        _, file_ext = os.path.splitext(filename)
         if use_abspath:
             file_abspath = os.path.abspath(filename)
         else:
@@ -1040,8 +1231,8 @@ class CommandDesign(Command):
 
 
         if file_abspath in self.files:
-            util.debug("Not adding file %s, already have it" % (file_abspath))
-            return
+            util.debug(f"Not adding file {file_abspath}, already have it")
+            return ''
 
         known_file_ext_dict = self.config.get('file_extensions', {})
         v_file_ext_list = known_file_ext_dict.get('verilog', [])
@@ -1064,34 +1255,43 @@ class CommandDesign(Command):
 
         if add_to_non_sources:
             self.files_non_source.append(file_abspath)
-            util.debug("Added non-source file file %s as %s" % (filename, file_abspath))
+            util.debug(f"Added non-source file file {filename} as {file_abspath}")
         elif file_ext in v_file_ext_list and not self.args['all-sv']:
             self.files_v.append(file_abspath)
-            util.debug("Added Verilog file %s as %s" % (filename, file_abspath))
-        elif file_ext in sv_file_ext_list or ((file_ext in v_file_ext_list) and self.args['all-sv']):
+            util.debug(f"Added Verilog file {filename} as {file_abspath}")
+        elif file_ext in sv_file_ext_list or \
+             ((file_ext in v_file_ext_list) and self.args['all-sv']):
             self.files_sv.append(file_abspath)
-            util.debug("Added SystemVerilog file %s as %s" % (filename, file_abspath))
+            util.debug(f"Added SystemVerilog file {filename} as {file_abspath}")
         elif file_ext in vhdl_file_ext_list:
             self.files_vhd.append(file_abspath)
-            util.debug("Added VHDL file %s as %s" % (filename, file_abspath))
+            util.debug(f"Added VHDL file {filename} as {file_abspath}")
         elif file_ext in cpp_file_ext_list:
             self.files_cpp.append(file_abspath)
-            util.debug("Added C++ file %s as %s" % (filename, file_abspath))
+            util.debug(f"Added C++ file {filename} as {file_abspath}")
         elif file_ext in sdc_file_ext_list:
             self.files_sdc.append(file_abspath)
-            util.debug("Added SDC file %s as %s" % (filename, file_abspath))
+            util.debug(f"Added SDC file {filename} as {file_abspath}")
         else:
             # unknown file extension. In these cases we link the file to the working directory
-            # so it is available (for example, a .mem file that is expected to exist with relative path)
+            # so it is available (for example, a .mem file that is expected to exist with relative
+            # path)
             self.files_non_source.append(file_abspath)
-            util.debug("Added non-source file %s as %s" % (filename, file_abspath))
+            util.debug(f"Added non-source file {filename} as {file_abspath}")
 
         self.files[file_abspath] = True
         self.files_caller_info[file_abspath] = caller_info
         return file_abspath
 
-    def process_tokens(self, tokens: list, process_all: bool = True,
-                       pwd: str = os.getcwd()) -> list:
+    def process_tokens( # pylint: disable=too-many-locals,too-many-branches,too-many-statements
+            self, tokens: list, process_all: bool = True,
+            pwd: str = os.getcwd()
+    ) -> list:
+        '''Returns a list of unparsed args (self.args did not have these keys present)
+
+        Entrypoint from eda.py calling a command handler obj.process_tokens(args).
+        Dervied classes are expected to call this parent process_tokens to parse and handle
+        their self.args dict'''
 
         util.debug(f'CommandDesign - process_tokens start - {tokens=}')
 
@@ -1105,19 +1305,21 @@ class CommandDesign(Command):
         # walk the list, remove all items after we're done.
         remove_list = []
         for token in unparsed:
-            # Since this is a raw argparser, we may have args that come from shlex.quote(token), such as:
-            # token = '\'+define+OC_ROOT="/foo/bar/opencos"\''
-            # So we have to check for strings that have been escaped for shell with extra single quotes.
+            # Since this is a raw argparser, we may have args that come from shlex.quote(token),
+            # such as:
+            #   token = '\'+define+OC_ROOT="/foo/bar/opencos"\''
+            # So we have to check for strings that have been escaped for shell with extra single
+            # quotes.
             m = re.match(r"^\'?\+\w+", token)
             if m:
                 # Copy and strip all outer ' or " on the plusarg:
-                plusarg = util.strip_outer_quotes(token)
+                plusarg = strip_outer_quotes(token)
                 self.process_plusarg(plusarg, pwd=pwd)
                 remove_list.append(token)
         for x in remove_list:
             unparsed.remove(x)
 
-        if len(unparsed) == 0 and self.error_on_no_files_or_targets:
+        if not unparsed and self.error_on_no_files_or_targets:
             # derived classes can set error_on_no_files_or_targets=True
             # For example: CommandSim will error (requires files/targets),
             # CommandWaves does not (files/targets not required)
@@ -1125,11 +1327,11 @@ class CommandDesign(Command):
             # check the DEPS markup file for a single target, and if so run it
             # on the one and only target.
             if self.config['deps_markup_supported']:
-                deps = deps_helpers.DepsFile(
+                deps = DepsFile(
                     command_design_ref=self, target_path=os.getcwd(), cache=self.cached_deps
                 )
                 if deps.deps_file and deps.data:
-                    all_targets = deps_helpers.deps_data_get_all_targets(deps.data)
+                    all_targets = deps_data_get_all_targets(deps.data)
                     if all_targets:
                         target = all_targets[-1]
                         unparsed.append(target)
@@ -1151,7 +1353,7 @@ class CommandDesign(Command):
             file_exists, fpath, forced_extension = files.get_source_file(token)
             if file_exists:
                 file_abspath = os.path.abspath(fpath)
-                file_base, file_ext = os.path.splitext(file_abspath)
+                _, file_ext = os.path.splitext(file_abspath)
                 if not forced_extension and not file_ext:
                     # This probably isn't a file we want to use
                     util.warning(f'looking for deps {token=}, found {file_abspath=}' \
@@ -1171,11 +1373,12 @@ class CommandDesign(Command):
                     remove_list.append(token)
                     continue # done with token, consume it, we added the file.
 
-            # we appear to be dealing with a target name which needs to be resolved (usually recursively)
+            # we appear to be dealing with a target name which needs to be resolved (usually
+            # recursively)
             if token.startswith(os.sep):
                 target_name = token # if it's absolute path, don't prepend anything
             else:
-                target_name = os.path.join(".", token) # prepend ./so that we always have a <path>/<file>
+                target_name = os.path.join(".", token) # prepend ./ to make it like: <path>/<file>
 
             util.debug(f'Calling self.resolve_target on {target_name=} ({token=})')
             if self.resolve_target(target_name, caller_info=caller_info):
@@ -1224,49 +1427,81 @@ class CommandDesign(Command):
                     self.target = self.args['top']
 
         if self.error_on_missing_top and not self.args.get('top', ''):
-            self.error(f"Did not get a --top or DEPS top, required to run command",
+            self.error("Did not get a --top or DEPS top, required to run command",
                        f"'{self.command_name}' for tool={self.args.get('tool', None)}")
 
         return unparsed
 
 
-    def get_command_line_args(self, remove_args:list=[], remove_args_startswith:list=[]) -> list:
+    def get_command_line_args( # pylint: disable=dangerous-default-value
+            self, remove_args: list = [], remove_args_startswith: list = []
+    ) -> list:
         '''Returns a list of all the args if you wanted to re-run this command
         (excludes eda, command, target).'''
 
         # This will not set bool's that are False, does not add --no-<somearg>
-        # nor --<somearg>=False
-        # This will not set str's that are empty.
-        # this will not set ints that are 0
+        # nor --<somearg>=False (it's unclear which are 'store_true' v/ bool-action-kwargs)
+        # This will not set str's that are empty
+        # this will not set ints that are 0 (unless modified)
+        # TODO(drew): we may want to revisit this if we tracked default arg values,
+        # or perhaps if they have been "modified".
         ret = []
         for k,v in self.args.items():
 
             # Some args cannot be extracted and work, so omit these:
             if k in ['top-path'] + remove_args:
                 continue
-            if any([k.startswith(x) for x in remove_args_startswith]):
+            if any(k.startswith(x) for x in remove_args_startswith):
                 continue
 
-            if type(v) is bool and v:
+            is_modified = self.modified_args.get(k, False)
+
+            if isinstance(v, bool) and v:
                 ret.append(f'--{k}')
-            elif type(v) is int and bool(v):
+            elif isinstance(v, int) and (bool(v) or is_modified):
                 ret.append(f'--{k}={v}')
-            elif type(v) is str and v:
+            elif isinstance(v, str) and v:
                 ret.append(f'--{k}={v}')
-            elif type(v) is list:
+            elif isinstance(v, list):
                 for item in v:
-                    if item or type(item) not in [bool, str]:
+                    if item or isinstance(item, (bool, str)):
                         # don't print bool/str that are blank.
                         ret.append(f'--{k}={item}') # lists append
 
         return ret
 
 
-_threads_start = 0
-_threads_done = 0
+#_THREADS_START = 0
+#_THREADS_DONE = 0
+
+class ThreadStats:
+    '''To avoid globals for two ints, keep a class holder so CommandParallel and
+    CommandParallelWorker can share values'''
+
+    done = 0
+    started = 0
+
+    def all_done(self) -> bool:
+        '''Returns True if all started jobs are done'''
+        return self.started == self.done
+
+    def get_remaining(self) -> int:
+        '''Returns remaining number of jobs'''
+        return max(self.started - self.done, 0)
+
+    def __repr__(self) -> str:
+        '''Pretty print DONE/STARTED'''
+        return f'{self.done}/{self.started}'
+
 
 class CommandParallelWorker(threading.Thread):
-    def __init__(self, n, work_queue, done_queue):
+    '''Helper class for a single threaded job, often run by a CommandParallel command
+    handler class'''
+
+    def __init__(
+            self, n, work_queue: queue.Queue, done_queue: queue.Queue,
+            threads_stats: ThreadStats
+    ):
         threading.Thread.__init__(self)
         self.n = n
         self.work_queue = work_queue
@@ -1276,54 +1511,46 @@ class CommandParallelWorker(threading.Thread):
         self.proc = None
         self.pid = None
         self.last_timer_debug = 0
+        self.threads_stats = threads_stats # ref to shared object
         util.debug(f"WORKER_{n}: START")
 
     def run(self):
-        global _threads_start
-        global _threads_done
+        '''Runs this single job via threading. This is typically created and called by
+
+        a CommandParallel class handler
+        '''
+
         while True:
             # Get the work from the queue and expand the tuple
-            i, command_list, job_name, work_dir = self.work_queue.get()
+            i, command_list, job_name, _ = self.work_queue.get()
             self.job_name = job_name
             try:
                 util.debug(f"WORKER_{self.n}: Running job {i}: {job_name}")
-                PIPE=subprocess.PIPE
-                STDOUT=subprocess.STDOUT
                 util.debug(f"WORKER_{self.n}: Calling Popen")
-                proc = subprocess.Popen(command_list, stdout=PIPE, stderr=STDOUT)
+                proc = subprocess.Popen( # pylint: disable=consider-using-with
+                    command_list, stdout=subprocess.PIPE, stderr=subprocess.STDOUT
+                )
                 self.proc = proc
                 util.debug(f"WORKER_{self.n}: Opened process, PID={proc.pid}")
                 self.pid = proc.pid
-                _threads_start += 1
-                while proc.returncode == None:
+                self.threads_stats.started += 1
+                while proc.returncode is None:
                     try:
                         if (time.time() - self.last_timer_debug) > 10:
                             util.debug(f"WORKER_{self.n}: Calling proc.communicate")
                         stdout, stderr = proc.communicate(timeout=0.5)
-                        util.debug(f"WORKER_{self.n}: got: \n*** stdout:\n{stdout}\n*** stderr:{stderr}")
+                        util.debug(f"WORKER_{self.n}: got: \n*** stdout:\n{stdout}\n***",
+                                   f"stderr:{stderr}")
                     except subprocess.TimeoutExpired:
                         if (time.time() - self.last_timer_debug) > 10:
-                            util.debug(f"WORKER_{self.n}: Timer expired, stop_request={self.stop_request}")
+                            util.debug(f"WORKER_{self.n}: Timer expired, stop_request=",
+                                       f"{self.stop_request}")
                             self.last_timer_debug = time.time()
-                        pass
                     if self.stop_request:
                         util.debug(f"WORKER_{self.n}: got stop request, issuing SIGINT")
                         proc.send_signal(signal.SIGINT)
                         util.debug(f"WORKER_{self.n}: got stop request, calling proc.wait")
                         proc.wait()
-                    if False and self.stop_request:
-                        util.debug(f"WORKER_{self.n}: got stop request, issuing proc.terminate")
-                        proc.terminate()
-                        util.debug(f"WORKER_{self.n}: proc poll returns is now {proc.poll()}")
-                        try:
-                            util.debug(f"WORKER_{self.n}: Calling proc.communicate")
-                            stdout, stderr = proc.communicate(timeout=0.2) # for completeness, in case we ever pipe/search stdout/stderr
-                            util.debug(f"WORKER_{self.n}: got: \n*** stdout:\n{stdout}\n*** stderr:{stderr}")
-                        except subprocess.TimeoutExpired:
-                            util.debug(f"WORKER_{self.n}: timeout waiting for comminicate after terminate")
-                        except:
-                            pass
-                        util.debug(f"WORKER_{self.n}: proc poll returns is now {proc.poll()}")
 
                 util.debug(f"WORKER_{self.n}: -- out of while loop")
                 self.pid = None
@@ -1332,99 +1559,113 @@ class CommandParallelWorker(threading.Thread):
                 util.debug(f"WORKER_{self.n}: proc poll returns is now {proc.poll()}")
                 try:
                     util.debug(f"WORKER_{self.n}: Calling proc.communicate one last time")
-                    stdout, stderr = proc.communicate(timeout=0.1) # for completeness, in case we ever pipe/search stdout/stderr
-                    util.debug(f"WORKER_{self.n}: got: \n*** stdout:\n{stdout}\n*** stderr:{stderr}")
+                    stdout, stderr = proc.communicate(timeout=0.1)
+                    util.debug(f"WORKER_{self.n}: got: \n*** stdout:\n{stdout}\n***",
+                               f"stderr:{stderr}")
                 except subprocess.TimeoutExpired:
                     util.debug(f"WORKER_{self.n}: timeout waiting for communicate after loop?")
-                except:
-                    pass
+                except Exception as e:
+                    util.debug(f"WORKER_{self.n}: timeout with exception {e=}")
+
                 return_code = proc.poll()
-                util.debug(f"WORKER_{self.n}: Finished job {i}: {job_name} with return code {return_code}")
+                util.debug(f"WORKER_{self.n}: Finished job {i}: {job_name} with return code",
+                           f"{return_code}")
                 self.done_queue.put((i, job_name, return_code))
             finally:
                 util.debug(f"WORKER_{self.n}: -- in finally block")
                 self.work_queue.task_done()
-                _threads_done += 1
+                self.threads_stats.done += 1
 
 
 class CommandParallel(Command):
+    '''Base class command handler for running multiple eda jobs, such as for child classes
+
+    in commands.multi or commands.sweep
+    '''
     def __init__(self, config: dict):
         Command.__init__(self, config=config)
         self.jobs = []
         self.jobs_status = []
         self.args['parallel'] = 1
         self.worker_threads = []
+        self.threads_stats = ThreadStats()
 
-    def __del__(self):
-        util.debug(f"In Command.__del__, threads done/started: {_threads_done}/{_threads_start}")
-        if _threads_start == _threads_done:
+    def __del__(self): # pylint: disable=too-many-branches
+        util.debug(f"In Command.__del__, threads done/started: {self.threads_stats}")
+        if self.threads_stats.all_done():
             return
-        util.warning(f"Need to shut down {_threads_start-_threads_done} worker threads...")
+        util.warning(f"Need to shut down {self.threads_stats.get_remaining()} worker threads...")
         for w in self.worker_threads:
             if w.proc:
                 util.warning(f"Requesting stop of PID {w.pid}: {w.job_name}")
                 w.stop_request = True
-        for i in range(10):
-            util.debug(f"Threads done/started: {_threads_done}/{_threads_start}")
-            if _threads_start == _threads_done:
-                util.info(f"All threads done")
+        for _ in range(10):
+            util.debug(f"Threads done/started: {self.threads_stats}")
+            if self.threads_stats.started == self.threads_stats.done:
+                util.info("All threads done")
                 return
             time.sleep(1)
-        subprocess.Popen(['stty', 'sane']).wait()
-        util.debug(f"Scanning workers again")
+        subprocess.Popen(['stty', 'sane']).wait() # pylint: disable=consider-using-with
+        util.debug("Scanning workers again")
         for w in self.worker_threads:
             if w.proc:
                 util.info(f"need to SIGINT WORKER_{w.n}, may need manual cleanup, check 'ps'")
                 if w.pid:
                     os.kill(w.pid, signal.SIGINT)
-        for i in range(5):
-            util.debug(f"Threads done/started: {_threads_done}/{_threads_start}")
-            if _threads_start == _threads_done:
-                util.info(f"All threads done")
+        for _ in range(5):
+            util.debug(f"Threads done/started: {self.threads_stats}")
+            if self.threads_stats.all_done():
+                util.info("All threads done")
                 return
             time.sleep(1)
-        subprocess.Popen(['stty', 'sane']).wait()
-        util.debug(f"Scanning workers again")
+        subprocess.Popen(['stty', 'sane']).wait() # pylint: disable=consider-using-with
+        util.debug("Scanning workers again")
         for w in self.worker_threads:
             if w.proc:
                 util.info(f"need to TERM WORKER_{w.n}, probably needs manual cleanup, check 'ps'")
                 if w.pid:
                     os.kill(w.pid, signal.SIGTERM)
-        for i in range(5):
-            util.debug(f"Threads done/started: {_threads_done}/{_threads_start}")
-            if _threads_start == _threads_done:
-                util.info(f"All threads done")
+        for _ in range(5):
+            util.debug(f"Threads done/started: {self.threads_stats}")
+            if self.threads_stats.all_done():
+                util.info("All threads done")
                 return
             time.sleep(1)
-        subprocess.Popen(['stty', 'sane']).wait()
-        util.debug(f"Scanning workers again")
+        subprocess.Popen(['stty', 'sane']).wait() # pylint: disable=consider-using-with
+        util.debug("Scanning workers again")
         for w in self.worker_threads:
             if w.proc:
                 util.info(f"need to KILL WORKER_{w.n}, probably needs manual cleanup, check 'ps'")
                 if w.pid:
                     os.kill(w.pid, signal.SIGKILL)
         util.stop_log()
-        subprocess.Popen(['stty', 'sane']).wait()
+        subprocess.Popen(['stty', 'sane']).wait() # pylint: disable=consider-using-with
 
-    def run_jobs(self, command):
-        # this is where we actually run the jobs.  it's a messy piece of code and prob could use refactoring
-        # but the goal was to share as much as possible (job start, end, pass/fail judgement, etc) while
-        # supporting various mode combinations (parallel mode, verbose mode, fancy mode, etc) and keeping the
-        # UI output functional and awesome sauce
+    def run_jobs( # pylint: disable=too-many-locals,too-many-branches,too-many-statements
+            self, command: str
+    ) -> None:
+        '''Runs all "jobs" in self.jobs list, either serially or in parallel'''
+
+        # this is where we actually run the jobs.  it's a messy piece of code and prob could use
+        # refactoring but the goal was to share as much as possible (job start, end, pass/fail
+        # judgement, etc) while supporting various mode combinations (parallel mode, verbose mode,
+        # fancy mode, etc) and keeping the UI output functional and awesome sauce
 
         # walk targets to find the longest name, for display reasons
         longest_job_name = 0
         total_jobs = len(self.jobs)
         self.jobs_status = [None] * total_jobs
         for i in range(total_jobs):
-            l = len(self.jobs[i]['name'])
-            if l>longest_job_name: longest_job_name = l
+            longest_job_name = max(longest_job_name, len(self.jobs[i]['name']))
 
         run_parallel = self.args['parallel'] > 1
 
         # figure out the width to print various numbers
         jobs_digits = len(f"{total_jobs}")
-        jobs_fmt = "%%%dd" % jobs_digits # ugh, for printing out a number with N digits
+
+        job_done_return_code = None
+        job_done_run_time = 0
+        job_done_name = ''
 
         # run the jobs!
         running_jobs = {}
@@ -1435,9 +1676,10 @@ class CommandParallel(Command):
         jobs_launched = 0
         num_parallel = min(len(self.jobs), self.args['parallel'])
         # 16 should really be the size of window or ?
-        (columns,lines) = shutil.get_terminal_size()
-        # we will enter fancy mode if we are parallel and we can leave 6 lines of regular scrolling output
-        fancy_mode = util.args['fancy'] and (num_parallel > 1) and (num_parallel <= (lines-6))
+        _, lines = shutil.get_terminal_size()
+        # we will enter fancy mode if we are parallel and we can leave 6 lines of regular scrolling
+        # output
+        fancy_mode = all([util.args['fancy'], num_parallel > 1, num_parallel <= (lines-6)])
         multi_cwd = util.getcwd() + os.sep
 
         self.patch_jobs_for_duplicate_target_names()
@@ -1448,8 +1690,12 @@ class CommandParallel(Command):
             work_queue = queue.Queue()
             done_queue = queue.Queue()
             for x in range(num_parallel):
-                worker = CommandParallelWorker(x, work_queue, done_queue)
-                # Setting daemon to True will let the main thread exit even though the workers are blocking
+                worker = CommandParallelWorker(
+                    n=x, work_queue=work_queue, done_queue=done_queue,
+                    threads_stats=self.threads_stats
+                )
+                # Setting daemon to True will let the main thread exit even though the workers are
+                # blocking
                 worker.daemon = True
                 worker.start()
                 self.worker_threads.append(worker)
@@ -1460,35 +1706,48 @@ class CommandParallel(Command):
                 for x in range(num_parallel):
                     util.fancy_print(f"Starting worker {x}", x)
 
-        while len(self.jobs) or len(running_jobs.items()):
+        while self.jobs or running_jobs:
             job_done = False
             job_done_quiet = False
             anything_done = False
 
             def sprint_job_line(job_number=0, job_name="", final=False, hide_stats=False):
-                return (f"INFO: [EDA] " +
-                        util.string_or_space(f"[job {jobs_fmt%job_number}/{jobs_fmt%total_jobs} ", final) +
-                        util.string_or_space(f"| pass ", hide_stats or final) +
-                        util.string_or_space(f"{jobs_fmt%len(passed_jobs)}/{jobs_fmt%jobs_complete} ", hide_stats) +
-                        util.string_or_space(f"@ {(100*(jobs_complete))/total_jobs:5.1f}%", hide_stats or final) +
-                        util.string_or_space(f"] ", final) +
-                        f"{command} {(job_name+' ').ljust(longest_job_name+3,'.')}")
-
-            # for any kind of run (parallel or not, fancy or not, verbose or not) ... can we launch a job?
-            if len(self.jobs) and (len(running_jobs.items()) < num_parallel):
+                return (
+                    "INFO: [EDA] " +
+                    string_or_space(
+                        f"[job {job_number:0{jobs_digits}d}/{total_jobs:0{jobs_digits}d} ",
+                        final) +
+                    string_or_space("| pass ", hide_stats or final) +
+                    string_or_space(
+                        f"{len(passed_jobs):0{jobs_digits}d}/{jobs_complete:0{jobs_digits}d} ",
+                        hide_stats) +
+                    string_or_space(f"@ {(100 * (jobs_complete)) / total_jobs : 5.1f}%",
+                                         hide_stats or final) +
+                    string_or_space("] ", final) +
+                    f"{command} {(job_name+' ').ljust(longest_job_name+3,'.')}"
+                )
+
+            # for any kind of run (parallel or not, fancy or not, verbose or not) ...
+            # can we launch a job?
+            if self.jobs and (len(running_jobs) < num_parallel):
                 # we are launching a job
                 jobs_launched += 1
                 anything_done = True
                 job = self.jobs.pop(0)
-                if job['name'].startswith(multi_cwd): job['name'] = job['name'][len(multi_cwd):]
-                # in all but fancy mode, we will print this text at the launch of a job.  It may get a newline below
+                # TODO(drew): it might be nice to pass more items on 'job' dict, like
+                # logfile or job-name, so CommandSweep or CommandMulti don't have to set
+                # via args. on their command_list.
+                if job['name'].startswith(multi_cwd):
+                    job['name'] = job['name'][len(multi_cwd):]
+                # in all but fancy mode, we will print this text at the launch of a job.  It may
+                # get a newline below
                 job_text = sprint_job_line(jobs_launched, job['name'], hide_stats=run_parallel)
                 command_list = job['command_list']
                 cwd = util.getcwd()
 
                 if run_parallel:
                     # multithreaded job launch: add to queue
-                    worker = workers.pop(0) # we don't actually know which thread will pick up, but GUI will be consistent
+                    worker = workers.pop(0)
                     running_jobs[str(jobs_launched)] = { 'name' : job['name'],
                                                          'number' : jobs_launched,
                                                          'worker' : worker,
@@ -1498,15 +1757,20 @@ class CommandParallel(Command):
                     suffix = "<START>"
                     if fancy_mode:
                         util.fancy_print(job_text+suffix, worker)
+                    elif failed_jobs:
+                        # if we aren't in fancy mode, we will print a START line, periodic RUNNING
+                        # lines, and PASS/FAIL line per-job
+                        util.print_orange(job_text + Colors.yellow + suffix)
                     else:
-                        # if we aren't in fancy mode, we will print a START line, periodic RUNNING lines, and PASS/FAIL line per-job
-                        if len(failed_jobs): util.print_orange(job_text + util.string_yellow + suffix)
-                        else:                util.print_yellow(job_text + util.string_yellow + suffix)
+                        util.print_yellow(job_text + Colors.yellow + suffix)
                 else:
-                    # single-threaded job launch, we are going to print out job info as we start each job... no newline
-                    # since non-verbose silences the job and prints only <PASS>/<FAIL> after the trailing "..." we leave here
-                    if len(failed_jobs): util.print_orange(job_text, end="")
-                    else:                util.print_yellow(job_text, end="")
+                    # single-threaded job launch, we are going to print out job info as we start
+                    # each job... no newline. since non-verbose silences the job and prints only
+                    # <PASS>/<FAIL> after the trailing "..." we leave here
+                    if failed_jobs:
+                        util.print_orange(job_text, end="")
+                    else:
+                        util.print_yellow(job_text, end="")
                     job_done_number = jobs_launched
                     job_done_name = job['name']
                     job_start_time = time.time()
@@ -1518,13 +1782,16 @@ class CommandParallel(Command):
                         _, _, job_done_return_code = self.exec(
                             cwd, command_list, background=False, stop_on_error=False, quiet=False
                         )
-                        # reprint the job text previously printed before running job(and given "\n" after the trailing "...")
+                        # reprint the job text previously printed before running job (and given
+                        # "\n" after the trailing "...")
                     else:
                         # run job, swallowing output (hope you have a logfile)
                         _, _, job_done_return_code = self.exec(
                             cwd, command_list, background=True, stop_on_error=False, quiet=True
                         )
-                        job_done_quiet = True # in this case, we have the job start text (trailing "...", no newline) printed
+                        # in this case, we have the job start text (trailing "...", no newline)
+                        # printed
+                        job_done_quiet = True
                     job_done = True
                     job_done_run_time = time.time() - job_start_time
                     # Since we consumed the job, use the job['index'] to track the per-job status:
@@ -1532,15 +1799,16 @@ class CommandParallel(Command):
             if run_parallel:
                 # parallel run, check for completed job
                 if done_queue.qsize():
-                    # we're collecting a finished job from a worker thread.  note we will only reap one job per iter of the big
-                    # loop, so as to share job completion code at the bottom
+                    # we're collecting a finished job from a worker thread.  note we will only
+                    # reap one job per iter of the big loop, so as to share job completion code
+                    # at the bottom
                     anything_done = True
                     job_done = True
                     job_done_number, job_done_name, job_done_return_code = done_queue.get()
                     t = running_jobs[str(job_done_number)]
                     # in fancy mode, we need to clear the worker line related to this job.
                     if fancy_mode:
-                        util.fancy_print(f"INFO: [EDA] Parallel: Worker Idle ...", t['worker'])
+                        util.fancy_print("INFO: [EDA] Parallel: Worker Idle ...", t['worker'])
                     job_done_run_time = time.time() - t['start_time']
                     util.debug(f"removing job #{job_done_number} from running jobs")
                     del running_jobs[str(job_done_number)]
@@ -1552,33 +1820,40 @@ class CommandParallel(Command):
                     if (fancy_mode or (time.time() - t['update_time']) > 30):
                         t['update_time'] = time.time()
                         job_text = sprint_job_line(t['number'], t['name'], hide_stats=True)
-                        suffix = f"<RUNNING: {util.sprint_time(time.time() - t['start_time'])}>"
+                        suffix = f"<RUNNING: {sprint_time(time.time() - t['start_time'])}>"
                         if fancy_mode:
                             util.fancy_print(f"{job_text}{suffix}", t['worker'])
+                        elif failed_jobs:
+                            util.print_orange(job_text + Colors.yellow + suffix)
                         else:
-                            if len(failed_jobs): util.print_orange(job_text+util.string_yellow+suffix)
-                            else:                util.print_yellow(job_text+util.string_yellow+suffix)
+                            util.print_yellow(job_text + Colors.yellow + suffix)
 
             # shared job completion code
-            # single or multi-threaded, we can arrive here to harvest <= 1 jobs, and need {job, return_code} valid, and
-            # we expect the start of a status line to have been printed, ready for pass/fail
+            # single or multi-threaded, we can arrive here to harvest <= 1 jobs, and need
+            # {job, return_code} valid, and we expect the start of a status line to have been
+            # printed, ready for pass/fail
             if job_done:
                 jobs_complete += 1
                 if job_done_return_code is None or job_done_return_code:
-                    # embed the color code, to change color of pass/fail during the util.print_orange/yellow below
+                    # embed the color code, to change color of pass/fail during the
+                    # util.print_orange/yellow below
                     if job_done_return_code == 124:
-                        # bash uses 124 for bash timeout errors, if that was preprended to the command list.
-                        suffix = f"{util.string_red}<TOUT: {util.sprint_time(job_done_run_time)}>"
+                        # bash uses 124 for bash timeout errors, if that was preprended to the
+                        # command list.
+                        suffix = f"{Colors.red}<TOUT: {sprint_time(job_done_run_time)}>"
                     else:
-                        suffix = f"{util.string_red}<FAIL: {util.sprint_time(job_done_run_time)}>"
+                        suffix = f"{Colors.red}<FAIL: {sprint_time(job_done_run_time)}>"
                     failed_jobs.append(job_done_name)
                 else:
-                    suffix = f"{util.string_green}<PASS: {util.sprint_time(job_done_run_time)}>"
+                    suffix = f"{Colors.green}<PASS: {sprint_time(job_done_run_time)}>"
                     passed_jobs.append(job_done_name)
                 # we want to print in one shot, because in fancy modes that's all that we're allowed
-                job_done_text = "" if job_done_quiet else sprint_job_line(job_done_number, job_done_name)
-                if len(failed_jobs): util.print_orange(f"{job_done_text}{suffix}")
-                else:                util.print_yellow(f"{job_done_text}{suffix}")
+                job_done_text = "" if job_done_quiet else sprint_job_line(job_done_number,
+                                                                          job_done_name)
+                if failed_jobs:
+                    util.print_orange(f"{job_done_text}{suffix}")
+                else:
+                    util.print_yellow(f"{job_done_text}{suffix}")
                 self.jobs_status[job_done_number-1] = job_done_return_code
 
             if not anything_done:
@@ -1586,23 +1861,26 @@ class CommandParallel(Command):
 
         if total_jobs:
             emoji = "< :) >" if (len(passed_jobs) == total_jobs) else "< :( >"
-            util.info(sprint_job_line(final=True,job_name="jobs passed")+emoji, start="")
+            util.info(sprint_job_line(final=True, job_name="jobs passed") + emoji, start="")
         else:
-            util.info(f"Parallel: <No jobs found>")
+            util.info("Parallel: <No jobs found>")
         # Make sure all jobs have a set status:
-        for i,rc in enumerate(self.jobs_status):
-            if rc is None or type(rc) != int:
+        for i, rc in enumerate(self.jobs_status):
+            if rc is None or not isinstance(rc, int):
                 self.error(f'job {i=} {rc=} did not return a proper return code')
-                jobs_status[i] = 1
+                self.jobs_status[i] = 2
 
         # if self.status > 0, then keep it non-zero, else set it if we still have running jobs.
         if self.status == 0:
-            self.status = 0 if len(self.jobs_status) == 0 else max(self.jobs_status)
+            if self.jobs_status:
+                self.status = max(self.jobs_status)
+            # else keep at 0, empty list.
         util.fancy_stop()
 
     @staticmethod
     def get_name_from_target(target: str) -> str:
-        return target.replace('../', '').lstrip('./')
+        '''Given a target path, strip leftmost path separators to get a shorter string name'''
+        return target.replace('../', '').lstrip('./').lstrip(os.path.sep)
 
 
     def update_args_list(self, args: list, tool: str) -> None:
@@ -1646,7 +1924,7 @@ class CommandParallel(Command):
             tokens=tokens.copy(),
             apply_parsed_args=False,
         )
-        util.debug(f'{self.command_name}: {single_cmd_unparsed=}')
+        util.debug(f'{self.command_name}: {single_cmd_parsed=}, {single_cmd_unparsed=}')
 
         # There should not be any single_cmd_unparsed args starting with '-'
         bad_remaining_args = [x for x in single_cmd_unparsed if x.startswith('-')]
@@ -1663,34 +1941,36 @@ class CommandParallel(Command):
         '''Examines list self.jobs, and if leaf target names are duplicate will
         patch each command's job-name to:
             --job-name=path.leaf.command[.tool]
+
+        Also do for --force-logfile
         '''
 
-        def get_job_name(job_dict: dict) -> str:
-            '''Fishes the job-name out of an entry in self.jobs'''
+        def get_job_arg(job_dict: dict, arg_name: str) -> str:
+            '''Fishes the arg_name out of an entry in self.jobs'''
             for i, item in enumerate(job_dict['command_list']):
-                if item.startswith('--job-name='):
-                    _, name = item.split('--job-name=')
+                if item.startswith(f'--{arg_name}='):
+                    _, name = item.split(f'--{arg_name}=')
                     return name
-                elif item == '--job-name':
+                if item == f'--{arg_name}':
                     return job_dict['command_list'][i + 1]
             return ''
 
-        def replace_job_name(job_dict: dict, new_job_name: str) -> dict:
-            '''Replaces the job-name in an entry in self.jobs'''
+        def replace_job_arg(job_dict: dict, arg_name: str, new_value: str) -> bool:
+            '''Replaces the arg_name's value in an entry in self.jobs'''
             for i, item in enumerate(job_dict['command_list']):
-                if item.startswith('--job-name='):
-                    job_dict['command_list'][i] = '--job-name=' + new_job_name
-                    return job_dict
-                elif item == '--job-name':
-                    job_dict['command_list'][i + 1] = new_job_name
-                    return job_dict
-            return job_dict
+                if item.startswith(f'--{arg_name}='):
+                    job_dict['command_list'][i] = f'--{arg_name}=' + new_value
+                    return True
+                if item == f'--{arg_name}':
+                    job_dict['command_list'][i + 1] = new_value
+                    return True
+            return False
 
 
         job_names_count_dict = {}
         for job_dict in self.jobs:
 
-            key = get_job_name(job_dict)
+            key = get_job_arg(job_dict, arg_name='job-name')
             if not key:
                 self.error(f'{job_dict=} needs to have a --job-name= arg attached')
             if key not in job_names_count_dict:
@@ -1699,16 +1979,29 @@ class CommandParallel(Command):
                 job_names_count_dict[key] += 1
 
         for i, job_dict in enumerate(self.jobs):
-            key = get_job_name(job_dict)
+            key = get_job_arg(job_dict, 'job-name')
             if job_names_count_dict[key] < 2:
                 continue
 
             tpath, _ = os.path.split(job_dict['target'])
 
             # prepend path information to job-name:
-            patched_sub_work_dir = False
             patched_target_path = os.path.relpath(tpath).replace(os.sep, '_')
             new_job_name = f'{patched_target_path}.{key}'
-            new_job_dict = replace_job_name(job_dict, new_job_name)
-            self.jobs[i] = new_job_dict
+            replace_job_arg(job_dict, arg_name='job-name', new_value=new_job_name)
+
+            # prepend path information to force-logfile (if present):
+            force_logfile = get_job_arg(job_dict, arg_name='force-logfile')
+            if force_logfile:
+                left, right = os.path.split(force_logfile)
+                new_force_logfile = os.path.join(left, f'{patched_target_path}.{right}')
+                replace_job_arg(
+                    job_dict, arg_name='force-logfile', new_value=new_force_logfile
+                )
+                util.debug(
+                    f'Patched job {job_dict["name"]}: --force-logfile={new_force_logfile}'
+                )
+
+
+            self.jobs[i] = job_dict
             util.debug(f'Patched job {job_dict["name"]}: --job-name={new_job_name}')