<divid="unreleased-message"> You are reading an old version of the documentation (v3.3.2). For the latest version see <ahref="https://matplotlib.org/stable/api/legend_handler_api.html">https://matplotlib.org/stable/api/legend_handler_api.html</a></div>
<spanid="matplotlib-legend-handler"></span><h1><codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.legend_handler</span></code><aclass="headerlink" href="#module-matplotlib.legend_handler" title="Permalink to this headline">¶</a></h1>
<p>Default legend handlers.</p>
<p>It is strongly encouraged to have read the <aclass="reference internal" href="../tutorials/intermediate/legend_guide.html"><spanclass="doc">legend guide</span></a> before this documentation.</p>
<p>Legend handlers are expected to be a callable object with a following
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>legend</strong><spanclass="classifier"><aclass="reference internal" href="legend_api.html#matplotlib.legend.Legend" title="matplotlib.legend.Legend"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Legend</span></code></a></span></dt><dd><p>The legend for which these legend artists are being created.</p>
</dd>
<dt><strong>orig_handle</strong><spanclass="classifier"><aclass="reference internal" href="artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">matplotlib.artist.Artist</span></code></a> or similar</span></dt><dd><p>The object for which these legend artists are being created.</p>
</dd>
<dt><strong>fontsize</strong><spanclass="classifier">int</span></dt><dd><p>The fontsize in pixels. The artists being created should
be scaled according to the given fontsize.</p>
</dd>
<dt><strong>handlebox</strong><spanclass="classifier"><aclass="reference internal" href="offsetbox_api.html#matplotlib.offsetbox.OffsetBox" title="matplotlib.offsetbox.OffsetBox"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.offsetbox.OffsetBox</span></code></a></span></dt><dd><p>The box which has been created to hold this legend entry's
artists. Artists created in the <aclass="reference internal" href="#matplotlib.legend_handler.HandlerBase.legend_artist" title="matplotlib.legend_handler.HandlerBase.legend_artist"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">legend_artist</span></code></a> method must
be added to this handlebox inside this method.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>numpoints</strong><spanclass="classifier">int</span></dt><dd><p>Number of points to show in legend entry.</p>
</dd>
<dt><strong>yoffsets</strong><spanclass="classifier">array of floats</span></dt><dd><p>Length <em>numpoints</em> list of y offsets for each point in
legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerNpoints" title="matplotlib.legend_handler.HandlerNpoints"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerNpoints</span></code></a>.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>marker_pad</strong><spanclass="classifier">float</span></dt><dd><p>Padding between points in legend entry.</p>
</dd>
<dt><strong>numpoints</strong><spanclass="classifier">int</span></dt><dd><p>Number of points to show in legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerNpoints" title="matplotlib.legend_handler.HandlerNpoints"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerNpoints</span></code></a>.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>marker_pad</strong><spanclass="classifier">float</span></dt><dd><p>Padding between points in legend entry.</p>
</dd>
<dt><strong>numpoints</strong><spanclass="classifier">int</span></dt><dd><p>Number of points to show in legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerNpoints" title="matplotlib.legend_handler.HandlerNpoints"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerNpoints</span></code></a>.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>marker_pad</strong><spanclass="classifier">float</span></dt><dd><p>Padding between points in legend entry.</p>
</dd>
<dt><strong>numpoints</strong><spanclass="classifier">int</span></dt><dd><p>Number of points to show in legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerNpoints" title="matplotlib.legend_handler.HandlerNpoints"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerNpoints</span></code></a>.</p>
<codeclass="descname">get_numpoints</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">legend</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerLineCollection.get_numpoints"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerLineCollection.get_numpoints" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py class">
<dtid="matplotlib.legend_handler.HandlerNpoints">
<emclass="property">class </em><codeclass="descclassname">matplotlib.legend_handler.</code><codeclass="descname">HandlerNpoints</code><spanclass="sig-paren">(</span><em><spanclass="n">marker_pad</span><spanclass="o">=</span><spanclass="default_value">0.3</span></em>, <em><spanclass="n">numpoints</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="o">**</span><spanclass="n">kw</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerNpoints"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerNpoints" title="Permalink to this definition">¶</a></dt>
<dd><p>A legend handler that shows <em>numpoints</em> points in the legend entry.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>marker_pad</strong><spanclass="classifier">float</span></dt><dd><p>Padding between points in legend entry.</p>
</dd>
<dt><strong>numpoints</strong><spanclass="classifier">int</span></dt><dd><p>Number of points to show in legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerBase" title="matplotlib.legend_handler.HandlerBase"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerBase</span></code></a>.</p>
<codeclass="descname">get_numpoints</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">legend</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerNpoints.get_numpoints"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerNpoints.get_numpoints" title="Permalink to this definition">¶</a></dt>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>numpoints</strong><spanclass="classifier">int</span></dt><dd><p>Number of points to show in legend entry.</p>
</dd>
<dt><strong>yoffsets</strong><spanclass="classifier">array of floats</span></dt><dd><p>Length <em>numpoints</em> list of y offsets for each point in
legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerNpoints" title="matplotlib.legend_handler.HandlerNpoints"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerNpoints</span></code></a>.</p>
<codeclass="descname">get_ydata</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">legend</span></em>, <em><spanclass="n">xdescent</span></em>, <em><spanclass="n">ydescent</span></em>, <em><spanclass="n">width</span></em>, <em><spanclass="n">height</span></em>, <em><spanclass="n">fontsize</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerNpointsYoffsets.get_ydata"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerNpointsYoffsets.get_ydata" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py class">
<dtid="matplotlib.legend_handler.HandlerPatch">
<emclass="property">class </em><codeclass="descclassname">matplotlib.legend_handler.</code><codeclass="descname">HandlerPatch</code><spanclass="sig-paren">(</span><em><spanclass="n">patch_func</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="o">**</span><spanclass="n">kw</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerPatch"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerPatch" title="Permalink to this definition">¶</a></dt>
<p>Subsequently the created artist will have its <codeclass="docutils literal notranslate"><spanclass="pre">update_prop</span></code>
method called and the appropriate transform will be applied.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerBase" title="matplotlib.legend_handler.HandlerBase"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerBase</span></code></a>.</p>
<emclass="property">class </em><codeclass="descclassname">matplotlib.legend_handler.</code><codeclass="descname">HandlerPathCollection</code><spanclass="sig-paren">(</span><em><spanclass="n">yoffsets</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">sizes</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="o">**</span><spanclass="n">kw</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerPathCollection"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerPathCollection" title="Permalink to this definition">¶</a></dt>
<dd><p>Handler for <aclass="reference internal" href="collections_api.html#matplotlib.collections.PathCollection" title="matplotlib.collections.PathCollection"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">PathCollection</span></code></a>s, which are used by <aclass="reference internal" href="_as_gen/matplotlib.axes.Axes.scatter.html#matplotlib.axes.Axes.scatter" title="matplotlib.axes.Axes.scatter"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">scatter</span></code></a>.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>numpoints</strong><spanclass="classifier">int</span></dt><dd><p>Number of points to show in legend entry.</p>
</dd>
<dt><strong>yoffsets</strong><spanclass="classifier">array of floats</span></dt><dd><p>Length <em>numpoints</em> list of y offsets for each point in
legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerNpoints" title="matplotlib.legend_handler.HandlerNpoints"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerNpoints</span></code></a>.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>numpoints</strong><spanclass="classifier">int</span></dt><dd><p>Number of points to show in legend entry.</p>
</dd>
<dt><strong>yoffsets</strong><spanclass="classifier">array of floats</span></dt><dd><p>Length <em>numpoints</em> list of y offsets for each point in
legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerNpoints" title="matplotlib.legend_handler.HandlerNpoints"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerNpoints</span></code></a>.</p>
<codeclass="descname">get_numpoints</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">legend</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerRegularPolyCollection.get_numpoints"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerRegularPolyCollection.get_numpoints" title="Permalink to this definition">¶</a></dt>
<codeclass="descname">update_prop</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">legend_handle</span></em>, <em><spanclass="n">orig_handle</span></em>, <em><spanclass="n">legend</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerRegularPolyCollection.update_prop"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerRegularPolyCollection.update_prop" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py class">
<dtid="matplotlib.legend_handler.HandlerStem">
<emclass="property">class </em><codeclass="descclassname">matplotlib.legend_handler.</code><codeclass="descname">HandlerStem</code><spanclass="sig-paren">(</span><em><spanclass="n">marker_pad</span><spanclass="o">=</span><spanclass="default_value">0.3</span></em>, <em><spanclass="n">numpoints</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">bottom</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">yoffsets</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="o">**</span><spanclass="n">kw</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerStem"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerStem" title="Permalink to this definition">¶</a></dt>
<dd><p>Handler for plots produced by <aclass="reference internal" href="_as_gen/matplotlib.axes.Axes.stem.html#matplotlib.axes.Axes.stem" title="matplotlib.axes.Axes.stem"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">stem</span></code></a>.</p>
<dt><strong>yoffsets</strong><spanclass="classifier">array of floats, optional</span></dt><dd><p>Length <em>numpoints</em> list of y offsets for each point in
legend entry.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Notes</p>
<p>Any other keyword arguments are given to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerNpointsYoffsets" title="matplotlib.legend_handler.HandlerNpointsYoffsets"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerNpointsYoffsets</span></code></a>.</p>
<codeclass="descname">get_ydata</code><spanclass="sig-paren">(</span><em><spanclass="n">self</span></em>, <em><spanclass="n">legend</span></em>, <em><spanclass="n">xdescent</span></em>, <em><spanclass="n">ydescent</span></em>, <em><spanclass="n">width</span></em>, <em><spanclass="n">height</span></em>, <em><spanclass="n">fontsize</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerStem.get_ydata"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerStem.get_ydata" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py class">
<dtid="matplotlib.legend_handler.HandlerTuple">
<emclass="property">class </em><codeclass="descclassname">matplotlib.legend_handler.</code><codeclass="descname">HandlerTuple</code><spanclass="sig-paren">(</span><em><spanclass="n">ndivide</span><spanclass="o">=</span><spanclass="default_value">1</span></em>, <em><spanclass="n">pad</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#HandlerTuple"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.HandlerTuple" title="Permalink to this definition">¶</a></dt>
<dd><p>Handler for Tuple.</p>
<p>Additional kwargs are passed through to <aclass="reference internal" href="#matplotlib.legend_handler.HandlerBase" title="matplotlib.legend_handler.HandlerBase"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">HandlerBase</span></code></a>.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>ndivide</strong><spanclass="classifier">int, default: 1</span></dt><dd><p>The number of sections to divide the legend area into. If None,
use the length of the input tuple.</p>
</dd>
<dt><strong>pad</strong><spanclass="classifier">float, default: <codeclass="docutils literal notranslate"><aclass="reference external" href="../tutorials/introductory/customizing.html?highlight=legend.borderpad#a-sample-matplotlibrc-file"><spanclass="pre">rcParams["legend.borderpad"]</span></a></code> (default: <codeclass="docutils literal notranslate"><spanclass="pre">0.4</span></code>)</span></dt><dd><p>Padding in units of fraction of font size.</p>
<codeclass="descclassname">matplotlib.legend_handler.</code><codeclass="descname">update_from_first_child</code><spanclass="sig-paren">(</span><em><spanclass="n">tgt</span></em>, <em><spanclass="n">src</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/legend_handler.html#update_from_first_child"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.legend_handler.update_from_first_child" title="Permalink to this definition">¶</a></dt>