python-openstackclient/doc/source/contributor/developing.rst

Developing with OpenStackClient

Communication

IRC Channel

The OpenStackClient team doesn't have regular meetings so if you have questions or anything you want to discuss, come to our channel: #openstack-sdks

Testing

Tox prerequisites and installation

Install the prerequisites for Tox:

• On Ubuntu or Debian:

  $ apt-get install gcc gettext python3-dev libxml2-dev libxslt1-dev \
    zlib1g-dev

  You may need to use pip install for some packages.

• On RHEL or CentOS including Fedora:

  $ yum install gcc python3-devel libxml2-devel libxslt-devel

• On openSUSE or SUSE linux Enterprise:

  $ zypper install gcc python3-devel libxml2-devel libxslt-devel

Install python-tox:

$ pip install tox

To run the full suite of tests maintained within OpenStackClient.

$ tox

Note

The first time you run tox, it will take additional time to build virtualenvs. You can later use the -r option with tox to rebuild your virtualenv in a similar manner.

To run tests for one or more specific test environments (for example, the most common configuration of the latest Python version and PEP-8), list the environments with the -e option, separated by spaces:

$ tox -e py38,pep8

See tox.ini for the full list of available test environments.

Running functional tests

OpenStackClient also maintains a set of functional tests that are optimally designed to be run against OpenStack's gate. Optionally, a developer may choose to run these tests against any OpenStack deployment, however depending on the services available, results vary.

To run the entire suite of functional tests:

$ tox -e functional

To run a specific functional test:

$ tox -e functional -- --regex tests.functional.compute.v2.test_server

Running with PDB

Using PDB breakpoints with tox and testr normally does not work since the tests fail with a BdbQuit exception rather than stopping at the breakpoint.

To run with PDB breakpoints during testing, use the debug tox environment. For example, passing a test name since you will normally only want to run the test that hits your breakpoint:

$ tox -e debug openstackclient.tests.identity.v3.test_group

For reference, the debug tox environment implements the instructions

Coding Style

OpenStackClient uses flake8 along with hacking, an OpenStack-specific superset of flake8 rules, to enforce coding style. This can be run manually using tox:

$ tox -e pep8

Alternatively, you can use the pre-commit framework to allow running of some linters on each commit. This must be enabled locally to function:

$ pip install --user pre-commit
$ pre-commit install --allow-missing-config

Documentation

The documentation is generated with Sphinx using the tox command. To create HTML docs, run the commands:

$ tox -e docs

The resultant HTML will be in the doc/build/html directory.

Release Notes

The release notes for a patch should be included in the patch. See the Project Team Guide for more information on using reno in OpenStack.

If any of the following applies to the patch, a release note is required:

• The deployer needs to take an action when upgrading
• The plugin interface changes
• A new feature is implemented
• A command or option is removed
• Current behavior is changed
• A security bug is fixed

Reno is used to generate release notes. Use the commands:

$ tox -e venv -- reno new <bug-,bp-,whatever>

Then edit the sample file that was created and push it with your change.

To run the commands and see results:

$ git commit  # Commit the change because reno scans git log.

$ tox -e releasenotes

At last, look at the generated release notes files in releasenotes/build/html in your browser.

Testing new code

If a developer wants to test new code (feature, command or option) that they have written, OpenStackClient may be installed from source by running the following commands in the base directory of the project:

$ python setup.py develop

or

$ pip install -e .

Standardize Import Format

More information about Import Format, see Import Order Guide.

The import order shows below:

{{stdlib imports in human alphabetical order}}
\n
{{third-party lib imports in human alphabetical order}}
\n
{{project imports in human alphabetical order}}
\n
\n
{{begin your code}}

Example

import copy
import fixtures
import os

from osc_lib.api import auth
from osc_lib import utils

from openstackclient import shell
from openstackclient.tests import utils
from unittest import mock