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; see e.g. contour_corner_mask_False.png where the old
("-expected.png") implementation would white out some extra L-shaped
areas between masked regions (particularly visible in the diff image).

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.

lib/matplotlib/axes/_base.py

@@ -2179,10 +2179,7 @@ def _sci(self, im):
         _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:
+        if im not in self._children:
             raise ValueError("Argument must be an image, collection, or "
                              "ContourSet in this Axes")
         self._current_image = im

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()