matplotlib.legend_handler#

Default legend handlers.

Legend handlers are expected to be a callable object with a followingsignature:

legend_handler(legend,orig_handle,fontsize,handlebox)

Wherelegend is the legend itself,orig_handle is the originalplot,fontsize is the fontsize in pixels, andhandlebox is anOffsetBox instance. Within the call, you should create relevantartists (using relevant properties from thelegend and/ororig_handle) and add them into thehandlebox. The artists need tobe scaled according to thefontsize (note that the size is in pixels,i.e., this is dpi-scaled value).

This module includes definition of several legend handler classesderived from the base class (HandlerBase) with the following method:

deflegend_artist(self,legend,orig_handle,fontsize,handlebox)

classmatplotlib.legend_handler.HandlerBase(xpad=0.0,ypad=0.0,update_func=None)[source]#

A base class for default legend handlers.

The derived classes are meant to overridecreate_artists method, whichhas the following signature:

defcreate_artists(self,legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans):

The overridden method needs to create artists of the giventransform that fits in the given dimension (xdescent, ydescent,width, height) that are scaled by fontsize if necessary.

Parameters:

xpadfloat, optional

Padding in x-direction.

ypadfloat, optional

Padding in y-direction.

update_funccallable, optional

Function for updating the legend handler properties from anotherlegend handler, used byupdate_prop.

adjust_drawing_area(legend,orig_handle,xdescent,ydescent,width,height,fontsize)[source]#

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

legend_artist(legend,orig_handle,fontsize,handlebox)[source]#

Return the artist that this HandlerBase generates for the givenoriginal artist/handle.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handlematplotlib.artist.Artist or similar

The object for which these legend artists are being created.

fontsizeint

The fontsize in pixels. The artists being created shouldbe scaled according to the given fontsize.

handleboxOffsetBox

The box which has been created to hold this legend entry'sartists. Artists created in thelegend_artist method mustbe added to this handlebox inside this method.

update_prop(legend_handle,orig_handle,legend)[source]#

classmatplotlib.legend_handler.HandlerCircleCollection(yoffsets=None,sizes=None,**kwargs)[source]#

Handler forCircleCollections.

Parameters:

numpointsint

Number of points to show in legend entry.

yoffsetsarray of floats

Lengthnumpoints list of y offsets for each point inlegend entry.

**kwargs

Keyword arguments forwarded toHandlerNpoints.

create_collection(orig_handle,sizes,offsets,offset_transform)[source]#

classmatplotlib.legend_handler.HandlerErrorbar(xerr_size=0.5,yerr_size=None,marker_pad=0.3,numpoints=None,**kwargs)[source]#

Handler for Errorbars.

Parameters:

marker_padfloat

Padding between points in legend entry.

numpointsint

Number of points to show in legend entry.

**kwargs

Keyword arguments forwarded toHandlerBase.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

get_err_size(legend,xdescent,ydescent,width,height,fontsize)[source]#

classmatplotlib.legend_handler.HandlerLine2D(marker_pad=0.3,numpoints=None,**kwargs)[source]#

Handler forLine2D instances.

See also

HandlerLine2DCompound

An earlier handler implementation, which used one artist for the line and another for the marker(s).

Parameters:

marker_padfloat

Padding between points in legend entry.

numpointsint

Number of points to show in legend entry.

**kwargs

Keyword arguments forwarded toHandlerBase.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

classmatplotlib.legend_handler.HandlerLine2DCompound(marker_pad=0.3,numpoints=None,**kwargs)[source]#

Original handler forLine2D instances, that relies on combininga line-only with a marker-only artist. May be deprecated in the future.

Parameters:

marker_padfloat

Padding between points in legend entry.

numpointsint

Number of points to show in legend entry.

**kwargs

Keyword arguments forwarded toHandlerBase.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

classmatplotlib.legend_handler.HandlerLineCollection(marker_pad=0.3,numpoints=None,**kwargs)[source]#

Handler forLineCollection instances.

Parameters:

marker_padfloat

Padding between points in legend entry.

numpointsint

Number of points to show in legend entry.

**kwargs

Keyword arguments forwarded toHandlerBase.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

get_numpoints(legend)[source]#

classmatplotlib.legend_handler.HandlerNpoints(marker_pad=0.3,numpoints=None,**kwargs)[source]#

A legend handler that showsnumpoints points in the legend entry.

Parameters:

marker_padfloat

Padding between points in legend entry.

numpointsint

Number of points to show in legend entry.

**kwargs

Keyword arguments forwarded toHandlerBase.

get_numpoints(legend)[source]#

get_xdata(legend,xdescent,ydescent,width,height,fontsize)[source]#

classmatplotlib.legend_handler.HandlerNpointsYoffsets(numpoints=None,yoffsets=None,**kwargs)[source]#

A legend handler that showsnumpoints in the legend, and allows them tobe individually offset in the y-direction.

Parameters:

numpointsint

Number of points to show in legend entry.

yoffsetsarray of floats

Lengthnumpoints list of y offsets for each point inlegend entry.

**kwargs

Keyword arguments forwarded toHandlerNpoints.

get_ydata(legend,xdescent,ydescent,width,height,fontsize)[source]#

classmatplotlib.legend_handler.HandlerPatch(patch_func=None,**kwargs)[source]#

Handler forPatch instances.

Parameters:

patch_funccallable, optional

The function that creates the legend key artist.patch_func should have the signature:

defpatch_func(legend=legend,orig_handle=orig_handle,xdescent=xdescent,ydescent=ydescent,width=width,height=height,fontsize=fontsize)

Subsequently, the created artist will have itsupdate_propmethod called and the appropriate transform will be applied.

**kwargs

Keyword arguments forwarded toHandlerBase.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

classmatplotlib.legend_handler.HandlerPathCollection(yoffsets=None,sizes=None,**kwargs)[source]#

Handler forPathCollections, which are used byscatter.

Parameters:

numpointsint

Number of points to show in legend entry.

yoffsetsarray of floats

Lengthnumpoints list of y offsets for each point inlegend entry.

**kwargs

Keyword arguments forwarded toHandlerNpoints.

create_collection(orig_handle,sizes,offsets,offset_transform)[source]#

classmatplotlib.legend_handler.HandlerPolyCollection(xpad=0.0,ypad=0.0,update_func=None)[source]#

Handler forPolyCollection used infill_between andstackplot.

Parameters:

xpadfloat, optional

Padding in x-direction.

ypadfloat, optional

Padding in y-direction.

update_funccallable, optional

Function for updating the legend handler properties from anotherlegend handler, used byupdate_prop.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

classmatplotlib.legend_handler.HandlerRegularPolyCollection(yoffsets=None,sizes=None,**kwargs)[source]#

Handler forRegularPolyCollections.

Parameters:

numpointsint

Number of points to show in legend entry.

yoffsetsarray of floats

Lengthnumpoints list of y offsets for each point inlegend entry.

**kwargs

Keyword arguments forwarded toHandlerNpoints.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

create_collection(orig_handle,sizes,offsets,offset_transform)[source]#

get_numpoints(legend)[source]#

get_sizes(legend,orig_handle,xdescent,ydescent,width,height,fontsize)[source]#

update_prop(legend_handle,orig_handle,legend)[source]#

classmatplotlib.legend_handler.HandlerStem(marker_pad=0.3,numpoints=None,bottom=None,yoffsets=None,**kwargs)[source]#

Handler for plots produced bystem.

Parameters:

marker_padfloat, default: 0.3

Padding between points in legend entry.

numpointsint, optional

Number of points to show in legend entry.

bottomfloat, optional

yoffsetsarray of floats, optional

Lengthnumpoints list of y offsets for each point inlegend entry.

**kwargs

Keyword arguments forwarded toHandlerNpointsYoffsets.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

get_ydata(legend,xdescent,ydescent,width,height,fontsize)[source]#

classmatplotlib.legend_handler.HandlerStepPatch(xpad=0.0,ypad=0.0,update_func=None)[source]#

Handler forStepPatch instances.

Parameters:

xpadfloat, optional

Padding in x-direction.

ypadfloat, optional

Padding in y-direction.

update_funccallable, optional

Function for updating the legend handler properties from anotherlegend handler, used byupdate_prop.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

classmatplotlib.legend_handler.HandlerTuple(ndivide=1,pad=None,**kwargs)[source]#

Handler for Tuple.

Parameters:

ndivideint or None, default: 1

The number of sections to divide the legend area into. If None,use the length of the input tuple.

padfloat, default:rcParams["legend.borderpad"] (default:0.4)

Padding in units of fraction of font size.

**kwargs

Keyword arguments forwarded toHandlerBase.

create_artists(legend,orig_handle,xdescent,ydescent,width,height,fontsize,trans)[source]#

Return the legend artists generated.

Parameters:

legendLegend

The legend for which these legend artists are being created.

orig_handleArtist or similar

The object for which these legend artists are being created.

xdescent, ydescent, width, heightint

The rectangle (xdescent,ydescent,width,height) that thelegend artists being created should fit within.

fontsizeint

The fontsize in pixels. The legend artists being created shouldbe scaled according to the given fontsize.

transTransform

The transform that is applied to the legend artists being created.Typically from unit coordinates in the handler box to screencoordinates.

matplotlib.legend_handler.update_from_first_child(tgt,src)[source]#