enhancement: add lint rules plugin support

Add plugin support using setuptools (pkg_resources) plugin mechanism to
yamllint to allow users to add their own custom lint rule plugins.

Also add some plugin support test cases, an example plugin as a
reference, and doc section about how to develop rules' plugins.

Signed-off-by: Satoru SATOH <satoru.satoh@gmail.com>
Co-authored-by: Adrien Vergé

tests/yamllint_plugin_example/rules/__init__.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2020 Satoru SATOH
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""yamllint plugin entry point
+"""
+from __future__ import absolute_import
+
+from . import (
+    forbid_comments, no_forty_two, random_failure
+)
+
+
+RULES = (
+    (forbid_comments.ID, forbid_comments),
+    (no_forty_two.ID, no_forty_two),
+    (random_failure.ID, random_failure)
+)

tests/yamllint_plugin_example/rules/forbid_comments.py

@@ -0,0 +1,61 @@
+#
+# Copyright (C) 2020 Satoru SATOH
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+"""
+Use this rule to forbid comments.
+
+.. rubric:: Options
+
+* Use ``forbid`` to control comments. Set to ``true`` to forbid comments
+  completely.
+
+.. rubric:: Examples
+
+#. With ``forbid-comments: {forbid: true}``
+
+   the following code snippet would **PASS**:
+   ::
+
+    foo: 1
+
+   the following code snippet would **FAIL**:
+   ::
+
+    # baz
+    foo: 1
+
+.. rubric:: Default values (when enabled)
+
+.. code-block:: yaml
+
+rules:
+  forbid-comments:
+    forbid: False
+
+"""
+from yamllint.linter import LintProblem
+
+
+ID = 'forbid-comments'
+TYPE = 'comment'
+CONF = {'forbid': bool}
+DEFAULT = {'forbid': False}
+
+
+def check(conf, comment):
+    if conf['forbid']:
+        yield LintProblem(comment.line_no, comment.column_no,
+                          'forbidden comment')

tests/yamllint_plugin_example/rules/no_forty_two.py

@@ -0,0 +1,49 @@
+#
+# Copyright (C) 2020 Satoru SATOH
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+"""
+Use this rule to forbid 42 in any values.
+
+.. rubric:: Examples
+
+#. With ``no-forty-two: {}``
+
+   the following code snippet would **PASS**:
+   ::
+
+    the_answer: 1
+
+   the following code snippet would **FAIL**:
+   ::
+
+    the_answer: 42
+"""
+import yaml
+
+from yamllint.linter import LintProblem
+
+
+ID = 'no-forty-two'
+TYPE = 'token'
+
+
+def check(conf, token, prev, next, nextnext, context):
+    if (isinstance(token, yaml.ScalarToken) and
+            isinstance(prev, yaml.ValueToken) and
+            token.value == '42'):
+        yield LintProblem(token.start_mark.line + 1,
+                          token.start_mark.column + 1,
+                          '42 is forbidden value')

tests/yamllint_plugin_example/rules/random_failure.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2020 Adrien Vergé
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import random
+
+from yamllint.linter import LintProblem
+
+ID = 'random-failure'
+TYPE = 'token'
+
+
+def check(conf, token, prev, next, nextnext, context):
+    if random.random() > 0.9:
+        yield LintProblem(token.start_mark.line + 1,
+                          token.start_mark.column + 1,
+                          'random failure')