Contribution Guide

This page explains how to get started contributing code to the SoftLayer API Python Bindings project.

Code Organization

  • docs - Where The source to this documentation lives.
  • SoftLayer - All the source lives under here.
    • API - Primary API client.
    • CLI - Code for the command-line interface.
      • modules - CLI Modules.
    • managers - API Managers. Abstractions to help use the API.

Setting Up A Dev Environment

Before working with the SoftLayer Python API client source, we strongly recommend that you know how to use Python’s virtualization environment, virtualenv. Virtualenv allows you to create Python setups that are individually tailored to particular develpment efforts. Each environment can have its own set of libraries and even its own Python interpreter. This keeps them isolated, reducing the possibility of library conflicts between different projects.

After you have virtualenv, you should set up a virtual environment and activate it whenever you are working on softlayer-python. The commands needed to setup an environment and activate it might look something like this:

virtualenv --no-site-packages softlayer_env

source softlayer_env/bin/activate

Please refer to the virtualenv documentation for more information about creating, and working with virtual environments.

Once you have an appropriate environment, you will then download the SoftLayer API Python Bindings source code by following the installation instructions. Change into softlayer-python source directory and run the following to install the pre-requisites needed to run the development tests:

pip install -r tools/test-requirements.txt

Testing

The project has a mix of functional and unit tests. Before submitting changes to be integrated into the project, you should validate your code using tox. Simply issue the tox command from the root of the source tree:

tox

In addition to testing different versions of Python, tox checks for common mistakes in the code using Flake8. You should eliminate the simple errors reported by Flake8 before submitting your code.

The project’s configuration instructs tox to test against many different versions of Python. A tox test will use as many of those as it can find on your local computer. Rather than installing all those versions, we recommend that you point the Travis integration tool at your github fork. Travis will run the test against the full suite of Python versions every time you push new code.

Running the tests in multiple environments, using tox, is very time consuming. If you wish to quickly run the tests in your own environment, you may do so using nose. The command to do that is:

python setup.py nosetests

Documentation

The project is documented in reStructuredText and built using Sphinx. If you have fabric installed, you simply need to run the following to build the docs:

fab make_html

The documentation will be built in docs/_build/html. If you don’t have fabric, use the following commands.

cd docs
make html

The primary docs are built at Read the Docs.

Style

This project follows PEP 8 and most of the style suggestions that pyflakes recommends. Run Flake8 regularly.

Contributing

Contributing to the Python API bindings follows the fork-pull-request model on github. The project uses Github’s issues and pull requests to manage source control, bug fixes and new feature development regarding the API bindings and the CLI.