docs: def magic_read(infile, data=None, return_keys=False, verbose=False):
      """
      Reads  a Magic template file, returns  data in a list of dictionaries.
  
      Parameters
      ___________
          Required:
              infile : the MagIC formatted tab delimited data file
                  first line contains 'tab' in the first column and the data file type in the second (e.g., measurements, specimen, sample, etc.)
          Optional:
              data : data read in with, e.g., file.readlines()
      Returns
      _______
          list of dictionaries, file type
      """
      if infile:
          if not os.path.exists(infile):
              if return_keys:
                  return [], 'empty_file', []
              return [], 'empty_file'
      hold, magic_data, magic_record, magic_keys = [], [], {}, []
      if data:
          lines = list(data)
      elif (not data) and (not infile):
          if return_keys:
              return [], 'empty_file', []
          return [], 'empty_file'
      else:
          # if the file doesn't exist, end here
          if not os.path.exists(infile):
              if return_keys:
                  return [], 'bad_file', []
              return [], 'bad_file'
          # use custom pmagpy open_file
          lines = open_file(infile, verbose=verbose)
      if not lines:
          if return_keys:
              return [], 'bad_file', []
          return [], 'bad_file'
      d_line = lines[0][:-1].strip('\n').strip('\r').strip('\t')
      if not d_line:
          if return_keys:
              return [], 'empty_file', []
          return [], 'empty_file'
      if d_line[0] == "s" or d_line[1] == "s":
          delim = 'space'
      elif d_line[0] == "t" or d_line[1] == "t":
          delim = 'tab'
      else:
          print('-W- error reading {}. Check that this is a MagIC-format file'.format(infile))
          if return_keys:
              return [], 'bad_file', []
          return [], 'bad_file'
      if delim == 'space':
          file_type = d_line.split()[1]
      if delim == 'tab':
          file_type = d_line.split('\t')[1]
      if file_type == 'delimited':
          if delim == 'space':
              file_type = d_line.split()[2]
          if delim == 'tab':
              file_type = d_line.split('\t')[2]
      line = lines[1].strip('\n').strip('\r')
      if delim == 'space':
          line = line.split()  # lines[1][:-1].split()
      if delim == 'tab':
          line = line.split('\t')  # lines[1][:-1].split('\t')
      for key in line:
          magic_keys.append(key)
      lines = lines[2:]
      if len(lines) < 1:
          if return_keys:
              return [], 'empty_file', []
          return [], 'empty_file'
      for line in lines[:-1]:
          line.replace('\n', '')
          if delim == 'space':
              rec = line[:-1].split()
          if delim == 'tab':
              rec = line[:-1].split('\t')
          hold.append(rec)
      line = lines[-1].replace('\n', '').replace('\r', '')
      if delim == 'space':
          rec = line[:-1].split()
      if delim == 'tab':
          rec = line.split('\t')
      hold.append(rec)
      for rec in hold:
          magic_record = {}
          if len(magic_keys) > len(rec):
              # pad rec with empty strings if needed
              for i in range(len(magic_keys) - len(rec)):
                  rec.append('')
          if len(magic_keys) != len(rec):
              # ignores this warning when reading the dividers in an upload.txt
              # composite file
              if rec != ['>>>>>>>>>>'] and 'delimited' not in rec[0]:
                  print("Warning: Uneven record lengths detected in {}: ".format(infile))
                  print('keys:', magic_keys)
                  print('record:', rec)
          # modified by Ron Shaar:
          # add a health check:
          # if len(magic_keys) > len(rec): take rec
          # if len(magic_keys) < len(rec): take magic_keys
          # original code: for k in range(len(rec)):
          # channged to: for k in range(min(len(magic_keys),len(rec))):
          for k in range(min(len(magic_keys), len(rec))):
              magic_record[magic_keys[k]] = rec[k].strip('\n').strip('\r')
          magic_data.append(magic_record)
      magictype = file_type.lower().split("_")
      Types = ['er', 'magic', 'pmag', 'rmag']
      if magictype in Types:
          file_type = file_type.lower()
      if return_keys:
          return magic_data, file_type, magic_keys
      return magic_data, file_type