Add pre-commit

This is helpful to automate code style checks at runtime. We include
documentation on how to run this as well as a general overview of style
guidelines in OSC.

Change-Id: I2dc5a0f760ce53269ae25677560b2611cc6bfd91
Signed-off-by: Stephen Finucane <>
This commit is contained in:
Stephen Finucane 2021-03-11 16:20:15 +00:00
parent 8e3dde03f9
commit 87e6828678
2 changed files with 69 additions and 13 deletions

.pre-commit-config.yaml Normal file
View File

@ -0,0 +1,29 @@
# force all unspecified python hooks to run python3
python: python3
- repo:
rev: v3.4.0
- id: trailing-whitespace
- id: mixed-line-ending
args: ['--fix', 'lf']
exclude: '.*\.(svg)$'
- id: check-byte-order-marker
- id: check-executables-have-shebangs
- id: check-merge-conflict
- id: debug-statements
- id: check-yaml
files: .*\.(yaml|yml)$
- repo: local
- id: flake8
name: flake8
- hacking>=2.0.0
- flake8-import-order>=0.13
language: python
entry: flake8
files: '^.*\.py$'
exclude: '^(doc|releasenotes|tools)/.*$'

View File

@ -6,16 +6,18 @@ 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:
Tox prerequisites and installation
Install the prerequisites for Tox:
@ -23,23 +25,22 @@ Install the prerequisites for Tox:
.. code-block:: bash
$ apt-get install gcc gettext python-dev libxml2-dev libxslt1-dev \
$ apt-get install gcc gettext python3-dev libxml2-dev libxslt1-dev \
You may need to use pip install for some packages.
* On RHEL or CentOS including Fedora:
.. code-block:: bash
$ yum install gcc python-devel libxml2-devel libxslt-devel
$ yum install gcc python3-devel libxml2-devel libxslt-devel
* On openSUSE or SUSE linux Enterprise:
.. code-block:: bash
$ zypper install gcc python-devel libxml2-devel libxslt-devel
$ zypper install gcc python3-devel libxml2-devel libxslt-devel
Install python-tox:
@ -59,7 +60,7 @@ To run the full suite of tests maintained within OpenStackClient.
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
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:
@ -70,7 +71,7 @@ environments with the ``-e`` option, separated by spaces:
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
@ -90,7 +91,7 @@ To run a specific functional test:
$ tox -e functional -- --regex functional.tests.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
@ -109,8 +110,32 @@ For reference, the `debug`_ ``tox`` environment implements the instructions
.. _`debug`:
Building the Documentation
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``:
.. code-block:: bash
$ 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:
.. code-block:: bash
$ pip install --user pre-commit
$ pre-commit install --allow-missing-config
.. __:
.. __:
.. __:
The documentation is generated with Sphinx using the ``tox`` command. To
create HTML docs, run the commands:
@ -121,6 +146,7 @@ create HTML docs, run the commands:
The resultant HTML will be in the ``doc/build/html`` directory.
Release Notes
@ -156,6 +182,7 @@ To run the commands and see results:
At last, look at the generated release notes files in ``releasenotes/build/html`` in your browser.
Testing new code
@ -174,7 +201,7 @@ or
$ pip install -e .
Standardize Import Format
More information about Import Format, see `Import Order Guide
@ -193,7 +220,7 @@ The import order shows below:
{{begin your code}}
.. code-block:: python