.. _coding_guidelines:

Coding guidelines

While the current state of the Matplotlib code base is not compliant with all

of these guidelines, our goal in enforcing these constraints on new

contributions is that it improves the readability and consistency of the code base

going forward.

API changes

If you are adding new features, changing behavior or function signatures, or

removing classes, functions, methods, or properties, please see the :ref:`api_changes`

guide.

PEP8, as enforced by flake8

Formatting should follow the recommendations of PEP8_, as enforced by flake8_.

Matplotlib modifies PEP8 to extend the maximum line length to 88

characters. You can check flake8 compliance from the command line with ::

or your editor may provide integration with it. Note that 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__).

.. _PEP8: https://www.python.org/dev/peps/pep-0008/

.. _flake8: https://flake8.pycqa.org/

.. _black: https://black.readthedocs.io/

.. __: https://github.com/matplotlib/matplotlib/issues/18796

.. __: https://github.com/psf/black/issues/148

.. __: https://github.com/psf/black/issues/1984

Package imports

Import the following modules using the standard scipy conventions::

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 |

| `~matplotlib.figure.FigureBase` | ``fig`` | |

| `~matplotlib.axes.Axes` | ``ax`` | |

| `~matplotlib.transforms.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:

Type hints

If you add new public API or change public API, update or add the

corresponding `mypy <https://mypy.readthedocs.io/en/latest/>`_ type hints.

We generally use `stub files

<https://typing.readthedocs.io/en/latest/source/stubs.html#type-stubs>`_

(``*.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 are checked by the mypy :ref:`pre-commit hook <pre-commit-hooks>`

and can often be verified using ``tools\stubtest.py`` and occasionally may

require the use of ``tools\check_typehints.py``.

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 :file:`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 :file:`FOO_wrap.cpp` or

:file:`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 :file:`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.

.. _keyword-argument-processing:

Keyword argument processing

Matplotlib makes extensive use of ``**kwargs`` for pass-through customizations

from one function to another. A typical example is

`~matplotlib.axes.Axes.text`. The definition of `matplotlib.pyplot.text` is a

simple pass-through to `matplotlib.axes.Axes.text`::

`matplotlib.axes.Axes.text` (simplified for illustration) just

passes all ``args`` and ``kwargs`` on to ``matplotlib.text.Text.__init__``::

and ``matplotlib.text.Text.__init__`` (again, simplified)

just passes them on to the `matplotlib.artist.Artist.update` method::

``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

:meth:`~matplotlib.axes.Axes.plot`, ``scalex`` and ``scaley`` are

local arguments and the rest are passed on as

:meth:`~matplotlib.lines.Line2D` keyword arguments::

.. _using_logging:

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::

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::

or manually with ::

Then they will receive messages like

.. code-block:: none

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 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::

running the script::

will display

.. code-block:: none

Modifying the module to use `._api.warn_external`::

and running the same script will display

.. code-block:: none

.. _logging tutorial: https://docs.python.org/3/howto/logging.html#logging-basic-tutorial

.. _licence-coding-guide:

.. include:: license.rst

:start-line: 2

.. toctree::

:hidden:

license.rst