Getting Started¶
We’re pleased that you are interested in working on pip.
This document is meant to get you setup to work on pip and to act as a guide and reference to the the development setup. If you face any issues during this process, please open an issue about it on the issue tracker.
Development tools¶
pip uses tox for testing against multiple different Python environments and ensuring reproducible environments for linting and building documentation.
For developing pip, you need to install tox
on your system. Often, you can
just do python -m pip install tox
to install and use it.
Running Tests¶
pip uses the pytest test framework, mock and pretend for testing. These are automatically installed by tox for running the tests.
To run tests locally, run:
$ tox -e py36
The example above runs tests against Python 3.6. You can also use other
versions like py27
and pypy3
.
tox
has been configured to any additional arguments it is given to
pytest
. This enables the use of pytest’s rich CLI. As an example, you
can select tests using the various ways that pytest provides:
$ # Using file name
$ tox -e py36 -- tests/functional/test_install.py
$ # Using markers
$ tox -e py36 -- -m unit
$ # Using keywords
$ tox -e py36 -- -k "install and not wheel"
Running pip’s test suite requires supported version control tools (subversion, bazaar, git, and mercurial) to be installed. If you are missing one of the VCS tools, you can tell pip to skip those tests:
$ tox -e py36 -- -k "not svn"
$ tox -e py36 -- -k "not (svn or git)"
Running Linters¶
pip uses flake8 and isort for linting the codebase. These ensure that the codebase is in compliance with PEP 8 and the imports are consistently ordered and styled.
To use linters locally, run:
$ tox -e lint-py2
$ tox -e lint-py3
The above commands run the linters on Python 2 followed by Python 3.
Note
Do not silence errors from flake8 with # noqa
comments or otherwise.
The only exception to this is silencing unused-import errors for imports
related to static type checking as currently flake8 does not understand
PEP 484 type-comments.
Running mypy¶
pip uses mypy to run static type analysis, which helps catch certain kinds of bugs. The codebase uses PEP 484 type-comments due to compatibility requirements with Python 2.7.
To run the mypy
type checker, run:
$ tox -e mypy