HACKING

Keystone Style Commandments
===========================

Step 1: Read http://www.python.org/dev/peps/pep-0008/
Step 2: Read http://www.python.org/dev/peps/pep-0008/ again
Step 3: Read on

Imports
-------
- thou shalt not import objects, only modules
- thou shalt not import more than one module per line
- thou shalt not make relative imports
- thou shalt organize your imports according to the following template

::
  # vim: tabstop=4 shiftwidth=4 softtabstop=4
  {{stdlib imports in human alphabetical order}}
  \n
  {{third-party library imports in human alphabetical order}}
  \n
  {{keystoneclient imports in human alphabetical order}}
  \n
  \n
  {{begin your code}}


General
-------
- thou shalt put two newlines twixt toplevel code (funcs, classes, etc)
- thou shalt put one newline twixt methods in classes and anywhere else
- thou shalt not write "except:", use "except Exception:" at the very least
- thou shalt include your name with TODOs as in "TODO(termie)"
- thou shalt not name anything the same name as a builtin or reserved word
- thou shalt not violate causality in our time cone, or else


Human Alphabetical Order Examples
---------------------------------
::
  import httplib
  import logging
  import random
  import StringIO
  import testtools
  import time

  import httplib2

  from keystoneclient import exceptions
  from keystoneclient import service_catalog
  from keystoneclient.v2_0 import client

Docstrings
----------
  """A one line docstring looks like this and ends in a period."""


  """A multiline docstring has a one-line summary, less than 80 characters.

  Then a new paragraph after a newline that explains in more detail any
  general information about the function, class or method. Example usages
  are also great to have here if it is a complex class for function. After
  you have finished your descriptions add an extra newline and close the
  quotations.

  When writing the docstring for a class, an extra line should be placed
  after the closing quotations. For more in-depth explanations for these
  decisions see http://www.python.org/dev/peps/pep-0257/

  If you are going to describe parameters and return values, use Sphinx, the
  appropriate syntax is as follows.

  :param foo: the foo parameter
  :param bar: the bar parameter
  :returns: description of the return value

  """

Exceptions
----------

When dealing with exceptions from underlying libraries, translate those
exceptions to an instance or subclass of ClientException.

=======
Testing
=======

python-keystoneclient uses testtools and testr for its unittest suite
and its test runner. Basic workflow around our use of tox and testr can
be found at http://wiki.openstack.org/testr. If you'd like to learn more
in depth:

  https://testtools.readthedocs.org/
  https://testrepository.readthedocs.org/

Happy hacking!