Turn ContourSet into a standard Collection artist.

Keep (some) backcompat by making access to ContourSet.collection trigger
the self-replacement of the ContourSet by the old-style list of
PathCollections.

The baseline images are slighly shifted, but the new images actually
look more correct:

- contour_corner_mask_False the old implementation would white out some
  extra L-shaped areas between masked regions (particularly visible in
  the diff image).
- 3d/contour3d: The order of the "contours" on the panes is a bit
  arbitrary, but note that previously on the left pane the white
  (medium) contour was drawn first, then overlaid with the blue (low)
  contour, then overlaid with the red (high) contour; the new image
  draws the contours more consistently in the order blue/white/red.
- 3d/tricontour: The new draw order of the unfilled contours (on the left)
  is clearly better, with the highest contour (light green) drawn above
  the lower one (medium green).

Limitations:
- 3d contours used to rely on being able to set a different sort_zpos
  for each contour level; this change gets rid of that.  Per the above
  it's not clear this is actually worse in practice...

doc/api/next_api_changes/deprecations/25247-AL.rst

@@ -0,0 +1,9 @@
+``ContourSet.collections``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+... is deprecated.  `.ContourSet` is now implemented as a single `.Collection` of paths,
+each path corresponding to a contour level, possibly including multiple unconnected
+components.
+
+During the deprecation period, accessing ``ContourSet.collections`` will revert the
+current ContourSet instance to the old object layout, with a separate `.PathCollection`
+per contour level.

galleries/examples/images_contours_and_fields/contour_demo.py

@@ -85,7 +85,9 @@
                 linewidths=2, extent=(-3, 3, -2, 2))
 
 # Thicken the zero contour.
-CS.collections[6].set_linewidth(4)
+lws = np.broadcast_to(CS.get_linewidth(), len(levels)).copy()
+lws[6] = 4
+CS.set_linewidth(lws)
 
 ax.clabel(CS, levels[1::2],  # label every second level
           inline=True, fmt='%1.1f', fontsize=14)

galleries/examples/images_contours_and_fields/contour_image.py

@@ -56,9 +56,7 @@
 
 # We don't really need dashed contour lines to indicate negative
 # regions, so let's turn them off.
-
-for c in cset2.collections:
-    c.set_linestyle('solid')
+cset2.set_linestyle('solid')
 
 # It is easier here to make a separate call to contour than
 # to set up an array of colors and linewidths.

galleries/examples/images_contours_and_fields/contours_in_optimization_demo.py

@@ -17,7 +17,6 @@
 `~matplotlib.patheffects.TickedStroke` to illustrate a constraint in
 a typical optimization problem, the angle should be set between
 zero and 180 degrees.
-
 """
 
 import matplotlib.pyplot as plt
@@ -48,16 +47,13 @@
 ax.clabel(cntr, fmt="%2.1f", use_clabeltext=True)
 
 cg1 = ax.contour(x1, x2, g1, [0], colors='sandybrown')
-plt.setp(cg1.collections,
-         path_effects=[patheffects.withTickedStroke(angle=135)])
+cg1.set(path_effects=[patheffects.withTickedStroke(angle=135)])
 
 cg2 = ax.contour(x1, x2, g2, [0], colors='orangered')
-plt.setp(cg2.collections,
-         path_effects=[patheffects.withTickedStroke(angle=60, length=2)])
+cg2.set(path_effects=[patheffects.withTickedStroke(angle=60, length=2)])
 
 cg3 = ax.contour(x1, x2, g3, [0], colors='mediumblue')
-plt.setp(cg3.collections,
-         path_effects=[patheffects.withTickedStroke(spacing=7)])
+cg3.set(path_effects=[patheffects.withTickedStroke(spacing=7)])
 
 ax.set_xlim(0, 4)
 ax.set_ylim(0, 4)

galleries/examples/misc/patheffect_demo.py

@@ -29,8 +29,7 @@
 ax2.imshow(arr)
 cntr = ax2.contour(arr, colors="k")
 
-plt.setp(cntr.collections, path_effects=[
-    patheffects.withStroke(linewidth=3, foreground="w")])
+cntr.set(path_effects=[patheffects.withStroke(linewidth=3, foreground="w")])
 
 clbls = ax2.clabel(cntr, fmt="%2.0f", use_clabeltext=True)
 plt.setp(clbls, path_effects=[

galleries/examples/misc/tickedstroke_demo.py

@@ -89,16 +89,13 @@
 ax.clabel(cntr, fmt="%2.1f", use_clabeltext=True)
 
 cg1 = ax.contour(x1, x2, g1, [0], colors='sandybrown')
-plt.setp(cg1.collections,
-         path_effects=[patheffects.withTickedStroke(angle=135)])
+cg1.set(path_effects=[patheffects.withTickedStroke(angle=135)])
 
 cg2 = ax.contour(x1, x2, g2, [0], colors='orangered')
-plt.setp(cg2.collections,
-         path_effects=[patheffects.withTickedStroke(angle=60, length=2)])
+cg2.set(path_effects=[patheffects.withTickedStroke(angle=60, length=2)])
 
 cg3 = ax.contour(x1, x2, g3, [0], colors='mediumblue')
-plt.setp(cg3.collections,
-         path_effects=[patheffects.withTickedStroke(spacing=7)])
+cg3.set(path_effects=[patheffects.withTickedStroke(spacing=7)])
 
 ax.set_xlim(0, 4)
 ax.set_ylim(0, 4)

lib/matplotlib/axes/_base.py

@@ -2171,15 +2171,9 @@ def _sci(self, im):
         ``pyplot.viridis``, and other functions such as `~.pyplot.clim`.  The
         current image is an attribute of the current Axes.
         """
-        _api.check_isinstance(
-            (mpl.contour.ContourSet, mcoll.Collection, mimage.AxesImage),
-            im=im)
-        if isinstance(im, mpl.contour.ContourSet):
-            if im.collections[0] not in self._children:
-                raise ValueError("ContourSet must be in current Axes")
-        elif im not in self._children:
-            raise ValueError("Argument must be an image, collection, or "
-                             "ContourSet in this Axes")
+        _api.check_isinstance((mcoll.Collection, mimage.AxesImage), im=im)
+        if im not in self._children:
+            raise ValueError("Argument must be an image or collection in this Axes")
         self._current_image = im
 
     def _gci(self):

lib/matplotlib/colorbar.py

@@ -767,15 +767,15 @@ def add_lines(self, *args, **kwargs):
              lambda self, levels, colors, linewidths, erase=True: locals()],
             self, *args, **kwargs)
         if "CS" in params:
-            self, CS, erase = params.values()
-            if not isinstance(CS, contour.ContourSet) or CS.filled:
+            self, cs, erase = params.values()
+            if not isinstance(cs, contour.ContourSet) or cs.filled:
                 raise ValueError("If a single artist is passed to add_lines, "
                                  "it must be a ContourSet of lines")
             # TODO: Make colorbar lines auto-follow changes in contour lines.
             return self.add_lines(
-                CS.levels,
-                CS.to_rgba(CS.cvalues, CS.alpha),
-                [coll.get_linewidths()[0] for coll in CS.collections],
+                cs.levels,
+                cs.to_rgba(cs.cvalues, cs.alpha),
+                cs.get_linewidths(),
                 erase=erase)
         else:
             self, levels, colors, linewidths, erase = params.values()