Developer Guide

This guide provides basic information about setting up a development environment and writing code for the COMPAS framework.

For instructions on how to submit contributions, see Contributions

Installation

1. clone repo
2. make an environment with conda
3. install from source with pip

$ pip install -r requirements-dev.txt

Writing code

• https://www.python.org/dev/peps/pep-0008/
• https://www.python.org/dev/peps/pep-0020/

We try to follow the default Python style and formatting rules as closely as possible and use flake8 for linting and autopep8 for automatic formatting. Imports are sorted according to the settings in setup.cfg. We indent using (4) spaces.

Naming conventions

• US English
  • https://en.wikisource.org/wiki/The_Elements_of_Style
  • https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style

Package structure

• https://github.com/audreyr/cookiecutter

Module structure

In general, we use the __all__ variable to explicitly declare a public module API. The if __name__ is "__main__" guard is used to test the examples declared in docstrings. We do three from __future__ imports to provide compatibility with Python 2.7x.

Class modules

We define one class per module. Two blank lines are inserted before and after the class definition.

from __future__ import print_function
from __future__ import absolute_import
from __future__ import division

__all__ = ['MyClass']


class MyClass(object):

    pass


# ==============================================================================
# Main
# ==============================================================================

if __name__ == "__main__":

    import doctest
    doctest.testmod(globs=globals())

Docstrings

• We use the sphinxcontrib extension Napoleon - Marching towards legible docstrings (https://sphinxcontrib-napoleon.readthedocs.io/en/latest/)
• We prefer Numpy-style docstrings (https://numpydoc.readthedocs.io/en/latest/format.html)

Testing

• We use pytest for writing unit tests

Benchmarking