plugin.py: Add API to allow plugins to raise deprecation warningsphil/848-plugin-deprecation-warnings

A plugin's deprecation warning may be silenced by a project by adding
the plugin to the list 'supress-deprecation-warnings' in the project's
project.conf

2 files changed, 40 insertions, 1 deletions

diff --git a/buildstream/_versions.py b/buildstream/_versions.py
index a9eb86d69..5affc7870 100644
--- a/buildstream/_versions.py
+++ b/buildstream/_versions.py
@@ -23,7 +23,7 @@
 # This version is bumped whenever enhancements are made
 # to the `project.conf` format or the core element format.
 #
-BST_FORMAT_VERSION = 21
+BST_FORMAT_VERSION = 22
 
 
 # The base BuildStream artifact version
diff --git a/buildstream/plugin.py b/buildstream/plugin.py
index 2f51c8807..c21ae939e 100644
--- a/buildstream/plugin.py
+++ b/buildstream/plugin.py
@@ -164,6 +164,25 @@ class Plugin():
        core format version :ref:`core format version <project_format_version>`.
     """
 
+    BST_PLUGIN_DEPRECATED = False
+    """True if this element plugin has been deprecated.
+
+    If this is set to true, BuildStream will emmit a deprecation
+    warning when this plugin is loaded. This deprecation warning may
+    be suppressed on a plugin by plugin basis by setting
+    ``suppress-deprecation-warnings: true`` in the relevent section of
+    the project's :ref:`plugin configuration overrides <project_overrides>`.
+
+    """
+
+    BST_PLUGIN_DEPRECATION_MESSAGE = ""
+    """ The message printed when this element shows a deprecation warning.
+
+    This should be set if BST_PLUGIN_DEPRECATED is True and should direct the user
+    to the deprecated plug-in's replacement.
+
+    """
+
     def __init__(self, name, context, project, provenance, type_tag):
 
         self.name = name
@@ -188,6 +207,12 @@ class Plugin():
         self.__kind = modulename.split('.')[-1]
         self.debug("Created: {}".format(self))
 
+        # If this plugin has been deprecated, emit a warning.
+        if self.BST_PLUGIN_DEPRECATED and not self.__deprecation_warning_silenced():
+            detail = "Using deprecated plugin {}: {}".format(self.__kind,
+                                                             self.BST_PLUGIN_DEPRECATION_MESSAGE)
+            self.__message(MessageType.WARN, detail)
+
     def __del__(self):
         # Dont send anything through the Message() pipeline at destruction time,
         # any subsequent lookup of plugin by unique id would raise KeyError.
@@ -767,6 +792,20 @@ class Plugin():
         else:
             return self.name
 
+    def __deprecation_warning_silenced(self):
+        if not self.BST_PLUGIN_DEPRECATED:
+            return False
+        else:
+            silenced_warnings = set()
+            project = self.__project
+            plugin_overrides = {**project.element_overrides, **project.source_overrides}
+
+            for key, value in self.node_items(plugin_overrides):
+                if value.get('suppress-deprecation-warnings', False):
+                    silenced_warnings.add(key)
+
+            return self.get_kind() in silenced_warnings
+
 
 # Hold on to a lookup table by counter of all instantiated plugins.
 # We use this to send the id back from child processes so we can lookup