Skip to content

Commit 5e76f94

Browse files
Eric-ArellanoEric-Arellano
authored
Upgrade to 2.2 and improve explanation of targets (pantsbuild#61)
Thanks to 2.2, we can now use the simplified design for `pex_binary` and `python_awslambda`. They no longer have `sources` fields, but have fields that act like it. We can also simplify thanks to dep inference for Protobuf. In the process, we do a better job explaining what each target is precisely doing. This is easier to do now that we have cleared up the responsibility of each target type.
1 parent 55a48bb commit 5e76f94

6 files changed

Lines changed: 63 additions & 46 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,11 @@ Pants commands are called _goals_. You can get a list of goals with
2525

2626
# Targets
2727

28-
Targets are sets of source files with some attached metadata. Targets are provided in `BUILD` files.
29-
Targets have types, such as `python_library`, `resources`, `python_binary`. Examples of metadata include
30-
timeouts for tests, Python interpreter constraints, entry points for binaries, and so on.
28+
Targets are a way of setting metadata for some part of your code, such as timeouts for tests and
29+
entry points for binaries. Targets have types like `python_binary`, `resources`, and
30+
`pex_binary`. They are defined in `BUILD` files.
3131

32-
Pants goals can be invoked on targets or directly on source files/directories (which is often more intuitive and convenient).
32+
Pants goals can be invoked on targets or directly on source files (which is often more intuitive and convenient).
3333
In the latter case, Pants locates target metadata for the source files as needed.
3434

3535
## File specifications
@@ -176,7 +176,7 @@ We can also remove the `setup_py_commands` field from `helloworld/util/BUILD` to
176176
(This example only works on Linux because it has an sdist. See https://www.pantsbuild.org/docs/awslambda-python.)
177177

178178
```
179-
./pants package helloworld:helloworld-awslambda
179+
./pants package helloworld/awslambda.py
180180
```
181181

182182
## Count lines of code

‎helloworld/BUILD‎

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,36 @@
11
# Copyright 2020 Pants project contributors.
22
# Licensed under the Apache License, Version 2.0 (see LICENSE).
33

4-
# `name` defaults to the name of this directory, i.e., `helloworld`.
5-
pex_binary(
6-
sources=["main.py"],
7-
entry_point="helloworld.main",
8-
)
9-
4+
# This target sets the metadata for all the Python non-test files in this directory.
5+
#
6+
# * `name` defaults to the name of this directory, i.e., `helloworld`.
7+
# * `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
8+
# * Pants cannot infer dependencies on resources targets, so we explicitly add it.
109
python_library(
11-
name="awslambda_lib",
12-
sources=["awslambda.py"],
10+
dependencies=[":config_file"],
1311
)
1412

15-
# Note: This has sdist dependencies, so it must be built on Linux.
16-
python_awslambda(
17-
name="helloworld-awslambda",
18-
dependencies=[":awslambda_lib"],
19-
handler="helloworld.awslambda:handler",
20-
runtime="python3.7",
13+
# This target teaches Pants about our JSON file, which allows for other targets to depend on it.
14+
resources(
15+
name="config_file",
16+
sources=["config.json"],
2117
)
2218

23-
# Pants cannot infer dependencies on resources targets and Protobuf, so we explicitly add them.
24-
python_library(
25-
name="config",
26-
sources=["config.py"],
27-
dependencies=[":config_file", "helloworld/util/proto"],
19+
# This target allows us to bundle our app into a PEX binary file via
20+
# `./pants package`. We can also run it with `./pants run`. See
21+
# https://www.pantsbuild.org/docs/python-package-goal and
22+
# https://www.pantsbuild.org/docs/python-run-goal.
23+
pex_binary(
24+
name="pex_binary",
25+
entry_point="main.py",
2826
)
2927

30-
resources(
31-
name="config_file",
32-
sources=["config.json"],
28+
# This target allows us to create an AWS Lambda binary via `./pants package`.
29+
# See https://www.pantsbuild.org/docs/awslambda-python.
30+
#
31+
# Note: This has sdist dependencies, so it must be built on Linux.
32+
python_awslambda(
33+
name="awslambda",
34+
handler="awslambda.py:handler",
35+
runtime="python3.7",
3336
)

‎helloworld/greet/BUILD‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
# Copyright 2020 Pants project contributors.
22
# Licensed under the Apache License, Version 2.0 (see LICENSE).
33

4-
# `name` defaults to the name of this directory, i.e., `greet`.
5-
# `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
6-
# `dependencies` are inferred.
4+
# This target sets the metadata for all the Python non-test files in this directory.
5+
#
6+
# * `name` defaults to the name of this directory, i.e., `greet`.
7+
# * `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
8+
# * `dependencies` are inferred.
79
python_library()
810

9-
# `sources` defaults to ['*_test.py', 'test_*.py', 'conftest.py'].
10-
# `dependencies` are inferred.
11-
python_tests(name = 'tests')
11+
# This target sets the metadata for all the Python test files in this directory.
12+
#
13+
# * `sources` defaults to ['*_test.py', 'test_*.py', 'conftest.py'].
14+
# * `dependencies` are inferred.
15+
python_tests(name='tests')

‎helloworld/util/BUILD‎

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,34 @@
11
# Copyright 2020 Pants project contributors.
22
# Licensed under the Apache License, Version 2.0 (see LICENSE).
33

4-
# `name` defaults to the name of this directory, i.e., `util`.
5-
# `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
6-
# `dependencies` is set because only Pants 2.2+ can infer dependencies on Protobuf.
7-
python_library(
8-
dependencies=["helloworld/util/proto"],
9-
)
4+
# This target sets the metadata for all the Python non-test files in this directory.
5+
#
6+
# * `name` defaults to the name of this directory, i.e., `util`.
7+
# * `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
8+
# * `dependencies` are inferred.
9+
python_library()
1010

11-
# `sources` defaults to ['*_test.py', 'test_*.py', 'conftest.py'].
12-
# Pants cannot infer dependencies on `resources` targets, so we explicitly add the dep.
11+
# This target sets the metadata for all the Python test files in this directory.
12+
#
13+
# * `sources` defaults to ['*_test.py', 'test_*.py', 'conftest.py'].
14+
# * Pants cannot infer dependencies on `resources` targets, so we explicitly add the dep.
1315
python_tests(
1416
name='tests',
1517
dependencies=[":test_data"],
1618
)
1719

20+
# This target teaches Pants about our JSON file, which allows for other targets to depend on it.
1821
resources(
1922
name='test_data',
2023
sources=['*_test_data.json'],
2124
)
2225

23-
# See https://www.pantsbuild.org/docs/python-distributions.
24-
# Because this target has no source code, Pants cannot infer dependencies.
26+
# This target allows us to build a `.whl` bdist and a `.tar.gz` sdist by auto-generating
27+
# `setup.py`. See https://www.pantsbuild.org/docs/python-distributions.
28+
#
29+
# Because this target has no source code, Pants cannot infer dependencies. We depend on `:util`,
30+
# which means we'll include all the non-test Python files in this directory, and any of
31+
# their dependencies.
2532
python_distribution(
2633
name="dist",
2734
dependencies=[":util"],

‎helloworld/util/proto/BUILD‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
# Copyright 2020 Pants project contributors.
22
# Licensed under the Apache License, Version 2.0 (see LICENSE).
33

4-
# `name` defaults to the name of this directory, i.e., `proto`.
5-
# `sources` defaults to ["*.proto"].
4+
# This target sets the metadata for all the `.proto` files in this directory.
5+
# See https://www.pantsbuild.org/docs/protobuf.
6+
#
7+
# * `name` defaults to the name of this directory, i.e., `proto`.
8+
# * `sources` defaults to ["*.proto"].
69
protobuf_library()
710

811
# Note that we have an empty `__init__.py` file in this folder. Pants will generate

‎pants.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
# Licensed under the Apache License, Version 2.0 (see LICENSE).
33

44
[GLOBAL]
5-
pants_version = "2.1.1"
5+
pants_version = "2.2.0"
66
pantsd = true # Enable the Pants daemon for better performance.
77

88
backend_packages.add = [

0 commit comments

Comments
 (0)