GNOME.org
 

[Notes] [Git][BuildStream/buildstream][phil/848-plugin-deprecation-warnings] plugin.py: Add API to allow plugins to raise deprecation warnings

Title: GitLab

Phil Dawson pushed to branch phil/848-plugin-deprecation-warnings at BuildStream / buildstream

Commits:

7 changed files:

Changes:

  • buildstream/_versions.py
    ... ... @@ -23,7 +23,7 @@
    23 23 
     # This version is bumped whenever enhancements are made
    24 24 
     # to the `project.conf` format or the core element format.
    25 25 
     #
    26 
    -BST_FORMAT_VERSION = 21
    26 
    +BST_FORMAT_VERSION = 22
    27 27
    28 28
    29 29 
     # The base BuildStream artifact version

  • buildstream/plugin.py
    ... ... @@ -164,6 +164,25 @@ class Plugin():
    164 164 
            core format version :ref:`core format version <project_format_version>`.
    165 165 
         """
    166 166
    167 
    +    BST_PLUGIN_DEPRECATED = False
    168 
    +    """True if this element plugin has been deprecated.
    169 
    +
    170 
    +    If this is set to true, BuildStream will emmit a deprecation
    171 
    +    warning when this plugin is loaded. This deprecation warning may
    172 
    +    be suppressed on a plugin by plugin basis by setting
    173 
    +    ``suppress-deprecation-warnings: true`` in the relevent section of
    174 
    +    the project's :ref:`plugin configuration overrides <project_overrides>`.
    175 
    +
    176 
    +    """
    177 
    +
    178 
    +    BST_PLUGIN_DEPRECATION_MESSAGE = ""
    179 
    +    """ The message printed when this element shows a deprecation warning.
    180 
    +
    181 
    +    This should be set if BST_PLUGIN_DEPRECATED is True and should direct the user
    182 
    +    to the deprecated plug-in's replacement.
    183 
    +
    184 
    +    """
    185 
    +
    167 186 
         def __init__(self, name, context, project, provenance, type_tag):
    168 187
    169 188 
             self.name = name
    ... ... @@ -188,6 +207,12 @@ class Plugin():
    188 207 
             self.__kind = modulename.split('.')[-1]
    189 208 
             self.debug("Created: {}".format(self))
    190 209
    210 
    +        # If this plugin has been deprecated, emit a warning.
    211 
    +        if self.BST_PLUGIN_DEPRECATED and not self.__deprecation_warning_silenced():
    212 
    +            detail = "Using deprecated plugin {}: {}".format(self.__kind,
    213 
    +                                                             self.BST_PLUGIN_DEPRECATION_MESSAGE)
    214 
    +            self.__message(MessageType.WARN, detail)
    215 
    +
    191 216 
         def __del__(self):
    192 217 
             # Dont send anything through the Message() pipeline at destruction time,
    193 218 
             # any subsequent lookup of plugin by unique id would raise KeyError.
    ... ... @@ -767,6 +792,20 @@ class Plugin():
    767 792 
             else:
    768 793 
                 return self.name
    769 794
    795 
    +    def __deprecation_warning_silenced(self):
    796 
    +        if not self.BST_PLUGIN_DEPRECATED:
    797 
    +            return False
    798 
    +        else:
    799 
    +            silenced_warnings = set()
    800 
    +            project = self.__project
    801 
    +            plugin_overrides = {**project.element_overrides, **project.source_overrides}
    802 
    +
    803 
    +            for key, value in self.node_items(plugin_overrides):
    804 
    +                if value.get('suppress-deprecation-warnings', False):
    805 
    +                    silenced_warnings.add(key)
    806 
    +
    807 
    +            return self.get_kind() in silenced_warnings
    808 
    +
    770 809
    771 810 
     # Hold on to a lookup table by counter of all instantiated plugins.
    772 811 
     # We use this to send the id back from child processes so we can lookup

  • tests/plugins/deprecationwarnings/deprecationwarnings.py
    1 
    +import pytest
    2 
    +import tempfile
    3 
    +import os
    4 
    +from buildstream.plugintestutils import cli
    5 
    +from buildstream import _yaml
    6 
    +import buildstream.plugins.elements.manual
    7 
    +
    8 
    +
    9 
    +DATA_DIR = os.path.join(
    10 
    +    os.path.dirname(os.path.realpath(__file__)),
    11 
    +    "project"
    12 
    +)
    13 
    +
    14 
    +_DEPRECATION_MESSAGE = "Here is some detail."
    15 
    +_DEPRECATION_WARNING = "Using deprecated plugin deprecated_plugin: {}".format(_DEPRECATION_MESSAGE)
    16 
    +
    17 
    +
    18 
    +@pytest.mark.datafiles(DATA_DIR)
    19 
    +def test_deprecation_warning_present(cli, datafiles):
    20 
    +    project = os.path.join(datafiles.dirname, datafiles.basename)
    21 
    +    result = cli.run(project=project, args=['show', 'deprecated.bst'])
    22 
    +    result.assert_success()
    23 
    +    assert _DEPRECATION_WARNING in result.stderr
    24 
    +
    25 
    +
    26 
    +@pytest.mark.datafiles(DATA_DIR)
    27 
    +def test_suppress_deprecation_warning(cli, datafiles):
    28 
    +    project = os.path.join(datafiles.dirname, datafiles.basename)
    29 
    +    result = cli.run(project=project, args=['show', 'manual.bst'])
    30 
    +
    31 
    +    element_overrides = "elements:\n" \
    32 
    +                        "  deprecated_plugin:\n" \
    33 
    +                        "    suppress-deprecation-warnings : True\n"
    34 
    +
    35 
    +    project_conf = os.path.join(project, 'project.conf')
    36 
    +    with open(project_conf, 'a') as f:
    37 
    +        f.write(element_overrides)
    38 
    +
    39 
    +    result = cli.run(project=project, args=['show', 'deprecated.bst'])
    40 
    +    result.assert_success()
    41 
    +    assert _DEPRECATION_WARNING not in result.stderr

  • tests/plugins/deprecationwarnings/project/elements/deprecated.bst
    1 
    +kind: deprecated_plugin
    \ No newline at end of file

  • tests/plugins/deprecationwarnings/project/plugins/elements/deprecated_plugin.py
    1 
    +from buildstream import BuildElement, SandboxFlags
    2 
    +
    3 
    +
    4 
    +class DeprecatedPlugin(BuildElement):
    5 
    +    BST_PLUGIN_DEPRECATED = True
    6 
    +    BST_PLUGIN_DEPRECATION_MESSAGE = "Here is some detail."
    7 
    +
    8 
    +
    9 
    +# Plugin entry point
    10 
    +def setup():
    11 
    +    return DeprecatedPlugin

  • tests/plugins/deprecationwarnings/project/plugins/elements/deprecated_plugin.yaml
    1 
    +# Deprecated-plugin build element does not provide any default
    2 
    +# build commands
    3 
    +config:
    4 
    +
    5 
    +  # Commands for configuring the software
    6 
    +  #
    7 
    +  configure-commands: []
    8 
    +
    9 
    +  # Commands for building the software
    10 
    +  #
    11 
    +  build-commands: []
    12 
    +
    13 
    +  # Commands for installing the software into a
    14 
    +  # destination folder
    15 
    +  #
    16 
    +  install-commands: []
    17 
    +
    18 
    +  # Commands for stripping installed binaries
    19 
    +  #
    20 
    +  strip-commands:
    21 
    +  - |
    22 
    +    %{strip-binaries}
    \ No newline at end of file

  • tests/plugins/deprecationwarnings/project/project.conf
    1 
    +# Unique project name
    2 
    +name: deprecation-warnings
    3 
    +
    4 
    +# Required BuildStream format version
    5 
    +format-version: 20
    6 
    +
    7 
    +# Subdirectory where elements are stored
    8 
    +element-path: elements
    9 
    +
    10 
    +plugins:
    11 
    +
    12 
    +- origin: local
    13 
    +  path: plugins/elements
    14 
    +  elements:
    15 
    +    deprecated_plugin: 0

    • —
    View it on GitLab.
    You're receiving this email because of your account on gitlab.com. If you'd like to receive fewer emails, you can adjust your notification settings.

    [Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]