Pylint: anomalous backslash in string warning in docstrings (W1401)

Created on 18 Jun 2014 · 31Comments · Source: PyCQA/pylint

Originally reported by: BitBucket: hayne, GitHub: @hayne?

Pylint (1.2.1) gives a W1401 warning ("anomalous backslash in string ...") about the following code
where the backslash is inside a docstring.
I don't think this is desirable (hence I'm listing this as a bug).
There should be at least an option to disable the warning in this specific context.

------------------------------------------------------------

def getCurrentResultFolderPath():
"""
Return the full path to the current result folder.
Example of use:
currResultFolderPath = getCurrentResultFolderPath()
# gives something like: "C:\MyStuff\TestA\Results\Run_2013-11-08_2159_59"
"""
pass

------------------------------------------------------------

Bitbucket: https://bitbucket.org/logilab/pylint/issue/264

bug

Source

pylint-bot

👍3

Most helpful comment

_Original comment by_ BitBucket: hayne, GitHub: @hayne?:

That "solution" (making the docstring a raw string by prefacing it with 'r') does work in the sense of preventing PyLint from warning about the backslashes.
I knew about that possibility before.

But putting an 'r' in front of the docstring destroys the aesthetics - it would make every reader of the code pause and wonder - "why is that 'r' there" when skimming through the code.
As such it is a worse cure than the disease.

I'm hoping that others will agree that PyLint shouldn't be warning about things that happen in the "privacy" of a docstring - which of course means that PyLint needs to be able to recognize docstrings as special.

pylint-bot on 3 Jul 2014

👍10 ❤1

All 31 comments

_Original comment by_ BitBucket: rneu31, GitHub: @rneu31?:

Could you re-post your issue using the Code button so we can see the problem more clearly? The problem is hard to identify as is.

pylint-bot on 3 Jul 2014

_Original comment by_ BitBucket: hayne, GitHub: @hayne?:

Here's the code from above but using the Code button (didn't know about it before):

#!python

def getCurrentResultFolderPath():
    """
    Return the full path to the current result folder.
    Example of use:
    currResultFolderPath = getCurrentResultFolderPath()
    # gives something like: "C:\MyStuff\TestA\Results\Run_2013-11-08_2159_59"
    """
    pass

pylint-bot on 3 Jul 2014

_Original comment by_ BitBucket: rneu31, GitHub: @rneu31?:

An easy solution (have not tested it) would be to make the docstring a raw string by adding 'r' to the front.

#!python

def getCurrentResultFolderPath():
    r"""
    Return the full path to the current result folder.
    Example of use:
    currResultFolderPath = getCurrentResultFolderPath()
    # gives something like: "C:\MyStuff\TestA\Results\Run_2013-11-08_2159_59"
    """
    pass

pylint-bot on 3 Jul 2014

👍6

_Original comment by_ BitBucket: hayne, GitHub: @hayne?:

That "solution" (making the docstring a raw string by prefacing it with 'r') does work in the sense of preventing PyLint from warning about the backslashes.
I knew about that possibility before.

pylint-bot on 3 Jul 2014

👍10 ❤1

_Original comment by_ Mike Frysinger (BitBucket: vapier, GitHub: @vapier?):

i don't think docstrings should be granted blanket immunity. if you do introspection on the code, then it might render incorrectly:

>>> s = """You need to use \n\r sequences when you want ..."""
>>> def func(): pass
>>> func.__doc__ = s
>>> help(func)
Help on function func in module __main__:

func()
    You need to use 
    sequences when you want ...

surely in that case you want to use a r prefix else any tooling will show it wrong.

the posted case though doesn't use backslashes with any known sequences (\P will get you a \P), so perhaps split the warning into known & unknown escape sequences ? that way people can filter out the issue when the case is truly harmless while still getting warnings when there might be a surprising difference.

possible bucketing:

anomalous-backslash-in-string (any use of \ in a string)
anomalous-backslash-in-docstring (any use of \ in a docstring)
anomalous-known-backslash-in-string (use of \ in a string with a sequence python is known to interpret e.g. \nr\t)
anomalous-known-backslash-in-docstring (use of \ in a docstring with a sequence python is known to interpret e.g. \nr\t)

pylint-bot on 21 Nov 2014

👍6

_Original comment by_ BitBucket: hayne, GitHub: @hayne?:

But in Mike Frysinger's example above, the warning would (and should) occur on the line that assigns to the variable 's'.
There is no need to also have a warning on any other line.
I.e. we are in agreement that there should be a warning for that line.

But I don't see any problem in not warning about docstrings as defined as:

strings that are not assigned to anything
that occur immediately after a 'def' statement
I.e. the example of Mike Frysinger is not relevant to my suggestion that such docstrings be excluded from this warning.

pylint-bot on 21 Nov 2014

_Original comment by_ Mike Frysinger (BitBucket: vapier, GitHub: @vapier?):

mmm, that's incorrect. sorry if my example is confusing if you aren't familiar with Python internals. having docstrings immediately after a definition _is_ assigned to something -- __doc__. thus my example using the python interp is equivalent to this:

$ cat test.py
def func():
  """You need to use \n\r sequences when you want ..."""

$ python
>>> import test
>>> test.func.__doc__
'You need to use \n\r sequences when you want ...'
>>> help(test.func)
<output is wrong>

it's basically a shorthand for this:

def func():
  __doc__ = """..."""

so docstrings should not be immune to this check.

pylint-bot on 21 Nov 2014

_Original comment by_ BitBucket: hayne, GitHub: @hayne?:

What I was suggesting is that PyLint should pick out docstrings via a special parsing of the source code - not rely on the internal representation of that code.
I don't know if PyLint makes use of the internal representation or not.
But this is precisely what I meant by PyLint needing to recognize docstrings as special.

But in your example, I would venture to suggest that what is wrong is the behaviour of the 'help' function.
I submit that the 'help' function should display the docstring precisely the way it appears in the source code.
In any case, my opinion is that PyLint should not warn (ever) about docstrings. It is a much lesser evil to have incorrect interactive help for those few cases where the docstring has special escape sequences than to have spurious warnings for docstrings. I guess my position could be summed up by saying that I consider PyLint's job to warn about problems that affect execution of the code, not interactive introspection of the code.

pylint-bot on 21 Nov 2014

_Original comment by_ Mike Frysinger (BitBucket: vapier, GitHub: @vapier?):

i disagree that python's behavior is wrong, but in all likelihood, it's never going to change. fundamentally, a docstring is merely an assignment of a string to doc (usually, but not required to be, triple quotes). which means it should behave that way.

some code utilizes doc normally during runtime too. it's not uncommon for setting up argparse module like so:

  parser = argparse.ArgumentParser(description=__doc__)

in which case, the execution of the code is wrong and pylint should be warning.

pylint-bot on 21 Nov 2014

_Original comment by_ Steven Myint (BitBucket: myint, GitHub: @myint?):

@hayne, the warning is correct. If you print your docstring, you will get garbage out if your Windows-style path happens to contain a \n in it. I suggest you use an r prefix as @vapier suggested or use normal slashes rather than Windows-specific backslashes.

pylint-bot on 8 Feb 2015

👍3