<divid="unreleased-message"> You are reading an old version of the documentation (v1.5.3). For the latest version see <ahref="https://matplotlib.org/stable/devel/coding_guide.html">https://matplotlib.org/stable/devel/coding_guide.html</a></div>
<spanid="id1"></span><h1>Coding guide<aclass="headerlink" href="#coding-guide" title="Permalink to this headline">¶</a></h1>
<divclass="section" id="pull-request-checklist">
<spanid="id2"></span><h2>Pull request checklist<aclass="headerlink" href="#pull-request-checklist" title="Permalink to this headline">¶</a></h2>
<p>This checklist should be consulted when creating pull requests to make
sure they are complete before merging. These are not intended to be
rigidly followed—it’s just an attempt to list in one place all of
the items that are necessary for a good pull request. Of course, some
items will not always apply.</p>
<divclass="section" id="branch-selection">
<h3>Branch selection<aclass="headerlink" href="#branch-selection" title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li>In general, simple bugfixes that are unlikely to introduce new bugs
of their own should be merged onto the maintenance branch. New
features, or anything that changes the API, should be made against
master. The rules are fuzzy here – when in doubt, try to get some
consensus.<ul>
<li>Once changes are merged into the maintenance branch, they should
be merged into master.</li>
</ul>
</li>
</ul>
</div>
<divclass="section" id="style">
<h3>Style<aclass="headerlink" href="#style" title="Permalink to this headline">¶</a></h3>
<ul>
<li><pclass="first">Formatting should follow <aclass="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP8</a>. Exceptions to these
rules are acceptable if it makes the code objectively more readable.</p>
<ulclass="simple">
<li>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.</li>
</ul>
</li>
<li><pclass="first">No tabs (only spaces). No trailing whitespace.</p>
<ulclass="simple">
<li>Configuring your editor to remove these things upon saving will
save a lot of trouble.</li>
</ul>
</li>
<li><pclass="first">Import the following modules using the standard scipy conventions:</p>
<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 code in your pull request
does that.</p>
</li>
<li><pclass="first">Adding a new pyplot function involves generating code. See
<aclass="reference internal" href="#new-pyplot-function"><spanclass="std std-ref">Writing a new pyplot function</span></a> for more information.</p>
</li>
</ul>
</div>
<divclass="section" id="documentation">
<h3>Documentation<aclass="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h3>
<ul>
<li><pclass="first">Every new feature should be documented. If it’s a new module, don’t
forget to add a new rst file to the API docs.</p>
</li>
<li><pclass="first">Docstrings should be in <aclass="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpydoc format</a>.
Don’t be thrown off by the fact that many of the existing docstrings
are not in that format; we are working to standardize on
<spanid="id3"></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"><spanclass="pre">**kwargs</span></code> for pass-through
customizations from one function to another. A typical example is in
<codeclass="xref py py-func docutils literal"><spanclass="pre">matplotlib.pylab.text()</span></code>. The definition of the pylab text
<p><aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.text" title="matplotlib.axes.Axes.text"><codeclass="xref py py-meth docutils literal"><spanclass="pre">text()</span></code></a> in simplified form looks like this,
i.e., it just passes all <codeclass="docutils literal"><spanclass="pre">args</span></code> and <codeclass="docutils literal"><spanclass="pre">kwargs</span></code> on to
<p><codeclass="docutils literal"><spanclass="pre">update</span></code> does the work looking for methods named like
<codeclass="docutils literal"><spanclass="pre">set_property</span></code> if <codeclass="docutils literal"><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"><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"><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. You can <codeclass="docutils literal"><spanclass="pre">pop</span></code> the ones to be
used locally and pass on the rest. For example, in
<aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><codeclass="xref py py-meth docutils literal"><spanclass="pre">plot()</span></code></a>, <codeclass="docutils literal"><spanclass="pre">scalex</span></code> and <codeclass="docutils literal"><spanclass="pre">scaley</span></code> are
<spanid="custom-backend"></span><h3>Developing a new backend<aclass="headerlink" href="#developing-a-new-backend" title="Permalink to this headline">¶</a></h3>
<p>If you are working on a custom backend, the <em>backend</em> setting in
<codeclass="file docutils literal"><spanclass="pre">matplotlibrc</span></code> (<aclass="reference internal" href="../users/customizing.html#customizing-matplotlib"><spanclass="std std-ref">Customizing matplotlib</span></a>) supports an
external backend via the <codeclass="docutils literal"><spanclass="pre">module</span></code> directive. if
<codeclass="file docutils literal"><spanclass="pre">my_backend.py</span></code> is a matplotlib backend in your
<spanclass="target" id="index-0"></span><aclass="reference internal" href="../faq/environment_variables_faq.html#envvar-PYTHONPATH"><codeclass="xref std std-envvar docutils literal"><spanclass="pre">PYTHONPATH</span></code></a>, you can set use it on one of several ways</p>
<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"><spanclass="pre">matplotlib/examples</span></code>, and these are automatically generated
when the website is built to show up both in the <aclass="reference external" href="../examples/index.html">examples</a> and <aclass="reference external" href="../gallery.html">gallery</a> sections of the website.</p>
<p>Any sample data that the example uses should be kept small and
distributed with matplotlib in the
<codeclass="xref py py-obj docutils literal"><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>
<spanid="new-pyplot-function"></span><h3>Writing a new pyplot function<aclass="headerlink" href="#writing-a-new-pyplot-function" title="Permalink to this headline">¶</a></h3>
<p>A large portion of the pyplot interface is automatically generated by the
<codeclass="xref py py-obj docutils literal"><spanclass="pre">boilerplate.py</span></code> script (in the root of the source tree). To add or remove
a plotting method from pyplot, edit the appropriate list in <codeclass="xref py py-obj docutils literal"><spanclass="pre">boilerplate.py</span></code>
and then run the script which will update the content in
<codeclass="xref py py-obj docutils literal"><spanclass="pre">lib/matplotlib/pyplot.py</span></code>. Both the changes in <codeclass="xref py py-obj docutils literal"><spanclass="pre">boilerplate.py</span></code> and
<codeclass="xref py py-obj docutils literal"><spanclass="pre">lib/matplotlib/pyplot.py</span></code> should be checked into the repository.</p>
<p>Note: boilerplate.py looks for changes in the installed version of matplotlib
and not the source tree. If you expect the pyplot.py file to show your new
changes, but they are missing, this might be the cause.</p>
<p>Install your new files by running <codeclass="xref py py-obj docutils literal"><spanclass="pre">python</span><spanclass="pre">setup.py</span><spanclass="pre">build</span></code> and <codeclass="xref py py-obj docutils literal"><spanclass="pre">python</span><spanclass="pre">setup.py</span>
<spanclass="pre">install</span></code> followed by <codeclass="xref py py-obj docutils literal"><spanclass="pre">python</span><spanclass="pre">boilerplate.py</span></code>. The new pyplot.py file should now