From 7e13c142a97387e449d87de4fce667562891d736 Mon Sep 17 00:00:00 2001 From: Mateo Rodriguez Date: Sun, 24 Apr 2016 15:36:20 -0400 Subject: [PATCH] Add public API markers to targets and base tasks used by plugins. Foursquare has plugins that use these internally and they appear to be things that would be of use to task or plugin developers. The targets are self explanatory - we consume products of these targets in plugin tasks. The fingerprint strategy is a core tool in a task developer's toolbox. If the task involves jvm code, then it may need do jar operations, this exposes as public some of those tasks. Ivy is marked public because it provides a custom exception that doesn't inherit from anything descriptive - Ivy.Error is just an Exception. We publish jars with a custom pom-publish task - where every jar has a common version. Catching Ivy failures required catching Ivy.Error. Testing Done: I ran the unit tests locally to catch style or syntax errors. Running the CI to be sure since we are getting so close to release. https://travis-ci.org/pantsbuild/pants/builds/125091874 Bugs closed: 3253 Reviewed at https://rbcommons.com/s/twitter/r/3746/ --- .../pants/backend/codegen/targets/python_thrift_library.py | 5 ++++- src/python/pants/backend/jvm/targets/jarable.py | 5 ++++- src/python/pants/backend/jvm/targets/jvm_app.py | 2 ++ src/python/pants/backend/jvm/tasks/jar_task.py | 7 ++++++- src/python/pants/backend/jvm/tasks/jvm_binary_task.py | 4 ++++ src/python/pants/backend/jvm/tasks/scala_repl.py | 5 +++++ src/python/pants/backend/python/targets/python_binary.py | 2 ++ .../backend/python/targets/python_requirement_library.py | 5 ++++- src/python/pants/backend/python/targets/python_target.py | 5 ++++- src/python/pants/ivy/ivy.py | 2 ++ 10 files changed, 37 insertions(+), 5 deletions(-) diff --git a/src/python/pants/backend/codegen/targets/python_thrift_library.py b/src/python/pants/backend/codegen/targets/python_thrift_library.py index 19d9ce73d5a..00318dc0e03 100644 --- a/src/python/pants/backend/codegen/targets/python_thrift_library.py +++ b/src/python/pants/backend/codegen/targets/python_thrift_library.py @@ -9,7 +9,10 @@ class PythonThriftLibrary(PythonTarget): - """A Python library generated from Thrift IDL files.""" + """A Python library generated from Thrift IDL files. + + :API: public + """ def __init__(self, **kwargs): """ diff --git a/src/python/pants/backend/jvm/targets/jarable.py b/src/python/pants/backend/jvm/targets/jarable.py index dfdfbea4479..0d0cda9f3ba 100644 --- a/src/python/pants/backend/jvm/targets/jarable.py +++ b/src/python/pants/backend/jvm/targets/jarable.py @@ -12,7 +12,10 @@ class Jarable(AbstractClass): - """A mixin that identifies a target as one that can provide a jar.""" + """A mixin that identifies a target as one that can provide a jar. + + :API: public + """ @abstractproperty def identifier(self): diff --git a/src/python/pants/backend/jvm/targets/jvm_app.py b/src/python/pants/backend/jvm/targets/jvm_app.py index f31b4b64f20..4f75ef39841 100644 --- a/src/python/pants/backend/jvm/targets/jvm_app.py +++ b/src/python/pants/backend/jvm/targets/jvm_app.py @@ -185,6 +185,8 @@ class JvmApp(Target): self-contained artifact suitable for deployment on some other machine. The artifact contains the executable jar, its dependencies, and extra files like config files, startup scripts, etc. + + :API: public """ def __init__(self, name=None, payload=None, binary=None, bundles=None, basename=None, **kwargs): diff --git a/src/python/pants/backend/jvm/tasks/jar_task.py b/src/python/pants/backend/jvm/tasks/jar_task.py index 6090034d95a..b0683129538 100644 --- a/src/python/pants/backend/jvm/tasks/jar_task.py +++ b/src/python/pants/backend/jvm/tasks/jar_task.py @@ -33,6 +33,8 @@ class Jar(object): Upon construction the jar is conceptually opened for writes. The write methods are called to add to the jar's contents and then changes are finalized with a call to close. If close is not called the staged changes will be lost. + + :API: public """ class Error(Exception): @@ -326,7 +328,10 @@ def open_jar(self, path, overwrite=False, compressed=True, jar_rules=None): class JarBuilderTask(JarTask): class JarBuilder(AbstractClass): - """A utility to aid in adding the classes and resources associated with targets to a jar.""" + """A utility to aid in adding the classes and resources associated with targets to a jar. + + :API: public + """ @staticmethod def _add_agent_manifest(agent, manifest): diff --git a/src/python/pants/backend/jvm/tasks/jvm_binary_task.py b/src/python/pants/backend/jvm/tasks/jvm_binary_task.py index 78fe0542434..eb89bfc777c 100644 --- a/src/python/pants/backend/jvm/tasks/jvm_binary_task.py +++ b/src/python/pants/backend/jvm/tasks/jvm_binary_task.py @@ -22,6 +22,10 @@ class JvmBinaryTask(JarBuilderTask): + """Encapsulates operations to build or update JvmBinary jars. + + :API: public + """ @staticmethod def is_binary(target): diff --git a/src/python/pants/backend/jvm/tasks/scala_repl.py b/src/python/pants/backend/jvm/tasks/scala_repl.py index 25942455214..5a1198f4c62 100644 --- a/src/python/pants/backend/jvm/tasks/scala_repl.py +++ b/src/python/pants/backend/jvm/tasks/scala_repl.py @@ -16,6 +16,11 @@ class ScalaRepl(JvmToolTaskMixin, ReplTaskMixin, JvmTask): + """Operations to create or launch Scala repls. + + :API: public + """ + _RUNNER_MAIN = 'org.pantsbuild.tools.runner.PantsRunner' @classmethod diff --git a/src/python/pants/backend/python/targets/python_binary.py b/src/python/pants/backend/python/targets/python_binary.py index 15a249d6236..5cfdaf1e092 100644 --- a/src/python/pants/backend/python/targets/python_binary.py +++ b/src/python/pants/backend/python/targets/python_binary.py @@ -22,6 +22,8 @@ class PythonBinary(PythonTarget): scripts that contain a complete Python environment capable of running the target. For more information about pex files see http://pantsbuild.github.io/python-readme.html#how-pex-files-work. + + :API: public """ # TODO(wickman) Consider splitting pex options out into a separate PexInfo builder that can be diff --git a/src/python/pants/backend/python/targets/python_requirement_library.py b/src/python/pants/backend/python/targets/python_requirement_library.py index 094998a18b0..461de2cb30f 100644 --- a/src/python/pants/backend/python/targets/python_requirement_library.py +++ b/src/python/pants/backend/python/targets/python_requirement_library.py @@ -13,7 +13,10 @@ class PythonRequirementLibrary(Target): - """A set of pip requirements.""" + """A set of pip requirements. + + :API: public + """ def __init__(self, payload=None, requirements=None, **kwargs): """ diff --git a/src/python/pants/backend/python/targets/python_target.py b/src/python/pants/backend/python/targets/python_target.py index e1257ac7494..6e9d1221329 100644 --- a/src/python/pants/backend/python/targets/python_target.py +++ b/src/python/pants/backend/python/targets/python_target.py @@ -19,7 +19,10 @@ class PythonTarget(Target): - """Base class for all Python targets.""" + """Base class for all Python targets. + + :API: public + """ def __init__(self, address=None, diff --git a/src/python/pants/ivy/ivy.py b/src/python/pants/ivy/ivy.py index 62d6f82737d..5adf2ead710 100644 --- a/src/python/pants/ivy/ivy.py +++ b/src/python/pants/ivy/ivy.py @@ -21,6 +21,8 @@ class Ivy(object): """Encapsulates the ivy cli taking care of the basic invocation letting you just worry about the args to pass to the cli itself. + + :API: public """ class Error(Exception):