2018-06-23 11:50:42 +02:00
|
|
|
|
===============
|
|
|
|
|
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
|
2019-12-29 00:05:43 +01:00
|
|
|
|
reference to the development setup. If you face any issues during this
|
2018-06-23 11:50:42 +02:00
|
|
|
|
process, please `open an issue`_ about it on the issue tracker.
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2019-11-18 02:46:19 +01:00
|
|
|
|
Get the source code
|
2020-02-11 14:00:03 +01:00
|
|
|
|
===================
|
2019-11-18 02:46:19 +01:00
|
|
|
|
|
|
|
|
|
To work on pip, you first need to get the source code of pip. The source code is
|
|
|
|
|
available on `GitHub`_.
|
|
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
|
|
$ git clone https://github.com/pypa/pip
|
|
|
|
|
$ cd pip
|
|
|
|
|
|
|
|
|
|
|
2018-09-26 07:59:19 +02:00
|
|
|
|
Development Environment
|
2020-02-11 14:00:03 +01:00
|
|
|
|
=======================
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
2019-09-24 13:00:44 +02:00
|
|
|
|
pip is a command line application written in Python. For developing pip,
|
|
|
|
|
you should `install Python`_ on your computer.
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
2019-09-24 18:43:14 +02:00
|
|
|
|
For developing pip, you need to install :pypi:`tox`. Often, you can run
|
2019-09-24 13:00:44 +02:00
|
|
|
|
``python -m pip install tox`` to install and use it.
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2018-10-27 17:44:57 +02:00
|
|
|
|
Running pip From Source Tree
|
2020-02-11 14:00:03 +01:00
|
|
|
|
============================
|
2018-10-27 17:44:57 +02:00
|
|
|
|
|
2020-04-26 20:05:54 +02:00
|
|
|
|
To run the pip executable from your source tree during development, install pip
|
|
|
|
|
locally using editable installation (inside a virtualenv).
|
|
|
|
|
You can then invoke your local source tree pip normally.
|
2018-10-27 17:44:57 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Unix/macOS
|
2020-08-04 05:30:43 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2020-08-04 05:30:43 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
virtualenv venv # You can also use "python -m venv venv" from python3.3+
|
|
|
|
|
source venv/bin/activate
|
|
|
|
|
python -m pip install -e .
|
|
|
|
|
python -m pip --version
|
2020-08-04 05:30:43 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. tab:: Windows
|
2020-08-04 05:30:43 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
.. code-block:: shell
|
2018-10-27 17:44:57 +02:00
|
|
|
|
|
2020-10-18 19:12:24 +02:00
|
|
|
|
virtualenv venv # You can also use "py -m venv venv" from python3.3+
|
|
|
|
|
venv\Scripts\activate
|
|
|
|
|
py -m pip install -e .
|
|
|
|
|
py -m pip --version
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2018-06-23 11:50:42 +02:00
|
|
|
|
Running Tests
|
2020-02-11 14:00:03 +01:00
|
|
|
|
=============
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
2019-09-24 13:01:58 +02:00
|
|
|
|
pip's tests are written using the :pypi:`pytest` test framework, :pypi:`mock`
|
|
|
|
|
and :pypi:`pretend`. :pypi:`tox` is used to automate the setup and execution of
|
|
|
|
|
pip's tests.
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
2020-03-21 09:58:34 +01:00
|
|
|
|
It is preferable to run the tests in parallel for better experience during development,
|
|
|
|
|
since the tests can take a long time to finish when run sequentially.
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
2020-03-24 15:02:37 +01:00
|
|
|
|
To run tests:
|
2020-03-29 12:26:04 +02:00
|
|
|
|
|
2018-06-23 11:50:42 +02:00
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
2020-03-21 08:19:15 +01:00
|
|
|
|
$ tox -e py36 -- -n auto
|
2019-10-15 22:50:38 +02:00
|
|
|
|
|
2020-03-24 15:02:37 +01:00
|
|
|
|
To run tests without parallelization, run:
|
2020-03-29 12:26:04 +02:00
|
|
|
|
|
2019-10-15 22:50:38 +02:00
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
2020-03-21 08:19:15 +01:00
|
|
|
|
$ tox -e py36
|
2019-10-15 22:50:38 +02:00
|
|
|
|
|
2018-06-23 11:50:42 +02:00
|
|
|
|
The example above runs tests against Python 3.6. You can also use other
|
|
|
|
|
versions like ``py27`` and ``pypy3``.
|
|
|
|
|
|
2019-09-24 13:01:09 +02:00
|
|
|
|
``tox`` has been configured to forward any additional arguments it is given to
|
2018-07-02 16:08:36 +02:00
|
|
|
|
``pytest``. This enables the use of pytest's `rich CLI`_. As an example, you
|
|
|
|
|
can select tests using the various ways that pytest provides:
|
|
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
|
|
$ # 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:
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
|
|
$ tox -e py36 -- -k "not svn"
|
|
|
|
|
$ tox -e py36 -- -k "not (svn or git)"
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2018-06-23 11:50:42 +02:00
|
|
|
|
Running Linters
|
2020-02-11 14:00:03 +01:00
|
|
|
|
===============
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
2019-09-24 13:31:45 +02:00
|
|
|
|
pip uses :pypi:`pre-commit` for managing linting of the codebase.
|
|
|
|
|
``pre-commit`` performs various checks on all files in pip and uses tools that
|
|
|
|
|
help follow a consistent code style within the codebase.
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
|
|
|
|
To use linters locally, run:
|
|
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
2019-08-27 10:25:20 +02:00
|
|
|
|
$ tox -e lint
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
2019-12-06 10:40:33 +01:00
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
Avoid using ``# noqa`` comments to suppress linter warnings - wherever
|
|
|
|
|
possible, warnings should be fixed instead. ``# noqa`` comments are
|
|
|
|
|
reserved for rare cases where the recommended style causes severe
|
|
|
|
|
readability problems.
|
|
|
|
|
|
2020-02-11 14:05:28 +01:00
|
|
|
|
|
2018-06-23 11:50:42 +02:00
|
|
|
|
Building Documentation
|
2020-02-11 14:00:03 +01:00
|
|
|
|
======================
|
2018-06-23 11:50:42 +02:00
|
|
|
|
|
|
|
|
|
pip's documentation is built using :pypi:`Sphinx`. The documentation is written
|
|
|
|
|
in reStructuredText.
|
|
|
|
|
|
|
|
|
|
To build it locally, run:
|
|
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
|
|
$ tox -e docs
|
|
|
|
|
|
|
|
|
|
The built documentation can be found in the ``docs/build`` folder.
|
|
|
|
|
|
2020-07-27 18:26:41 +02:00
|
|
|
|
For each Pull Request made the documentation is deployed following this link:
|
|
|
|
|
|
|
|
|
|
.. code-block:: none
|
|
|
|
|
|
|
|
|
|
https://pip--<PR-NUMBER>.org.readthedocs.build/en/<PR-NUMBER>
|
|
|
|
|
|
|
|
|
|
|
2020-03-21 11:52:32 +01:00
|
|
|
|
What Next?
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
The following pages may be helpful for new contributors on where to look next
|
|
|
|
|
in order to start contributing.
|
|
|
|
|
|
|
|
|
|
* Some `good first issues`_ on GitHub for new contributors
|
|
|
|
|
* A deep dive into `pip's architecture`_
|
|
|
|
|
* A guide on `triaging issues`_ for issue tracker
|
2020-07-15 20:45:01 +02:00
|
|
|
|
* Getting started with Git
|
|
|
|
|
|
|
|
|
|
- `Hello World for Git`_
|
|
|
|
|
- `Understanding the GitHub flow`_
|
|
|
|
|
- `Start using Git on the command line`_
|
2020-03-21 11:52:32 +01:00
|
|
|
|
|
|
|
|
|
|
2018-07-02 16:08:36 +02:00
|
|
|
|
.. _`open an issue`: https://github.com/pypa/pip/issues/new?title=Trouble+with+pip+development+environment
|
2019-09-24 13:00:44 +02:00
|
|
|
|
.. _`install Python`: https://realpython.com/installing-python/
|
2018-06-23 11:50:42 +02:00
|
|
|
|
.. _`PEP 484 type-comments`: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
|
2018-07-02 16:08:36 +02:00
|
|
|
|
.. _`rich CLI`: https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests
|
2019-11-18 02:46:19 +01:00
|
|
|
|
.. _`GitHub`: https://github.com/pypa/pip
|
2020-03-21 11:52:32 +01:00
|
|
|
|
.. _`good first issues`: https://github.com/pypa/pip/labels/good%20first%20issue
|
|
|
|
|
.. _`pip's architecture`: https://pip.pypa.io/en/latest/development/architecture/
|
|
|
|
|
.. _`triaging issues`: https://pip.pypa.io/en/latest/development/issue-triage/
|
2020-07-15 22:31:59 +02:00
|
|
|
|
.. _`Hello World for Git`: https://guides.github.com/activities/hello-world/
|
2020-07-15 20:45:01 +02:00
|
|
|
|
.. _`Understanding the GitHub flow`: https://guides.github.com/introduction/flow/
|
|
|
|
|
.. _`Start using Git on the command line`: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html
|