# pip plugin

## pip - stage python packages using pip

Host depndencies:

> - `pip` python module

This plugin will download source distributions for specified packages using `pip` but will not install them. It is expected that the elements using this source will install the downloaded packages.

Downloaded tarballs will be stored in a directory called “.bst_pip_downloads”.

Usage:

    # Specify the pip source kind
    kind: pip

    # Optionally specify index url, defaults to PyPi
    # This url is used to discover new versions of packages and download them
    # Projects intending to mirror their sources to a permanent location should
    # use an aliased url, and declare the alias in the project configuration
    url: https://mypypi.example.com/simple

    # Optionally specify the path to requirements files
    # Note that either 'requirements-files' or 'packages' must be defined
    requirements-files:
    - requirements.txt

    # Optionally specify a list of additional packages
    # Note that either 'requirements-files' or 'packages' must be defined
    packages:
    - flake8

    # Specify the ref. It is a list of strings of format
    # "<package-name>==<version>", separated by "\n".
    # Usually this will be contents of a requirements.txt file where all
    # package versions have been frozen.
    ref: "flake8==3.5.0\nmccabe==0.6.1\npkg-resources==0.0.0\npycodestyle==2.3.1\npyflakes==1.6.0"

See built-in functionality doumentation for details on common configuration options for sources.

### Reporting SourceInfo

The pip source reports the python package index (PyPI) instance as the url.

Further, the pip source reports the SourceInfoMedium.PYTHON_PACKAGE_INDEX medium and the SourceVersionType.INDEXED_VERSION version_type, for which it reports the tracked package version as the version and the version_guess.

Additionally, the pip source reports the package name through the `package-name` key of the extra_data.

The pip source will report one SourceInfo instance for each of the packages discovered in tracking.