getting-started.rst

Getting started

Working on packaging requires the installation of a small number of development dependencies. To see what dependencies are required to run the tests manually, please look at the noxfile.py file.

Running tests

The packaging unit tests are found in the tests/ directory and are designed to be run using pytest. pytest will discover the tests automatically, so all you have to do is:

$ python -m pytest
...
29204 passed, 4 skipped, 1 xfailed in 83.98 seconds

This runs the tests with the default Python interpreter. This also allows you to run select tests instead of the entire test suite.

You can also verify that the tests pass on other supported Python interpreters. For this we use nox, which will automatically create a virtualenv for each supported Python version and run the tests. For example:

$ nox -s tests
...
nox > Ran multiple sessions:
nox > * tests-3.6: success
nox > * tests-3.7: success
nox > * tests-3.8: success
nox > * tests-3.9: success
nox > * tests-pypy3: skipped

You may not have all the required Python versions installed, in which case you will see one or more InterpreterNotFound errors.

Running linters

If you wish to run the linting rules, you may use pre-commit or run nox -s lint.

$ nox -s lint
...
nox > Session lint was successful.

Building documentation

packaging documentation is stored in the docs/ directory. It is written in reStructured Text and rendered using Sphinx.

Use nox to build the documentation. For example:

$ nox -s docs
...
nox > Session docs was successful.

The HTML documentation index can now be found at docs/_build/html/index.html.