MNT: move ArtistList into artist module by rcomer · Pull Request #31794 · matplotlib/matplotlib

rcomer · 2026-05-31T11:08:36Z

PR summary

Make ArtistList a standalone class in the artist module, and deprecate accessing as an attribute of the axes class. This is pulled out of #31746 to make the review easier. The only changes to the AxesList class are

White space
__init__ call sequence is now on one line
The isinstance call in __add__ now checks for ArtistList instead of Axes.ArtistList

I suspect this will need the second commit from #31746, but I'm curious to actually see the doc failure.

AI Disclosure

No AI used.

PR checklist

[n/a] "closes #0000" is in the body of the PR description to link the related issue
[n/a] new and changed code is tested
[n/a] 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

timhoffm

Thanks, much easier to review 😄.

As expected, the doc failure is the same strange inheritance-diagram related failure as in the other PR.

rcomer · 2026-05-31T14:09:57Z

Force-pushed because I also needed to rename the changenote filename, and I wanted that in the first commit.

rcomer · 2026-05-31T14:25:01Z

Notes on second commit for second reviewer:

For some reason, modifying the artist_api.rst triggered warnings and therefore a Circle-CI failure like this. I demonstrated that removing the inheritance diagram at the top of the file made the problem go away, so that seems to be the cause but I'm unclear why the inheritance diagram has not been a problem before now.

To fix it, I went ahead and added docs for the missing private artists.

For _ImageBase and _AnnotationBase I think these are reasonable to include as they have useful methods that do not show in the docs for the public arists. E.g. get_shape, get_size, set_data on _ImageBase and get/set_annotation_clip on _AnnotationBase.

For _AxesBase I made it as unobtrusive as possible.

QuLogic

I will note that all the doc problems were already listed in doc/missing-references.json, but at a different line number. So if you've fixed them, then you should remove the entries from there.

QuLogic · 2026-06-25T17:11:18Z

@@ -0,0 +1,3 @@
+The ``Axes.AxesList`` attribute


What is AxesList?

Ooops; fixed.

QuLogic · 2026-06-25T17:16:58Z

    def pprint_getters(self) -> list[str]: ...

+
+class ArtistList(Sequence[_T_Artist]):


This needs updating for #31923.

ayshih · 2026-06-25T17:54:53Z

I will note that all the doc problems were already listed in doc/missing-references.json

Ah, I didn't know about that file! I had hit the same docs failures after I modified artist_api.rst in #31162, so it's great to now understand why that happened.

rcomer · 2026-06-25T18:25:46Z

I had heard of that file but never made the effort to learn what it's about! Thanks @QuLogic it's good to have an explanation.

rcomer · 2026-06-25T19:13:13Z

I am in two minds what to do about the _AxesBase reference. The stub file I created seems like documentation clutter, but the missing_references.json solution is brittle - it has confused at least three of us. Does anyone have an opinion which solution is the lesser evil?

QuLogic · 2026-06-25T20:56:14Z

What about _AxesBase here?

See my previous comment #31794 (comment). I’m not sure whether to remove this or revert the doc addition.

IMHO private base classes are an inconsistent concept. They "should not be used" but OTOH provide public functionality. We should come up with a strategy how to handle them. But that is beyound the scope of this PR.

As far as we are concerned here, we just have the problem of missing references due to undocumented base classes, and our current imperfect solution is to list them in missing-references. I'm inclined to do this here and defer everything else to a follow-up.

Side-note: It's a bit annoying that JSON does not support comments, which we could have used to annotate where the missing reference is coming from.

OK - so I should drop the second commit completely and just update the line numbers in the json?

That would be my way forward. You can reuse the second commit as a baseline for a follow-up.

OK, the second commit is now saved in its own branch for future reference https://github.com/rcomer/matplotlib/tree/private-artist-docs

👍 It's a known issue that the line number is part of the message and when code moves, the line number match gets lost. In the past, we corrected the line numbers as is now done here. Future improvements could be to remove the missing reference or make the matching more permissive.

github-actions Bot added topic: axes Documentation: tutorials files in galleries/tutorials labels May 31, 2026

timhoffm approved these changes May 31, 2026

View reviewed changes

rcomer force-pushed the standalone-artistlist branch from a9d220f to 8e05633 Compare May 31, 2026 14:07

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

rcomer mentioned this pull request May 31, 2026

Introduce ArtistList for FigureBase #31746

Draft

5 tasks

rcomer changed the title ~~MNT: move Artistlist into artist module~~ MNT: move ArtistList into artist module May 31, 2026

rcomer added this to the v3.12.0 milestone Jun 2, 2026

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

QuLogic reviewed Jun 25, 2026

View reviewed changes

rcomer force-pushed the standalone-artistlist branch from 8e05633 to b28308f Compare June 25, 2026 19:13

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

QuLogic reviewed Jun 25, 2026

View reviewed changes

MNT: move Artistlist into artist module

74ea04e

rcomer force-pushed the standalone-artistlist branch from b28308f to 74ea04e Compare June 27, 2026 07:15

github-actions Bot removed the topic: text label Jun 27, 2026

timhoffm approved these changes Jun 27, 2026

View reviewed changes

		def pprint_getters(self) -> list[str]: ...


		class ArtistList(Sequence[_T_Artist]):

Uh oh!

Uh oh!

Conversation

rcomer commented May 31, 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!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

rcomer commented May 31, 2026

Uh oh!

rcomer commented May 31, 2026

Uh oh!

QuLogic left a comment

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!

ayshih commented Jun 25, 2026

Uh oh!

rcomer commented Jun 25, 2026

Uh oh!

rcomer commented Jun 25, 2026

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rcomer commented May 31, 2026 •

edited

Loading