docs: def write(source_mapping, output_stream=sys.stdout):
          """This method writes a Python module respresenting all the keys
          and values known to configman.
          """
          # a set of classes, modules and/or functions that are values in
          # configman options.  These values will have to be imported in the
          # module that this method is writing.
          set_of_classes_needing_imports = set()
          # once symbols are imported, they are in the namespace of the module,
          # but that's not where we want them.  We only want them to be values
          # in configman Options.  This set will be used to make a list of
          # these symbols, to forewarn a future configman that reads this
          # module, that it can ignore these symbols. This will prevent that
          # future configman from issuing a "mismatced symbols" warinng.
          symbols_to_ignore = set()
  
          # look ahead to see what sort of imports we're going to have to do
          for key in source_mapping.keys_breadth_first():
              value = source_mapping[key]
  
              if isinstance(value, Aggregation):
                  # Aggregations don't get included, skip on
                  continue
  
              if '.' in key:
                  # this indicates that there are things in nested namespaces,
                  # we will use the DotDict class to represent namespaces
                  set_of_classes_needing_imports.add(DotDict)
  
              option = None
              if isinstance(value, Option):
                  # it's the value inside the option, not the option itself
                  # that is of interest to us
                  option = value
                  value = option.value
  
              if value is None:
                  # we don't need in import anything having to do with None
                  continue
  
              if isclass(value) or ismodule(value) or isfunction(value):
                  # we know we need to import any of these types
                  set_of_classes_needing_imports.add(value)
              else:
                  try:
                      # perhaps the value is an instance of a class?  If so,
                      # we'll likely need to import that class, but only if
                      # we don't have a way to convert a string to that class
                      set_of_classes_needing_imports.add(value.__class__)
                  except AttributeError:
                      # it's not a class instance, we can skip on
                      pass
  
          # for everyone of the imports that we're going to have to create
          # we need to know the dotted module pathname and the name of the
          # of the class/module/function.  This routine make a list of 3-tuples
          # class, dotted_module_path, class_name
          class_and_module_path_and_class_name = []
          for a_class in set_of_classes_needing_imports:
              module_path, class_name = get_import_for_type(a_class)
              if (not module_path) and (not class_name):
                  continue
              class_and_module_path_and_class_name.append(
                  (a_class, module_path, class_name)
              )
  
          # using the collection of 3-tuples, create a lookup mapping where a
          # class is the key to a 2-tuple of the dotted_module_path & class_name.
          # This is also the appropriate time to detect any name collisions
          # and create a mapping of aliases, so we can resolve name collisions.
          class_name_by_module_path_list = defaultdict(list)
          alias_by_class = {}
          previously_used_names = set()
          for (
              a_class,
              a_module_path,
              class_name
          ) in class_and_module_path_and_class_name:
              if class_name:
                  if class_name in previously_used_names:
                      new_class_name_alias = "%s_%s" % (
                          a_module_path.replace('.', '_'),
                          class_name
                      )
                      alias_by_class[a_class] = new_class_name_alias
                      previously_used_names.add(new_class_name_alias)
                  else:
                      previously_used_names.add(class_name)
                  class_name_by_module_path_list[a_module_path].append(
                      (a_class, class_name)
                  )
  
          # start writing the output module
          print("# generated Python configman file\n", file=output_stream)
  
          # the first section that we're going to write is imports of the form:
          #     from X import Y
          # and
          #     from X import (
          #         A,
          #         B,
          #     )
          sorted_list = [x.value for x in sorted([OrderableObj(x) for x in
                         class_name_by_module_path_list.keys()])]
          for a_module_path in sorted_list:
              print(a_module_path)
              # if there is no module path, then it is something that we don't
              # need to import.  If the module path begins with underscore then
              # it is private and we ought not step into that mire.  If that
              # causes the output module to fail, it is up to the implementer
              # of the configman option to have created an approprate
              # "from_string" & "to_string" configman Option function references.
              if a_module_path is None or a_module_path.startswith('_'):
                  continue
              list_of_class_names = \
                  class_name_by_module_path_list[a_module_path]
              if len(list_of_class_names) > 1:
                  output_line = "from %s import (\n" % a_module_path
                  sorted_list = [x.value for x in sorted([OrderableTuple(x)
                                 for x in list_of_class_names])]
                  for a_class, a_class_name in sorted_list:
                      if a_class in alias_by_class:
                          output_line = "%s\n    %s as %s," % (
                              output_line,
                              a_class_name,
                              alias_by_class[a_class]
                          )
                          symbols_to_ignore.add(alias_by_class[a_class])
                      else:
                          output_line = "%s    %s,\n" % (
                              output_line,
                              a_class_name
                          )
                          symbols_to_ignore.add(a_class_name)
  
                  output_line = output_line + ')'
                  print(output_line.strip(), file=output_stream)
              else:
                  a_class, a_class_name = list_of_class_names[0]
                  output_line = "from %s import %s" % (
                      a_module_path,
                      a_class_name
                  )
                  if a_class in alias_by_class:
                      output_line = "%s as %s" % (
                          output_line,
                          alias_by_class[a_class]
                      )
                      symbols_to_ignore.add(alias_by_class[a_class])
                  else:
                      symbols_to_ignore.add(a_class_name)
                  print(output_line.strip(), file=output_stream)
          print('', file=output_stream)
  
          # The next section to write will be the imports of the form:
          #     import X
          sorted_list = [x.value for x in sorted([OrderableObj(x) for x in
                         class_name_by_module_path_list.keys()])]
          for a_module_path in sorted_list:
              list_of_class_names = \
                  class_name_by_module_path_list[a_module_path]
              a_class, a_class_name = list_of_class_names[0]
              if a_module_path:
                  continue
              import_str = ("import %s" % a_class_name).strip()
              symbols_to_ignore.add(a_class_name)
              print(import_str, file=output_stream)
  
          # See the explanation of 'symbols_to_ignore' above
          if symbols_to_ignore:
              print(
                  "\n" \
                  "# the following symbols will be ignored by configman when\n" \
                  "# this module is used as a value source.  This will\n" \
                  "# suppress the mismatch warning since these symbols are\n" \
                  "# values for options, not option names themselves.",
                  file=output_stream
              )
              print("ignore_symbol_list = [", file=output_stream)
              for a_symbol in sorted(symbols_to_ignore):
                  print('    "%s",' % a_symbol, file=output_stream)
              print(']\n', file=output_stream)
  
          # finally, as the last step, we need to write out the keys and values
          # will be used by a future configman as Options and values.
          sorted_keys = sorted(
              source_mapping.keys_breadth_first(include_dicts=True)
          )
          for key in sorted_keys:
              value = source_mapping[key]
              if isinstance(value, Namespace):
                  ValueSource.write_namespace(key, value, output_stream)
              elif isinstance(value, Option):
                  ValueSource.write_option(
                      key,
                      value,
                      alias_by_class,
                      output_stream
                  )
              elif isinstance(value, Aggregation):
                  # skip Aggregations
                  continue
              else:
                  ValueSource.write_bare_value(key, value, output_stream)