Python Guidelines

This page gives our guidelines for the Python Interface.

Miscellaneous

 * Take a user's perspective, not a perspective from the code
 * Prefer keyword arguments over positional arguments in sample scripts
 * Easier to read
 * Allows to leave out arguments

Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Special cases aren't special enough to break the rules. Although practicality beats purity. Errors should never pass silently. Unless explicitly silenced. In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it. Although that way may not be obvious at first unless you're Dutch. Now is better than never. Although never is often better than *right* now. If the implementation is hard to explain, it's a bad idea. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea -- let's do more of those!
 * The C interface and the Python interface are kept separated. There is no need to fit the Python interface to the C interface.
 * To handle the global variables in the C code of, we use the Highlander Pattern.
 * Remember the Zen of Python

Properties

 * When properties are used correctly, they are a good idea
 * I suggest that we use properties if and only if (stolen from ):
 * they are simply used to make an attribute read only OR
 * they reproduce attribute access with run time check (raising errors) but no change to the attribute value being set AND
 * the get and set code is very short (in the order of 5 lines) AND
 * the get and set do not set off demanding computation (think ipython tab completion) AND
 * the get and set methods are private by convention or otherwise AND
 * accessing the property has no unexpected side effects

Guidelines by others

 * Design Guidelines of the NiPy (Neuroimaging) community