Exempt `__doc__` from triggering a `redefined-builtin`

`__doc__` can be used to specify a docstring for a module without
passing it as a first-statement string.

3 files changed, 7 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index 26145f81a..4e915a9d4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -12,6 +12,11 @@ Release date: -
 
       Close #1794
 
+     * Exempt `__doc__` from triggering a `redefined-builtin`
+
+      `__doc__` can be used to specify a docstring for a module without
+      passing it as a first-statement string.
+
     * Fix false positive ``inconsistent-return-statements`` message by
       avoiding useless exception inference if the exception is not handled.
 
diff --git a/pylint/checkers/variables.py b/pylint/checkers/variables.py
index d65da49ce..9d856c3b3 100644
--- a/pylint/checkers/variables.py
+++ b/pylint/checkers/variables.py
@@ -501,7 +501,7 @@ class VariablesChecker(BaseChecker):
         self._to_consume = [NamesConsumer(node, 'module')]
         for name, stmts in six.iteritems(node.locals):
             if utils.is_builtin(name) and not utils.is_inside_except(stmts[0]):
-                if self._should_ignore_redefined_builtin(stmts[0]):
+                if self._should_ignore_redefined_builtin(stmts[0]) or name == '__doc__':
                     continue
                 self.add_message('redefined-builtin', args=name, node=stmts[0])
 
diff --git a/pylint/test/functional/redefined_builtin.py b/pylint/test/functional/redefined_builtin.py
index d6bca4b72..c840f8dd5 100644
--- a/pylint/test/functional/redefined_builtin.py
+++ b/pylint/test/functional/redefined_builtin.py
@@ -8,3 +8,4 @@ def function():
 
 # pylint:disable=invalid-name
 map = {}  # [redefined-builtin]
+__doc__ = 'reset the doc'