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

== Committing changes ==

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

consider posting to mpl-devel

== Naming and spacing conventions ==

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.

== 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 exmaple 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. Whenever you mutate a kwargs dictionary (eg

by popping it), you must first copy it since the user may be explitly

passing in a dictionary which is used across many function calls. As

an example of a copy, pop, passthrough usage, see Axes.plot:

# in axes.py

# in contour.py

== Class documentation ==

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

# in lines.py

of kwargs. Here is an example from matplotlib.lines

# in lines.py

artist.kwdocd['Line2D'] = '\n'.join(artist.ArtistInspector(Line2D).pprint_setters(leadingspace=12))

# in axes.py

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