docs: def topological_sort(unsorted_dict):
      """Sort objects by dependency.
  
      Sort a dict of obsoleting PID to obsoleted PID to a list of PIDs in order of
      obsolescence.
  
      Args:
        unsorted_dict : dict
          Dict that holds obsolescence information. Each ``key/value`` pair establishes
          that the PID in ``key`` identifies an object that obsoletes an object identifies
          by the PID in ``value``.
  
  
      Returns:
        tuple of sorted_list, unconnected_dict :
  
        ``sorted_list``: A list of PIDs ordered so that all PIDs that obsolete an object
        are listed after the object they obsolete.
  
        ``unconnected_dict``: A dict of PID to obsoleted PID of any objects that could not
        be added to a revision chain. These items will have obsoletes PIDs that directly
        or indirectly reference a PID that could not be sorted.
  
      Notes:
        ``obsoletes_dict`` is modified by the sort and on return holds any items that
        could not be sorted.
  
        The sort works by repeatedly iterating over an unsorted list of PIDs and
        moving PIDs to the sorted list as they become available. A PID is available to
        be moved to the sorted list if it does not obsolete a PID or if the PID it
        obsoletes is already in the sorted list.
  
      """
      sorted_list = []
      sorted_set = set()
      found = True
      unconnected_dict = unsorted_dict.copy()
      while found:
          found = False
          for pid, obsoletes_pid in list(unconnected_dict.items()):
              if obsoletes_pid is None or obsoletes_pid in sorted_set:
                  found = True
                  sorted_list.append(pid)
                  sorted_set.add(pid)
                  del unconnected_dict[pid]
      return sorted_list, unconnected_dict