Merge pull request #22215 from meeseeksmachine/auto-backport-of-pr-22177-on-v3.5.x

timhoffm · web-flow · commit 7b50116cbc1b · 2022-01-12T19:18:19.000+01:00
Backport PR #22177 on branch v3.5.x (Document ArtistList)
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -607,3 +607,5 @@ Other
    Axes.get_transformed_clip_path_and_affine
    Axes.has_data
    Axes.set
+
+.. autoclass:: matplotlib.axes.Axes.ArtistList
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1315,8 +1315,12 @@ class ArtistList(MutableSequence):
         """
         A sublist of Axes children based on their type.
 
-        This exists solely to warn on modification. In the future, the
-        type-specific children sublists will be immutable tuples.
+        The type-specific children sublists will become immutable in
+        Matplotlib 3.7. Then, these artist lists will likely be replaced by
+        tuples. Use as if this is a tuple already.
+
+        This class exists only for the transition period to warn on the
+        deprecated modifcation of artist lists.
         """
         def __init__(self, axes, prop_name, add_name,
                      valid_types=None, invalid_types=None):
