Contributing¶

This project is a community effort, and everyone is welcome to contribute. Everyone within the community is expected to abide by our code of conduct.

The project is hosted on https://github.com/matplotlib/matplotlib

Contributor Incubator¶

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 gitter 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.

Issues for New Contributors¶

While any contributions are welcome, we have marked some issues as particularly suited for new contributors by the label good first issue 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. Difficulty: Easy is suited for people with little Python experience. Difficulty: Medium and Difficulty: Hard are not trivial to solve and require more thought and programming experience.

Submitting a bug report¶

If you find a bug in the code or documentation, do not hesitate to submit a ticket to the Issue Tracker. You are also welcome to post feature requests or pull requests.

If you are reporting a bug, please do your best to include the following:

A short, top-level summary of the bug. In most cases, this should be 1-2 sentences.
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.
The actual outcome of the code snippet.
The expected outcome of the code snippet.

The Matplotlib version, Python version and platform that you are using. You can grab the version with the following commands:

>>> import matplotlib
>>> matplotlib.__version__
'3.4.1'
>>> import platform
>>> platform.python_version()
'3.9.2'

We have preloaded the issue creation page with a Markdown template that you can use to organize this information.

Thank you for your help in keeping bug reports complete, targeted and descriptive.

Requesting a new feature¶

Please post feature requests to the Issue Tracker.

The Matplotlib developers will give feedback on the feature proposal. Since Matplotlib is an open source project with limited resources, we encourage users to then also participate in the implementation.

Contributing code¶

How to contribute¶

The preferred way to contribute to Matplotlib is to fork the main repository on GitHub, then submit a "pull request" (PR).

A brief overview is:

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 https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git

Enter the directory and install the local version of Matplotlib. See ref`<installing_for_devs>` for instructions
Create a branch to hold your changes:
```
git checkout -b my-feature origin/master
```
and start making changes. Never work in the master branch!
Work on this copy, on your computer, using Git to do the version control. When you're done editing e.g., lib/matplotlib/collections.py, do:
```
git add lib/matplotlib/collections.py
git commit
```
to record your changes in Git, then push them to GitHub with:
```
git push -u origin my-feature
```

Finally, go to the web page of your fork of the Matplotlib repo, and click 'Pull request' to send your changes to the maintainers for review.

Contributing pull requests¶

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 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.
All public methods should have informative docstrings with sample usage when appropriate. Use the numpy docstring standard.
Formatting should follow the recommendations of PEP8. 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 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.
Changes (both new features and bugfixes) should be tested. See 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
import matplotlib.pyplot as plt
import matplotlib.cbook as cbook
import matplotlib.patches as mpatches
```
In general, Matplotlib modules should not import rcParams using from matplotlib import rcParams, but rather access it as mpl.rcParams. This is because some modules are imported very early, before the rcParams singleton is constructed.
If your change is a major new feature, add an entry to the What's new section by adding a new file in doc/users/next_whats_new (see doc/users/next_whats_new/README.rst for more information).
If you change the API in a backward-incompatible way, please document it in doc/api/next_api_changes/behavior, by adding a new file with the naming convention 99999-ABC.rst where the pull request number is followed by the contributor's initials. (see doc/api/api_changes.rst for more information)
See below for additional points about Keyword argument processing, if applicable for your pull request.

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:

python -m pip install coverage
python -m pytest --cov=matplotlib --showlocals -v

No pyflakes warnings, check with:

python -m 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 move the overall code base quality in the right direction.

Contributing documentation¶

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:

Fix a typo
Clarify a docstring
Write or update an example plot
Write or update a comprehensive tutorial

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 How to contribute.

If you have trouble getting started, you may instead open an issue describing the intended improvement.

Other ways to contribute¶

It also helps us if you spread the word: reference the project from your blog and articles or link to it from your website! If Matplotlib contributes to a project that leads to a scientific publication, please follow the Citing Matplotlib guidelines.

Coding guidelines¶

API changes¶

Changes to the public API must follow a standard deprecation procedure to prevent unexpected breaking of code that uses Matplotlib.

Deprecations must be announced via a new file in a new file in doc/api/next_api_changes/deprecations/ with naming convention 99999-ABC.rst where 99999 is the pull request number and ABC are the contributor's initials.
Deprecations are targeted at the next point-release (i.e. 3.x.0).
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.
If possible, usage of an deprecated API should emit a MatplotlibDeprecationWarning. There are a number of helper tools for this:
- Use cbook.warn_deprecated() for general deprecation warnings.
- Use the decorator @cbook.deprecated to deprecate classes, functions, methods, or properties.
- To warn on changes of the function signature, use the decorators @cbook._delete_parameter, @cbook._rename_parameter, and @cbook._make_keyword_only.
Deprecated API may be removed two point-releases after they were deprecated.

Adding new API¶

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:

Mark helper functions and internal attributes as private by prefixing them with an underscore.
Carefully think about good names for your functions and variables.
Try to adopt patterns and naming conventions from existing parts of the Matplotlib API.
Consider making as many arguments keyword-only as possible. See also API Evolution the Right Way -- Add Parameters Compatibly.

New modules and files: installation¶

If you have added new files or directories, or reorganized existing ones, make sure the new files are included in the match patterns in MANIFEST.in, and/or in package_data in setup.py.

C/C++ extensions¶

Extensions may be written in C or C++.
Code style should conform to PEP7 (understanding that PEP7 doesn't address C++, but most of its admonitions still apply).
Python/C interface code should be kept separate from the core C/C++ code. The interface code should be named FOO_wrap.cpp or FOO_wrapper.cpp.
Header file documentation (aka docstrings) should be in Numpydoc format. We don't plan on using automated tools for these docstrings, and the Numpydoc format is well understood in the scientific Python community.

Keyword argument processing¶

Matplotlib makes extensive use of **kwargs for pass-through customizations from one function to another. A typical example is in matplotlib.pyplot.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/_axes.py
def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
    t = Text(x=x, y=y, text=s, **kwargs)

and matplotlib.text.Text.__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):
    super().__init__()
    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. Instead of popping arguments to use off **kwargs, 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 plot(), scalex and scaley are local arguments and the rest are passed on as Line2D() keyword arguments:

# in axes/_axes.py
def plot(self, *args, scalex=True, scaley=True, **kwargs):
    lines = []
    for line in self._get_lines(*args, **kwargs):
        self.add_line(line)
        lines.append(line)

Using logging for debug messages¶

Matplotlib uses the standard Python logging library to write verbose warnings, information, and debug messages. Please use it! In all those places you write print calls to do your debugging, try using logging.debug instead!

To include logging in your module, at the top of the module, you need to import logging. Then calls in your code like:

_log = logging.getLogger(__name__)  # right after the imports

# code
# more code
_log.info('Here is some information')
_log.debug('Here is some more detailed information')

will log to a logger named matplotlib.yourmodulename.

If an end-user of Matplotlib sets up logging to display at levels more verbose than logging.WARNING in their code with the Matplotlib-provided helper:

plt.set_loglevel("debug")

or manually with

import logging
logging.basicConfig(level=logging.DEBUG)
import matplotlib.pyplot as plt

Then they will receive messages like:

DEBUG:matplotlib.backends:backend MacOSX version unknown
DEBUG:matplotlib.yourmodulename:Here is some information
DEBUG:matplotlib.yourmodulename:Here is some more detailed information

Which logging level to use?¶

There are five levels at which you can emit messages.

logging.critical and logging.error are really only there for errors that will end the use of the library but not kill the interpreter.
logging.warning and _api.warn_external are used to warn the user, see below.
logging.info 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 NaN, that can usually be ignored, but a mystified user could call logging.basicConfig(level=logging.INFO) and get an error message that says why.
logging.debug 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.

By default, logging displays all log messages at levels higher than logging.WARNING to sys.stderr.

The logging tutorial suggests that the difference between logging.warning and _api.warn_external (which uses warnings.warn) is that _api.warn_external should be used for things the user must change to stop the warning (typically in the source), whereas logging.warning can be more persistent. Moreover, note that _api.warn_external will by default only emit a given warning once for each line of user code, whereas logging.warning will display the message every time it is called.

By default, warnings.warn displays the line of code that has the warn call. This usually isn't more informative than the warning message itself. Therefore, Matplotlib uses _api.warn_external which uses warnings.warn, but goes up the stack and displays the first line of code outside of Matplotlib. For example, for the module:

# in my_matplotlib_module.py
import warnings

def set_range(bottom, top):
    if bottom == top:
        warnings.warn('Attempting to set identical bottom==top')

running the script:

from matplotlib import my_matplotlib_module
my_matplotlib_module.set_range(0, 0)  #set range

will display:

UserWarning: Attempting to set identical bottom==top
warnings.warn('Attempting to set identical bottom==top')

Modifying the module to use _api.warn_external:

from matplotlib import _api

def set_range(bottom, top):
    if bottom == top:
        _api.warn_external('Attempting to set identical bottom==top')

and running the same script will display:

UserWarning: Attempting to set identical bottom==top
my_matplotlib_module.set_range(0, 0)  #set range

Writing examples¶

We have hundreds of examples in subdirectories of matplotlib/examples, and these are automatically generated when the website is built to show up in the examples section 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')