<divid="unreleased-message"> You are reading an old version of the documentation (v3.4.0). For the latest version see <ahref="https://matplotlib.org/stable/devel/contributing.html">https://matplotlib.org/stable/devel/contributing.html</a></div>
<h2>Contributor Incubator<aclass="headerlink" href="#contributor-incubator" title="Permalink to this headline">¶</a></h2>
<p>If you are interested in becoming a regular contributor to Matplotlib, but
don't know where to start or feel insecure about it, you can join our non-public
communication channel for new contributors. To do so, please go to <aclass="reference external" href="https://gitter.im/matplotlib/matplotlib">gitter</a> and ask to be added to '#incubator'.
This is a private gitter room moderated by core Matplotlib developers where you can
get guidance and support for your first few PRs. This is a place you can ask questions
about anything: how to use git, github, how our PR review process works, technical questions
about the code, what makes for good documentation or a blog post, how to get involved involved
in community work, or get "pre-review" on your PR.</p>
<spanid="new-contributors"></span><h3>Issues for New Contributors<aclass="headerlink" href="#issues-for-new-contributors" title="Permalink to this headline">¶</a></h3>
<p>While any contributions are welcome, we have marked some issues as
particularly suited for new contributors by the label
<aclass="reference external" href="https://github.com/matplotlib/matplotlib/labels/good%20first%20issue">good first issue</a>
These are well documented issues, that do not require a deep understanding of
the internals of Matplotlib. The issues may additionally be tagged with a
difficulty. <codeclass="docutils literal notranslate"><spanclass="pre">Difficulty:</span><spanclass="pre">Easy</span></code> is suited for people with little Python experience.
<codeclass="docutils literal notranslate"><spanclass="pre">Difficulty:</span><spanclass="pre">Medium</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Difficulty:</span><spanclass="pre">Hard</span></code> are not trivial to solve and
require more thought and programming experience.</p>
</div>
</div>
<divclass="section" id="submitting-a-bug-report">
<spanid="id2"></span><h2>Submitting a bug report<aclass="headerlink" href="#submitting-a-bug-report" title="Permalink to this headline">¶</a></h2>
<p>If you find a bug in the code or documentation, do not hesitate to submit a
ticket to the
<aclass="reference external" href="https://github.com/matplotlib/matplotlib/issues">Issue Tracker</a>. You are
also welcome to post feature requests or pull requests.</p>
<p>If you are reporting a bug, please do your best to include the following:</p>
<olclass="arabic">
<li><pclass="first">A short, top-level summary of the bug. In most cases, this should be 1-2
sentences.</p>
</li>
<li><pclass="first">A short, self-contained code snippet to reproduce the bug, ideally allowing
a simple copy and paste to reproduce. Please do your best to reduce the code
snippet to the minimum required.</p>
</li>
<li><pclass="first">The actual outcome of the code snippet.</p>
</li>
<li><pclass="first">The expected outcome of the code snippet.</p>
</li>
<li><pclass="first">The Matplotlib version, Python version and platform that you are using. You
can grab the version with the following commands:</p>
<li><aclass="reference external" href="https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project">Git-Contributing to a Project</a></li>
<li><aclass="reference external" href="https://lab.github.com/githubtraining/introduction-to-github">Introduction to GitHub</a></li>
<li><aclass="reference internal" href="gitwash/development_workflow.html#development-workflow"><spanclass="std std-ref">Development workflow</span></a> for best practices for Matplotlib</li>
<li><aclass="reference internal" href="gitwash/index.html#using-git"><spanclass="std std-ref">Working with Matplotlib source code</span></a></li>
<h3>Contributing pull requests<aclass="headerlink" href="#contributing-pull-requests" title="Permalink to this headline">¶</a></h3>
<p>It is recommended to check that your contribution complies with the following
rules before submitting a pull request:</p>
<ul>
<li><pclass="first">If your pull request addresses an issue, please use the title to describe the
issue and mention the issue number in the pull request description to ensure
that a link is created to the original issue.</p>
</li>
<li><pclass="first">All public methods should have informative docstrings with sample usage when
appropriate. Use the <aclass="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpy docstring standard</a>.</p>
</li>
<li><pclass="first">Formatting should follow the recommendations of <aclass="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP8</a>. You should consider
installing/enabling automatic PEP8 checking in your editor. Part of the test
suite is checking PEP8 compliance, things go smoother if the code is mostly
PEP8 compliant to begin with.</p>
</li>
<li><pclass="first">Each high-level plotting function should have a simple example in the
<codeclass="docutils literal notranslate"><spanclass="pre">Example</span></code> section of the docstring. This should be as simple as possible
to demonstrate the method. More complex examples should go in the
<li><pclass="first">Changes (both new features and bugfixes) should be tested. See <aclass="reference internal" href="testing.html#testing"><spanclass="std std-ref">Testing</span></a>
for more details.</p>
</li>
<li><pclass="first">Import the following modules using the standard scipy conventions:</p>
<p>In general, Matplotlib modules should <strong>not</strong> import <aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">rcParams</span></code></a> using <codeclass="docutils literal notranslate"><spanclass="pre">from</span>
<spanclass="pre">matplotlib</span><spanclass="pre">import</span><spanclass="pre">rcParams</span></code>, but rather access it as <codeclass="docutils literal notranslate"><spanclass="pre">mpl.rcParams</span></code>. This
is because some modules are imported very early, before the <aclass="reference internal" href="../api/matplotlib_configuration_api.html#matplotlib.rcParams" title="matplotlib.rcParams"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">rcParams</span></code></a>
singleton is constructed.</p>
</li>
<li><pclass="first">If your change is a major new feature, add an entry to the <codeclass="docutils literal notranslate"><spanclass="pre">What's</span><spanclass="pre">new</span></code>
section by adding a new file in <codeclass="docutils literal notranslate"><spanclass="pre">doc/users/next_whats_new</span></code> (see
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/users/next_whats_new/README.rst</span></code> for more information).</p>
</li>
<li><pclass="first">If you change the API in a backward-incompatible way, please document it in
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/next_api_changes/behavior</span></code>, by adding a new file with the
naming convention <codeclass="docutils literal notranslate"><spanclass="pre">99999-ABC.rst</span></code> where the pull request number is followed
by the contributor's initials. (see <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/api_changes.rst</span></code> for more
information)</p>
</li>
<li><pclass="first">See below for additional points about <aclass="reference internal" href="#keyword-argument-processing"><spanclass="std std-ref">Keyword argument processing</span></a>, if
applicable for your pull request.</p>
</li>
</ul>
<p>In addition, you can check for common programming errors with the following
tools:</p>
<ul>
<li><pclass="first">Code with a good unittest coverage (at least 70%, better 100%), check with:</p>
<spanid="id6"></span><h2>Contributing documentation<aclass="headerlink" href="#contributing-documentation" title="Permalink to this headline">¶</a></h2>
<p>You as an end-user of Matplotlib can make a valuable contribution because you
more clearly see the potential for improvement than a core developer. For example, you can:</p>
<ulclass="simple">
<li>Fix a typo</li>
<li>Clarify a docstring</li>
<li>Write or update an <aclass="reference internal" href="../gallery/index.html#gallery"><spanclass="std std-ref">example plot</span></a></li>
<li>Write or update a comprehensive <aclass="reference internal" href="../tutorials/index.html#tutorials"><spanclass="std std-ref">tutorial</span></a></li>
</ul>
<p>The documentation source files live in the same GitHub repository as the code.
Contributions are proposed and accepted through the pull request process.
For details see <aclass="reference internal" href="#how-to-contribute"><spanclass="std std-ref">How to contribute</span></a>.</p>
<p>If you have trouble getting started, you may instead open an <aclass="reference external" href="https://github.com/matplotlib/matplotlib/issues">issue</a>
<spanid="id8"></span><h2>Coding guidelines<aclass="headerlink" href="#coding-guidelines" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="api-changes">
<h3>API changes<aclass="headerlink" href="#api-changes" title="Permalink to this headline">¶</a></h3>
<p>Changes to the public API must follow a standard deprecation procedure to
prevent unexpected breaking of code that uses Matplotlib.</p>
<ulclass="simple">
<li>Deprecations must be announced via a new file in
a new file in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/next_api_changes/deprecations/</span></code> with
naming convention <codeclass="docutils literal notranslate"><spanclass="pre">99999-ABC.rst</span></code> where <codeclass="docutils literal notranslate"><spanclass="pre">99999</span></code> is the pull request
number and <codeclass="docutils literal notranslate"><spanclass="pre">ABC</span></code> are the contributor's initials.</li>
<li>Deprecations are targeted at the next point-release (i.e. 3.x.0).</li>
<li>The deprecated API should, to the maximum extent possible, remain fully
functional during the deprecation period. In cases where this is not
possible, the deprecation must never make a given piece of code do something
different than it was before; at least an exception should be raised.</li>
<li>If possible, usage of an deprecated API should emit a
<aclass="reference internal" href="../api/_api_api.html#matplotlib._api.deprecation.MatplotlibDeprecationWarning" title="matplotlib._api.deprecation.MatplotlibDeprecationWarning"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">MatplotlibDeprecationWarning</span></code></a>. There are a number of helper tools for this:<ul>
<li>Use <codeclass="docutils literal notranslate"><spanclass="pre">cbook.warn_deprecated()</span></code> for general deprecation warnings.</li>
<li>Use the decorator <codeclass="docutils literal notranslate"><spanclass="pre">@cbook.deprecated</span></code> to deprecate classes, functions,
methods, or properties.</li>
<li>To warn on changes of the function signature, use the decorators
<codeclass="docutils literal notranslate"><spanclass="pre">@cbook._delete_parameter</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">@cbook._rename_parameter</span></code>, and
<li>Deprecated API may be removed two point-releases after they were deprecated.</li>
</ul>
</div>
<divclass="section" id="adding-new-api">
<h3>Adding new API<aclass="headerlink" href="#adding-new-api" title="Permalink to this headline">¶</a></h3>
<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>Mark helper functions and internal attributes as private by prefixing them
with an underscore.</li>
<li>Carefully think about good names for your functions and variables.</li>
<li>Try to adopt patterns and naming conventions from existing parts of the
Matplotlib API.</li>
<li>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>.</li>
<spanid="id10"></span><h3>Keyword argument processing<aclass="headerlink" href="#keyword-argument-processing" title="Permalink to this headline">¶</a></h3>
<p>Matplotlib makes extensive use of <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code> for pass-through customizations
from one function to another. A typical example is in <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.text.html#matplotlib.pyplot.text" title="matplotlib.pyplot.text"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.pyplot.text</span></code></a>.
The definition of the pylab text function is a simple pass-through to
<p><aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.text.html#matplotlib.axes.Axes.text" title="matplotlib.axes.Axes.text"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">text</span></code></a> in simplified form looks like this, i.e., it just
passes all <codeclass="docutils literal notranslate"><spanclass="pre">args</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">kwargs</span></code> on to <codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.text.Text.__init__</span></code>:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in axes/_axes.py</span>
<p>and <codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.text.Text.__init__</span></code> (again with liberties for illustration)
just passes them on to the <aclass="reference internal" href="../api/_as_gen/matplotlib.artist.Artist.update.html#matplotlib.artist.Artist.update" title="matplotlib.artist.Artist.update"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.artist.Artist.update</span></code></a> method:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in text.py</span>
<p><codeclass="docutils literal notranslate"><spanclass="pre">update</span></code> does the work looking for methods named like
<codeclass="docutils literal notranslate"><spanclass="pre">set_property</span></code> if <codeclass="docutils literal notranslate"><spanclass="pre">property</span></code> is a keyword argument. i.e., no one
looks at the keywords, they just get passed through the API to the
artist constructor which looks for suitably named methods and calls
them with the value.</p>
<p>As a general rule, the use of <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code> should be reserved for
pass-through keyword arguments, as in the example above. If all the
keyword args are to be used in the function, and not passed
on, use the key/value keyword args in the function definition rather
than the <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code> idiom.</p>
<p>In some cases, you may want to consume some keys in the local
function, and let others pass through. Instead of popping arguments to
use off <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code>, specify them as keyword-only arguments to the local
function. This makes it obvious at a glance which arguments will be
consumed in the function. For example, in
<aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.plot.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">plot()</span></code></a>, <codeclass="docutils literal notranslate"><spanclass="pre">scalex</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">scaley</span></code> are
<spanid="using-logging"></span><h3>Using logging for debug messages<aclass="headerlink" href="#using-logging-for-debug-messages" title="Permalink to this headline">¶</a></h3>
<p>Matplotlib uses the standard Python <aclass="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging</span></code></a> library to write verbose
warnings, information, and debug messages. Please use it! In all those places
you write <aclass="reference external" href="https://docs.python.org/3/library/functions.html#print" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">print</span></code></a> calls to do your debugging, try using <aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.debug" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.debug</span></code></a>
instead!</p>
<p>To include <aclass="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging</span></code></a> in your module, at the top of the module, you need to
<codeclass="docutils literal notranslate"><spanclass="pre">import</span><spanclass="pre">logging</span></code>. Then calls in your code like:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="n">_log</span><spanclass="o">=</span><spanclass="n">logging</span><spanclass="o">.</span><spanclass="n">getLogger</span><spanclass="p">(</span><spanclass="vm">__name__</span><spanclass="p">)</span><spanclass="c1"># right after the imports</span>
<spanclass="c1"># code</span>
<spanclass="c1"># more code</span>
<spanclass="n">_log</span><spanclass="o">.</span><spanclass="n">info</span><spanclass="p">(</span><spanclass="s1">'Here is some information'</span><spanclass="p">)</span>
<spanclass="n">_log</span><spanclass="o">.</span><spanclass="n">debug</span><spanclass="p">(</span><spanclass="s1">'Here is some more detailed information'</span><spanclass="p">)</span>
</pre></div>
</div>
<p>will log to a logger named <codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.yourmodulename</span></code>.</p>
<p>If an end-user of Matplotlib sets up <aclass="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging</span></code></a> to display at levels more
verbose than <codeclass="docutils literal notranslate"><spanclass="pre">logging.WARNING</span></code> in their code with the Matplotlib-provided
<h4>Which logging level to use?<aclass="headerlink" href="#which-logging-level-to-use" title="Permalink to this headline">¶</a></h4>
<p>There are five levels at which you can emit messages.</p>
<ulclass="simple">
<li><aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.critical" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.critical</span></code></a> and <aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.error" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.error</span></code></a> are really only there for errors that
will end the use of the library but not kill the interpreter.</li>
<li><aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.warning" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.warning</span></code></a> and <aclass="reference internal" href="../api/_api_api.html#matplotlib._api.warn_external" title="matplotlib._api.warn_external"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">_api.warn_external</span></code></a> are used to warn the user,
see below.</li>
<li><aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.info" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.info</span></code></a> is for information that the user may want to know if the
program behaves oddly. They are not displayed by default. For instance, if
an object isn't drawn because its position is <codeclass="docutils literal notranslate"><spanclass="pre">NaN</span></code>, that can usually
be ignored, but a mystified user could call
<codeclass="docutils literal notranslate"><spanclass="pre">logging.basicConfig(level=logging.INFO)</span></code> and get an error message that
says why.</li>
<li><aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.debug" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.debug</span></code></a> is the least likely to be displayed, and hence can be the
most verbose. "Expected" code paths (e.g., reporting normal intermediate
steps of layouting or rendering) should only log at this level.</li>
</ul>
<p>By default, <aclass="reference external" href="https://docs.python.org/3/library/logging.html#module-logging" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging</span></code></a> displays all log messages at levels higher than
<p>The <aclass="reference external" href="https://docs.python.org/3/howto/logging.html#logging-basic-tutorial">logging tutorial</a> suggests that the difference between <aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.warning" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.warning</span></code></a>
and <aclass="reference internal" href="../api/_api_api.html#matplotlib._api.warn_external" title="matplotlib._api.warn_external"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">_api.warn_external</span></code></a> (which uses <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>) is that
<aclass="reference internal" href="../api/_api_api.html#matplotlib._api.warn_external" title="matplotlib._api.warn_external"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">_api.warn_external</span></code></a> should be used for things the user must change to stop
the warning (typically in the source), whereas <aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.warning" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.warning</span></code></a> can be more
persistent. Moreover, note that <aclass="reference internal" href="../api/_api_api.html#matplotlib._api.warn_external" title="matplotlib._api.warn_external"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">_api.warn_external</span></code></a> will by default only
emit a given warning <em>once</em> for each line of user code, whereas
<aclass="reference external" href="https://docs.python.org/3/library/logging.html#logging.warning" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">logging.warning</span></code></a> will display the message every time it is called.</p>
<p>By default, <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> displays the line of code that has the <codeclass="docutils literal notranslate"><spanclass="pre">warn</span></code>
call. This usually isn't more informative than the warning message itself.
<spanclass="n">warnings</span><spanclass="o">.</span><spanclass="n">warn</span><spanclass="p">(</span><spanclass="s1">'Attempting to set identical bottom==top'</span><spanclass="p">)</span>
<spanclass="n">warnings</span><spanclass="o">.</span><spanclass="n">warn</span><spanclass="p">(</span><spanclass="s1">'Attempting to set identical bottom==top'</span><spanclass="p">)</span>
</pre></div>
</div>
<p>Modifying the module to use <aclass="reference internal" href="../api/_api_api.html#matplotlib._api.warn_external" title="matplotlib._api.warn_external"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">_api.warn_external</span></code></a>:</p>
<spanclass="n">_api</span><spanclass="o">.</span><spanclass="n">warn_external</span><spanclass="p">(</span><spanclass="s1">'Attempting to set identical bottom==top'</span><spanclass="p">)</span>
<spanid="sample-data"></span><h3>Writing examples<aclass="headerlink" href="#writing-examples" title="Permalink to this headline">¶</a></h3>
<p>We have hundreds of examples in subdirectories of <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlib/examples</span></code>,
and these are automatically generated when the website is built to show up in
the <aclass="reference internal" href="../gallery/index.html#gallery"><spanclass="std std-ref">examples</span></a> section of the website.</p>
<p>Any sample data that the example uses should be kept small and
distributed with Matplotlib in the
<codeclass="file docutils literal notranslate"><spanclass="pre">lib/matplotlib/mpl-data/sample_data/</span></code> directory. Then in your
example code you can load it into a file handle with:</p>