opencos-eda 0.2.48__py3-none-any.whl → 0.2.50__py3-none-any.whl

opencos/util.py

@@ -1,27 +1,214 @@
+'''opencos.util -- support global logging, argparser for printing (colors)'''
 
-# SPDX-License-Identifier: MPL-2.0
-
-import sys
-import subprocess
+import argparse
+import atexit
 import datetime
+import json
 import os
-import time
-import atexit
+import re
 import shutil
+import subprocess
+import sys
+import time
 import traceback
-import argparse
-import yaml
-import re
-import textwrap
 
-from opencos import eda_config
+from enum import Enum
+from pathlib import Path
+from importlib import import_module
+
+global_exit_allowed = False # pylint: disable=invalid-name
+progname = "UNKNOWN"        # pylint: disable=invalid-name
+progname_in_message = True  # pylint: disable=invalid-name
+debug_level = 0             # pylint: disable=invalid-name
+
+args = {                    # pylint: disable=invalid-name
+    'color' : False,
+    'quiet' : False,
+    'verbose' : False,
+    'debug' : False,
+    'fancy' : sys.stdout.isatty(),
+    'warnings' : 0,
+    'errors' : 0,
+    'artifacts-json': True,
+}
+
+class Colors:
+    '''Namespace class for color printing help'''
+    red = "\x1B[31m"
+    green = "\x1B[32m"
+    orange = "\x1B[33m"
+    yellow = "\x1B[39m"
+    normal = "\x1B[0m"
+
+    @staticmethod
+    def color_text(text: str, color: str) -> str:
+        '''Wraps 'text' (str) with color (one of red|green|orange|yellow) prefix and
+
+        color (normal) suffix. Disables color prefix/suffix wrapping if args['color']=False
+        '''
+        if args['color']:
+            return color + text + "\x1B[0m" # (normal)
+        return text
+
+def red_text(text: str) -> str:
+    '''Wraps text for printing as red, disabled if global args['color']=False'''
+    if args['color']:
+        return Colors.red + text + Colors.normal
+    return text
+
+def green_text(text: str) -> str:
+    '''Wraps text for printing as green, disabled if global args['color']=False'''
+    if args['color']:
+        return Colors.green + text + Colors.normal
+    return text
+
+def orange_text(text: str) -> str:
+    '''Wraps text for printing as orange, disabled if global args['color']=False'''
+    if args['color']:
+        return Colors.orange + text + Colors.normal
+    return text
+
+def yellow_text(text: str) -> str:
+    '''Wraps text for printing as yellow, disabled if global args['color']=False'''
+    if args['color']:
+        return Colors.yellow + text + Colors.normal
+    return text
+
+class ArtifactTypes(Enum):
+    '''Types that are allow-listed for artifacts.add* methods. If you don't use one of
+    these, you'll get a warning'''
+    TEXT = 0
+    JSON = 1
+    YAML = 2
+    WAVEFORM = 3
+    DOTF = 4
+    TCL = 5
+    SHELL = 6
+
+class Artifacts:
+    '''Class to hold file artifacts, for logs generated by EDA, or other artifcats created
+    by a specific tool.
+
+    If enabled, will write out an artifacts.json file upon util.exit()
+    '''
+
+    data = {}
+    unresolved_data = {}
+    enabled = True
+    artifacts_json_filepath = os.path.join('eda.work', 'artifacts.json')
+
+    def _get_type_str(self, typ: str) -> (bool, str):
+        '''Gets the name from ArtifactTypes, and returns tuple of (True, str)
+
+        if the ArtifactTypes exists, else (False, str.upper())'''
+        ret = getattr(ArtifactTypes, typ.upper(), '')
+        if ret:
+            return True, ret.name.lower()
+        return False, typ.lower()
+
+    def add(self, name: str, typ: str, description: str = '') -> None:
+        '''Adds file to artifacts'''
+
+        if not self.enabled:
+            return # artifacts dumping disabled.
+
+        _, shortname = os.path.split(name)
+        if shortname in self.data:
+            return # artifact already registered
+
+        type_exists, type_str = self._get_type_str(typ)
+        if not type_exists:
+            warning(f'Unknown artifacts {typ=} add for {name=} {description=}')
+
+        self.data[shortname] = {
+            'name': name,
+            'type': type_str,
+            'size': 0, # will be filled in when JSON written upon exit.
+            'description': description,
+        }
+
+    def add_extension(
+            self, search_paths: list, file_extension: str, typ: str, description: str = ''
+    ) -> None:
+        '''Adds a placeholder for file extensions to add to artifacts
+
+        For example, when saving a Simulation waves, we may know it's a .fst or .vcd file,
+        but we do not know what the testbench SV file has set in $dumpfile(filepath)
+        '''
+        type_exists, type_str = self._get_type_str(typ)
+        if not type_exists:
+            warning(f'Unknown artifacts {typ=} add_extension for {search_paths=}',
+                    f'{file_extension=} {description=}')
+
+        if isinstance(search_paths, str):
+            sp = [search_paths]
+        else:
+            sp = search_paths
+        self.unresolved_data[file_extension] = {
+            'search_paths': sp,
+            'type': type_str,
+            'description': description
+        }
+
+    def set_artifacts_json_dir(self, dirpath: str) -> None:
+        '''Sets the artifacts_json_filepath'''
+        _, right = os.path.split(self.artifacts_json_filepath)
+        self.artifacts_json_filepath = os.path.join(dirpath, right)
+
+    def reset(self, enable: bool = True) -> None:
+        '''Clears internal data (dict). Called by util.process_tokens()'''
+        self.data = {}
+        self.unresolved_data = {}
+        self.enabled = enable or args['artifacts-json']
+        self.artifacts_json_filepath = os.path.join('eda.work', 'artifacts.json')
+
+    def _resolve_unresolved_data(self, ext: str) -> None:
+        '''Find files for this extension that were registered using add_extension(...)
+
+        adds to self.data'''
+        entry = self.unresolved_data[ext]
+        if not entry:
+            return
+
+        for search_path in entry['search_paths']:
+            p = Path(search_path)
+            for posix_filename in p.glob(f'*.{ext}'):
+                self.add(
+                    name=str(posix_filename), typ=entry['type'], description=entry['description']
+                )
+
+    def write_json(self) -> None:
+        '''Write out the artifacts.json file, called by util.exit()'''
+
+        if not self.enabled:
+            return # artifacts dumping disabled.
+
+        if self.unresolved_data:
+            for ext in self.unresolved_data:
+                self._resolve_unresolved_data(ext)
+
+        if not self.data:
+            return # do nothing if we have no artifacts
+
+        # Update all file sizes:
+        for key, entry in self.data.items():
+            if os.path.isfile(entry['name']):
+                entry['size'] = os.path.getsize(entry['name'])
+            else:
+                # file doesn't exist, remove it from artifacts.
+                warning(f'Removing {key} ({entry["name"]}) from artifacts (file does not exist)')
+                del self.data[key]
+
+        with open(self.artifacts_json_filepath, 'w', encoding='utf-8') as f:
+            json.dump(self.data, f, indent=4)
+            info(f'Wrote artifacts JSON: {self.artifacts_json_filepath}')
+
+
+artifacts = Artifacts()
 
-global_exit_allowed = False
-progname = "UNKNOWN"
-progname_in_message = True
-debug_level = 0
 
 class UtilLogger:
+    '''Class for the util.global_log'''
     file = None
     filepath = ''
     time_last = 0 #timestamp via time.time()
@@ -32,11 +219,13 @@ class UtilLogger:
     default_log_filepath = os.path.join('eda.work', 'eda.log')
 
     def clear(self) -> None:
+        '''Resets internals'''
         self.file = None
         self.filepath = ''
         self.time_last = 0
 
     def stop(self) -> None:
+        '''Closes open log, resets internals'''
         if self.file:
             self.write_timestamp(f'stop - {self.filepath}')
             info(f"Closing logfile: {self.filepath}")
@@ -44,8 +233,9 @@ class UtilLogger:
         self.clear()
 
     def start(self, filename: str, force: bool = False) -> None:
+        '''Starts (opens) log'''
         if not filename:
-            error(f'Trying to start a logfile, but filename is missing')
+            error('Trying to start a logfile, but filename is missing')
             return
         if os.path.exists(filename):
             if force:
@@ -57,26 +247,35 @@ class UtilLogger:
         else:
             safe_mkdir_for_file(filename)
         try:
-            self.file = open(filename, 'w')
+            self.file = open(filename, 'w', encoding='utf-8') # pylint: disable=consider-using-with
             debug(f"Opened logfile '{filename}' for writing")
             self.filepath = filename
             self.write_timestamp(f'start - {self.filepath}')
+            # add to global artifacts:
+            artifacts.add(name=filename, typ='text', description='EDA stdout logfile')
         except Exception as e:
             error(f"Error opening '{filename}' for writing, {e}")
             self.clear()
 
     def write_timestamp(self, text: str = "") -> None:
+        '''Writes timestamp to opened log'''
+        if not self.file:
+            return
         dt = datetime.datetime.now().ctime()
         print(f"INFO: [{progname}] Time: {dt} {text}", file=self.file)
         self.time_last = time.time()
 
-    def write(self, text: str, end: str) -> None:
-        sw = text.startswith(f"INFO: [{progname}]")
-        if (((time.time() - self.time_last) > 10) and
-            (text.startswith(f"DEBUG: [{progname}]") or
-             text.startswith(f"INFO: [{progname}]") or
-             text.startswith(f"WARNING: [{progname}]") or
-             text.startswith(f"ERROR: [{progname}]"))):
+    def write(self, text: str, end: str = '\n') -> None:
+        '''Writes text to opened log'''
+        if not self.file:
+            return
+
+        if ((time.time() - self.time_last) > 10) and \
+           any(text.startswith(x) for x in [
+               f"DEBUG: [{progname}]",
+               f"INFO: [{progname}]",
+               f"WARNING: [{progname}]",
+               f"ERROR: [{progname}]"]):
             self.write_timestamp()
         print(text, end=end, file=self.file)
         self.file.flush()
@@ -86,134 +285,28 @@ class UtilLogger:
 global_log = UtilLogger()
 
 
-def start_log(filename, force=False):
+def start_log(filename: str, force: bool = False) -> None:
+    '''Starts the global_log, if not already started'''
     global_log.start(filename=filename, force=force)
 
-def write_log(text, end):
+def write_log(text: str, end: str = '\n') -> None:
+    '''Writes to the global_log, if started'''
     global_log.write(text=text, end=end)
 
-def stop_log():
+def stop_log() -> None:
+    '''Stops/closed the global_log'''
     global_log.stop()
 
-atexit.register(stop_log)
-
-
-EDA_OUTPUT_CONFIG_FNAME = 'eda_output_config.yml'
-
-args = {
-    'color' : False,
-    'quiet' : False,
-    'verbose' : False,
-    'debug' : False,
-    'fancy' : sys.stdout.isatty(),
-    'warnings' : 0,
-    'errors' : 0,
-}
-
-def strip_all_quotes(s: str) -> str:
-    return s.replace("'", '').replace('"', '')
-
-def strip_outer_quotes(s: str) -> str:
-    ret = str(s)
-    while (ret.startswith("'") and ret.endswith("'")) or \
-          (ret.startswith('"') and ret.endswith('"')):
-        ret = ret[1:-1]
-    return ret
-
-
-def yaml_load_only_root_line_numbers(filepath:str):
-    '''Returns a dict of {key: int line number}, very crude'''
-    # Other solutions aren't as attractive, require a lot of mappers to get
-    # line numbers on returned values that aren't dict
-    data = None
-    with open(filepath) as f:
-        try:
-            # Try to do a very lazy parse of root level keys only, returns dict{key:lineno}
-            data = dict()
-            for lineno,line in enumerate(f.readlines()):
-                m = re.match(r'^(\w+):', line)
-                if m:
-                    key = m.group(1)
-                    data[key] = lineno + 1
-        except Exception as e:
-            error(f"Error loading YAML {filepath=}:", e)
-    return data
-
-
-def toml_load_only_root_line_numbers(filepath:str):
-    '''Returns a dict of {key: int line number}, very crude'''
-    data = None
-    with open(filepath) as f:
-        try:
-            data = dict()
-            for lineno, line in enumerate(f.readlines()):
-                m = re.match(r'^\[(\w+)\]', line)
-                if m:
-                    key = m.group(1)
-                    data[key] = lineno + 1
-        except Exception as e:
-            error(f'Error loading TOML {filepath=}', e)
-    return data
 
+atexit.register(stop_log)
 
-def yaml_safe_load(filepath:str, only_root_line_numbers=False):
-    '''Returns dict or None from filepath (str), errors if return type not in assert_return_types.
 
-    (assert_return_types can be empty list to avoid check.)
+def get_argparse_bool_action_kwargs() -> dict:
+    '''Returns args for BooleanOptionalAction kwargs for an ArgumentParser.add_argument
 
-    only_root_line_numbers -- if True, will return a dict of {key: line number (int)} for
-                              all the root level keys. Used for debugging DEPS.yml in
-                              eda.CommandDesign.resolve_target_core
+    This is mostly for python compatibility to support --some-enable and --no-some-enable
     '''
-
-    data = None
-
-    if only_root_line_numbers:
-        return yaml_load_only_root_line_numbers(filepath)
-
-    with open(filepath) as f:
-        debug(f'Opening {filepath=}')
-        try:
-            data = yaml.safe_load(f)
-        except yaml.YAMLError as e:
-
-            # if yamllint is installed, then use it to get all errors in the .yml|.yaml
-            # file, instead of the single exception.
-            if shutil.which('yamllint'):
-                try:
-                    sp_out = subprocess.run(
-                        f'yamllint -d relaxed --no-warnings {filepath}'.split(),
-                        capture_output=True, text=True )
-                    for x in sp_out.stdout.split('\n'):
-                        if x:
-                            info('yamllint: ' + x)
-                except:
-                    pass
-
-            if hasattr(e, 'problem_mark'):
-                mark = e.problem_mark
-                error(f"Error parsing {filepath=}: line {mark.line + 1},",
-                      f"column {mark.column +1}: {e.problem}")
-            else:
-                error(f"Error loading YAML {filepath=}:", e)
-        except Exception as e:
-            error(f"Error loading YAML {filepath=}:", e)
-
-    return data
-
-
-def yaml_safe_writer(data:dict, filepath:str) -> None:
-
-    if filepath.endswith('.yml') or filepath.endswith('.yaml'):
-        with open(filepath, 'w', encoding='utf-8') as f:
-            yaml.dump(data, f, allow_unicode=True,
-                      default_flow_style=False, sort_keys=False, encoding=('utf-8'))
-    else:
-        warning(f'{filepath=} to be written for this extension not implemented.')
-
-
-def get_argparse_bool_action_kwargs() -> dict:
-    bool_kwargs = dict()
+    bool_kwargs = {}
     x = getattr(argparse, 'BooleanOptionalAction', None)
     if x is not None:
         bool_kwargs['action'] = x
@@ -221,8 +314,12 @@ def get_argparse_bool_action_kwargs() -> dict:
         bool_kwargs['action'] = 'store_true'
     return bool_kwargs
 
+
 def get_argparser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog='opencos common options', add_help=False, allow_abbrev=False)
+    '''Returns the opencos.util ArgumentParser'''
+    parser = argparse.ArgumentParser(
+        prog='opencos common options', add_help=False, allow_abbrev=False
+    )
     # We set allow_abbrev=False so --force-logfile won't try to attempt parsing shorter similarly
     # named args like --force, we want those to go to unparsed list.
     # For bools, support --color and --no-color with this action=argparse.BooleanOptionalAction
@@ -254,9 +351,13 @@ def get_argparser() -> argparse.ArgumentParser:
     parser.add_argument('--no-respawn', action='store_true',
                         help=('Legacy mode (default respawn disabled) for respawning eda.py'
                               ' using $OC_ROOT/bin'))
+    parser.add_argument('--artifacts-json', **bool_action_kwargs,
+                        help='Store a work-dir/artifacts.json file of known tool output files')
     return parser
 
-def get_argparser_short_help(parser=None) -> str:
+
+def get_argparser_short_help(parser: object = None) -> str:
+    '''Returns short help for our ArgumentParser'''
     if not parser:
         parser = get_argparser()
     full_lines = parser.format_help().split('\n')
@@ -268,18 +369,25 @@ def get_argparser_short_help(parser=None) -> str:
     return f'{parser.prog}:\n' + '\n'.join(full_lines[lineno + 1:])
 
 
-def process_token(arg:str) -> bool:
-    # This is legacy holdover for oc_cli.py, that would process one token at a time.
-    # Simply run through our full argparser.
-    parsed, unparsed = process_tokens(tokens[arg])
-    if len(unparsed) == 0:
-        debug(f"Processed command: {arg}")
+def process_token(arg: list) -> bool:
+    '''Returns true if we parsed arg (list, because we may pass --arg value)
+
+    This is legacy holdover for oc_cli.py, that would process one token at a time.
+    Simply run through our full argparser.
+    '''
+    _, unparsed = process_tokens(arg)
+    if not unparsed: # empty list
+        debug(f"Processed token or pair: {arg}")
         return True
     return False
 
 
 def process_tokens(tokens:list) -> (argparse.Namespace, list):
-    global debug_level
+    '''Processes tokens (unparsed args list) on util's ArgumentParser
+
+    Returns tuple of (parsed Namespace, unparsed args list)
+    '''
+    global debug_level # pylint: disable=global-statement
 
     parser = get_argparser()
     try:
@@ -288,256 +396,328 @@ def process_tokens(tokens:list) -> (argparse.Namespace, list):
     except argparse.ArgumentError:
         error(f'problem attempting to parse_known_args for {tokens=}')
 
-    if parsed.debug_level: set_debug_level(parsed.debug_level)
-    elif parsed.debug:     set_debug_level(1)
-    else:                  debug_level = 0
+    if parsed.debug_level:
+        set_debug_level(parsed.debug_level)
+    elif parsed.debug:
+        set_debug_level(1)
+    else:
+        debug_level = 0
 
     debug(f'util.process_tokens: {parsed=} {unparsed=}  from {tokens=}')
 
+    # clear existing artifacts dicts (mostly for pytests repeatedly calling eda.main),
+    # set artifacts.enabled based on args['artifacts-json']
+    artifacts.reset(enable=parsed.artifacts_json)
+
     if parsed.force_logfile:
         start_log(parsed.force_logfile, force=True)
     elif parsed.logfile:
         start_log(parsed.logfile, force=False)
     elif parsed.default_log and \
+         not any(x in unparsed for x in ('help', '-h', '--help')) and \
          (parsed.force_logfile is None and parsed.logfile is None):
         # Use a forced logfile in the eda.work/eda.log:
+        # avoid this if someone has --help arg not yet parsed.
         start_log(global_log.default_log_filepath, force=True)
 
 
     parsed_as_dict = vars(parsed)
     for key,value in parsed_as_dict.items():
+        key = key.replace('_', '-')
         if value is not None:
             args[key] = value # only update with non-None values to our global 'args' dict
-    return parsed, unparsed
 
-def indent_wrap_long_text(text, width=80, initial_indent=0, indent=4):
-    """Returns str, wraps text to a specified width and indents subsequent lines."""
-    wrapped_lines = textwrap.wrap(text, width=width,
-                                  initial_indent=' ' * initial_indent,
-                                  subsequent_indent=' ' * indent)
-    return '\n'.join(wrapped_lines)
+
+    return parsed, unparsed
 
 # ********************
 # fancy support
-# In fancy mode, we take the bottom fancy_lines_ lines of the screen to be written using fancy_print,
-# while the lines above that show regular scrolling content (via info, debug, warning, error above).
-# User should not use print() when in fancy mode
-
-fancy_lines_ = []
-
-def fancy_start(fancy_lines = 4, min_vanilla_lines = 4):
-    global fancy_lines_
-    (columns,lines) = shutil.get_terminal_size()
-    if (fancy_lines < 2):
-        error(f"Fancy mode requires at least 2 fancy lines")
-    if (fancy_lines > (lines-min_vanilla_lines)):
-        error(f"Fancy mode supports at most {(lines-min_vanilla_lines)} fancy lines, given {min_vanilla_lines} non-fancy lines")
-    if len(fancy_lines_): error(f"We are already in fancy line mode??")
-    for _ in range(fancy_lines-1):
-        print("") # create the requisite number of blank lines
-        fancy_lines_.append("")
+# In fancy mode, we take the bottom _FANCY_LINES lines of the screen to be written using
+# fancy_print, while the lines above that show regular scrolling content (via info, debug, warning,
+# error above). User should not use print() when in fancy mode
+
+_FANCY_LINES = []
+
+def fancy_start(fancy_lines: int = 4, min_vanilla_lines: int = 4) -> None:
+    '''Starts fancy line support. This is not called by util internally
+
+    It is called by an opencos.eda Command handling class, it can check if util.args['fancy']
+    is set
+    '''
+    _, lines = shutil.get_terminal_size()
+    if fancy_lines < 2:
+        error("Fancy mode requires at least 2 fancy lines")
+    if fancy_lines > (lines - min_vanilla_lines):
+        error(f"Fancy mode supports at most {(lines - min_vanilla_lines)} fancy lines, given",
+              f"{min_vanilla_lines} non-fancy lines")
+    if _FANCY_LINES:
+        error("We are already in fancy line mode, cannot call fancy_start() again")
+    for _ in range(fancy_lines - 1):
+        print() # create the requisite number of blank lines
+        _FANCY_LINES.append("")
     print("", end="") # the last line has no "\n" because we don't want ANOTHER blank line below
-    fancy_lines_.append("")
+    _FANCY_LINES.append("")
     # the cursor remains at the leftmost character of the bottom line of the screen
 
-def fancy_stop():
-    global fancy_lines_
-    if len(fancy_lines_): # don't do anything if we aren't in fancy mode
-        # user is expected to have painted something into the fancy lines, we can't "pull down" the regular
-        # lines above, and we don't want fancy_lines_ blank or garbage lines either, that's not pretty
-        fancy_lines_ = []
-        # since cursor is always left at the leftmost character of the bottom line of the screen, which was
-        # one of the fancy lines which now has the above-mentioned "something", we want to move one lower
-        print("")
-
-def fancy_print(text, line):
-    global fancy_lines_
+def fancy_stop() -> None:
+    '''Stops fancy mode. Intended to be called by an opencos.eda Command handling class'''
+    if not _FANCY_LINES:
+        # don't do anything if we aren't in fancy mode.
+        return
+
+    # user is expected to have painted something into the fancy lines, we can't "pull down"
+    # the regular lines above, and we don't want _FANCY_LINES blank or garbage lines either,
+    # that's not pretty
+    _FANCY_LINES.clear()
+    # since cursor is always left at the leftmost character of the bottom line of the screen,
+    # which was one of the fancy lines which now has the above-mentioned "something", we want
+    # to move one lower
+    print()
+
+
+def fancy_print(text: str, line: int) -> None:
+    '''Fancy print, intended to be called by an opencos.eda Command handling class'''
+
     # strip any newline, we don't want to print that
-    if text.endswith("\n"): text.rstrip()
-    lines_above = len(fancy_lines_) - line - 1
+    text = text.rstrip("\n")
+    lines_above = len(_FANCY_LINES) - line - 1
     if lines_above:
-        print(f"\033[{lines_above}A"+ # move cursor up
-              text+f"\033[1G"+ # desired text, then move cursor to the first character of the line
-              f"\033[{lines_above}B", # move the cursor down
-              end="", flush=True)
+        print(
+            (f"\033[{lines_above}A" # move cursor up
+             f"{text}\033[1G" # desired text, then move cursor to the first character of the line
+             f"\033[{lines_above}B" # move the cursor down
+             ),
+            end="", flush=True
+        )
     else:
-        print(text+f"\033[1G", # desired text, then move cursor to the first character of the line
-              end="", flush=True)
-    fancy_lines_[line] = text
-
-def print_pre():
+        print(
+            f"{text}\033[1G", # desired text, then move cursor to the first character of the line
+            end="", flush=True
+        )
+    _FANCY_LINES[line] = text
+
+def print_pre() -> None:
+    '''called by all util info/warning/debug/error. Handles fancy mode'''
     # stuff we do before printing any line
-    if len(fancy_lines_):
-        # Also, note that in fancy mode we don't allow the "above lines" to be partially written, they
-        # are assumed to be full lines ending in "\n"
-        # As always, we expect the cursor was left in the leftmost character of bottom line of screen
-        print(f"\033[{len(fancy_lines_)-1}A"+ # move the cursor up to where the first fancy line is drawn
-              f"\033[0K", # clear the old fancy line 0
-              end="",flush=True)
-
-def print_post(text, end):
+    if not _FANCY_LINES:
+        return
+
+    # Also, note that in fancy mode we don't allow the "above lines" to be partially written, they
+    # are assumed to be full lines ending in "\n"
+    # As always, we expect the cursor was left in the leftmost character of bottom line of screen
+    print(
+        (f"\033[{len(_FANCY_LINES)-1}A" # move the cursor up to where the first fancy line is drawn
+         f"\033[0K"                     # clear the old fancy line 0
+         ),
+        end="", flush=True
+    )
+
+def print_post(text: str, end: str) -> None:
+    '''called by all util info/warning/debug/error. Handles fancy mode'''
     # stuff we do after printing any line
-    if len(fancy_lines_):
-        #time.sleep(1)
-        # we just printed a line, including a new line, on top of where fancy line 0 used to be, so cursor
-        # is now at the start of fancy line 1.
-        # move cursor down to the beginning of the final fancy line (i.e. standard fancy cursor resting place)
-        for x in range(len(fancy_lines_)):
-            print("\033[0K",end="") # erase the line to the right
-            print(fancy_lines_[x],flush=True,end=('' if x==(len(fancy_lines_)-1) else '\n'))
-            #time.sleep(1)
+    if _FANCY_LINES:
+        # we just printed a line, including a new line, on top of where fancy line 0 used to be,
+        # so cursor is now at the start of fancy line 1. move cursor down to the beginning of the
+        # final fancy line (i.e. standard fancy cursor resting place)
+        for x, line in enumerate(_FANCY_LINES):
+            print("\033[0K", end="") # erase the line to the right
+            print(line, flush=True,
+                  end=('' if x == (len(_FANCY_LINES) - 1) else '\n'))
+
         print("\033[1G", end="", flush=True)
-    if global_log.file: write_log(text, end=end)
+    if global_log.file:
+        write_log(text, end=end)
 
-string_red = f"\x1B[31m"
-string_green = f"\x1B[32m"
-string_orange = f"\x1B[33m"
-string_yellow = f"\x1B[39m"
-string_normal = f"\x1B[0m"
 
-def print_red(text, end='\n'):
+def print_color(text: str, color: str, end: str = '\n') -> None:
+    '''Note that color(str) must be one of Colors.[red|green|orange|yellow|normal]'''
     print_pre()
-    print(f"{string_red}{text}{string_normal}" if args['color'] else f"{text}", end=end, flush=True)
+    print(Colors.color_text(text, color), end=end, flush=True)
     print_post(text, end)
 
-def print_green(text, end='\n'):
+def print_red(text: str, end: str = '\n') -> None:
+    '''Print text as red, goes back to normal color'''
     print_pre()
-    print(f"{string_green}{text}{string_normal}" if args['color'] else f"{text}", end=end, flush=True)
+    print(red_text(text), end=end, flush=True)
     print_post(text, end)
 
-def print_orange(text, end='\n'):
+def print_green(text: str, end: str = '\n') -> None:
+    '''Print text as green, goes back to normal color'''
     print_pre()
-    print(f"{string_orange}{text}{string_normal}" if args['color'] else f"{text}", end=end, flush=True)
+    print(green_text(text), end=end, flush=True)
     print_post(text, end)
 
-def print_yellow(text, end='\n'):
+def print_orange(text: str, end: str = '\n') -> None:
+    '''Print text as orange, goes back to normal color'''
     print_pre()
-    print(f"{string_yellow}{text}{string_normal}" if args['color'] else f"{text}", end=end, flush=True)
+    print(orange_text(text), end=end, flush=True)
     print_post(text, end)
 
-def set_debug_level(level):
-    global debug_level
+def print_yellow(text: str, end: str = '\n') -> None:
+    '''Print text as yellow, goes back to normal color'''
+    print_pre()
+    print(yellow_text(text), end=end, flush=True)
+    print_post(text, end)
+
+
+def set_debug_level(level) -> None:
+    '''Sets global debug level, sets args['debug'] and args['verbose']'''
+    global debug_level # pylint: disable=global-statement
     debug_level = level
-    args['debug'] = (level > 0)
-    args['verbose'] = (level > 1)
+    args['debug'] = level > 0
+    args['verbose'] = level > 1
     info(f"Set debug level to {debug_level}")
 
-# the <<d>> stuff is because we change progname after this is read in.  if we instead infer progname or
-# get it passed somehow, we can avoid this ugliness / performance impact (lots of calls to debug happen)
-def debug(*text, level=1, start='<<d>>', end='\n'):
-    if start=='<<d>>': start = f"DEBUG: " + (f"[{progname}] " if progname_in_message else "")
-    if args['debug'] and (((level==1) and args['verbose']) or (debug_level >= level)):
+
+def debug(*text, level: int = 1, start: object = None, end: str = '\n') -> None:
+    '''Print debug messaging (in yellow if possible). If args['debug'] is false, prints nothing.
+
+    *text: (positional str args) to be printed
+    level: (int) debug level to decide if printed or not.
+    start: (optional str) prefix to message; if None: chooses default start str
+    end: (optional str) suffix to print
+
+    Note these messages append to global logging (but require args['debug'] to be set)
+    '''
+    if start is None:
+        start = "DEBUG: " + (f"[{progname}] " if progname_in_message else "")
+    if args['debug'] and \
+       (((level==1) and args['verbose']) or (debug_level >= level)):
         print_yellow(f"{start}{' '.join(list(text))}", end=end)
 
-def info(*text, start='<<d>>', end='\n'):
-    if start=='<<d>>': start = f"INFO: " + (f"[{progname}] " if progname_in_message else "")
+
+def info(*text, start: object = None, end='\n') -> None:
+    '''Print information messaging (in green if possible). If args['quiet'], prints nothing.
+
+    *text: (positional str args) to be printed
+    start: (optional str) prefix to message; if None: chooses default start str
+    end: (optional str) suffix to print
+
+    Note these messages append to global logging even if args['quiet'] is set
+    '''
+    if start is None:
+        start = "INFO: " + (f"[{progname}] " if progname_in_message else "")
     if not args['quiet']:
         print_green(f"{start}{' '.join(list(text))}", end=end)
 
-def warning(*text, start='<<d>>', end='\n'):
-    if start=='<<d>>': start = f"WARNING: " + (f"[{progname}] " if progname_in_message else "")
+def warning(*text, start: object = None, end: str = '\n') -> None:
+    '''Print warning messaging (in orange if possible).
+
+    *text: (positional str args) to be printed
+    start: (optional str) prefix to message; if None: chooses default start str
+    end: (optional str) suffix to print
+
+    Note these messages append to global logging. Increments global args['warnings'] int.
+    '''
+    if start is None:
+        start = "WARNING: " + (f"[{progname}] " if progname_in_message else "")
     args['warnings'] += 1
     print_orange(f"{start}{' '.join(list(text))}", end=end)
 
-def error(*text, error_code=-1, do_exit=True, start='<<d>>', end='\n') -> int:
-    if start=='<<d>>': start = f"ERROR: " + (f"[{progname}] " if progname_in_message else "")
+
+def error(
+        *text, error_code: int = 255, do_exit: bool = True, start: object = None, end: str = '\n'
+) -> int:
+    '''Print error messaging (in red if possible).
+
+    *text: (positional str args) to be printed
+    error_code: (int) shell style return code (non-zero is error, but prefer > 1 b/c those are
+                python exceptions)
+    do_exit: (bool) if True will call exit based on global_exit_allowed.
+    start: (optional str) prefix to message; if None: chooses default start str
+    end: (optional str) suffix to print
+
+    Note these messages append to global logging. Increments global args['errors'] int.
+    '''
+    if start is None:
+        start = "ERROR: " + (f"[{progname}] " if progname_in_message else "")
     args['errors'] += 1
     print_red(f"{start}{' '.join(list(text))}", end=end)
     if do_exit:
-        if args['debug']: print(traceback.print_stack())
-        return exit(error_code)
-    else:
-        if error_code is None:
-            return 0
-        else:
-            return abs(int(error_code))
+        if args['debug']:
+            print(traceback.print_stack())
+        # Call our overriden-builtin function for 'exit':
+        return exit(error_code) # pylint: disable=consider-using-sys-exit
+
+    if error_code is None:
+        return 0
+    return abs(int(error_code))
+
+
+def exit( # pylint: disable=redefined-builtin
+        error_code: int = 0, quiet: bool = False
+) -> int:
+    '''sys.exit(int) wrapper, returns the error_code if global_exit_allowed=False'''
+
+    # Save out artifacts file:
+    artifacts.write_json()
 
-def exit(error_code=0, quiet=False):
     if global_exit_allowed:
-        if not quiet: info(f"Exiting with {args['warnings']} warnings, {args['errors']} errors")
+        if not quiet:
+            info(f"Exiting with {args['warnings']} warnings, {args['errors']} errors")
         sys.exit(error_code)
 
     if error_code is None:
         return 0
-    else:
-        return abs(int(error_code))
+
+    return abs(int(error_code))
+
 
 def getcwd():
+    '''Wrapper for os.getcwd() for current working dir'''
     try:
-        cc = os.getcwd()
+        return os.getcwd()
     except Exception as e:
-        error("Unable to getcwd(), did it get deleted from under us?")
-    return cc
-
-_oc_root=None
-_oc_root_set=False
-def get_oc_root(error_on_fail:bool=False):
-    global _oc_root
-    global _oc_root_set
+        error(f"Unable to getcwd(), did it get deleted from under us? Exception: {e}")
+        return None
+
+_OC_ROOT = None
+_OC_ROOT_SET = False
+
+def get_oc_root(error_on_fail: bool = False) -> None:
     '''Returns a str or False for the root directory of *this* repo.
 
     If environment variable OC_ROOT is set, that is used instead, otherwise attempts to use
     `git rev-parse`
     '''
+
+    global _OC_ROOT      # pylint: disable=global-statement
+    global _OC_ROOT_SET  # pylint: disable=global-statement
     # if we've already run through here once, just return the memorized result
-    if _oc_root_set: return _oc_root
+    if _OC_ROOT_SET:
+        return _OC_ROOT
 
     # try looking for an env var
     s = os.environ.get('OC_ROOT')
     if s:
         debug(f'get_oc_root() -- returning from env: {s=}')
-        _oc_root = s.strip()
+        _OC_ROOT = s.strip()
     else:
         # try asking GIT
-        cp = subprocess.run('git rev-parse --show-toplevel', stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
-                            shell=True, universal_newlines=True)
+        cp = subprocess.run(
+            'git rev-parse --show-toplevel', stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+            shell=True, check=False, universal_newlines=True
+        )
         if cp.returncode != 0:
-            # TODO(drew): at some point, address the fact that not all repos are oc_root.  Is this function asking for
-            # the repo we are in?  or a pointer to the oc_root which maybe elsewhere on the system?
+            # TODO(drew): at some point, address the fact that not all repos are oc_root.
+            # Is this function asking for the repo we are in?  or a pointer to the oc_root which
+            # maybe elsewhere on the system?
             print_didnt_find_it = debug
             if error_on_fail:
                 print_didnt_find_it = error
-            print_didnt_find_it(f'Unable to get a OC_ROOT directory using git rev-parse')
+            print_didnt_find_it('Unable to get a OC_ROOT directory using git rev-parse')
         else:
-            _oc_root = cp.stdout.strip()
-            if sys.platform == 'win32':
-                _oc_root = _oc_root.replace('/', '\\') # git gives us /, but we need \
+            _OC_ROOT = cp.stdout.strip()
+            if sys.platform.startswith('win'):
+                _OC_ROOT = _OC_ROOT.replace('/', '\\') # git gives us /, but we need \
 
     # there is no sense running through this code more than once
-    _oc_root_set = True
-    return _oc_root
+    _OC_ROOT_SET = True
+    return _OC_ROOT
 
-def string_or_space(text, whitespace=False):
-    if whitespace:
-        return " " * len(text)
-    else:
-        return text
 
-def sprint_time(s):
-    s = int(s)
-    txt = ""
-    do_all = False
-    # days
-    if (s >= (24*60*60)): # greater than 24h, we show days
-        d = int(s/(24*60*60))
-        txt += f"{d}d:"
-        s -= (d*24*60*60)
-        do_all = True
-    # hours
-    if do_all or (s >= (60*60)):
-        d = int(s/(60*60))
-        txt += f"{d:2}:"
-        s -= (d*60*60)
-        do_all = True
-    # minutes
-    d = int(s/(60))
-    txt += f"{d:02}:"
-    s -= (d*60)
-    # seconds
-    txt += f"{s:02}"
-    return txt
-
-def safe_cp(source:str, destination:str, create_dirs:bool=False):
+def safe_cp(source: str, destination: str, create_dirs: bool = False) -> None:
+    '''shutil.copy2 wrapper to optionally make the destination directories'''
     try:
         # Infer if destination is a directory
         if destination.endswith('/') or os.path.isdir(destination):
@@ -551,51 +731,45 @@ def safe_cp(source:str, destination:str, create_dirs:bool=False):
                 os.makedirs(parent_dir, exist_ok=True)
         # actually copy the file
         shutil.copy2(source, destination)
+        info(f"Copied {source} to {destination}")
     except Exception as e:
         print(f"Error copying file from '{source}' to '{destination}': {e}")
-    info(f"Copied {source} to {destination}")
 
-def safe_rmdir(path):
-    """Safely and reliably remove a non-empty directory."""
-    try:
-        # Ensure the path exists
-        if os.path.exists(path):
-            shutil.rmtree(path)
-            info(f"Directory '{path}' has been removed successfully.")
-        else:
-            debug(f"Directory '{path}' does not exist.")
-    except Exception as e:
-        error(f"An error occurred while removing the directory '{path}': {e}")
 
-def safe_mkdir(path : str):
+def safe_mkdir(path : str) -> None:
+    '''Attempt to make dir at path, and make all subdirs up to that path'''
     if os.path.exists(path):
         return
-    left, right = os.path.split(os.path.relpath(path))
+    left, _ = os.path.split(os.path.relpath(path))
     if left and left not in ['.', '..', os.path.sep]:
         safe_mkdir(left)
     try:
         os.mkdir(path)
     except FileExistsError:
         pass
-    except:
+    except Exception as e1:
         try:
             os.system(f'mkdir -p {path}')
-        except Exception as e:
-            error(f'unable to mkdir {path=}, exception {e=}')
+        except Exception as e2:
+            error(f'unable to mkdir {path=}, exceptions {e1}, {e2=}')
+
 
-def safe_mkdirs(base : str, new_dirs : list):
+def safe_mkdirs(base : str, new_dirs : list) -> None:
+    '''Create new_dirs at base'''
     for p in new_dirs:
         safe_mkdir( os.path.join(base, p) )
 
-def safe_mkdir_for_file(filepath: str):
-    left, right = os.path.split(filepath)
+
+def safe_mkdir_for_file(filepath: str) -> None:
+    '''Given a new filepath, create dir for that filepath'''
+    left, _ = os.path.split(filepath)
     if left:
         safe_mkdir(left)
 
 
-def import_class_from_string(full_class_name):
+def import_class_from_string(full_class_name: str) -> None:
     """
-    Imports a class given its full name as a string.
+    Imports a class given its full name as a str.
 
     Args:
         full_class_name: The full name of the class,
@@ -604,18 +778,21 @@ def import_class_from_string(full_class_name):
     Returns:
         The imported class, or None if an error occurs.
     """
-    from importlib import import_module
     try:
         module_path, class_name = full_class_name.rsplit(".", 1)
         module = import_module(module_path)
         return getattr(module, class_name)
-    except (ImportError, AttributeError) as e:
-        print(f"Error importing class {full_class_name=}: {e=}")
+    except Exception as e:
+        print(f"Error importing class {full_class_name=}: {e}")
         return None
 
 
 class ShellCommandList(list):
-    def __init__(self, obj=None, tee_fpath=None):
+    '''Wrapper around a list, of str that we'll run as a subprocess command
+
+    included member var for tee_path, to save a log from this subprocess commands list
+    '''
+    def __init__(self, obj: object = None, tee_fpath: str = ''):
         super().__init__(obj)
         for k in ['tee_fpath']:
             setattr(self, k, getattr(obj, k, None))
@@ -623,29 +800,35 @@ class ShellCommandList(list):
             self.tee_fpath = tee_fpath
 
 
-def write_shell_command_file(dirpath : str, filename : str, command_lists : list, line_breaks : bool = False):
-    ''' Writes new file at {dirpath}/{filename} as a bash shell command, using command_lists (list of lists)
+def write_shell_command_file(
+        dirpath : str, filename : str, command_lists : list, line_breaks : bool = False
+) -> None:
+    ''' Writes new file at {dirpath}/{filename} as a bash shell command, using command_lists
+    (list of lists)
 
     -- dirpath (str)        -- directory where file is written (usually eda.work/{target}_sim
     -- filename (str)       -- filename, for example compile_only.sh
-    -- command_lists (list) -- list of (list or ShellCommandList), each item in the list is a list of commands (aka, how
-                               subprocess.run(args) uses a list of commands.
-    -- line_breaks (bool)   -- Set to True to have 1 word per line in the file followed by a line break.
-                               Default False has an entry in command_lists all on a single line.
+    -- command_lists (list) -- list of (list or ShellCommandList), each item in the list is a
+                               list of commands (aka, how subprocess.run(args) uses a list of
+                               commands.
+    -- line_breaks (bool)   -- Set to True to have 1 word per line in the file followed by a line
+                               break. Default False has an entry in command_lists all on a single
+                               line.
 
     Returns None, writes the file and chmod's it to 0x755.
-
     '''
+
     # command_lists should be a list-of-lists.
     bash_path = shutil.which('bash')
-    assert type(command_lists) is list, f'{command_lists=}'
+    assert isinstance(command_lists, list), f'{command_lists=}'
     fullpath = os.path.join(dirpath, filename)
-    with open(fullpath, 'w') as f:
+    with open(fullpath, 'w', encoding='utf-8') as f:
         if not bash_path:
             bash_path = "/bin/bash" # we may not get far, but we'll try
         f.write('#!' + bash_path + '\n\n')
         for obj in command_lists:
-            assert isinstance(obj, list), f'{obj=} (obj must be list/ShellCommandList) {command_lists=}'
+            assert isinstance(obj, list), \
+                f'{obj=} (obj must be list/ShellCommandList) {command_lists=}'
             clist = list(obj).copy()
             tee_fpath = getattr(obj, 'tee_fpath', None)
             if tee_fpath:
@@ -657,7 +840,7 @@ def write_shell_command_file(dirpath : str, filename : str, command_lists : list
                 else:
                     clist.append(f'2>&1 | tee {tee_fpath}')
 
-            if len(clist) > 0:
+            if clist:
                 if line_breaks:
                     # line_breaks=True - have 1 word per line, followed by \ and \n
                     sep = " \\" + "\n"
@@ -674,26 +857,6 @@ def write_shell_command_file(dirpath : str, filename : str, command_lists : list
         os.chmod(fullpath, 0o755)
 
 
-def write_eda_config_and_args(dirpath : str, filename=EDA_OUTPUT_CONFIG_FNAME, command_obj_ref=None):
-    import copy
-    if command_obj_ref is None:
-        return
-    fullpath = os.path.join(dirpath, filename)
-    data = dict()
-    for x in ['command_name', 'config', 'target', 'args', 'modified_args', 'defines',
-              'incdirs', 'files_v', 'files_sv', 'files_vhd']:
-        # Use deep copy b/c otherwise these are references to opencos.eda.
-        data[x] = copy.deepcopy(getattr(command_obj_ref, x, ''))
-
-    # fix some burried class references in command_obj_ref.config,
-    # otherwise we won't be able to safe load this yaml, so cast as str repr.
-    for k, v in command_obj_ref.config.items():
-        if k == 'command_handler':
-            data['config'][k] = str(v)
-
-    yaml_safe_writer(data=data, filepath=fullpath)
-
-
 def get_inferred_top_module_name(module_guess: str, module_fpath: str) -> str:
     '''Returns the best guess as the 'top' module name name, given a fpath where
 
@@ -718,114 +881,9 @@ def get_inferred_top_module_name(module_guess: str, module_fpath: str) -> str:
                 if bool(re.fullmatch(r'^\w+$', module_name)):
                     if module_name == module_guess:
                         return module_guess
-                    elif module_name:
+                    if module_name:
                         best_guess = module_name
     if best_guess:
         return best_guess
-    else:
-        return ''
-
-
-def subprocess_run(work_dir, command_list, fake:bool=False, shell=False) -> int:
-    ''' Run command_list in the foreground, with preference to use bash if shell=True.'''
-
-    if work_dir is not None:
-        os.chdir(work_dir)
 
-    is_windows = sys.platform.startswith('win')
-
-    proc_kwargs = {'shell': shell}
-    bash_exec = shutil.which('bash')
-    if shell and bash_exec and not is_windows:
-        proc_kwargs.update({'executable': bash_exec})
-
-    if not is_windows and shell:
-        c = ' '.join(command_list)
-    else:
-        c = command_list
-
-    if fake:
-        info(f"util.subprocess_run FAKE: would have called subprocess.run({c}, **{proc_kwargs}")
-        return 0
-    else:
-        debug(f"util.subprocess_run: About to call subprocess.run({c}, **{proc_kwargs}")
-        proc = subprocess.run(c, **proc_kwargs)
-        return proc.returncode
-
-
-def subprocess_run_background(work_dir, command_list, background=True, fake:bool=False,
-                              shell=False, tee_fpath=None) -> (str, str, int):
-    ''' Run command_list in the background, with preference to use bash if shell=True
-
-    tee_fpath is relative to work_dir.
-    '''
-
-
-    is_windows = sys.platform.startswith('win')
-
-    debug(f'util.subprocess_run_background: {background=} {tee_fpath=} {shell=}')
-
-    if fake:
-        # let subprocess_run handle it (won't run anything)
-        rc = subprocess_run(work_dir, command_list, fake=fake, shell=shell)
-        return '', '', rc
-
-    if work_dir is not None:
-        os.chdir(work_dir)
-
-    proc_kwargs = {'shell': shell,
-                   'stdout': subprocess.PIPE,
-                   'stderr': subprocess.STDOUT,
-                   }
-
-    bash_exec = shutil.which('bash')
-    if shell and bash_exec and not is_windows:
-        # Note - windows powershell will end up calling: /bin/bash /c, which won't work
-        proc_kwargs.update({'executable': bash_exec})
-
-    if not is_windows and shell:
-        c = ' '.join(command_list)
-    else:
-        c = command_list # leave as list.
-
-    debug(f"util.subprocess_run_background: about to call subprocess.Popen({c}, **{proc_kwargs})")
-    proc = subprocess.Popen(c, **proc_kwargs)
-
-    stdout = ''
-    stderr = ''
-    tee_fpath_f = None
-    if tee_fpath:
-        try:
-            tee_fpath_f = open(tee_fpath, 'w')
-        except Exception as e:
-            error(f'Unable to open file "{tee_fpath}" for writing, {e}')
-
-    for line in iter(proc.stdout.readline, b''):
-        line = line.rstrip().decode("utf-8", errors="replace")
-        if not background:
-            print(line)
-        if tee_fpath_f:
-            tee_fpath_f.write(line + '\n')
-        if global_log.file:
-            global_log.write(line, '\n')
-        stdout += line + '\n'
-
-    proc.communicate()
-    rc = proc.returncode
-    if tee_fpath_f:
-        tee_fpath_f.write(f'INFO: [{progname}] util.subprocess_run_background: returncode={rc}\n')
-        tee_fpath_f.close()
-        info('util.subprocess_run_background: wrote: ' + os.path.abspath(tee_fpath))
-
-    return stdout, stderr, rc
-
-
-def sanitize_defines_for_sh(value):
-    # Need to sanitize this for shell in case someone sends a +define+foo+1'b0,
-    # which needs to be escaped as +define+foo+1\'b0, otherwise bash or sh will
-    # think this is an unterminated string.
-    # TODO(drew): decide if we should instead us shlex.quote('+define+key=value')
-    # instead of this function.
-    if type(value) is str:
-        value = value.replace("'", "\\" + "'")
-    return value
+    return ''