PatchCollection instances do not currently display in legends even when assigned a label. This has been a long-standing limitation that forces users to create manual legend entries, making the API inconsistent with other collection types likePolyCollection andPathCollection.

What problem does it solve?

Before this fix, the following code would not display a legend entry:

importmatplotlib.pyplotaspltfrommatplotlib.collectionsimportPatchCollectionfrommatplotlib.patchesimportPolygonfig,ax=plt.subplots()p1=Polygon([[0,0], [100,100], [200,0]])p2=Polygon([[400,0], [500,100], [600,0]])pc=PatchCollection([p1,p2],label="my patches",facecolor='blue')ax.add_collection(pc)ax.legend()# Legend was empty ❌plt.show()

After this fix, the legend correctly displays the "my patches" label with a rectangular swatch matching the collection's visual properties.

Implementation reasoning

The implementation adds a newHandlerPatchCollection class that inherits from the existingHandlerPolyCollection. This approach:

Eliminates code duplication: BothPatchCollection andPolyCollection inherit fromCollection and share identical APIs for accessing colors, line styles, and other visual properties
Maintains consistency: Uses the same legend representation (Rectangle) asPolyCollection
Ensures maintainability: Bug fixes or enhancements toHandlerPolyCollection automatically benefitHandlerPatchCollection

The handler extracts visual properties (face color, edge color, line width, line style) from the first patch in the collection and creates a rectangular legend entry.

Minimum self-contained example

importmatplotlib.pyplotaspltimportmatplotlib.patchesasmpatchesfrommatplotlib.collectionsimportPatchCollectionfig,ax=plt.subplots()# Create various patchespatches= [mpatches.Circle((0.2,0.5),0.1),mpatches.Rectangle((0.5,0.3),0.2,0.3),]# Create PatchCollection with labelpc=PatchCollection(patches,facecolor='red',edgecolor='black',linewidths=2,label='My patches')ax.add_collection(pc)ax.autoscale_view()# Legend now works!ax.legend()plt.show()

PR checklist

"closesLabels for PatchCollection do not show #23998" is in the body of the PR description to link the related issue
New and changed code is tested
- Added 5 comprehensive tests covering:
  - Basic functionality
  - Visual property preservation
  - match_original=True parameter
  - Empty collection edge case
  - Visual regression test with@image_comparison
[N/A] Plotting related features are demonstrated in an example
- This is a bug fix for existing functionality, not a new plotting feature
- Code examples are included in the What's New entry
New Features and API Changes are noted with a directive and release note
- Addeddoc/release/next_whats_new/patchcollection_legend.rst
- Includes user-facing description and code example
Documentation complies with general and docstring guidelines
- HandlerPatchCollection includes comprehensive docstring
- Follows matplotlib's docstring conventions
- Includes "See Also" section

Add support for PatchCollection legends and update documentation

0f13209

github-actionsbot added the topic: legend label

Nov 17, 2025

FazeelUsmani marked this pull request as draft

November 17, 2025 13:42

FazeelUsmani added3 commits

November 17, 2025 13:45

Add type stub for HandlerPatchCollection

3f013f6

Remove visual regression test (baseline image needed)

567b478

The @image_comparison test requires a baseline image that doesn't exist yet.Removing it for now - we still have 4 comprehensive functional tests thatverify the functionality works correctly.

Trigger CI re-run

8fc57eb

FazeelUsmani marked this pull request as ready for review

November 17, 2025 15:51

Add explicit figure cleanup in PatchCollection legend tests

478de45

Close figures explicitly at the end of each test to prevent anypotential state leakage that could affect other tests in parallelexecution environments.

timhoffm reviewed

Nov 17, 2025

View reviewed changes

Copy link

Member

timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Thanks! Looks good. Only minor style improvements to the tests.

lib/matplotlib/tests/test_legend.py OutdatedShow resolvedHide resolved

lib/matplotlib/tests/test_legend.py Outdated

Comment on lines 1736 to 1737

		deftest_patchcollection_legend_match_original():
		# Test PatchCollection legend with match_original=True

Copy link

Member

timhoffmNov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Do we need this test? The legend patch takes the properties from the first patch.match_original applies the properties from the first patch to all other patches. I don't see how any reasonable implementation ofmatch_original could adversingly affect the legend.

Copy link

ContributorAuthor

FazeelUsmaniNov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I've removed thetest_patchcollection_legend_match_original test. You're absolutely right - since the legend handler always takes properties from the first patch in the collection,match_original doesn't affect the legend behavior. The test was redundant withtest_patchcollection_legend_properties.

Now we have 3 focused tests:

test_patchcollection_legend - Basic functionality (label appears in legend)
test_patchcollection_legend_properties - Visual properties are preserved
test_patchcollection_legend_empty - Edge case: empty collection doesn't crash

lib/matplotlib/tests/test_legend.py OutdatedShow resolvedHide resolved

lib/matplotlib/tests/test_legend.py Outdated


		# The legend handle should exist (with default/transparent colors)
		assertlen(leg.legend_handles)==1
		assertisinstance(leg.legend_handles[0],mpatches.Rectangle)

Copy link

Member

timhoffmNov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Do we want to leave this out? I'd claim that being aRectangle is an implementation detail that we don't want to test.

Instead we should check the color.

Copy link

ContributorAuthor

FazeelUsmaniNov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I've removed theisinstance(Rectangle) checks from both tests.

Intest_patchcollection_legend, I replaced it with color verification - now checking that the legend patch has the correct facecolor and edgecolor.
Intest_patchcollection_legend_empty, I simply verify that the handle exists since the main goal is to test that empty collections don't crash.

This way the tests focus on actual behavior (correct colors) rather than implementation details (patch type).

FazeelUsmaniand others added11 commits

November 18, 2025 12:12

Update lib/matplotlib/tests/test_legend.py

8536bfc

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Update lib/matplotlib/tests/test_legend.py

71c9a86

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Update lib/matplotlib/tests/test_legend.py

618d426

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Update lib/matplotlib/tests/test_legend.py

122a7d6

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Update lib/matplotlib/tests/test_legend.py

83adf5c

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Update lib/matplotlib/tests/test_legend.py

477bf97

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Update lib/matplotlib/tests/test_legend.py

1a1b20a

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Update lib/matplotlib/tests/test_legend.py

bd2f926

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Update lib/matplotlib/tests/test_legend.py

33242ca

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

Remove redundant test_patchcollection_legend_match_original test

b669f4d

As noted by@timhoffm, this test doesn't add value because:- match_original affects how colors are applied to patches in the collection- The legend handler always takes properties from the first patch- Whether match_original is True or False, the legend gets the same result- This is already covered by test_patchcollection_legend_properties

Test behavior instead of implementation details

92aaeca

As suggested by@timhoffm:- Remove isinstance(Rectangle) checks - this is an implementation detail- In test_patchcollection_legend: Check colors match instead- In test_patchcollection_legend_empty: Just verify legend handle existsThis focuses tests on actual behavior (correct colors) rather thaninternal implementation choices (what patch type is used).

timhoffm approved these changes

Nov 18, 2025

View reviewed changes

FazeelUsmani mentioned this pull request

Nov 18, 2025

Fix PDF bloat for off-axis scatter with per-point colors#30746

Open

2 tasks

Copy link

ContributorAuthor

FazeelUsmani commentedNov 19, 2025

Hi@timhoffm,
Do I need to find out another reviewer for this PR? Or the maintainers of this repo will check regularly. What I heard is atelast 2 approvals are required to merge a PR.

Copy link

Member

rcomer commentedNov 19, 2025

Unfortunately the bot that posts it is currently broken, but when you opened your first PR you should have got a comment withthis message. So about a week is reasonable to wait for a review.

story645 reviewed

Nov 19, 2025

View reviewed changes

lib/matplotlib/legend_handler.py Outdated

Comment on lines 825 to 828

		# PatchCollection and PolyCollection have the same API for accessing
		# colors, line properties, etc., so we can reuse HandlerPolyCollection
		# implementation directly via inheritance.
		pass

Copy link

Member

story645Nov 19, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

What's the reason to bother w/ a new class vs. just directly registering, e.g.:

PatchCollection:legend_handler.HandlerPolyCollection()

Copy link

ContributorAuthor

FazeelUsmaniNov 20, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

There's no reason.PatchCollection andPolyCollection have identical APIs for accessing colors and line properties, so we can just registerHandlerPolyCollection directly. I'll remove the new class.

story645 reviewed

Nov 19, 2025

View reviewed changes

lib/matplotlib/tests/test_legend.py Outdated

Comment on lines 1735 to 1737

		ax.set_xlim(0,1)
		ax.set_ylim(0,1)

Copy link

Member

story645Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

does this matter if you're just testing object properties?

Copy link

ContributorAuthor

FazeelUsmaniNov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

No, it doesn't matter. Since we're only testing that the legend handler creates the correct objects with the right properties, the axis limits aren't needed. I'll remove these lines.

lib/matplotlib/tests/test_legend.py Outdated


		# Verify that visual properties are preserved
		legend_patch=leg.legend_handles[0]
		assert_allclose(legend_patch.get_facecolor()[:3],

Copy link

Member

story645Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

why is alpha getting ignored here?

Copy link

ContributorAuthor

FazeelUsmaniNov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

It shouldn't be. The alpha channel should also be verified. I'll change it to check all 4 RGBA components instead of just RGB.

Address story645's review: simplify implementation and improve tests

555faa6

- Remove HandlerPatchCollection class - use HandlerPolyCollection directly  Since PatchCollection and PolyCollection have identical APIs, we can  register PatchCollection to use the existing handler without creating  a new class. This follows YAGNI principle.- Check all 4 color components (RGBA) instead of just RGB  The alpha channel should also be verified for completeness.- Remove unnecessary axis limits from empty collection test  Since we're only testing object properties, not visual rendering,  the axis limits aren't needed.Addresses feedback from@story645

Copy link

Member