Added example of deprecation checker

doc/how_tos/custom_checkers.rst

@@ -4,8 +4,10 @@ How to Write a Checker
 ======================
 You can find some simple examples in the distribution
 (`custom.py <https://github.com/PyCQA/pylint/blob/master/examples/custom.py>`_
+,
+`custom_raw.py <https://github.com/PyCQA/pylint/blob/master/examples/custom_raw.py>`_
 and
-`custom_raw.py <https://github.com/PyCQA/pylint/blob/master/examples/custom_raw.py>`_).
+`deprecation_checker.py <https://github.com/PyCQA/pylint/blob/master/examples/deprecation_checker.py>`_).
 
 .. TODO Create custom_token.py
 

examples/deprecation_checker.py

@@ -0,0 +1,88 @@
+"""
+Example checker detecting deprecated functions/methods. Following example searches for usages of
+deprecated function `deprecated_function` and deprecated method MyClass.deprecated_method from module mymodule:
+
+.. code-block:: console
+    $ cat mymodule.py
+    def deprecated_function():
+        pass
+
+    class MyClass:
+        def deprecated_method(self):
+            pass
+
+    $ cat mymain.py
+    from mymodule import deprecated_function, MyClass
+
+    deprecated_function()
+    MyClass().deprecated_method()
+
+    $ pylint --load-plugins=deprecation_checker mymain.py
+    ************* Module mymain
+    mymain.py:3:0: W1505: Using deprecated method deprecated_function() (deprecated-method)
+    mymain.py:4:0: W1505: Using deprecated method deprecated_method() (deprecated-method)
+
+    ------------------------------------------------------------------
+    Your code has been rated at 3.33/10 (previous run: 3.33/10, +0.00)
+"""
+
+import astroid
+
+from pylint.checkers import BaseChecker, DeprecatedMixin, utils
+from pylint.interfaces import IAstroidChecker
+
+
+class DeprecationChecker(BaseChecker, DeprecatedMixin):
+    """Class implementing deprecation checker."""
+    __implements__ = (IAstroidChecker,)
+    # The name defines a custom section of the config for this checker.
+    name = "deprecated"
+    # This class variable declares the messages (ie the warnings and errors)
+    # that the checker can emit.
+    msgs = {
+        # Each message has a code, a message that the user will see,
+        # a unique symbol that identifies the message,
+        # and a detailed help message
+        # that will be included in the documentation.
+        "W1505": (
+            "Using deprecated method %s()",
+            "deprecated-method",
+            "The method is marked as deprecated and will be removed in "
+            "the future.",
+        ),
+    }
+
+    @utils.check_messages(
+        "deprecated-method",
+    )
+    def visit_call(self, node):
+        """Called when a :class:`.astroid.node_classes.Call` node is visited.
+
+        See :mod:`astroid` for the description of available nodes.
+
+        :param node: The node to check.
+        :type node: astroid.node_classes.Call
+        """
+        try:
+            for inferred in node.func.infer():
+                # Calling entry point for deprecation check logic.
+                self.check_deprecated_method(node, inferred)
+        except astroid.InferenceError:
+            return
+
+    def deprecated_methods(self):
+        """Callback method called by DeprecatedMixin for every method/function found in the code.
+
+        Returns:
+            collections.abc.Container of deprecated function/method names.
+        """
+        return {'mymodule.deprecated_function', 'mymodule.MyClass.deprecated_method'}
+
+
+def register(linter):
+    """This required method auto registers the checker.
+
+    :param linter: The linter to register the checker to.
+    :type linter: pylint.lint.PyLinter
+    """
+    linter.register_checker(DeprecationChecker(linter))