code: def promote_loops( loops, index, shared ):
      
      for loop in loops:
          loop = list(loop)
          members = [index[addr] for addr in loop]
          external_parents = list(set([
              addr for addr in sum([shared.get(addr,[]) for addr in loop],[])
              if addr not in loop 
          ]))
          if external_parents:
              if len(external_parents) == 1:
                  # potentially a loop that's been looped...
                  parent = index.get( external_parents[0] )
                  if parent['type'] == LOOP_TYPE:
                      continue 
              # we haven't already been looped...
              loop_addr = new_address( index )
              shared[loop_addr] = external_parents
              loop_record = index[loop_addr] = {
                  'address': loop_addr,
                  'refs': loop,
                  'parents': external_parents,
                  'type': LOOP_TYPE,
                  'size': 0,
              }
              for member in members:
                  # member's references must *not* point to loop...
                  member['refs'] = [
                      ref for ref in member['refs']
                      if ref not in loop 
                  ]
                  # member's parents are *just* the loop
                  member['parents'][:] = [loop_addr]
              # each referent to loop holds a single reference to the loop rather than many to children
              for parent in external_parents:
                  parent = index[parent]
                  for member in members:
                      rewrite_references( parent['refs'], member['address'], None )
                  parent['refs'].append( loop_addr )
docs: Turn loops into "objects" that can be processed normally