= The matplotlib developer's guide =

This is meant to be a guide to developers on the mpl coding practices

and standards. Please edit and extend this document.

== svn checkouts ==

# checking out everything (toolkits, user's guide, htdocs, etc..)

svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk matplotlib --username=youruser --password=yourpass

# checking out the main src

svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/matplotlib matplotlib --username=youruser --password=yourpass

# branch checkouts, eg the transforms branch

svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/transforms transbranch

== Committing changes ==

When committing changes to matplotlib, there are a few things to bear

in mind.

* if your changes are non-trivial, please make an entry in the

CHANGELOG

* if you change the API, please document it in API_CHANGES, and

consider posting to mpl-devel

* Are your changes python2.3 compatible? We are still trying to

support 2.3, so avoid 2.4 only features like decorators until we

remove 2.3 support

* Can you pass examples/backend_driver.py? This is our poor man's

unit test.

* If you have altered extension code, do you pass

unit/memleak_hawaii.py?

* if you have added new files or directories, or reorganized

existing ones, are the new files included in the match patterns in

MANIFEST.in. This file determines what goes into the src

distribution of the mpl build.

== Importing and name spaces ==

For numpy, use:

import numpy as npy

a = npy.array([1,2,3])

For masked arrays, use:

import matplotlib.numerix.npyma as ma

(This is needed to support the maskedarray module as an

alternative to the original numpy ma module; eventually,

the maskedarray implementation is likely to replace the

ma implementation.)

For matplotlib main module, use:

import matplotlib as mpl

mpl.rcParams['xtick.major.pad'] = 6

For matplotlib modules (or any other modules), use:

import matplotlib.cbook as cbook

if cbook.iterable(z):

pass

We prefer this over the equivalent 'from matplotlib import cbook'

because the latter is ambiguous whether cbook is a module or a

function to the new developer. The former makes it explcit that

you are importing a module or package.

== Naming, spacing, and formatting conventions ==

In general, we want to hew as closely as possible to the standard

coding guidelines for python written by Guido in

http://www.python.org/dev/peps/pep-0008, though we do not do this

throughout.

functions and class methods : lower or lower_underscore_separated

attributes and variables : lower or lowerUpper

classes : Upper or MixedCase

Personally, I prefer the shortest names that are still readable.

Also, use an editor that does not put tabs in files. Four spaces

should be used for indentation everywhere and if there is a file with

tabs or more or less spaces it is a bug -- please fix it.

Please avoid spurious invisible spaces at the ends of lines.

(Tell your editor to strip whitespace from line ends when saving

a file.)

Keep docstrings uniformly indented as in the example below, with

nothing to the left of the triple quotes. The dedent() function

is needed to remove excess indentation only if something will be

interpolated into the docstring, again as in the example above.

Limit line length to 80 characters. If a logical line needs to be

longer, use parentheses to break it; do not use an escaped

newline. It may be preferable to use a temporary variable

to replace a single long line with two shorter and more

readable lines.

Please do not commit lines with trailing white space, as it causes

noise in svn diffs. If you are an emacs user, the following in your

.emacs will cause emacs to strip trailing white space on save for

python, C and C++

; and similarly for c++-mode-hook and c-mode-hook

(add-hook 'python-mode-hook

(lambda ()

(add-hook 'write-file-functions 'delete-trailing-whitespace)))

for older versions of emacs (emacs<22) you need to do

(add-hook 'python-mode-hook

(lambda ()

(add-hook 'local-write-file-hooks 'delete-trailing-whitespace)))

== Licenses ==

matplotlib only uses BSD compatible code. If you bring in code from

another project make sure it has a PSF, BSD, MIT or compatible

license. If not, you may consider contacting the author and asking

them to relicense it. GPL and LGPL code are not acceptible in the

main code base, though we are considering an alternative way of

distributing L/GPL code through an separate channel, possibly a

toolkit. If you include code, make sure you include a copy of that

code's license in the license directory if the code's license requires

you to distribute the license with it.

== Keyword argument processing ==

Matplotlib makes extensive use of **kwargs for pass through

customizations from one function to another. A typical example is in

pylab.text, The definition of the pylab text function is a simple

pass-through to axes.Axes.text

# in pylab.py

def text(*args, **kwargs):

ret = gca().text(*args, **kwargs)

draw_if_interactive()

return ret

axes.Axes.text in simplified form looks like this, ie it just passes

them on to 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 Text.__init__ (again with liberties for illustration) just passes

them on to the 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. Ie, noone 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 examaple above. If I intend

for all the keyword args to be used in some function and not passed

on, I just use the key/value keyword args in the function definition

rather than the **kwargs idiom.

In some cases I want to consume some keys and pass through the others,

in which case I pop the ones I want to use locally and pass on the

rest, eg I pop scalex and scaley in Axes.plot and assume the rest are

Line2D keyword arguments. As an example of a pop, passthrough

usage, see Axes.plot:

# 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)

The matplotlib.cbook function popd() is rendered

obsolete by the pop() dictionary method introduced in Python 2.3,

so it should not be used for new code.

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

== Class documentation ==

matplotlib uses artist instrospection of docstrings to support

properties. All properties that you want to support through setp and

getp should have a set_property and get_property method in the Artist

class. Yes, this is not ideal given python properties or enthought

traits, but it is a historical legacy for now. The setter methods use

the docstring with the ACCEPTS token to indicate the type of argument

the method accepts. Eg in matplotlib.lines.Line2D

# in lines.py

def set_linestyle(self, linestyle):

"""

Set the linestyle of the line

ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]

"""

Since matplotlib uses a lot of pass through kwargs, eg in every

function that creates a line (plot, semilogx, semilogy, etc...), it

can be difficult for the new user to know which kwargs are supported.

I have developed a docstring interpolation scheme to support

documentation of every function that takes a **kwargs. The

requirements are:

1) single point of configuration so changes to the properties don't

require multiple docstring edits

2) as automated as possible so that as properties change the docs

are updated automagically.

I have added a matplotlib.artist.kwdocd and kwdoc() to faciliate this.

They combines python string interpolation in the docstring with the

matplotlib artist introspection facility that underlies setp and getp.

The kwdocd is a single dictionary that maps class name to a docstring

of kwargs. Here is an example from matplotlib.lines

# in lines.py

artist.kwdocd['Line2D'] = artist.kwdoc(Line2D)

Then in any function accepting Line2D passthrough kwargs, eg

matplotlib.axes.Axes.plot

# in axes.py

...

def plot(self, *args, **kwargs):

"""

Some stuff omitted

The kwargs are Line2D properties:

%(Line2D)s

kwargs scalex and scaley, if defined, are passed on

to autoscale_view to determine whether the x and y axes are

autoscaled; default True. See Axes.autoscale_view for more

information

"""

pass

plot.__doc__ = cbook.dedent(plot.__doc__) % artist.kwdocd

Note there is a problem for Artist __init__ methods, eg Patch.__init__

which supports Patch kwargs, since the artist inspector cannot work

until the class is fully defined and we can't modify the

Patch.__init__.__doc__ docstring outside the class definition. I have

made some manual hacks in this case which violates the "single entry

point" requirement above; hopefully we'll find a more elegant solution

before too long