docs: def _overlay_expand(self):
          """This method overlays each of the value sources onto the default
          in each of the defined options.  It does so using a breadth first
          iteration, overlaying and expanding each level of the tree in turn.
          As soon as no changes were made to any level, the loop breaks and the
          work is done.  The actual action of the overlay is to take the value
          from the source and copy into the 'default' member of each Option
          object.
  
          "expansion" means converting an option value into its real type from
          string. The conversion is accomplished by simply calling the
          'set_value' method of the Option object.  If the resultant type has its
          own configuration options, bring those into the current namespace and
          then proceed to overlay/expand those.
          """
          new_keys_have_been_discovered = True  # loop control, False breaks loop
          finished_keys = set()
          all_reference_values = {}
  
          while new_keys_have_been_discovered:  # loop until nothing more is done
              # names_of_all_exsting_options holds a list of all keys in the
              # option definitons in breadth first order using this form:
              # [ 'x', 'y', 'z', 'x.a', 'x.b', 'z.a', 'z.b', 'x.a.j', 'x.a.k',
              # 'x.b.h']
              names_of_all_exsting_options = [
                  x for x
                  in self.option_definitions.keys_breadth_first()
                  if isinstance(self.option_definitions[x], Option)
              ]
              new_keys_have_been_discovered = False  # setup to break loop
  
              # create alternate paths options
              set_of_reference_value_option_names = \
                  self._create_reference_value_options(
                      names_of_all_exsting_options,
                      finished_keys
                  )
  
              for a_ref_option_name in set_of_reference_value_option_names:
                  if a_ref_option_name not in all_reference_values:
                      all_reference_values[a_ref_option_name] = []
  
              all_keys = list(set_of_reference_value_option_names) \
                  + names_of_all_exsting_options
  
              # previous versions of this method pulled the values from the
              # values sources deeper within the following nested loops.
              # that was not necessary and caused a lot of redundant work.
              # the 'values_from_all_sources' now holds all the the values
              # from each of the value sources.
              values_from_all_sources = [
                  a_value_source.get_values(
                      self,  # pass in the config_manager itself
                      True,  # ignore mismatches
                      self.value_source_object_hook  # build with this class
                  )
                  for a_value_source in self.values_source_list
              ]
  
              # overlay process:
              # fetch all the default values from the value sources before
              # applying the from string conversions
  
              for key in all_keys:
                  if key in finished_keys:
                      continue
                  #if not isinstance(an_option, Option):
                  #   continue  # aggregations and other types are ignored
                  # loop through all the value sources looking for values
                  # that match this current key.
                  if self.option_definitions[key].reference_value_from:
                      reference_value_from = (
                          self.option_definitions[key].reference_value_from
                      )
                      top_key = key.split('.')[-1]
                      self.option_definitions[key].default = (
                          self.option_definitions[reference_value_from]
                          [top_key].default
                      )
                      all_reference_values[
                          '.'.join((reference_value_from, top_key))
                      ].append(
                          key
                      )
  
                  an_option = self.option_definitions[key]
                  if key in all_reference_values:
                      # make sure that this value gets propagated to keys
                      # even if the keys have already been overlaid
                      finished_keys -= set(
                          all_reference_values[key]
                      )
  
                  for val_src_dict in values_from_all_sources:
                      try:
  
                          # overlay the default with the new value from
                          # the value source.  This assignment may come
                          # via acquisition, so the key given may not have
                          # been an exact match for what was returned.
                          an_option.has_changed = (
                              an_option.default != val_src_dict[key]
                          )
                          an_option.default = val_src_dict[key]
                          if key in all_reference_values:
                              # make sure that this value gets propagated to keys
                              # even if the keys have already been overlaid
                              finished_keys -= set(
                                  all_reference_values[key]
                              )
                      except KeyError as x:
                          pass  # okay, that source doesn't have this value
  
              # expansion process:
              # step through all the keys converting them to their proper
              # types and bringing in any new keys in the process
              for key in all_keys:
                  if key in finished_keys:
                      continue
                  # mark this key as having been seen and processed
                  finished_keys.add(key)
                  an_option = self.option_definitions[key]
                  #if not isinstance(an_option, Option):
                  #    continue  # aggregations, namespaces are ignored
                  # apply the from string conversion to make the real value
                  an_option.set_value(an_option.default)
                  # new values have been seen, don't let loop break
                  new_keys_have_been_discovered = True
                  try:
                      try:
                          # try to fetch new requirements from this value
                          new_requirements = \
                              an_option.value.get_required_config()
                      except (AttributeError, KeyError):
                          new_requirements = getattr(
                              an_option.value,
                              'required_config',
                              None
                          )
                      # make sure what we got as new_req is actually a
                      # Mapping of some sort
                      if not isinstance(new_requirements, collections.Mapping):
                          # we didn't get a mapping, perhaps the option value
                          # was a Mock object - in any case we can't try to
                          # interpret 'new_req' as a configman requirement
                          # collection.  We must abandon processing this
                          # option further
                          continue
                      if not isinstance(new_requirements, Namespace):
                          new_requirements = Namespace(
                              initializer=new_requirements
                          )
                      # get the parent namespace
                      current_namespace = self.option_definitions.parent(key)
                      if current_namespace is None:
                          # we're at the top level, use the base namespace
                          current_namespace = self.option_definitions
                      if current_namespace._reference_value_from:
                          # don't expand things that are in reference value
                          # namespaces, they will be populated by expanding the
                          # targets
                          continue
                      # some new Options to be brought in may have already been
                      # seen and in the finished_keys set.  They must be reset
                      # as unfinished so that a new default doesn't permanently
                      # overwrite any of the values already placed by the
                      # overlays.  So we've got to remove those keys from the
                      # finished keys list.
                      # Before we can do that however, we need the fully
                      # qualified names for the new keys.
                      qualified_parent_name_list = key.rsplit('.', 1)
                      if len(qualified_parent_name_list) > 1:
                          qualified_parent_name = qualified_parent_name_list[0]
                      else:
                          qualified_parent_name = ''
  
                      finished_keys = finished_keys.difference(
                          '.'.join((qualified_parent_name, ref_option_name))
                          for ref_option_name in new_requirements
                      )
                      # add the new Options to the namespace
                      new_namespace = new_requirements.safe_copy(
                          an_option.reference_value_from
                      )
  
                      for new_key in new_namespace.keys_breadth_first():
                          if new_key not in current_namespace:
                              current_namespace[new_key] = new_namespace[new_key]
                  except AttributeError as x:
                      # there are apparently no new Options to bring in from
                      # this option's value
                      pass
          return finished_keys