Introduce ArtistList for FigureBase by rcomer · Pull Request #31746 · matplotlib/matplotlib

rcomer · 2026-05-25T19:28:40Z

PR summary

We deprecated directly mutating the artist lists on Axes a while ago, but apparently forgot to do that on Figure as well!

This PR generalises the ArtistList so it can work for both figures and axes. The new _FigureArtistList subclasses it just to add the deprecated methods. I adapted the deprecated methods and their tests from #18216, where this was originally done for Axes. Note that fig.subfigures is still a plain list. I do not think subfigures belong in fig._children, but rather should have their own handling similar to fig.axes. That can be done separately.

AI Disclosure

I asked duck.ai how to get a class as a string, to use in the ArtistList repr self._parent.__class__.__name__.

PR checklist

"closes #0000" is in the body of the PR description to link the related issue
new and changed code is tested
Plotting related features are demonstrated in an example
New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

rcomer · 2026-05-25T21:24:09Z

It seems I have discovered something that only works at py314 🧐

timhoffm · 2026-05-30T22:34:12Z

+    A sublist of Figure children based on their type.  This subclass exists only to
+    provide deprecation warnings.  When the deprecations expire, use ArtistList


Wouldn't it be simpler to add

if isinstance(parent, FigureBase): _api.warn_deprecated(...)

or even

self.warn_deprecated_if_on_figure(...)

to the regular ArtistList methods?

ArtistList is already immutable. It doesn’t have these methods.

Ok, I see. There's a lot of unforeseen complexity in the migration of ArtistList from AxesBase to artist, which gives me a bit of a headeache overlooking the complete PR. In hindsight it would likely have been better to either split this in two PRs / commits: (1) move ArtistList (2) use ArtistList in Figure; or alternatively just duplicate the 70 lines of ArtistList in Figure, and when the Figure deprecations run out and both classes become identical merge them back together. But I'm somewhat reluctant to request that now.

Ah sorry. It did occur to me when I was moving it that splitting into separate commits for moving and modifying might help the review, but at the time I couldn't quite see how to split it. I will have a go at just moving it in a separate branch and if it works I'll make a prequel PR.

... and now the difference appears.

rcomer · 2026-05-31T14:30:45Z

Hid the discussion about doc-failure debugging as that is now fixed in #31794 and summarised at #31794 (comment).

timhoffm · 2026-07-19T02:12:47Z

+# children. Adding images and text is usually achieved with the
+# `~.Figure.figimage` and `~.Figure.text` methods.  Other artists may be added
+# with the `~.Figure.add_artist` method.


To me, there is not enough distinction between the factory methods and add_artist. You are using "add" with different semantics: For the factory methods it's a high-level logical add ("add a text to the figure") whereas for add_artist it's a technical "add an Artists instance to the figure".

Suggested change

# children. Adding images and text is usually achieved with the

# `~.Figure.figimage` and `~.Figure.text` methods. Other artists may be added

# with the `~.Figure.add_artist` method.

# children. Artists are added to theses lists via `~.Figure.add_artist`.

Then put the example (which now does not contain transforms.

Then add

# As a convenience for images and text, the helper methods # `~.Figure.figimage` and `~.Figure.text` conveniently create the # respective Artists and internally call `~.Figure.add_artist`.

to set the stage for images and text.

I tweaked your suggestion slightly as currently figimage and text are not calling add_artist but directly appending to _children. I did go back and forth on that:

Obviously using add_artist would mean less code duplication.

Using _children.append kept the change within those functions minimal.

If figimage used add_artist then it would need to explicitly set the IdentityTransform to prevent add_artist setting transSubfigure. This might arguably be a good thing to do (and would fix [Bug]: Figure.add_artist() fails to re-render an image previously added via Figure.figimage() after .remove() #31730) but it created an extra thing to think about and there was already more than enough in this PR!

Possibly some other consideration that I have since forgotten...

QuLogic · 2026-07-25T03:25:52Z

+        return _FigureArtistList(self, 'texts', valid_types=Text)
+
+
+
    def _get_draw_artists(self, renderer):


Too many blank lines.

Suggested change

return _FigureArtistList(self, 'texts', valid_types=Text)

def _get_draw_artists(self, renderer):

return _FigureArtistList(self, 'texts', valid_types=Text)

def _get_draw_artists(self, renderer):

Huh. I wonder why ruff doesn't catch that.

Even though we enable E rules, we also have explicit-preview-rules=true, so those blank line ones are not enabled yet. #32126

Following matplotlib#18216 for Axes artists, combine all figure artists except axes and subfigures into a single list and deprecate modifying the lists directly.

QuLogic · 2026-07-28T03:54:20Z

So I'm looking at type hint errors, and I noticed that this doesn't mark the Figure-level lists as modifiable since it uses the original ArtistList. We have a mix of whether we change type hints to match future behaviour or not, so I just wanted to flag this here in case we did want the type hints to match current behaviour.

timhoffm · 2026-07-28T04:35:30Z

Let’s not jump extra hoops. This will become immutable in the future, so already flaggingbitbin typing is ok.

rcomer added API: changes Changes to the public API, typically requiring deprecation. status: waiting for other PR labels May 25, 2026

rcomer added this to the v3.12.0 milestone May 25, 2026

rcomer force-pushed the fig-artistlist branch from 1549484 to ca8db73 Compare May 26, 2026 12:25

This comment was marked as outdated.

Sign in to view

rcomer force-pushed the fig-artistlist branch 3 times, most recently from 527f6fe to 81d29da Compare May 26, 2026 20:21

github-actions Bot added the status: needs rebase label May 27, 2026

rcomer force-pushed the fig-artistlist branch from 81d29da to 0d5b37d Compare May 27, 2026 17:40

github-actions Bot removed topic: mplot3d GUI: Qt backend: cairo CI: Run cibuildwheel Run wheel building tests on a PR CI: Run cygwin Run cygwin tests on a PR Documentation: devdocs files in doc/devel status: needs rebase labels May 27, 2026

rcomer removed the status: waiting for other PR label May 27, 2026

This comment was marked as outdated.

Sign in to view

rcomer force-pushed the fig-artistlist branch from 6b557f4 to 61392df Compare May 30, 2026 15:27

github-actions Bot added the topic: text label May 30, 2026

rcomer force-pushed the fig-artistlist branch from 61392df to a2b6fa6 Compare May 30, 2026 15:29

This comment was marked as outdated.

Sign in to view

rcomer marked this pull request as ready for review May 30, 2026 15:49

timhoffm reviewed May 30, 2026

View reviewed changes

rcomer marked this pull request as draft May 31, 2026 09:51

rcomer mentioned this pull request May 31, 2026

MNT: move ArtistList into artist module #31794

Merged

2 tasks

rcomer added the status: waiting for other PR label May 31, 2026

github-actions Bot added the status: needs rebase label Jun 25, 2026

rcomer force-pushed the fig-artistlist branch from a2b6fa6 to 7b67f2c Compare July 17, 2026 08:36

github-actions Bot removed topic: text status: needs rebase labels Jul 17, 2026

rcomer force-pushed the fig-artistlist branch from 7b67f2c to dc738f1 Compare July 18, 2026 09:05

github-actions Bot removed the topic: axes label Jul 18, 2026

rcomer removed the status: waiting for other PR label Jul 18, 2026

rcomer marked this pull request as ready for review July 18, 2026 09:25

timhoffm approved these changes Jul 19, 2026

View reviewed changes

rcomer force-pushed the fig-artistlist branch from dc738f1 to 8bd4e25 Compare July 19, 2026 09:26

rcomer mentioned this pull request Jul 23, 2026

[Bug]: Figure.add_artist() fails to re-render an image previously added via Figure.figimage() after .remove() #31730

Open

QuLogic reviewed Jul 25, 2026

View reviewed changes

Introduce ArtistList for FigureBase

9ce5e3d

Following matplotlib#18216 for Axes artists, combine all figure artists except axes and subfigures into a single list and deprecate modifying the lists directly.

rcomer force-pushed the fig-artistlist branch from 8bd4e25 to 9ce5e3d Compare July 26, 2026 11:10

QuLogic approved these changes Jul 27, 2026

View reviewed changes

QuLogic merged commit 7ad06b1 into matplotlib:main Jul 27, 2026
41 checks passed

rcomer deleted the fig-artistlist branch July 28, 2026 11:03

		A sublist of Figure children based on their type. This subclass exists only to
		provide deprecation warnings. When the deprecations expire, use ArtistList

		return _FigureArtistList(self, 'texts', valid_types=Text)



		def _get_draw_artists(self, renderer):

Uh oh!

Uh oh!

Conversation

rcomer commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR summary

AI Disclosure

PR checklist

Uh oh!

rcomer commented May 25, 2026

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rcomer commented May 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

QuLogic commented Jul 28, 2026

Uh oh!

timhoffm commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rcomer commented May 25, 2026 •

edited

Loading