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.

Author: Eric-Arellano

README.md

@@ -25,11 +25,11 @@ Pants commands are called _goals_. You can get a list of goals with
 
 # Targets
 
-Targets are sets of source files with some attached metadata. Targets are provided in `BUILD` files.
-Targets have types, such as `python_library`, `resources`, `python_binary`. Examples of metadata include
-timeouts for tests, Python interpreter constraints, entry points for binaries, and so on.
+Targets are a way of setting metadata for some part of your code, such as timeouts for tests and 
+entry points for binaries. Targets have types like `python_binary`, `resources`, and 
+`pex_binary`. They are defined in `BUILD` files.
 
-Pants goals can be invoked on targets or directly on source files/directories (which is often more intuitive and convenient).
+Pants goals can be invoked on targets or directly on source files (which is often more intuitive and convenient).
 In the latter case, Pants locates target metadata for the source files as needed.
 
 ## File specifications
@@ -176,7 +176,7 @@ We can also remove the `setup_py_commands` field from `helloworld/util/BUILD` to
 (This example only works on Linux because it has an sdist. See https://www.pantsbuild.org/docs/awslambda-python.)
 
 ```
-./pants package helloworld:helloworld-awslambda
+./pants package helloworld/awslambda.py
 ```
 
 ## Count lines of code

helloworld/BUILD

@@ -1,33 +1,36 @@
 # Copyright 2020 Pants project contributors.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
-# `name` defaults to the name of this directory, i.e., `helloworld`.
-pex_binary(
-    sources=["main.py"],
-    entry_point="helloworld.main",
-)
-
+# This target sets the metadata for all the Python non-test files in this directory.
+#
+# * `name` defaults to the name of this directory, i.e., `helloworld`.
+# * `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
+# * Pants cannot infer dependencies on resources targets, so we explicitly add it.
 python_library(
-  name="awslambda_lib",
-  sources=["awslambda.py"],
+    dependencies=[":config_file"],
 )
 
-# Note: This has sdist dependencies, so it must be built on Linux.
-python_awslambda(
-    name="helloworld-awslambda",
-    dependencies=[":awslambda_lib"],
-    handler="helloworld.awslambda:handler",
-    runtime="python3.7",
+# This target teaches Pants about our JSON file, which allows for other targets to depend on it.
+resources(
+    name="config_file",
+    sources=["config.json"],
 )
 
-# Pants cannot infer dependencies on resources targets and Protobuf, so we explicitly add them.
-python_library(
-    name="config",
-    sources=["config.py"],
-    dependencies=[":config_file", "helloworld/util/proto"],
+# This target allows us to bundle our app into a PEX binary file via
+#  `./pants package`. We can also run it with `./pants run`. See
+#  https://www.pantsbuild.org/docs/python-package-goal and
+#  https://www.pantsbuild.org/docs/python-run-goal.
+pex_binary(
+    name="pex_binary",
+    entry_point="main.py",
 )
 
-resources(
-    name="config_file",
-    sources=["config.json"],
+# This target allows us to create an AWS Lambda binary via `./pants package`.
+#  See https://www.pantsbuild.org/docs/awslambda-python.
+#
+# Note: This has sdist dependencies, so it must be built on Linux.
+python_awslambda(
+    name="awslambda",
+    handler="awslambda.py:handler",
+    runtime="python3.7",
 )

helloworld/greet/BUILD

@@ -1,11 +1,15 @@
 # Copyright 2020 Pants project contributors.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
-# `name` defaults to the name of this directory, i.e., `greet`.
-# `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
-# `dependencies` are inferred.
+# This target sets the metadata for all the Python non-test files in this directory.
+#
+# * `name` defaults to the name of this directory, i.e., `greet`.
+# * `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
+# * `dependencies` are inferred.
 python_library()
 
-# `sources` defaults to ['*_test.py', 'test_*.py', 'conftest.py'].
-# `dependencies` are inferred.
-python_tests(name = 'tests')
+# This target sets the metadata for all the Python test files in this directory.
+#
+# * `sources` defaults to ['*_test.py', 'test_*.py', 'conftest.py'].
+# * `dependencies` are inferred.
+python_tests(name='tests')

helloworld/util/BUILD

@@ -1,27 +1,34 @@
 # Copyright 2020 Pants project contributors.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
-# `name` defaults to the name of this directory, i.e., `util`.
-# `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
-# `dependencies` is set because only Pants 2.2+ can infer dependencies on Protobuf.
-python_library(
-    dependencies=["helloworld/util/proto"],
-)
+# This target sets the metadata for all the Python non-test files in this directory.
+#
+# * `name` defaults to the name of this directory, i.e., `util`.
+# * `sources` defaults to ['*.py', '!*_test.py', '!test_*.py', '!conftest.py'].
+# * `dependencies` are inferred.
+python_library()
 
-# `sources` defaults to ['*_test.py', 'test_*.py', 'conftest.py'].
-# Pants cannot infer dependencies on `resources` targets, so we explicitly add the dep.
+# This target sets the metadata for all the Python test files in this directory.
+#
+# * `sources` defaults to ['*_test.py', 'test_*.py', 'conftest.py'].
+# * Pants cannot infer dependencies on `resources` targets, so we explicitly add the dep.
 python_tests(
     name='tests',
     dependencies=[":test_data"],
 )
 
+# This target teaches Pants about our JSON file, which allows for other targets to depend on it.
 resources(
     name='test_data',
     sources=['*_test_data.json'],
 )
 
-# See https://www.pantsbuild.org/docs/python-distributions.
-# Because this target has no source code, Pants cannot infer dependencies.
+# This target allows us to build a `.whl` bdist and a `.tar.gz` sdist by auto-generating
+#  `setup.py`. See https://www.pantsbuild.org/docs/python-distributions.
+#
+# Because this target has no source code, Pants cannot infer dependencies. We depend on `:util`,
+#  which means we'll include all the non-test Python files in this directory, and any of
+#  their dependencies.
 python_distribution(
     name="dist",
     dependencies=[":util"],

helloworld/util/proto/BUILD

@@ -1,8 +1,11 @@
 # Copyright 2020 Pants project contributors.
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
-# `name` defaults to the name of this directory, i.e., `proto`.
-# `sources` defaults to ["*.proto"].
+# This target sets the metadata for all the `.proto` files in this directory.
+#  See https://www.pantsbuild.org/docs/protobuf.
+#
+# * `name` defaults to the name of this directory, i.e., `proto`.
+# * `sources` defaults to ["*.proto"].
 protobuf_library()
 
 # Note that we have an empty `__init__.py` file in this folder. Pants will generate

pants.toml

@@ -2,7 +2,7 @@
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
 [GLOBAL]
-pants_version = "2.1.1"
+pants_version = "2.2.0"
 pantsd = true  # Enable the Pants daemon for better performance.
 
 backend_packages.add = [