Text of matplotlib.org › devdocs › devel › coding_guide.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Coding guidelines — Matplotlib 3.12.0.dev924+g1fedee5e3 documentation

Skip to main content Plot types User guide Tutorials Examples Reference Contribute Releases Gitter Discourse GitHub Coding guidelines # We appreciate these guidelines being followed because it improves the readability, consistency, and maintainability of the code base. API guidelines If adding new features, changing behavior or function signatures, or removing public interfaces, please consult the API guidelines . PEP8, as enforced by ruff # Formatting should follow the recommendations of PEP8 , as enforced by ruff .

Matplotlib modifies PEP8 to extend the maximum line length to 88 characters. You can check PEP8 compliance from the command line with python - m pip install ruff ruff check / path / to / module . py or your editor may provide integration with it. To check all files, and fix any errors in-place (where possible) run ruff check -- fix Matplotlib intentionally does not use the black auto-formatter ( 1 ), in particular due to its inability to understand the semantics of mathematical expressions ( 2 , 3 ).

Package imports # 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.

Variable names # When feasible, please use our internal variable naming convention for objects of a given class and objects of any child class: base class variable multiples FigureBase fig Axes ax Transform trans trans_<source>_<target> trans_<source> when target is screen Generally, denote more than one instance of the same class by adding suffixes to the variable names. If a format isn't specified in the table, use numbers or letters as appropriate.

Type hints # If you add new public API or change public API, update or add the corresponding mypy type hints. We generally use stub files ( *.pyi ) to store the type information; for example colors.pyi contains the type information for colors.py . A notable exception is pyplot.py , which is type hinted inline. Type hints can be validated by the stubtest tool, which can be run locally using tox -e stubtest and is a part of the Automated tests suite.

Type hints for existing functions are also checked by the mypy pre-commit hook . 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 meson.build in the corresponding directories. New modules may be typed inline or using parallel stub file like existing modules. 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.

C/C++ code in the extern/ directory is vendored, and should be kept close to upstream whenever possible. It can be modified to fix bugs or implement new features only if the required changes cannot be made elsewhere in the codebase. In particular, avoid making style fixes to it. Static analysis with clang-tidy # Matplotlib's C/C++ sources in src/ are checked with clang-tidy in CI (see .github/workflows/linting.yml ). The check configuration lives in .clang-tidy .

The logic lives in tools/run_clang_tidy.py . It requires clang-tidy on PATH and meson and pybind11 installed: pip install meson pybind11 setuptools - scm On macOS, clang-tidy is not on PATH after a Homebrew install: brew install llvm export PATH=$(brew --prefix llvm)/bin:$PATH The script uses a dedicated build/clang-tidy/ directory (created automatically on first run) and delegates to meson's built-in clang-tidy target.

To run locally: python tools/run_clang_tidy.py To suppress false-positives use narrow checks and a comment: * indices ++ = value ; // NOLINT(clang-analyzer-security.ArrayBound): loop // iterates exactly N times; the analyzer cannot prove this from the macro. Keyword argument processing # Matplotlib makes extensive use of **kwargs for pass-through customizations from one function to another. A typical example is text .

The definition of matplotlib.pyplot.text is a simple pass-through to matplotlib.axes.Axes.text : # in pyplot.py def text ( x , y , s , fontdict = None , ** kwargs ): return gca () . text ( x , y , s , fontdict = fontdict , ** kwargs ) matplotlib.axes.Axes.text (simplified for illustration) just passes all args and kwargs on to matplotlib.text.Text.__init__ : # in axes/_axes.py def text ( self , x , y , s , fontdict = None , ** kwargs ): t = Text ( x = x , y = y , text = s , ** kwargs ) and matplotlib.text.Text.__init__ (again, simplified) 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 ) Use 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 Avoid using pre-computed strings ( f-strings , str.format ,etc.) for logging because of security and performance issues, and because they interfere with style handlers.

For example, use _log.error('hello %s', 'world') rather than _log.error('hello {}'.format('world')) or _log.error(f'hello {s}') . Which l

The rest of this page is on the live site.