8000 Clean up legend docstrings by dstansby · Pull Request #9946 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Clean up legend docstrings #9946

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 12, 2017
Merged

Clean up legend docstrings #9946

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aac4d2b
Clean up legend docstrings
dstansby Dec 7, 2017
473f449
Fixed links
jklymak Dec 12, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 43 additions & 29 deletions lib/matplotlib/legend.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,11 @@
class DraggableLegend(DraggableOffsetBox):
def __init__(self, legend, use_blit=False, update="loc"):
"""
update : If "loc", update *loc* parameter of
legend upon finalizing. If "bbox", update
*bbox_to_anchor* parameter.
Parameters
----------
update : string
If "loc", update *loc* parameter of legend upon finalizing.
If "bbox", update *bbox_to_anchor* parameter.
"""
self.legend = legend

Expand Down Expand Up @@ -581,8 +583,8 @@ def __init__(self, parent, handles, labels,
del locals_view
# trim handles and labels if illegal label...
for label, handle in zip(labels[:], handles[:]):
if (isinstance(label, six.string_types)
and label.startswith('_')):
if (isinstance(label, six.string_types) and
label.startswith('_')):
warnings.warn('The handle {!r} has a label of {!r} which '
'cannot be automatically added to the '
'legend.'.format(handle, label))
Expand Down Expand Up @@ -709,7 +711,7 @@ def __init__(self, parent, handles, labels,

def _set_artist_props(self, a):
"""
set the boilerplate props for artists added to axes
Set the boilerplate props for artists added to axes.
"""
a.set_figure(self.figure)
if self.isaxes:
Expand All @@ -731,7 +733,7 @@ def _get_loc(self):
_loc = property(_get_loc, _set_loc)

def _findoffset(self, width, height, xdescent, ydescent, renderer):
"Helper function to locate the legend"
"Helper function to locate the legend."

if self._loc == 0: # "best".
x, y = self._find_best_position(width, height, renderer)
Expand All @@ -749,7 +751,7 @@ def _findoffset(self, width, height, xdescent, ydescent, renderer):

@allow_rasterization
def draw(self, renderer):
"Draw everything that belongs to the legend"
"Draw everything that belongs to the legend."
if not self.get_visible():
return

Expand Down Expand Up @@ -836,7 +838,7 @@ def update_default_handler_map(cls, handler_map):

def get_legend_handler_map(self):
"""
return the handler map.
Return the handler map.
"""

default_handler_map = self.get_default_handler_map()
Expand All @@ -851,7 +853,7 @@ def get_legend_handler_map(self):
@staticmethod
def get_legend_handler(legend_handler_map, orig_handle):
"""
return a legend handler from *legend_handler_map* that
Return a legend handler from *legend_handler_map* that
corresponds to *orig_handler*.

*legend_handler_map* should be a dictionary object (that is
Expand All @@ -861,7 +863,7 @@ def get_legend_handler(legend_handler_map, orig_handle):
*legend_hanler_map* and return the associated value.
Otherwise, it checks for each of the classes in its
method-resolution-order. If no matching key is found, it
returns None.
returns ``None``.
"""
if is_hashable(orig_handle):
try:
Expand Down Expand Up @@ -1058,11 +1060,17 @@ def _auto_legend_data(self):
return [vertices, bboxes, lines, offsets]

def draw_frame(self, b):
'b is a boolean. Set draw frame to b'
'''
Set draw frame to b.

Parameters
----------
b : bool
'''
self.set_frame_on(b)

def get_children(self):
'return a list of child artists'
'Return a list of child artists.'
children = []
if self._legend_box:
children.append(self._legend_box)
Expand All @@ -1071,26 +1079,28 @@ def get_children(self):
return children

def get_frame(self):
'return the Rectangle instance used to frame the legend'
'''
Return the `~.patches.Rectangle` instances used to frame the legend.
'''
return self.legendPatch

def get_lines(self):
'return a list of lines.Line2D instances in the legend'
'Return a list of `~.lines.Line2D` instances in the legend.'
return [h for h in self.legendHandles if isinstance(h, Line2D)]

def get_patches(self):
'return a list of patch instances in the legend'
'Return a list of `~.patches.Patch` instances in the legend.'
return silent_list('Patch',
[h for h in self.legendHandles
if isinstance(h, Patch)])

def get_texts(self):
'return a list of text.Text instance in the legend'
'Return a list of `~.text.Text` instances in the legend.'
return silent_list('Text', self.texts)

def set_title(self, title, prop=None):
"""
set the legend title. Fontproperties can be optionally set
Set the legend title. Fontproperties can be optionally set
with *prop* parameter.
"""
self._legend_title_box._text.set_text(title)
Expand All @@ -1107,16 +1117,16 @@ def set_title(self, title, prop=None):
self.stale = True

def get_title(self):
'return Text instance for the legend title'
'Return `~.text.Text` instance for the legend title.'
return self._legend_title_box._text

def get_window_extent(self, *args, **kwargs):
'return a extent of the legend'
'Return extent of the legend.'
return self.legendPatch.get_window_extent(*args, **kwargs)

def get_frame_on(self):
"""
Get whether the legend box patch is drawn
Get whether the legend box patch is drawn.
"""
return self._drawFrame

Expand All @@ -1131,7 +1141,7 @@ def set_frame_on(self, b):

def get_bbox_to_anchor(self):
"""
return the bbox that the legend will be anchored
Return the bbox that the legend will be anchored.
"""
if self._bbox_to_anchor is None:
return self.parent.bbox
Expand All @@ -1140,12 +1150,16 @@ def get_bbox_to_anchor(self):

def set_bbox_to_anchor(self, bbox, transform=None):
"""
set the bbox that the legend will be anchored.
Set the bbox that the legend will be anchored.

*bbox* can be

- A `~.BboxBase` instance
- A tuple of ``(left, bottom, width, height)`` in the given transform
(normalized axes coordinate if None)
- A tuple of ``[left, bottom]`` where the width and height will be
assumed to be zero.

*bbox* can be a BboxBase instance, a tuple of [left, bottom,
width, height] in the given transform (normalized axes
coordinate if None), or a tuple of [left, bottom] where the
width and height will be assumed to be zero.
"""
if bbox is None:
self._bbox_to_anchor = None
Expand Down Expand Up @@ -1209,7 +1223,7 @@ def _find_best_position(self, width, height, renderer, consider=None):
"""
Determine the best location to place the legend.

`consider` is a list of (x, y) pairs to consider as a potential
*consider* is a list of ``(x, y)`` pairs to consider as a potential
lower-left corner of the legend. All are display coords.
"""
# should always hold because function is only called internally
Expand Down Expand Up @@ -1258,7 +1272,7 @@ def draggable(self, state=None, use_blit=False, update="loc"):
* False : turn draggable off

If draggable is on, you can drag the legend on the canvas with
the mouse. The DraggableLegend helper instance is returned if
the mouse. The `~.DraggableLegend` helper instance is returned if
draggable is on.

The update parameter control which parameter of the legend changes
Expand Down
0