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.
Formatting should follow PEP8. Exceptions to these rules are acceptable if it makes the code objectively more readable.
No tabs (only spaces). No trailing whitespace.
Import the following modules using the standard scipy conventions:
import numpy as np
import numpy.ma as ma
import matplotlib as mpl
from matplotlib import pyplot as plt
import matplotlib.cbook as cbook
import matplotlib.collections as mcol
import matplotlib.patches as mpatches
See below for additional points about Keyword argument processing, if code in your pull request does that.
Adding a new pyplot function involves generating code. See Writing a new pyplot function for more information.
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.
Docstrings should be in numpydoc format.
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
numpydoc
.
Docstrings should look like (at a minimum):
def foo(bar, baz=None):
"""
This is a prose description of foo and all the great
things it does.
Parameters
----------
bar : (type of bar)
A description of bar
baz : (type of baz), optional
A description of baz
Returns
-------
foobar : (type of foobar)
A description of foobar
foobaz : (type of foobaz)
A description of foobaz
"""
# some very clever code
return foobar, foobaz
Each high-level plotting function should have a simple example in
the Example
section of the docstring. This should be as simple as
possible to demonstrate the method. More complex examples should go
in the examples
tree.
Build the docs and make sure all formatting warnings are addressed.
See Documenting matplotlib for our documentation style guide.
If your changes are non-trivial, please make an entry in the
CHANGELOG
.
If your change is a major new feature, add an entry to
doc/users/whats_new.rst
.
If you change the API in a backward-incompatible way, please
document it in doc/api/api_changes.rst
.
Using the test framework is discussed in detail in the section Testing.
--with-coverage
option may be
useful here).tox
support in matplotlib may be useful for testing locally.MANIFEST.in
, and/or in package_data
in setup.py
.FOO_wrap.cpp
or
FOO_wrapper.cpp
.Matplotlib makes extensive use of **kwargs
for pass-through
customizations from one function to another. A typical example is in
matplotlib.pylab.text()
. The definition of the pylab text
function is a simple pass-through to
matplotlib.axes.Axes.text()
:
# in pylab.py
def text(*args, **kwargs):
ret = gca().text(*args, **kwargs)
draw_if_interactive()
return ret
text()
in simplified form looks like this,
i.e., it just passes all args
and kwargs
on to
matplotlib.text.Text.__init__()
:
# in axes.py
def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
t = Text(x=x, y=y, text=s, **kwargs)
and __init__()
(again with liberties for
illustration) just passes them on to the
matplotlib.artist.Artist.update()
method:
# in text.py
def __init__(self, x=0, y=0, text='', **kwargs):
Artist.__init__(self)
self.update(kwargs)
update
does the work looking for methods named like
set_property
if property
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.
As a general rule, the use of **kwargs
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 **kwargs
idiom.
In some cases, you may want to consume some keys in the local
function, and let others pass through. You can pop
the ones to be
used locally and pass on the rest. For example, in
plot()
, scalex
and scaley
are
local arguments and the rest are passed on as
Line2D()
keyword arguments:
# in axes.py
def plot(self, *args, **kwargs):
scalex = kwargs.pop('scalex', True)
scaley = kwargs.pop('scaley', True)
if not self._hold: self.cla()
lines = []
for line in self._get_lines(*args, **kwargs):
self.add_line(line)
lines.append(line)
Note: there is a use case when kwargs
are meant to be used locally
in the function (not passed on), but you still need the **kwargs
idiom. That is when you want to use *args
to allow variable
numbers of non-keyword args. In this case, python will not allow you
to use named keyword args after the *args
usage, so you will be
forced to use **kwargs
. An example is
matplotlib.contour.ContourLabeler.clabel()
:
# in contour.py
def clabel(self, *args, **kwargs):
fontsize = kwargs.get('fontsize', None)
inline = kwargs.get('inline', 1)
self.fmt = kwargs.get('fmt', '%1.3f')
colors = kwargs.get('colors', None)
if len(args) == 0:
levels = self.levels
indices = range(len(self.levels))
elif len(args) == 1:
...etc...
This section describes how to add certain kinds of new features to matplotlib.
If you are working on a custom backend, the backend setting in
matplotlibrc
(Customizing matplotlib) supports an
external backend via the module
directive. if
my_backend.py
is a matplotlib backend in your
PYTHONPATH
, you can set use it on one of several ways
in matplotlibrc:
backend : module://my_backend
with the MPLBACKEND
environment variable:
> export MPLBACKEND="module://my_backend"
> python simple_plot.py
from the command shell with the -d
flag:
> python simple_plot.py -dmodule://my_backend
with the use directive in your script:
import matplotlib
matplotlib.use('module://my_backend')
We have hundreds of examples in subdirectories of
matplotlib/examples
, and these are automatically generated
when the website is built to show up both in the examples and gallery sections of the website.
Any sample data that the example uses should be kept small and
distributed with matplotlib in the
lib/matplotlib/mpl-data/sample_data/
directory. Then in your
example code you can load it into a file handle with:
import matplotlib.cbook as cbook
fh = cbook.get_sample_data('mydata.dat')
A large portion of the pyplot interface is automatically generated by the
boilerplate.py
script (in the root of the source tree). To add or remove
a plotting method from pyplot, edit the appropriate list in boilerplate.py
and then run the script which will update the content in
lib/matplotlib/pyplot.py
. Both the changes in boilerplate.py
and
lib/matplotlib/pyplot.py
should be checked into the repository.
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.
Install your new files by running python setup.py build
and python setup.py
install
followed by python boilerplate.py
. The new pyplot.py file should now
have the latest changes.