Table Of Contents

Previous topic

Associated Projects

Next topic

SAIO - Swift All In One

This Page

Development Guidelines

Coding Guidelines

For the most part we try to follow PEP 8 guidelines which can be viewed here: http://www.python.org/dev/peps/pep-0008/

There is a useful pep8 command line tool for checking files for pep8 compliance which can be installed with easy_install pep8.

Testing Guidelines

Swift has a comprehensive suite of tests that are run on all submitted code, and it is recommended that developers execute the tests themselves to catch regressions early. Developers are also expected to keep the test suite up-to-date with any submitted code changes.

Swift’s suite of unit tests can be executed in an isolated environment with Tox: http://tox.testrun.org/

To execute the unit tests:

  • Install Tox:

    • pip install tox
  • If you do not have python 2.6 installed (as in 12.04):

    • Add export TOXENV=py27,pep8 to your ~/.bashrc
    • . ~/.bashrc
  • Run Tox from the root of the swift repo:

    • tox

    Remarks: If you installed using: cd ~/swift; sudo python setup.py develop, you may need to do: cd ~/swift; sudo chown -R swift:swift swift.egg-info prior to running tox. If you ever encounter DistributionNotFound, try to use tox –recreate or removing .tox directory to force tox to recreate the dependency list

  • Optionally, run only specific tox builds:

    • tox -e pep8,py26

Coding Style

Swift use flake8 with the OpenStack hacking module to enforce coding style.

Install flake8 and hacking with pip or by the packages of your Operating System.

It is advised to integrate flake8+hacking with your editor to get it automated and not get caught by Jenkins.

For example for Vim the syntastic plugin can do this for you.

Documentation Guidelines

The documentation in docstrings should follow the PEP 257 conventions (as mentioned in the PEP 8 guidelines).

More specifically:

  1. Triple qutes should be used for all docstrings.
  2. If the docstring is simple and fits on one line, then just use one line.
  3. For docstrings that take multiple lines, there should be a newline after the opening quotes, and before the closing quotes.
  4. Sphinx is used to build documentation, so use the restructured text markup to designate parameters, return values, etc. Documentation on the sphinx specific markup can be found here: http://sphinx.pocoo.org/markup/index.html
Installing Sphinx:
  1. Install sphinx (On Ubuntu: sudo apt-get install python-sphinx)
  2. python setup.py build_sphinx