OxRSE Template Python Project

Overview

This project provides a template for Python projects that want to adhere to good software practices. It includes:

• A setup.py script for installation with pip.
• Style checking using flake8 to check PEP8 adherence.
• Documentation built from dosctrings using Sphinx and reStructuredText.
• Online documentation hosted on readthedocs.org.
• Unit tests built using the unittest module.
• Automated testing using Travis for Linux and OS/X, and AppVeyor for Windows
• Automated coverage testing using coverage and codecov.

Installation

To install (for all users), use

pip install -e .

After running this, you can use import oxrse from anywhere on your system.

To install as a developer, use

$ pip install -e .[dev,docs]

Unlike a normal install, this doesn't copy your project, but just makes a link to your source code. As a result, you can still use import oxrse anywhere on your system, but the imported code will be the code in your development folder.

How does it work?

Installation is handled via setup.py, which uses setuptools. This can then be used either directly (python setup.py install) or via pip. Both methods install both the module and its dependencies.

Style

OxRSE is written in Python and we follow the PEP8 recommendations for coding style.

Style checking

Adherence to PEP8 is checked using flake8. To test your style locally, navigate to the OxRSE directory and type

$ flake8

Flake8 is configured using the file .flake8.

When there is no alternative (e.g. for imports in an __init__.py), individual lines of code can be excluded from style checking by adding # noqa.

Documentation

Documentation is built from the docstrings found in every module, class, and method. Docstrings are written in reStructuredText (see also wikipedia.

Documentation is built using Sphinx. To do this locally, navigate to the OxRSE directory and type

cd doc
make clean
make html

Online documentation is built automatically and hosted by readthedocs.org.

To configure readthedocs, you must make an account on readthedocs.org and follow to instructions to create a project and link it to github. Finally, make sure to tick "Install your project inside a virtualenv using setup.py install" on readthedocs "Advanced settings" tab.

Testing

Unit tests are implemented using the unittest package.

To run all unit tests, use

$ python -m unittest discover

To run a specific test, use e.g.

$ python -m unittest oxrse.tests.test_calculate

Automated testing with Travis

We use Travis to test on Linux (Ubuntu) and OS/X.

To set this up, create an account on Travis (free for open source), and follow the instructions about setting up a project and linking it to github.

Once that's done, you can write a .travis.yml configuration script (syntax) that tells travis which Python versions to use, which commands to call for testing etc. Feel free to copy-paste from our example code!

Automated testing with AppVeyor

AppVeyor offers free testing on Windows systems.

As before, set up an account and follow the instructions. An appveyor.yml configuration file (syntax) is used to tell AppVeyor which Python versions to test, what to install, and what test commands to run.

Automated coverage checking with CodeCov

We use codecov.io, which builds on coverage, to test if every line of code is hit during unit testing, and to generate nice reports.

Again, follow the instructions to set up and account and link it to github.

Some parts of your code (e.g. NotImplementedErrors) can be excluded by writing a configuration file: .coveragerc (syntax).

Feedback and suggestions

If you have any feedback or suggestions about this project, please get in touch or open an issue.