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 4776e50

Browse filesBrowse files
timhoffmtimhoffm
committed
improve legend docstring
1 parent 2132073 commit 4776e50
Copy full SHA for 4776e50

File tree

Expand file treeCollapse file tree

5 files changed

+97
-22
lines changed
Filter options
Expand file treeCollapse file tree

5 files changed

+97
-22
lines changed

‎lib/matplotlib/axes/_axes.py

Copy file name to clipboardExpand all lines: lib/matplotlib/axes/_axes.py
+57-12Lines changed: 57 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -283,38 +283,83 @@ def legend(self, *args, **kwargs):
283283
"""
284284
Places a legend on the axes.
285285
286-
To make a legend for lines which already exist on the axes
287-
(via plot for instance), simply call this function with an iterable
288-
of strings, one for each legend item. For example::
286+
Call signatures::
289287
290-
ax.plot([1, 2, 3])
291-
ax.legend(['A simple line'])
288+
legend()
289+
legend(labels)
290+
legend(handles, labels)
291+
292+
The call signatures correspond to three different ways how to use
293+
this method.
292294
293-
However, in order to keep the "label" and the legend element
294-
instance together, it is preferable to specify the label either at
295-
artist creation, or by calling the
296-
:meth:`~matplotlib.artist.Artist.set_label` method on the artist::
295+
**1. Automatic detection of elements to be shown in the legend**
296+
297+
The elements to be added to the legend are automatically determined,
298+
when you do not pass in any extra arguments.
299+
300+
In this case, the labels are taken from the artist. You can specify
301+
them either at artist creation or by calling the
302+
:meth:`~.Artist.set_label` method on the artist::
297303
298304
line, = ax.plot([1, 2, 3], label='Inline label')
299-
# Overwrite the label by calling the method.
305+
ax.legend()
306+
307+
or::
308+
300309
line.set_label('Label via method')
310+
line, = ax.plot([1, 2, 3])
301311
ax.legend()
302312
303313
Specific lines can be excluded from the automatic legend element
304314
selection by defining a label starting with an underscore.
305-
This is default for all artists, so calling :meth:`legend` without
315+
This is default for all artists, so calling `Axes.legend` without
306316
any arguments and without setting the labels manually will result in
307317
no legend being drawn.
308318
319+
320+
**2. Labeling existing plot elements**
321+
322+
To make a legend for lines which already exist on the axes
323+
(via plot for instance), simply call this function with an iterable
324+
of strings, one for each legend item. For example::
325+
326+
ax.plot([1, 2, 3])
327+
ax.legend(['A simple line'])
328+
329+
Note: This way of using is discouraged, because the relation between
330+
plot elements and labels is only implicit by their order and can
331+
easily be mixed up.
332+
333+
334+
**3. Explicitly defining the elements in the legend**
335+
309336
For full control of which artists have a legend entry, it is possible
310337
to pass an iterable of legend artists followed by an iterable of
311338
legend labels respectively::
312339
313-
legend((line1, line2, line3), ('label1', 'label2', 'label3'))
340+
legend((line1, line2, line3), ('label1', 'label2', 'label3'))
314341
315342
Parameters
316343
----------
317344
345+
handles : sequence of `~.Artist`, optional
346+
A list of Artists (lines, patches) to be added to the legend.
347+
Use this together with *labels*, if you need full control on what
348+
is shown in the legend and the automatic mechanism described above
349+
is not sufficient.
350+
351+
The length of handles and labels should be the same in this
352+
case. If they are not, they are truncated to the smaller length.
353+
354+
labels : sequence of strings, optional
355+
A list of labels to show next to the artists.
356+
Use this together with *handles*, if you need full control on what
357+
is shown in the legend and the automatic mechanism described above
358+
is not sufficient.
359+
360+
Other Parameters
361+
----------------
362+
318363
loc : int or string or pair of floats, default: 'upper right'
319364
The location of the legend. Possible codes are:
320365

‎lib/matplotlib/figure.py

Copy file name to clipboardExpand all lines: lib/matplotlib/figure.py
+18Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1373,6 +1373,24 @@ def legend(self, *args, **kwargs):
13731373
Parameters
13741374
----------
13751375
1376+
handles : sequence of `~.Artist`, optional
1377+
A list of Artists (lines, patches) to be added to the legend.
1378+
Use this together with *labels*, if you need full control on what
1379+
is shown in the legend and the automatic mechanism described above
1380+
is not sufficient.
1381+
1382+
The length of handles and labels should be the same in this
1383+
case. If they are not, they are truncated to the smaller length.
1384+
1385+
labels : sequence of strings, optional
1386+
A list of labels to show next to the artists.
1387+
Use this together with *handles*, if you need full control on what
1388+
is shown in the legend and the automatic mechanism described above
1389+
is not sufficient.
1390+
1391+
Other Parameters
1392+
----------------
1393+
13761394
loc : int or string or pair of floats, default: 'upper right'
13771395
The location of the legend. Possible codes are:
13781396

‎lib/matplotlib/legend.py

Copy file name to clipboardExpand all lines: lib/matplotlib/legend.py
+14-7Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -286,9 +286,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
286286

287287
class Legend(Artist):
288288
"""
289-
Place a legend on the axes at location loc. Labels are a
290-
sequence of strings and loc can be a string or an integer
291-
specifying the legend location
289+
Place a legend on the axes at location loc.
292290
293291
"""
294292
codes = {'best': 0, # only implemented for axes legends
@@ -353,13 +351,22 @@ def __init__(self, parent, handles, labels,
353351
handler_map=None,
354352
):
355353
"""
356-
- *parent*: the artist that contains the legend
357-
- *handles*: a list of artists (lines, patches) to be added to the
358-
legend
359-
- *labels*: a list of strings to label the legend
360354
361355
Parameters
362356
----------
357+
parent : `.Axes` or `.Figure`
358+
The artist that contains the legend.
359+
360+
handles : sequence of `.Artist`
361+
A list of Artists (lines, patches) to be added to the legend.
362+
363+
labels : sequence of strings
364+
A list of labels to show next to the artists. The length of handles
365+
and labels should be the same. If they are not, they are truncated
366+
to the smaller of both lengths.
367+
368+
Other Parameters
369+
----------------
363370
364371
loc : int or string or pair of floats, default: 'upper right'
365372
The location of the legend. Possible codes are:

‎lib/matplotlib/pyplot.py

Copy file name to clipboardExpand all lines: lib/matplotlib/pyplot.py
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -283,8 +283,8 @@ def pause(interval):
283283
This can be used for crude animation. For more complex animation, see
284284
:mod:`matplotlib.animation`.
285285
286-
Note
287-
----
286+
Notes
287+
-----
288288
This function is experimental; its behavior may be changed or extended in a
289289
future release.
290290
"""

‎lib/matplotlib/tests/test_legend.py

Copy file name to clipboardExpand all lines: lib/matplotlib/tests/test_legend.py
+6-1Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,14 @@ def get_docstring_section(func, section):
4040

4141

4242
def test_legend_kwdocstrings():
43-
stleg = get_docstring_section(mpl.legend.Legend.__init__, 'Parameters')
4443
stax = get_docstring_section(mpl.axes.Axes.legend, 'Parameters')
4544
stfig = get_docstring_section(mpl.figure.Figure.legend, 'Parameters')
45+
assert stfig == stax
46+
47+
stleg = get_docstring_section(mpl.legend.Legend.__init__,
48+
'Other Parameters')
49+
stax = get_docstring_section(mpl.axes.Axes.legend, 'Other Parameters')
50+
stfig = get_docstring_section(mpl.figure.Figure.legend, 'Other Parameters')
4651
assert stleg == stax
4752
assert stfig == stax
4853
assert stleg == stfig

0 commit comments

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