docs: def _parse_multifile(self, desired_type: Type[Union[Dict, List, Set, Tuple]], obj: PersistedObject,
                           parsing_plan_for_children: Dict[str, ParsingPlan], logger: Logger,
                           options: Dict[str, Dict[str, Any]]) \
              -> Union[Dict, List, Set, Tuple]:
          """
          Options may contain a section with id 'MultifileCollectionParser' containing the following options:
          * lazy_parsing: if True, the method will return immediately without parsing all the contents. Instead, the
          returned collection will perform the parsing the first time an item is required.
          * background_parsing: if True, the method will return immediately while a thread parses all the contents in
          the background. Note that users cannot set both lazy_parsing and background_parsing to True at the same time
  
          :param desired_type:
          :param obj:
          :param parsing_plan_for_children:
          :param logger:
          :param options:
          :return:
          """
  
          # first get the options and check them
          lazy_parsing = False
          background_parsing = False
  
          opts = self._get_applicable_options(options)
          for opt_key, opt_val in opts.items():
              if opt_key is 'lazy_parsing':
                  lazy_parsing = opt_val
              elif opt_key is 'background_parsing':
                  background_parsing = opt_val
              else:
                  raise Exception('Invalid option in MultiFileCollectionParser : ' + opt_key)
  
          check_var(lazy_parsing, var_types=bool, var_name='lazy_parsing')
          check_var(background_parsing, var_types=bool, var_name='background_parsing')
  
          if lazy_parsing and background_parsing:
              raise ValueError('lazy_parsing and background_parsing cannot be set to true at the same time')
  
          if lazy_parsing:
              # build a lazy dictionary
              results = LazyDictionary(sorted(list(parsing_plan_for_children.keys())),
                                       loading_method=lambda x: parsing_plan_for_children[x].execute(logger, options))
              # logger.debug('Assembling a ' + get_pretty_type_str(desired_type) + ' from all children of ' + str(obj)
              #             + ' (lazy parsing: children will be parsed when used) ')
              logger.debug('(P) {loc} : lazy parsing ON, children will be parsed only if/when used'.format(
                  loc=obj.get_pretty_location(blank_parent_part=(not GLOBAL_CONFIG.full_paths_in_logs),
                                              compact_file_ext=True)))
  
          elif background_parsing:
              # -- TODO create a thread to perform the parsing in the background
              raise ValueError('Background parsing is not yet supported')
  
          else:
              # Parse right now
              results = OrderedDict()
  
              # parse all children according to their plan
              # -- use key-based sorting on children to lead to reproducible results
              # (in case of multiple errors, the same error will show up first everytime)
              for child_name, child_plan in sorted(parsing_plan_for_children.items()):
                  results[child_name] = child_plan.execute(logger, options)
              # logger.debug('Assembling a ' + get_pretty_type_str(desired_type) + ' from all parsed children of '
              #             + str(obj))
  
          if issubclass(desired_type, list):
              # return a list facade
              return KeySortedListFacadeForDict(results)
          elif issubclass(desired_type, tuple):
              # return a tuple facade
              return KeySortedTupleFacadeForDict(results)
          elif issubclass(desired_type, set):
              # return a set facade
              return SetFacadeForDict(results)
          elif issubclass(desired_type, dict):
              # return the dict directly
              return results
          else:
              raise TypeError('Cannot build the desired collection out of the multifile children: desired type is not '
                              'supported: ' + get_pretty_type_str(desired_type))