Python 3rdparty Pattern

In general, we use the 3rdparty idiom to organize dependencies on code from outside the source tree. This document describes how to make this work for Python code.

Your Python code can pull in code written elsewhere. Pants fetches code via a library that uses pip-style specifications (name and version-range).

To keep all of your code depending on the same versions of third-party Python artifacts, you might use the idiom of keeping them in a directory tree under 3rdparty/python. If your organization has many such dependencies, you might arrange them in several directories: this can ease later "git detective work" when finding out who changed a version. (Pants itself doesn't have many Python dependencies; thus, we haven't split its 3rdparty tree into many directories.)

pip-style requirements.txt:

To define some third-party dependencies, use a python_requirements in your BUILD file and make a pip requirements.txt file in the same directory.

E.g, your 3rdparty/python/BUILD file might look like:

python_requirements()

...with 3rdparty/python/requirements.txt like:

ansicolors==1.0.2
beautifulsoup4>=4.3.2,<4.4
coverage>=3.7,<3.8
docutils>=0.12,<0.13
Markdown==2.1.1
mock==1.0.1

python_requirements defines a named target for each line in the requirements.txt line. For example, a line like ansicolors==1.0.2 in requirements.txt defines a target named ansicolors that pulls in ansicolors version 1.0.2.

python_requirement_library and python_requirement:

A BUILD file can also define requirements without a requirements.txt file. Set up a python_requirement_library with one or more python_requirements like:

python_requirement_library(
  name='beautifulsoup',
  requirements=[
    python_requirement(name='beautifulsoup',
                       requirement='BeautifulSoup==3.2.0'),
  ])

In your code's BUILD file, introduce a dependency on the 3rdparty target:

python_library(name='greet',
  dependencies=[
    '3rdparty/python:ansicolors',
  ],
  sources=globs('*.py'),
)

Then in your Python code, you can import from that package: