Merge pull request matplotlib#18216 from QuLogic/combine-Axes-children

MNT: Combine Axes.{lines,images,collections,patches,text,tables} into single list

Author: tacaswell

doc/api/next_api_changes/behavior/18216-ES.rst

@@ -0,0 +1,30 @@
+.. _Behavioral API Changes 3.5 - Axes children combined:
+
+``Axes`` children are no longer separated by type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Formerly, `.axes.Axes` children were separated by `.Artist` type, into sublists
+such as ``Axes.lines``. For methods that produced multiple elements (such as
+`.Axes.errorbar`), though individual parts would have similar *zorder*, this
+separation might cause them to be drawn at different times, causing
+inconsistent results when overlapping other Artists.
+
+Now, the children are no longer separated by type, and the sublist properties
+are generated dynamically when accessed. Consequently, Artists will now always
+appear in the correct sublist; e.g., if `.axes.Axes.add_line` is called on a
+`.Patch`, it will be appear in the ``Axes.patches`` sublist, _not_
+``Axes.lines``. The ``Axes.add_*`` methods will now warn if passed an
+unexpected type.
+
+Modification of the following sublists is still accepted, but deprecated:
+
+* ``Axes.artists``
+* ``Axes.collections``
+* ``Axes.images``
+* ``Axes.lines``
+* ``Axes.patches``
+* ``Axes.tables``
+* ``Axes.texts``
+
+To remove an Artist, use its `.Artist.remove` method. To add an Artist, use the
+corresponding ``Axes.add_*`` method.

doc/api/next_api_changes/deprecations/18216-ES.rst

@@ -0,0 +1,22 @@
+Modification of ``Axes`` children sublists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`Behavioral API Changes 3.5 - Axes children combined` for more
+information; modification of the following sublists is deprecated:
+
+* ``Axes.artists``
+* ``Axes.collections``
+* ``Axes.images``
+* ``Axes.lines``
+* ``Axes.patches``
+* ``Axes.tables``
+* ``Axes.texts``
+
+To remove an Artist, use its `.Artist.remove` method. To add an Artist, use the
+corresponding ``Axes.add_*`` method.
+
+Passing incorrect types to ``Axes.add_*`` methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``Axes.add_*`` methods will now warn if passed an unexpected type. See
+their documentation for the types they expect.

lib/matplotlib/axes/_axes.py

@@ -866,9 +866,9 @@ def axline(self, xy1, xy2=None, *, slope=None, **kwargs):
         if line.get_clip_path() is None:
             line.set_clip_path(self.patch)
         if not line.get_label():
-            line.set_label(f"_line{len(self.lines)}")
-        self.lines.append(line)
-        line._remove_method = self.lines.remove
+            line.set_label(f"_child{len(self._children)}")
+        self._children.append(line)
+        line._remove_method = self._children.remove
         self.update_datalim(datalim)
 
         self._request_autoscale_view()