Clean up comments, docstrings, and fix broken testprojects integratio…

…n tests

src/python/pants/backend/python/tasks/pex_build_util.py

@@ -48,7 +48,7 @@ def has_python_requirements(tgt):
 
 
 def targets_are_invalid(targets, invalid_targets):
-  """Return whether a set of invalidated versioned targets containts a target from `targets`.
+  """Return whether `invalid_targets` contains at least one target from `targets`.
 
   :param invalid_targets: A list of targets that have been invalidated by a cache manager.
   :param targets: A list of targets to check for membership in `invalid_targets`.

src/python/pants/backend/python/tasks/resolve_requirements_task_base.py

@@ -65,7 +65,10 @@ def resolve_requirements(self, req_libs, python_dist_targets=()):
   def _build_requirements_pex(self, interpreter, path, req_libs):
     builder = PEXBuilder(path=path, interpreter=interpreter, copy=True)
     dump_requirements(builder, interpreter, req_libs, self.context.log)
-    # Dump built python distributions, if any, into requirements pex.
+    # Dump built python distributions, if any, into the requirements pex.
+    # NB: If a python_dist depends on a requirement X and another target in play requires
+    # an incompatible version of X, this will cause the pex resolver to throw an incompatiblity
+    # error and Pants will abort the build.
     built_dists = self.context.products.get_data(PythonCreateDistributions.PYTHON_DISTS)
     if built_dists:
       for dist in built_dists:

src/python/pants/backend/python/tasks2/python_create_distributions.py

@@ -71,15 +71,15 @@ def _create_dist(self, dist_tgt, dist_target_dir):
                                   dist_tgt.address.spec_path,
                                   src_relative_to_target_base)
       shutil.copyfile(abs_src_path, src_rel_to_results_dir)
-    # Build the whl from pex API using tempdir and get its location.
+    # Build a whl using SetupPyRunner and return its absolute path.
     install_dir = os.path.join(dist_target_dir, 'dist')
     safe_mkdir(install_dir)
     setup_runner = SetupPyRunner(dist_target_dir, 'bdist_wheel', interpreter=interpreter, install_dir=install_dir)
     setup_runner.run()
     return self._get_whl_from_dir(install_dir)
 
   def _get_whl_from_dir(self, install_dir):
-    """Return the location of the whl on disk."""
+    """Return the absolute path of the whl in a setup.py install directory."""
     dists = os.listdir(install_dir)
     if len(dists) == 0:
       raise TaskError('No distributions were produced by python_create_distribution task.')

tests/python/pants_test/backend/python/tasks2/test_python_create_distributions.py

@@ -44,7 +44,7 @@ def setUp(self):
 
   def test_python_create_distributions(self):
     context = self.context(target_roots=[self.python_dist_tgt], for_task_types=[PythonCreateDistributions])
-    python_create_distributions_task = self.create_task(context,)
+    python_create_distributions_task = self.create_task(context)
     python_create_distributions_task.execute()
     built_dists = context.products.get_data(PythonCreateDistributions.PYTHON_DISTS)
     self.assertGreater(len(built_dists), 0)

tests/python/pants_test/backend/python/tasks2/test_python_distribution_integration.py

@@ -13,8 +13,8 @@
 
 
 class PythonDistributionIntegrationTest(PantsRunIntegrationTest):
-  # The paths a project and an associated test containing a simple C extension to 
-  # be packaged into a whl by setup.py and consumed by the pants goals tested below. 
+  # The paths to both a project containing a simple C extension (to be packaged into a
+  # whl by setup.py) and an associated test to be consumed by the pants goals tested below.
   superhello_project = 'examples/src/python/example/python_distribution/hello/superhello'
   superhello_tests = 'examples/tests/python/example/python_distribution/hello/test_superhello'
 

tests/python/pants_test/projects/test_testprojects_integration.py

@@ -65,6 +65,7 @@ def targets(self):
       'testprojects/tests/java/org/pantsbuild/testproject/depman:old-tests',
       'testprojects/tests/java/org/pantsbuild/testproject/htmlreport:htmlreport',
       'testprojects/tests/java/org/pantsbuild/testproject/parallel.*',
+      'examples/src/python/example/python_distribution/hello/superhello:main_with_conflicting_dep'
     ]
 
     # May not succeed without java8 installed