Add a new option for finding unused global variables.

Closes #919

12 files changed, 50 insertions, 2 deletions

diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 4ee0633c9..1dca11d01 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -101,7 +101,7 @@ Order doesn't matter (not that much, at least ;)
 
 * Mike Frysinger: contributor.
 
-* Łukasz Rogalski: invalid-length-returned
+* Łukasz Rogalski: contributor.
 
 * Moisés López (Vauxoo): Support for deprecated-modules in modules not installed,
   Refactory wrong-import-order to integrate it with `isort` library
diff --git a/ChangeLog b/ChangeLog
index c9a91ab55..1f6b22139 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -217,6 +217,9 @@ Release date: tba
 
     * Added refactoring message 'no-else-return'.
 
+    * Improve unused-variable checker to warn about unused variables in module scope.
+
+      Closes #919
 
 
 What's new in Pylint 1.6.3?
diff --git a/doc/whatsnew/2.0.rst b/doc/whatsnew/2.0.rst
index 6b3cee835..affd2064b 100644
--- a/doc/whatsnew/2.0.rst
+++ b/doc/whatsnew/2.0.rst
@@ -676,6 +676,11 @@ Bug fixes
      def _(x):
          return -x
 
+* `unused-variable` checker has new functionality of warning about unused
+  variables in global module namespace. Since globals in module namespace
+  may be a part of exposed API, this check is disabled by default. For
+  enabling it, set `allow-global-unused-variables` to false.
+
 Removed Changes
 ===============
 
diff --git a/pylint/checkers/variables.py b/pylint/checkers/variables.py
index e3257de6e..13ed86fc9 100644
--- a/pylint/checkers/variables.py
+++ b/pylint/checkers/variables.py
@@ -358,7 +358,13 @@ class VariablesChecker(BaseChecker):
                  'help' : 'Argument names that match this expression will be '
                           'ignored. Default to name with leading underscore'}
                ),
+               ('allow-global-unused-variables',
+                {'default': True,
+                 'type': 'yn', 'metavar': '<y_or_n>',
+                 'help': 'Tells whether unused global variables should be treated as a violation.'}
+               ),
               )
+
     def __init__(self, linter=None):
         BaseChecker.__init__(self, linter)
         self._to_consume = None  # list of tuples: (to_consume:dict, consumed:dict, scope_type:str)
@@ -374,6 +380,9 @@ class VariablesChecker(BaseChecker):
     def _ignored_modules(self):
         return get_global_option(self, 'ignored-modules', default=[])
 
+    @decorators.cachedproperty
+    def _allow_global_unused_variables(self):
+        return get_global_option(self, 'allow-global-unused-variables', default=True)
 
     @utils.check_messages('redefined-outer-name')
     def visit_for(self, node):
@@ -413,7 +422,7 @@ class VariablesChecker(BaseChecker):
 
     @utils.check_messages('unused-import', 'unused-wildcard-import',
                           'redefined-builtin', 'undefined-all-variable',
-                          'invalid-all-object')
+                          'invalid-all-object', 'unused-variable')
     def leave_module(self, node):
         """leave module: check globals
         """
@@ -422,6 +431,10 @@ class VariablesChecker(BaseChecker):
         # attempt to check for __all__ if defined
         if '__all__' in node.locals:
             self._check_all(node, not_consumed)
+
+        # check for unused globals
+        self._check_globals(not_consumed)
+
         # don't check unused imports in __init__ files
         if not self.config.init_import and node.package:
             return
@@ -476,6 +489,13 @@ class VariablesChecker(BaseChecker):
                             # when the file will be checked
                             pass
 
+    def _check_globals(self, not_consumed):
+        if self._allow_global_unused_variables:
+            return
+        for name, nodes in six.iteritems(not_consumed):
+            for node in nodes:
+                self.add_message('unused-variable', args=(name,), node=node)
+
     def _check_imports(self, not_consumed):
         local_names = _fix_dot_imports(not_consumed)
         checked = set()
diff --git a/pylint/test/functional/unused_global_variable1.py b/pylint/test/functional/unused_global_variable1.py
new file mode 100644
index 000000000..e630c3337
--- /dev/null
+++ b/pylint/test/functional/unused_global_variable1.py
@@ -0,0 +1,2 @@
+# pylint: disable=missing-docstring
+VAR = 'pylint'
diff --git a/pylint/test/functional/unused_global_variable2.py b/pylint/test/functional/unused_global_variable2.py
new file mode 100644
index 000000000..62224096e
--- /dev/null
+++ b/pylint/test/functional/unused_global_variable2.py
@@ -0,0 +1,2 @@
+# pylint: disable=missing-docstring
+VAR = 'pylint'  # [unused-variable]
diff --git a/pylint/test/functional/unused_global_variable2.rc b/pylint/test/functional/unused_global_variable2.rc
new file mode 100644
index 000000000..5dcd4a84c
--- /dev/null
+++ b/pylint/test/functional/unused_global_variable2.rc
@@ -0,0 +1,2 @@
+[variables]
+allow-global-unused-variables=no
diff --git a/pylint/test/functional/unused_global_variable2.txt b/pylint/test/functional/unused_global_variable2.txt
new file mode 100644
index 000000000..27019cbd7
--- /dev/null
+++ b/pylint/test/functional/unused_global_variable2.txt
@@ -0,0 +1 @@
+unused-variable:2::Unused variable 'VAR':HIGH
diff --git a/pylint/test/functional/unused_global_variable3.py b/pylint/test/functional/unused_global_variable3.py
new file mode 100644
index 000000000..896789eda
--- /dev/null
+++ b/pylint/test/functional/unused_global_variable3.py
@@ -0,0 +1,6 @@
+# pylint: disable=missing-docstring
+VAR = 'pylint'
+
+
+def func(argument):
+    return VAR + argument
diff --git a/pylint/test/functional/unused_global_variable4.py b/pylint/test/functional/unused_global_variable4.py
new file mode 100644
index 000000000..aef49d68c
--- /dev/null
+++ b/pylint/test/functional/unused_global_variable4.py
@@ -0,0 +1,3 @@
+# pylint: disable=missing-docstring
+VAR = 'pylint'  # [unused-variable]
+VAR = 'pylint2'  # [unused-variable]
diff --git a/pylint/test/functional/unused_global_variable4.rc b/pylint/test/functional/unused_global_variable4.rc
new file mode 100644
index 000000000..5dcd4a84c
--- /dev/null
+++ b/pylint/test/functional/unused_global_variable4.rc
@@ -0,0 +1,2 @@
+[variables]
+allow-global-unused-variables=no
diff --git a/pylint/test/functional/unused_global_variable4.txt b/pylint/test/functional/unused_global_variable4.txt
new file mode 100644
index 000000000..61e3b286c
--- /dev/null
+++ b/pylint/test/functional/unused_global_variable4.txt
@@ -0,0 +1,2 @@
+unused-variable:2::Unused variable 'VAR':HIGH
+unused-variable:3::Unused variable 'VAR':HIGH