Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit d51129f

Browse filesBrowse files
timhoffmtimhoffm
committed
Document legend(handles=handles) signature
- Add `legend(handles=handles)` - Reorder such that the discouraged signature `legend(labels)` is last - Minor text changes Closes #20213
1 parent 1bf216a commit d51129f
Copy full SHA for d51129f

File tree

Expand file treeCollapse file tree

2 files changed

+59
-31
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+59
-31
lines changed

‎lib/matplotlib/axes/_axes.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_axes.py
+30-16Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -191,10 +191,11 @@ def legend(self, *args, **kwargs):
191191
Call signatures::
192192
193193
legend()
194-
legend(labels)
195194
legend(handles, labels)
195+
legend(handles=handles)
196+
legend(labels)
196197
197-
The call signatures correspond to these three different ways to use
198+
The call signatures correspond to the following different ways to use
198199
this method:
199200
200201
**1. Automatic detection of elements to be shown in the legend**
@@ -222,27 +223,40 @@ def legend(self, *args, **kwargs):
222223
no legend being drawn.
223224
224225
225-
**2. Labeling existing plot elements**
226+
**2. Explicitly listing the artists and labels in the legend**
226227
227-
To make a legend for lines which already exist on the Axes
228-
(via plot for instance), simply call this function with an iterable
229-
of strings, one for each legend item. For example::
228+
For full control of which artists have a legend entry, it is possible
229+
to pass an iterable of legend artists followed by an iterable of
230+
legend labels respectively::
230231
231-
ax.plot([1, 2, 3])
232-
ax.legend(['A simple line'])
232+
ax.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
233233
234-
Note: This call signature is discouraged, because the relation between
235-
plot elements and labels is only implicit by their order and can
236-
easily be mixed up.
237234
235+
**3. Explicitly listing the artists in the legend**
238236
239-
**3. Explicitly defining the elements in the legend**
237+
This is similar to 2, but the labels are taken from the artists'
238+
label properties. Example::
240239
241-
For full control of which artists have a legend entry, it is possible
242-
to pass an iterable of legend artists followed by an iterable of
243-
legend labels respectively::
240+
line1, = ax.plot([1, 2, 3], label='label1')
241+
line2, = ax.plot([1, 2, 3], label='label2')
242+
ax.legend(handles=[line1, line2])
243+
244+
245+
**4. Labeling existing plot elements**
246+
247+
.. admonition:: Discouraged
248+
249+
This call signature is discouraged, because the relation between
250+
plot elements and labels is only implicit by their order and can
251+
easily be mixed up.
252+
253+
To make a legend for all artists on an Axes, call this function with
254+
an iterable of strings, one for each legend item. For example::
255+
256+
ax.plot([1, 2, 3])
257+
ax.plot([5, 6, 7])
258+
ax.legend(['First line', 'Second line'])
244259
245-
ax.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
246260
247261
Parameters
248262
----------

‎lib/matplotlib/figure.py

Copy file name to clipboardExpand all lines: lib/matplotlib/figure.py
+29-15Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -958,10 +958,11 @@ def legend(self, *args, **kwargs):
958958
Call signatures::
959959
960960
legend()
961-
legend(labels)
962961
legend(handles, labels)
962+
legend(handles=handles)
963+
legend(labels)
963964
964-
The call signatures correspond to these three different ways to use
965+
The call signatures correspond to the following different ways to use
965966
this method:
966967
967968
**1. Automatic detection of elements to be shown in the legend**
@@ -989,7 +990,32 @@ def legend(self, *args, **kwargs):
989990
no legend being drawn.
990991
991992
992-
**2. Labeling existing plot elements**
993+
**2. Explicitly listing the artists and labels in the legend**
994+
995+
For full control of which artists have a legend entry, it is possible
996+
to pass an iterable of legend artists followed by an iterable of
997+
legend labels respectively::
998+
999+
fig.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
1000+
1001+
1002+
**3. Explicitly listing the artists in the legend**
1003+
1004+
This is similar to 2, but the labels are taken from the artists'
1005+
label properties. Example::
1006+
1007+
line1, = ax1.plot([1, 2, 3], label='label1')
1008+
line2, = ax2.plot([1, 2, 3], label='label2')
1009+
fig.legend(handles=[line1, line2])
1010+
1011+
1012+
**4. Labeling existing plot elements**
1013+
1014+
.. admonition:: Discouraged
1015+
1016+
This call signature is discouraged, because the relation between
1017+
plot elements and labels is only implicit by their order and can
1018+
easily be mixed up.
9931019
9941020
To make a legend for all artists on all Axes, call this function with
9951021
an iterable of strings, one for each legend item. For example::
@@ -999,18 +1025,6 @@ def legend(self, *args, **kwargs):
9991025
ax2.plot([2, 4, 6], color='red')
10001026
fig.legend(['the blues', 'the reds'])
10011027
1002-
Note: This call signature is discouraged, because the relation between
1003-
plot elements and labels is only implicit by their order and can
1004-
easily be mixed up.
1005-
1006-
1007-
**3. Explicitly defining the elements in the legend**
1008-
1009-
For full control of which artists have a legend entry, it is possible
1010-
to pass an iterable of legend artists followed by an iterable of
1011-
legend labels respectively::
1012-
1013-
fig.legend([line1, line2, line3], ['label1', 'label2', 'label3'])
10141028
10151029
Parameters
10161030
----------

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.