This project is a community effort, and everyone is welcome to contribute.
The project is hosted on https://github.com/matplotlib/matplotlib
In case you experience issues using this package, do not hesitate to submit a ticket to the Bug Tracker. You are also welcome to post feature requests or pull requests.
We use Git for version control and GitHub for hosting our main repository.
You can check out the latest sources with the command:
git clone git@github.com:matplotlib/matplotlib.git
After obtaining a local copy of the matpotlib source code (Set up your fork), navigate to the matplotlib directory and run the following in the shell:
python setup.py develop
or:
pip install -v -e .
This installs matplotlib for development (i.e., builds everything and places the symbolic links back to the source code). You can then run the tests your work environment is set up properly:
python tests.py
You may want to consider setting up a virtual environment or a conda environment
Note
If you decide to do this, you will have to rerun:
python setup.py build
every time the source code of a compiled extension is changed (for instance when switching branches or pulling changes from upstream).
Note
Additional dependencies for testing: nose (version 1.0 or later), mock (if python < 3.3), Ghostscript, Inkscape
Note
To make sure the tests run locally:
test to True, and local_freetype to TrueWhen working on bleeding edge packages, setting up a virtual environment or a conda environment is recommended.
See also
The preferred way to contribute to matplotlib is to fork the main repository on GitHub, then submit a “pull request” (PR):
Create an account on GitHub if you do not already have one.
Fork the project repository: click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub server.
Clone this copy to your local disk:
$ git clone git@github.com:YourLogin/matplotlib.gitCreate a branch to hold your changes:
$ git checkout -b my-featureand start making changes. Never work in the
masterbranch!Work on this copy, on your computer, using Git to do the version control. When you’re done editing, do:
$ git add modified_files $ git committo record your changes in Git, then push them to GitHub with:
$ git push -u origin my-feature
Finally, go to the web page of the your fork of the matplotlib repo, and click ‘Pull request’ to send your changes to the maintainers for review. You may want to consider sending an email to the mailing list for more visibility.
It is recommended to check that your contribution complies with the following rules before submitting a pull request:
If your pull request addresses an issue, please use the title todescribe the issue and mention the issue number in the pull request description to ensure a link is created to the original issue.
All public methods should have informative docstrings with sample usage presented as doctests when appropriate. Use the numpy docstring standard
Formatting should follow PEP8 recommandation. 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.
Each high-level plotting function should have a simple example in the
Examplesection of the docstring. This should be as simple as possible to demonstrate the method. More complex examples should go in theexamplestree.Changes (both new features and bugfixes) should be tested. See Developer’s tips for testing for more details.
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 mpatchesIf your change is a major new feature, add an entry to
What's newsection by adding a new file indoc/users/whats_new(seedoc/users/whats_new/READMEfor more information).If you change the API in a backward-incompatible way, please document it in
doc/api/api_changes, by adding a new file describing your changes (seedoc/api/api_changes/READMEfor more information)See below for additional points about Keyword argument processing, if code in your pull request does that.
In addition, you can check for common programming errors with the following tools:
Code with a good unittest coverage (at least 70%, better 100%), check with:
pip install coverage python tests.py --with-coverageNo pyflakes warnings, check with:
pip install pyflakes pyflakes path/to/module.py
Note
The current state of the matplotlib code base is not compliant with all of those guidelines, but we expect that enforcing those constraints on all new contributions will get the overall code base quality in the right direction.
New contributors should look for the following tags when looking for issues. We strongly recommend that new contributors tackle “new-contributor-friendly” issues (easy, well documented issues, that do not require an understanding of the different submodules of matplotlib) and “Easy-fix” issues. This helps the contributor become familiar with the contribution workflow, and for the core devs to become acquainted with the contributor; besides which, we frequently underestimate how easy an issue is to solve!
new-contributor-friendly
A great way to start contributing to matplotlib is to pick an item from the list of new-contributor-friendly in the issue tracker. Resolving these issues allow you to start contributing to the project without much prior knowledge. Your assistance in this area will be greatly appreciated by the more experienced developers as it helps free up their time to concentrate on other issues.
Code is not the only way to contribute to matplotlib. For instance, documentation is also a very important part of the project and often doesn’t get as much attention as it deserves. If you find a typo in the documentation, or have made improvements, do not hesitate to send an email to the mailing list or submit a GitHub pull request. Full documentation can be found under the doc/ directory.
It also helps us if you spread the word: reference the project from your blog and articles or link to it from your website!
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...
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')