DOC: Document set_figure() is a low-level API

timhoffm · timhoffm · commit f7538b85ad99 · 2026-02-12T15:18:57.000+01:00
Closes #31135.
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -450,6 +450,7 @@ Units
    Axes.convert_yunits
    Axes.have_units
 
+.. _axes-api-adding-artists:
 
 Adding artists
 ==============
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -767,6 +767,19 @@ def set_figure(self, fig):
         """
         Set the `.Figure` or `.SubFigure` instance the artist belongs to.
 
+        .. warning::
+
+            This function should typically not be called by users.
+
+            This is a low-level API and only modifies the internal state of the
+            Artist. Only modifying this is not enough and will typically lead
+            to an inconsistent state, because the state of the figure has to
+            be changed as well.
+
+            Users should typically instead call one of the high-level APIs, i.e.
+            `.Figure.add_artist` or one of the Axes methods
+            :ref:`axes-api-adding-artists`.
+
         Parameters
         ----------
         fig : `~matplotlib.figure.Figure` or `~matplotlib.figure.SubFigure`
