Attention
This is copied verbatim from the old IPython wiki and is currently under development. Much of the information in this part of the development guide is out of date.
This document describes our coding style. Coding style refers to the following:
In general, we follow the standard Python style conventions as described in Python’s PEP 8, the official Python Style Guide.
Other general comments:
For naming conventions, we also follow the guidelines of PEP 8. Some of the existing code doesn’t honor this perfectly, but for all new and refactored IPython code, we’ll use:
lowercase
module names. Long module names can have words
separated by underscores (really_long_module_name.py
), but this
is not required. Try to use the convention of nearby files.CamelCase
for class names.lowercase_with_underscores
for methods, functions, variables and
attributes._single_underscore_prefix
. Names with a leading double underscore
will only be used in special cases, as they makes subclassing
difficult (such names are not easily seen by child classes).runlines()
where
runsource()
and runcode()
had established precedent).IP
of ip
. This is not necessary and
all new code should not use this prefix. The only case where this
approach is justified is for classes or functions which are expected
to be imported into external namespaces and a very generic name (like
Shell) that is likely to clash with something else. However, if a
prefix seems absolutely necessary the more specific IPY
or
ipy
are preferred.In general, objects should declare, in their class, all attributes the object is meant to hold throughout its life. While Python allows you to add an attribute to an instance at any point in time, this makes the code harder to read and requires methods to constantly use checks with hasattr() or try/except calls. By declaring all attributes of the object in the class header, there is a single place one can refer to for understanding the object’s data interface, where comments can explain the role of each variable and when possible, sensible deafaults can be assigned.
If an attribute is meant to contain a mutable object, it should be set
to None
in the class and its mutable value should be set in the
object’s constructor. Since class attributes are shared by all
instances, failure to do this can lead to difficult to track bugs. But
you should still set it in the class declaration so the interface
specification is complete and documented in one place.
A simple example:
class Foo(object):
# X does..., sensible default given:
x = 1
# y does..., default will be set by constructor
y = None
# z starts as an empty list, must be set in constructor
z = None
def __init__(self, y):
self.y = y
self.z = []
When starting a new Python file for IPython, you can use the following template as a starting point that has a few common things pre-written for you.