<liclass="toctree-l1 has-children"><aclass="reference internal" href="development_setup.html">Setting up Matplotlib for development</a><details><summary><spanclass="toctree-toggle" role="presentation"><iclass="fa-solid fa-chevron-down"></i></span></summary><ul>
<liclass="toctree-l2"><aclass="reference internal" href="license.html">Licenses for contributed code</a></li>
</ul>
</details></li>
<liclass="toctree-l1 current active has-children"><aclass="current reference internal" href="#">API guidelines</a><detailsopen="open"><summary><spanclass="toctree-toggle" role="presentation"><iclass="fa-solid fa-chevron-down"></i></span></summary><ul>
<liclass="toctree-l2"><aclass="reference internal" href="color_changes.html">Default color changes</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP12.html">MEP12: Improve Gallery and Examples</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP13.html">MEP13: Use properties for Artists</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP14.html">MEP14: Text handling</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP15.html">MEP15: Fix axis autoscaling when limits are specified for one axis only</a></li>
<spanid="api-changes"></span><h1>API guidelines<aclass="headerlink" href="#api-guidelines" title="Link to this heading">#</a></h1>
<p>API consistency and stability are of great value; Therefore, API changes
(e.g. signature changes, behavior changes, removals) will only be conducted
if the added benefit is worth the effort of adapting existing code.</p>
<p>Because we are a visualization library, our primary output is the final
visualization the user sees; therefore, the appearance of the figure is part of
the API and any changes, either semantic or <aclass="reference internal" href="color_changes.html#color-changes"><spanclass="std std-ref">aesthetic</span></a>,
are backwards-incompatible API changes.</p>
<divclass="toctree-wrapper compound">
</div>
<sectionid="add-new-api-and-features">
<h2>Add new API and features<aclass="headerlink" href="#add-new-api-and-features" title="Link to this heading">#</a></h2>
<p>Every new function, parameter and attribute that is not explicitly marked as
private (i.e., starts with an underscore) becomes part of Matplotlib's public
API. As discussed above, changing the existing API is cumbersome. Therefore,
take particular care when adding new API:</p>
<ulclass="simple">
<li><p>Mark helper functions and internal attributes as private by prefixing them
with an underscore.</p></li>
<li><p>Carefully think about good names for your functions and variables.</p></li>
<li><p>Try to adopt patterns and naming conventions from existing parts of the
Matplotlib API.</p></li>
<li><p>Consider making as many arguments keyword-only as possible. See also
<aclass="reference external" href="https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters">API Evolution the Right Way -- Add Parameters Compatibly</a>.</p>
</li>
</ul>
</section>
<sectionid="deprecate-api">
<spanid="deprecation-guidelines"></span><h2>Deprecate API<aclass="headerlink" href="#deprecate-api" title="Link to this heading">#</a></h2>
<p>API changes in Matplotlib have to be performed following the deprecation process
below, except in very rare circumstances as deemed necessary by the development
team. Generally API deprecation happens in two stages:</p>
<ulclass="simple">
<li><p><strong>introduce:</strong> warn users that the API <em>will</em> change</p></li>
<li><p><strong>expire:</strong> API <em>is</em> changed as described in the introduction period</p></li>
</ul>
<p>This ensures that users are notified before the change will take effect and thus
prevents unexpected breaking of code.</p>
<sectionid="rules">
<h3>Rules<aclass="headerlink" href="#rules" title="Link to this heading">#</a></h3>
<ulclass="simple">
<li><p>Deprecations are targeted at the next <aclass="reference internal" href="pr_guide.html#pr-milestones"><spanclass="std std-ref">meso release</span></a> (e.g. 3.x)</p></li>
<li><p>Deprecated API is generally removed (expired) two point-releases after introduction
of the deprecation. Longer deprecations can be imposed by core developers on
a case-by-case basis to give more time for the transition</p></li>
<li><p>The old API must remain fully functional during the deprecation period</p></li>
<li><p>If alternatives to the deprecated API exist, they should be available
during the deprecation period</p></li>
<li><p>If in doubt, decisions about API changes are finally made by the
<li><p>If possible, issue a <aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.MatplotlibDeprecationWarning" title="matplotlib.MatplotlibDeprecationWarning"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">MatplotlibDeprecationWarning</span></code></a> when the
deprecated API is used. There are a number of helper tools for this:</p>
<ulclass="simple">
<li><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">_api.warn_deprecated()</span></code> for general deprecation warnings</p></li>
<li><p>Use the decorator <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecated</span></code> to deprecate classes, functions,
methods, or properties</p></li>
<li><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecate_privatize_attribute</span></code> to annotate deprecation of
attributes while keeping the internal private version.</p></li>
<li><p>To warn on changes of the function signature, use the decorators
<codeclass="docutils literal notranslate"><spanclass="pre">@_api.delete_parameter</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">@_api.rename_parameter</span></code>, and
<p>All these helpers take a first parameter <em>since</em>, which should be set to
the next point release, e.g. "3.x".</p>
<p>You can use standard rst cross references in <em>alternative</em>.</p>
</li>
<li><p>Make appropriate changes to the type hints in the associated <codeclass="docutils literal notranslate"><spanclass="pre">.pyi</span></code> file.
The general guideline is to match runtime reported behavior.</p>
<ulclass="simple">
<li><p>Items marked with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecated</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecate_privatize_attribute</span></code>
are generally kept during the expiry period, and thus no changes are needed on
introduction.</p></li>
<li><p>Items decorated with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.rename_parameter</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">@_api.make_keyword_only</span></code>
report the <em>new</em> (post deprecation) signature at runtime, and thus <em>should</em> be
updated on introduction.</p></li>
<li><p>Items decorated with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.delete_parameter</span></code> should include a default value hint
for the deleted parameter, even if it did not previously have one (e.g.
<spanid="id2"></span><h3>Expire deprecation<aclass="headerlink" href="#expire-deprecation" title="Link to this heading">#</a></h3>
<olclass="arabic simple">
<li><p>Create <aclass="reference internal" href="#api-whats-new"><spanclass="std std-ref">deprecation announcement</span></a>. For the content,
you can usually copy the deprecation notice and adapt it slightly.</p></li>
<li><p>Change the code functionality and remove any related deprecation warnings.</p></li>
<li><p>Make appropriate changes to the type hints in the associated <codeclass="docutils literal notranslate"><spanclass="pre">.pyi</span></code> file.</p>
<ulclass="simple">
<li><p>Items marked with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecated</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">@_api.deprecate_privatize_attribute</span></code>
are to be removed on expiry.</p></li>
<li><p>Items decorated with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.rename_parameter</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">@_api.make_keyword_only</span></code>
will have been updated at introduction, and require no change now.</p></li>
<li><p>Items decorated with <codeclass="docutils literal notranslate"><spanclass="pre">@_api.delete_parameter</span></code> will need to be updated to the
final signature, in the same way as the <codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> file signature is updated.</p></li>
<li><p>Any entries in <codeclass="file docutils literal notranslate"><spanclass="pre">ci/mypy-stubtest-allowlist.txt</span></code> which indicate a deprecation
version should be double checked. In most cases this is not needed, though some
items were never type hinted in the first place and were added to this file
instead. For removed items that were not in the stub file, only deleting from the
allowlist is required.</p></li>
</ul>
</li>
</ol>
</section>
</section>
<sectionid="announce-new-and-deprecated-api">
<spanid="api-whats-new"></span><h2>Announce new and deprecated API<aclass="headerlink" href="#announce-new-and-deprecated-api" title="Link to this heading">#</a></h2>
<p>When adding or changing the API in a backward in-compatible way, please add the
appropriate <aclass="reference internal" href="#versioning-directives"><spanclass="std std-ref">versioning directive</span></a> and document it
for the release notes and add the entry to the appropriate folder:</p>
<p>For classes and functions, the directive should be placed before the
<em>Parameters</em> section. For parameters, the directive should be placed at the
end of the parameter description. The micro release version is omitted and
the directive should not be added to entire modules.</p>
</section>
<sectionid="release-notes">
<h3>Release notes<aclass="headerlink" href="#release-notes" title="Link to this heading">#</a></h3>
<p>For both change notes and what's new, please avoid using cross-references in section
titles as it causes links to be confusing in the table of contents. Instead, ensure that
a cross-reference is included in the descriptive text.</p>
<sectionid="api-change-notes">
<spanid="id4"></span><h4>API change notes<aclass="headerlink" href="#api-change-notes" title="Link to this heading">#</a></h4>
<p>API change notes for future releases are collected in
<codeclass="file docutils literal notranslate"><spanclass="pre">next_api_changes</span></code>. They are divided into four subdirectories:</p>
<ulclass="simple">
<li><p><strong>Deprecations</strong>: Announcements of future changes. Typically, these will
raise a deprecation warning and users of this API should change their code
to stay compatible with future releases of Matplotlib. If possible, state
what should be used instead.</p></li>
<li><p><strong>Removals</strong>: Parts of the API that got removed. If possible, state what
should be used instead.</p></li>
<li><p><strong>Behaviour changes</strong>: API that stays valid but will yield a different
result.</p></li>
<li><p><strong>Development changes</strong>: Changes to the build process, dependencies, etc.</p></li>
</ul>
<p>Please place new entries in these directories with a new file named
<codeclass="docutils literal notranslate"><spanclass="pre">99999-ABC.rst</span></code>, where <codeclass="docutils literal notranslate"><spanclass="pre">99999</span></code> would be the PR number, and <codeclass="docutils literal notranslate"><spanclass="pre">ABC</span></code> the
author's initials. Typically, each change will get its own file, but you may
also amend existing files when suitable. The overall goal is a comprehensible
The unused `Locator.autoscale()` method is deprecated (pass the axis
limits to `Locator.view_limits()` instead).
</pre></div>
</div>
</section>
<sectionid="what-s-new-notes">
<spanid="whats-new-notes"></span><h4>What's new notes<aclass="headerlink" href="#what-s-new-notes" title="Link to this heading">#</a></h4>
<p>Please place new portions of <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">whats_new.rst</span></code> in the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">next_whats_new</span></code> directory.</p>
<p>When adding an entry please look at the currently existing files to
see if you can extend any of them. If you create a file, name it
something like <codeclass="file docutils literal notranslate"><spanclass="pre">cool_new_feature.rst</span></code> if you have added a brand new
feature or something like <codeclass="file docutils literal notranslate"><spanclass="pre">updated_feature.rst</span></code> for extensions of