<divid="unreleased-message"> You are reading an old version of the documentation (v3.4.1). For the latest version see <ahref="https://matplotlib.org/stable/api/_api_api.html">https://matplotlib.org/stable/api/_api_api.html</a></div>
<spanid="matplotlib-api"></span><h1><codeclass="docutils literal notranslate"><spanclass="pre">matplotlib._api</span></code><aclass="headerlink" href="#module-matplotlib._api" title="Permalink to this headline">¶</a></h1>
<p>Helper functions for managing the Matplotlib API.</p>
<p>This documentation is only relevant for Matplotlib developers, not for users.</p>
<dlclass="py function">
<dtid="matplotlib._api.check_getitem">
<codeclass="descclassname">matplotlib._api.</code><codeclass="descname">check_getitem</code><spanclass="sig-paren">(</span><em><spanclass="n">_mapping</span></em>, <em><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api.html#check_getitem"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.check_getitem" title="Permalink to this definition">¶</a></dt>
<dd><p><em>kwargs</em> must consist of a single <em>key, value</em> pair. If <em>key</em> is in
<em>_mapping</em>, return <codeclass="docutils literal notranslate"><spanclass="pre">_mapping[value]</span></code>; else, raise an appropriate
<dt><strong>_values</strong><spanclass="classifier">iterable</span></dt><dd><p>Sequence of values to check on.</p>
</dd>
<dt><strong>_print_supported_values</strong><spanclass="classifier">bool, default: True</span></dt><dd><p>Whether to print <em>_values</em> when raising ValueError.</p>
</dd>
<dt><strong>**kwargs</strong><spanclass="classifier">dict</span></dt><dd><p><em>key, value</em> pairs as keyword arguments to find in <em>_values</em>.</p>
</dd>
</dl>
</td>
</tr>
<trclass="field-even field"><thclass="field-name">Raises:</th><tdclass="field-body"><dlclass="first last docutils">
<dt>ValueError</dt><dd><p>If any <em>value</em> in <em>kwargs</em> is not found in <em>_values</em>.</p>
<codeclass="descclassname">matplotlib._api.</code><codeclass="descname">check_isinstance</code><spanclass="sig-paren">(</span><em><spanclass="n">_types</span></em>, <em><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api.html#check_isinstance"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.check_isinstance" title="Permalink to this definition">¶</a></dt>
<dd><p>For each <em>key, value</em> pair in <em>kwargs</em>, check that <em>value</em> is an instance
of one of <em>_types</em>; if not, raise an appropriate TypeError.</p>
<p>As a special case, a <codeclass="docutils literal notranslate"><spanclass="pre">None</span></code> entry in <em>_types</em> is treated as NoneType.</p>
<codeclass="descclassname">matplotlib._api.</code><codeclass="descname">check_shape</code><spanclass="sig-paren">(</span><em><spanclass="n">_shape</span></em>, <em><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api.html#check_shape"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.check_shape" title="Permalink to this definition">¶</a></dt>
<dd><p>For each <em>key, value</em> pair in <em>kwargs</em>, check that <em>value</em> has the shape
<em>_shape</em>, if not, raise an appropriate ValueError.</p>
<p><em>None</em> in the shape is treated as a "free" size that can have any length.
<p>Like <aclass="reference external" href="https://docs.python.org/3/library/functions.html#property" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">property</span></code></a>, but also triggers on access via the class, and it is the
<emclass="property">property </em><codeclass="descname">fget</code><aclass="headerlink" href="#matplotlib._api.classproperty.fget" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dlclass="py function">
<dtid="matplotlib._api.warn_external">
<codeclass="descclassname">matplotlib._api.</code><codeclass="descname">warn_external</code><spanclass="sig-paren">(</span><em><spanclass="n">message</span></em>, <em><spanclass="n">category</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api.html#warn_external"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.warn_external" title="Permalink to this definition">¶</a></dt>
<dd><p><aclass="reference external" href="https://docs.python.org/3/library/warnings.html#warnings.warn" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">warnings.warn</span></code></a> wrapper that sets <em>stacklevel</em> to "outside Matplotlib".</p>
<p>The original emitter of the warning can be obtained by patching this
function back to <aclass="reference external" href="https://docs.python.org/3/library/warnings.html#warnings.warn" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">warnings.warn</span></code></a>, i.e. <codeclass="docutils literal notranslate"><spanclass="pre">_api.warn_external</span><spanclass="pre">=</span>
<emclass="property">exception </em><codeclass="descclassname">matplotlib._api.deprecation.</code><codeclass="descname">MatplotlibDeprecationWarning</code><aclass="reference internal" href="../_modules/matplotlib/_api/deprecation.html#MatplotlibDeprecationWarning"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.deprecation.MatplotlibDeprecationWarning" title="Permalink to this definition">¶</a></dt>
<codeclass="descclassname">matplotlib._api.deprecation.</code><codeclass="descname">delete_parameter</code><spanclass="sig-paren">(</span><em><spanclass="n">since</span></em>, <em><spanclass="n">name</span></em>, <em><spanclass="n">func</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/_api/deprecation.html#delete_parameter"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.deprecation.delete_parameter" title="Permalink to this definition">¶</a></dt>
<dd><p>Decorator indicating that parameter <em>name</em> of <em>func</em> is being deprecated.</p>
<p>The actual implementation of <em>func</em> should keep the <em>name</em> parameter in its
signature, or accept a <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code> argument (through which <em>name</em> would be
passed).</p>
<p>Parameters that come after the deprecated parameter effectively become
keyword-only (as they cannot be passed positionally without triggering the
DeprecationWarning on the deprecated parameter), and should be marked as
such after the deprecation period has passed and the deprecated parameter
is removed.</p>
<p>Parameters other than <em>since</em>, <em>name</em>, and <em>func</em> are keyword-only and
<codeclass="descclassname">matplotlib._api.deprecation.</code><codeclass="descname">deprecate_method_override</code><spanclass="sig-paren">(</span><em><spanclass="n">method</span></em>, <em><spanclass="n">obj</span></em>, <em><spanclass="o">*</span></em>, <em><spanclass="n">allow_empty</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <em><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api/deprecation.html#deprecate_method_override"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.deprecation.deprecate_method_override" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <codeclass="docutils literal notranslate"><spanclass="pre">obj.method</span></code> with a deprecation if it was overridden, else None.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>method</strong></dt><dd><p>An unbound method, i.e. an expression of the form
<codeclass="docutils literal notranslate"><spanclass="pre">Class.method_name</span></code>. Remember that within the body of a method, one
can always use <codeclass="docutils literal notranslate"><spanclass="pre">__class__</span></code> to refer to the class that is currently
being defined.</p>
</dd>
<dt><strong>obj</strong></dt><dd><p>Either an object of the class where <em>method</em> is defined, or a subclass
of that class.</p>
</dd>
<dt><strong>allow_empty</strong><spanclass="classifier">bool, default: False</span></dt><dd><p>Whether to allow overrides by "empty" methods without emitting a
warning.</p>
</dd>
<dt><strong>**kwargs</strong></dt><dd><p>Additional parameters passed to <aclass="reference internal" href="#matplotlib._api.deprecation.warn_deprecated" title="matplotlib._api.deprecation.warn_deprecated"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">warn_deprecated</span></code></a> to generate the
deprecation warning; must at least include the "since" key.</p>
<emclass="property">class </em><codeclass="descclassname">matplotlib._api.deprecation.</code><codeclass="descname">deprecate_privatize_attribute</code><spanclass="sig-paren">(</span><em><spanclass="o">*</span><spanclass="n">args</span></em>, <em><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api/deprecation.html#deprecate_privatize_attribute"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.deprecation.deprecate_privatize_attribute" title="Permalink to this definition">¶</a></dt>
<p>where <em>all</em> parameters are forwarded to <aclass="reference internal" href="#matplotlib._api.deprecation.deprecated" title="matplotlib._api.deprecation.deprecated"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">deprecated</span></code></a>. This form makes
<codeclass="docutils literal notranslate"><spanclass="pre">attr</span></code> a property which forwards access to <codeclass="docutils literal notranslate"><spanclass="pre">self._attr</span></code> (same name but
with a leading underscore), with a deprecation warning. Note that the
attribute name is derived from <em>the name this helper is assigned to</em>.</p>
</dd></dl>
<dlclass="py function">
<dtid="matplotlib._api.deprecation.deprecated">
<codeclass="descclassname">matplotlib._api.deprecation.</code><codeclass="descname">deprecated</code><spanclass="sig-paren">(</span><em><spanclass="n">since</span></em>, <em><spanclass="o">*</span></em>, <em><spanclass="n">message</span><spanclass="o">=</span><spanclass="default_value">''</span></em>, <em><spanclass="n">name</span><spanclass="o">=</span><spanclass="default_value">''</span></em>, <em><spanclass="n">alternative</span><spanclass="o">=</span><spanclass="default_value">''</span></em>, <em><spanclass="n">pending</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <em><spanclass="n">obj_type</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">addendum</span><spanclass="o">=</span><spanclass="default_value">''</span></em>, <em><spanclass="n">removal</span><spanclass="o">=</span><spanclass="default_value">''</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api/deprecation.html#deprecated"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.deprecation.deprecated" title="Permalink to this definition">¶</a></dt>
<dd><p>Decorator to mark a function, a class, or a property as deprecated.</p>
<p>When deprecating a classmethod, a staticmethod, or a property, the
<codeclass="docutils literal notranslate"><spanclass="pre">@deprecated</span></code> decorator should go <em>under</em><codeclass="docutils literal notranslate"><spanclass="pre">@classmethod</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">@staticmethod</span></code> (i.e., <aclass="reference internal" href="#matplotlib._api.deprecation.deprecated" title="matplotlib._api.deprecation.deprecated"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">deprecated</span></code></a> should directly decorate the
underlying callable), but <em>over</em><codeclass="docutils literal notranslate"><spanclass="pre">@property</span></code>.</p>
<p>When deprecating a class <codeclass="docutils literal notranslate"><spanclass="pre">C</span></code> intended to be used as a base class in a
(if <codeclass="docutils literal notranslate"><spanclass="pre">C</span></code> instead inherited its <codeclass="docutils literal notranslate"><spanclass="pre">__init__</span></code> from its own base class, then
<codeclass="docutils literal notranslate"><spanclass="pre">@deprecated</span></code> would mess up <codeclass="docutils literal notranslate"><spanclass="pre">__init__</span></code> inheritance when installing its
own (deprecation-emitting) <codeclass="docutils literal notranslate"><spanclass="pre">C.__init__</span></code>).</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>since</strong><spanclass="classifier">str</span></dt><dd><p>The release at which this API became deprecated.</p>
</dd>
<dt><strong>message</strong><spanclass="classifier">str, optional</span></dt><dd><p>Override the default deprecation message. The <codeclass="docutils literal notranslate"><spanclass="pre">%(since)s</span></code>,
and <codeclass="docutils literal notranslate"><spanclass="pre">%(removal)s</span></code> format specifiers will be replaced by the values
of the respective arguments passed to this function.</p>
</dd>
<dt><strong>name</strong><spanclass="classifier">str, optional</span></dt><dd><p>The name used in the deprecation message; if not provided, the name
is automatically determined from the deprecated object.</p>
</dd>
<dt><strong>alternative</strong><spanclass="classifier">str, optional</span></dt><dd><p>An alternative API that the user may use in place of the deprecated
API. The deprecation warning will tell the user about this alternative
if provided.</p>
</dd>
<dt><strong>pending</strong><spanclass="classifier">bool, optional</span></dt><dd><p>If True, uses a PendingDeprecationWarning instead of a
DeprecationWarning. Cannot be used together with <em>removal</em>.</p>
</dd>
<dt><strong>obj_type</strong><spanclass="classifier">str, optional</span></dt><dd><p>The object type being deprecated; by default, 'class' if decorating
a class, 'attribute' if decorating a property, 'function' otherwise.</p>
</dd>
<dt><strong>addendum</strong><spanclass="classifier">str, optional</span></dt><dd><p>Additional text appended directly to the final message.</p>
</dd>
<dt><strong>removal</strong><spanclass="classifier">str, optional</span></dt><dd><p>The expected removal version. With the default (an empty string), a
removal version is automatically computed from <em>since</em>. Set to other
Falsy values to not schedule a removal date. Cannot be used together
<codeclass="descclassname">matplotlib._api.deprecation.</code><codeclass="descname">make_keyword_only</code><spanclass="sig-paren">(</span><em><spanclass="n">since</span></em>, <em><spanclass="n">name</span></em>, <em><spanclass="n">func</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api/deprecation.html#make_keyword_only"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.deprecation.make_keyword_only" title="Permalink to this definition">¶</a></dt>
<dd><p>Decorator indicating that passing parameter <em>name</em> (or any of the following
ones) positionally to <em>func</em> is being deprecated.</p>
<codeclass="descclassname">matplotlib._api.deprecation.</code><codeclass="descname">mplDeprecation</code><aclass="headerlink" href="#matplotlib._api.deprecation.mplDeprecation" title="Permalink to this definition">¶</a></dt>
<codeclass="descclassname">matplotlib._api.deprecation.</code><codeclass="descname">suppress_matplotlib_deprecation_warning</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/_api/deprecation.html#suppress_matplotlib_deprecation_warning"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib._api.deprecation.suppress_matplotlib_deprecation_warning" 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>since</strong><spanclass="classifier">str</span></dt><dd><p>The release at which this API became deprecated.</p>
</dd>
<dt><strong>message</strong><spanclass="classifier">str, optional</span></dt><dd><p>Override the default deprecation message. The <codeclass="docutils literal notranslate"><spanclass="pre">%(since)s</span></code>,
and <codeclass="docutils literal notranslate"><spanclass="pre">%(removal)s</span></code> format specifiers will be replaced by the values
of the respective arguments passed to this function.</p>
</dd>
<dt><strong>name</strong><spanclass="classifier">str, optional</span></dt><dd><p>The name of the deprecated object.</p>
</dd>
<dt><strong>alternative</strong><spanclass="classifier">str, optional</span></dt><dd><p>An alternative API that the user may use in place of the deprecated
API. The deprecation warning will tell the user about this alternative
if provided.</p>
</dd>
<dt><strong>pending</strong><spanclass="classifier">bool, optional</span></dt><dd><p>If True, uses a PendingDeprecationWarning instead of a
DeprecationWarning. Cannot be used together with <em>removal</em>.</p>
</dd>
<dt><strong>obj_type</strong><spanclass="classifier">str, optional</span></dt><dd><p>The object type being deprecated.</p>
</dd>
<dt><strong>addendum</strong><spanclass="classifier">str, optional</span></dt><dd><p>Additional text appended directly to the final message.</p>
</dd>
<dt><strong>removal</strong><spanclass="classifier">str, optional</span></dt><dd><p>The expected removal version. With the default (an empty string), a
removal version is automatically computed from <em>since</em>. Set to other
Falsy values to not schedule a removal date. Cannot be used together
with <em>pending</em>.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Examples</p>
<p>Basic example:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># To warn of the deprecation of "matplotlib.name_of_module"</span>