Many programming languages organize code into packages. Usually, the packages form a hierarchy that mirrors the filesystem structure in which the source files live.
For example, this set of Python source files:
src/python/foo/foo.py src/python/foo/bar/bar.py src/python/baz/qux/quux/quux.py
Is organized into the following packages:
foo foo.bar baz.qux.quux
To understand your code's package structure, Pants needs to know about source_roots: the points in the filesystem that represent package roots. In the example above,
src/python/ is a source root. So when some code says
from import foo.bar import bar, Pants can know that this corresponds to the code in
There are two ways to configure source roots:
- Using patterns
- Using marker files
You can provide a set of patterns that match your source roots:
[source] root_patterns = [ 'src/python', 'test/python', ]
A directory whose suffix matches a root will be considered a source root for any code under it. So the example above will consider all of these to be source roots, if they exist:
If you want to anchor the source root so that it only matches at the build root, precede it with
[source] root_patterns = [ '/src/python', ]
This will match
<repo root>/src/python but not
Marking the repository root as a source root
It's common in smaller Python codebases for the root of the repository to be a source root. To configure that, use this in your
[source] root_patterns = ['/']
Default source roots
The default value of the
root_patternsconfig key is
["/", "src", "src/python", "src/py"].
These capture a range of common cases, including a source root at the root of the repository. If your source roots match these patterns, you don't need to explicitly configure them.
You can also denote your source roots using specially-named marker files. To do so, first pick a name (or multiple names) to use:
[source] marker_filenames = ['SOURCE_ROOT']
Then place a file of that name in each of the source roots. The contents of those files don't matter. They can be empty.
Note that you can mix
marker_filenames. Pants will use both.
setup.pyas a marker file
In some Python repos there may already be a
setup.pyfile at each source root. You can simply treat those as marker files:
[source] marker_filenames = ['setup.py']
You can use
./pants roots to view the current set of source roots.
Updated about 3 years ago