docs: def _polytree_node_to_shapely(node):
      """
      Recurses down a Clipper PolyTree, extracting the results as Shapely
      objects.
  
      Returns a tuple of (list of polygons, list of children)
      """
  
      polygons = []
      children = []
      for ch in node.Childs:
          p, c = _polytree_node_to_shapely(ch)
          polygons.extend(p)
          children.extend(c)
  
      if node.IsHole:
          # check expectations: a node should be a hole, _or_ return children.
          # this is because children of holes must be outers, and should be on
          # the polygons list.
          assert len(children) == 0
          if node.Contour:
              children = [node.Contour]
          else:
              children = []
  
      elif node.Contour:
          poly = _contour_to_poly(node.Contour)
  
          # we add each inner one-by-one so that we can reject them individually
          # if they cause the polygon to become invalid. if the shape has lots
          # of inners, then this can mean a proportional amount of work, and may
          # take 1,000s of seconds. instead, we can group inners together, which
          # reduces the number of times we call the expensive 'difference'
          # method.
          block_size = 200
          if len(children) > block_size:
              inners = _union_in_blocks(children, block_size)
          else:
              inners = _generate_polys(children)
  
          for inner in inners:
              # the difference of two valid polygons may fail, and in this
              # situation we'd like to be able to display the polygon anyway.
              # so we discard the bad inner and continue.
              #
              # see test_polygon_inners_crossing_outer for a test case.
              try:
                  diff = poly.difference(inner)
              except:
                  continue
  
              if not diff.is_valid:
                  diff = diff.buffer(0)
  
              # keep this for when https://trac.osgeo.org/geos/ticket/789 is
              # resolved.
              #
              #  assert diff.is_valid, \
              #      "Difference of %s and %s did not make valid polygon %s " \
              #      " because %s" \
              #      % (poly.wkt, inner.wkt, diff.wkt, explain_validity(diff))
              #
              # NOTE: this throws away the inner ring if we can't produce a
              # valid difference. not ideal, but we'd rather produce something
              # that's valid than nothing.
              if diff.is_valid:
                  poly = diff
  
          assert poly.is_valid
          if poly.type == 'MultiPolygon':
              polygons.extend(poly.geoms)
          else:
              polygons.append(poly)
          children = []
  
      else:
          # check expectations: this branch gets executed if this node is not a
          # hole, and has no contour. in that situation we'd expect that it has
          # no children, as it would not be possible to subtract children from
          # an empty outer contour.
          assert len(children) == 0
  
      return (polygons, children)