W9006: missing-raises-doc false positive

anuragagarwal561994 commented 7 years ago

Steps to reproduce

Make any method that throws an exception external or internally created.
Uses google style add Raises section.
If we simply mention the name of the exception, it works but if we mention the full path of the exception with :exc: like
```
Raises:
:exc:`exceptions.IOException`: it says missing raises doc for the given error.
```

Current behavior

Gives false positive.

Expected behavior

It should be able to realise internal, external linking.

pylint --version output

1.7.1

PCManticore commented 7 years ago

@AWhetter this seems right up your alley

AWhetter commented 7 years ago

This is raising an error because Google docstrings don't require you to specify the linking, it will link for you.
So saying exceptions.IOException: Something bad happened. will do what you're looking for in the documentation generated by Sphinx. The same applies to return types and argument types. Does this make sense?

anuragagarwal561994 commented 7 years ago

Not sure if it is the expected behaviour, your example worked but for that I had to raise the exact exception I am mentioning in the raises section.

Example:

from marshmallow import ValidationError

def some_method():
  """summary string.
  Raises:
      ~marshmallow.exceptions.ValidationError: reason, why being raised.
  """  
  raise ValidationError('message string')

does not work while the following works:

import marshmallow

def some_method():
  """summary string.
  Raises:
      ~marshmallow.exceptions.ValidationError: reason, why being raised.
  """  
  raise marshmallow.exceptions.ValidationError('message string')
  # or raise marshmallow.ValidationError('message string')

AWhetter commented 7 years ago

This definitely isn't expected behaviour! I'll take a look.

AWhetter commented 7 years ago

I can't reproduce with the latest pylint and astroid, both on master. Please could you confirm?

AWhetter commented 7 years ago

@anuragagarwal561994 We're you able to test this with the latest pylint?

anuragagarwal561994 commented 6 years ago

The problem still exists

pylint 1.8.4, 
astroid 1.6.3
Python 3.6.4 (default, Feb 20 2018, 15:37:40) 
[GCC 4.2.1 Compatible Apple LLVM 9.0.0 (clang-900.0.39.2)]

pip install marshmallow

script.py

"""Some Module"""

from marshmallow import ValidationError
# or from marshmallow.exceptions import ValidationError also doesn't work
# from marshmallow import exceptions and then use exceptions.ValidationError works

def some_method():
    """summary string.

    Raises:
        ~marshmallow.exceptions.ValidationError: reason, why being raised.
    """
    raise ValidationError('message string')

pylint --rcfile=.pylintrc --msg-template='{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}' script.py

.pylintrc

[MASTER]

# Specify a configuration file.
#rcfile=

# Python code to execute, usually for sys.path manipulation such as
# pygtk.require().
#init-hook=

# Add files or directories to the blacklist. They should be base names, not
# paths.
ignore=CVS

# Pickle collected data for later comparisons.
persistent=yes

# List of plugins (as comma separated values of python modules names) to load,
# usually to register additional checkers.
load-plugins=pylint.extensions.bad_builtin,pylint.extensions.check_elif,pylint.extensions.docparams,pylint.extensions.docstyle,pylint.extensions.mccabe

# Use multiple processes to speed up Pylint.
jobs=1

# Allow loading of arbitrary C extensions. Extensions are imported into the
# active Python interpreter and may run arbitrary code.
unsafe-load-any-extension=no

# A comma-separated list of package or module names from where C extensions may
# be loaded. Extensions are loading into the active Python interpreter and may
# run arbitrary code
extension-pkg-whitelist=

# Allow optimization of some AST trees. This will activate a peephole AST
# optimizer, which will apply various small optimizations. For instance, it can
# be used to obtain the result of joining multiple strings with the addition
# operator. Joining a lot of strings can lead to a maximum recursion error in
# Pylint and this flag can prevent that. It has one side effect, the resulting
# AST will be different than the one from reality.
optimize-ast=no

[MESSAGES CONTROL]

# Only show warnings with the listed confidence levels. Leave empty to show
# all. Valid levels: HIGH, INFERENCE, INFERENCE_FAILURE, UNDEFINED
confidence=

# Enable the message, report, category or checker with the given id(s). You can
# either give multiple identifier separated by comma (,) or put this option
# multiple time. See also the "--disable" option for examples.
#enable=

# Disable the message, report, category or checker with the given id(s). You
# can either give multiple identifiers separated by comma (,) or put this
# option multiple times (only on the command line, not in the configuration
# file where it should appear only once).You can also use "--disable=all" to
# disable everything first and then reenable specific checks. For example, if
# you want to run only the similarities checker, you can use "--disable=all
# --enable=similarities". If you want to run only the classes checker, but have
# no Warning level messages displayed, use"--disable=all --enable=classes
# --disable=W"
disable=duplicate-code,W0511

[REPORTS]

# Set the output format. Available formats are text, parseable, colorized, msvs
# (visual studio) and html. You can also give a reporter class, eg
# mypackage.mymodule.MyReporterClass.
output-format=text

# Put messages in a separate file for each module / package specified on the
# command line instead of printing them on stdout. Reports (if any) will be
# written in a file name "pylint_global.[txt|html]".
files-output=no

# Tells whether to display a full report or only the messages
reports=yes

# Python expression which should return a note less than 10 (10 is the highest
# note). You have access to the variables errors warning, statement which
# respectively contain the number of errors / warnings messages and the total
# number of statements analyzed. This is used by the global evaluation report
# (RP0004).
evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)

# Template used to display messages. This is a python new-style format string
# used to format the message information. See doc for all details
#msg-template=

[TYPECHECK]

# Tells whether missing members accessed in mixin class should be ignored. A
# mixin class is detected if its name ends with "mixin" (case insensitive).
ignore-mixin-members=yes

# List of module names for which member attributes should not be checked
# (useful for modules/projects where namespaces are manipulated during runtime
# and thus existing member attributes cannot be deduced by static analysis. It
# supports qualified module names, as well as Unix pattern matching.
ignored-modules=

# List of classes names for which member attributes should not be checked
# (useful for classes with attributes dynamically set). This supports can work
# with qualified names.
ignored-classes=SQLAlchemy

# List of members which are set dynamically and missed by pylint inference
# system, and so shouldn't trigger E1101 when accessed. Python regular
# expressions are accepted.
generated-members=etree.*

[FORMAT]

# Maximum number of characters on a single line.
max-line-length=80

# Regexp for a line that is allowed to be longer than the limit.
ignore-long-lines=^\s*(# )?<?https?://\S+>?$

# Allow the body of an if to be on the same line as the test if there is no
# else.
single-line-if-stmt=no

# List of optional constructs for which whitespace checking is disabled. `dict-
# separator` is used to allow tabulation in dicts, etc.: {1  : 1,\n222: 2}.
# `trailing-comma` allows a space between comma and closing bracket: (a, ).
# `empty-line` allows space-only lines.
no-space-check=trailing-comma,dict-separator

# Maximum number of lines in a module
max-module-lines=1000

# String used as indentation unit. This is usually "    " (4 spaces) or "\t" (1
# tab).
indent-string='    '

# Number of spaces of indent required inside a hanging  or continued line.
indent-after-paren=4

# Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
expected-line-ending-format=

[BASIC]

# List of builtins function names that should not be used, separated by a comma
bad-functions=map,filter,input

# Good variable names which should always be accepted, separated by a comma
good-names=i,j,k,ex,Run,_

# Bad variable names which should always be refused, separated by a comma
bad-names=foo,bar,baz,toto,tutu,tata

# Colon-delimited sets of names that determine each other's naming style when
# the name regexes allow several styles.
name-group=

# Include a hint for the correct naming format with invalid-name
include-naming-hint=yes

# Regular expression matching correct function names
function-rgx=[a-z_][a-z0-9_]{2,30}$

# Naming hint for function names
function-name-hint=[a-z_][a-z0-9_]{2,30}$

# Regular expression matching correct variable names
variable-rgx=[a-z_][a-z0-9_]{2,30}$

# Naming hint for variable names
variable-name-hint=[a-z_][a-z0-9_]{2,30}$

# Regular expression matching correct constant names
const-rgx=(([A-Z_][A-Z0-9_]*)|(__.*__)|([a-z_][a-z0-9_]*))$

# Naming hint for constant names
const-name-hint=(([A-Z_][A-Z0-9_]*)|(__.*__))$

# Regular expression matching correct attribute names
attr-rgx=[a-z_][a-z0-9_]{2,30}$

# Naming hint for attribute names
attr-name-hint=[a-z_][a-z0-9_]{2,30}$

# Regular expression matching correct argument names
argument-rgx=[a-z_][a-z0-9_]{2,30}$

# Naming hint for argument names
argument-name-hint=[a-z_][a-z0-9_]{2,30}$

# Regular expression matching correct class attribute names
class-attribute-rgx=([A-Za-z_][A-Za-z0-9_]{1,30}|(__.*__))$

# Naming hint for class attribute names
class-attribute-name-hint=([A-Za-z_][A-Za-z0-9_]{1,30}|(__.*__))$

# Regular expression matching correct inline iteration names
inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$

# Naming hint for inline iteration names
inlinevar-name-hint=[A-Za-z_][A-Za-z0-9_]*$

# Regular expression matching correct class names
class-rgx=[A-Z_][a-zA-Z0-9]+$

# Naming hint for class names
class-name-hint=[A-Z_][a-zA-Z0-9]+$

# Regular expression matching correct module names
module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$

# Naming hint for module names
module-name-hint=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$

# Regular expression matching correct method names
method-rgx=[a-z_][a-z0-9_]{2,30}$

# Naming hint for method names
method-name-hint=[a-z_][a-z0-9_]{2,30}$

# Regular expression which should only match function or class names that do
# not require a docstring.
no-docstring-rgx=^_

# Minimum line length for functions/classes that require docstrings, shorter
# ones are exempt.
docstring-min-length=-1

[ELIF]

# Maximum number of nested blocks for function / method body
max-nested-blocks=5

[LOGGING]

# Logging modules to check that the string format arguments are in logging
# function parameter format
logging-modules=logging

[SIMILARITIES]

# Minimum lines number of a similarity.
min-similarity-lines=4

# Ignore comments when computing similarities.
ignore-comments=yes

# Ignore docstrings when computing similarities.
ignore-docstrings=yes

# Ignore imports when computing similarities.
ignore-imports=no

[VARIABLES]

# Tells whether we should check for unused import in __init__ files.
init-import=no

# A regular expression matching the name of dummy variables (i.e. expectedly
# not used).
dummy-variables-rgx=_$|dummy

# List of additional names supposed to be defined in builtins. Remember that
# you should avoid to define new builtins when possible.
additional-builtins=

# List of strings which can identify a callback function by name. A callback
# name must start or end with one of those strings.
callbacks=cb_,_cb

[SPELLING]

# Spelling dictionary name. Available dictionaries: none. To make it working
# install python-enchant package.
spelling-dict=

# List of comma separated words that should not be checked.
spelling-ignore-words=

# A path to a file that contains private dictionary; one word per line.
spelling-private-dict-file=

# Tells whether to store unknown words to indicated private dictionary in
# --spelling-private-dict-file option instead of raising a message.
spelling-store-unknown-words=no

[MISCELLANEOUS]

# List of note tags to take in consideration, separated by a comma.
notes=FIXME,XXX,TODO

[IMPORTS]

# Deprecated modules which should not be used, separated by a comma
deprecated-modules=regsub,TERMIOS,Bastion,rexec

# Create a graph of every (i.e. internal and external) dependencies in the
# given file (report RP0402 must not be disabled)
import-graph=

# Create a graph of external dependencies in the given file (report RP0402 must
# not be disabled)
ext-import-graph=

# Create a graph of internal dependencies in the given file (report RP0402 must
# not be disabled)
int-import-graph=

[DESIGN]

# Maximum number of arguments for function / method
max-args=6

# Argument names that match this expression will be ignored. Default to name
# with leading underscore
ignored-argument-names=_.*

# Maximum number of locals for function / method body
max-locals=15

# Maximum number of return / yield for function / method body
max-returns=6

# Maximum number of branch for function / method body
max-branches=12

# Maximum number of statements in function / method body
max-statements=50

# Maximum number of parents for a class (see R0901).
max-parents=7

# Maximum number of attributes for a class (see R0902).
max-attributes=7

# Minimum number of public methods for a class (see R0903).
min-public-methods=0

# Maximum number of public methods for a class (see R0904).
max-public-methods=20

# Maximum number of boolean expressions in a if statement
max-bool-expr=5

[CLASSES]

# List of method names used to declare (i.e. assign) instance attributes.
defining-attr-methods=__init__,__new__,setUp

# List of valid names for the first argument in a class method.
valid-classmethod-first-arg=cls

# List of valid names for the first argument in a metaclass class method.
valid-metaclass-classmethod-first-arg=mcs

# List of member names, which should be excluded from the protected access
# warning.
exclude-protected=_asdict,_fields,_replace,_source,_make

[EXCEPTIONS]

# Exceptions that will emit a warning when being caught. Defaults to
# "Exception"
overgeneral-exceptions=Exception

result

************* Module script
script.py:5: [W9006(missing-raises-doc), some_method] "ValidationError" not documented as being raised

Report
======
3 statements analysed.

Statistics by type
------------------

+---------+-------+-----------+-----------+------------+---------+
|type     |number |old number |difference |%documented |%badname |
+=========+=======+===========+===========+============+=========+
|module   |1      |1          |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+
|class    |0      |0          |=          |0           |0        |
+---------+-------+-----------+-----------+------------+---------+
|method   |0      |0          |=          |0           |0        |
+---------+-------+-----------+-----------+------------+---------+
|function |1      |1          |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+

External dependencies
---------------------
::

    marshmallow (script)

Raw metrics
-----------

+----------+-------+------+---------+-----------+
|type      |number |%     |previous |difference |
+==========+=======+======+=========+===========+
|code      |5      |38.46 |4        |+1.00      |
+----------+-------+------+---------+-----------+
|docstring |6      |46.15 |6        |=          |
+----------+-------+------+---------+-----------+
|comment   |0      |0.00  |0        |=          |
+----------+-------+------+---------+-----------+
|empty     |2      |15.38 |2        |=          |
+----------+-------+------+---------+-----------+

Duplication
-----------

+-------------------------+------+---------+-----------+
|                         |now   |previous |difference |
+=========================+======+=========+===========+
|nb duplicated lines      |0     |0        |=          |
+-------------------------+------+---------+-----------+
|percent duplicated lines |0.000 |0.000    |=          |
+-------------------------+------+---------+-----------+

Messages by category
--------------------

+-----------+-------+---------+-----------+
|type       |number |previous |difference |
+===========+=======+=========+===========+
|convention |0      |0        |=          |
+-----------+-------+---------+-----------+
|refactor   |0      |0        |=          |
+-----------+-------+---------+-----------+
|warning    |1      |1        |=          |
+-----------+-------+---------+-----------+
|error      |0      |0        |=          |
+-----------+-------+---------+-----------+

Messages
--------

+-------------------+------------+
|message id         |occurrences |
+===================+============+
|missing-raises-doc |1           |
+-------------------+------------+

------------------------------------------------------------------
Your code has been rated at 6.67/10 (previous run: 6.67/10, +0.00)

AWhetter commented 6 years ago

To any new contributors looking to solve this issue; docparams currently does a simple set difference between the name of the exceptions in the code and the names of the exceptions in the docstring (https://github.com/PyCQA/pylint/blob/1c0356f0683901e6e3561f4caeb176ff3e20be1e/pylint/extensions/docparams.py#L216). It does not attempt to do any kind of name resolution. This process will need to be made more intelligent, either by attempting to fully resolve where the exception comes from or at least by doing something like a docstring_exception.endswith(source_exception).

jrobertson98atx commented 5 years ago

Can anyone provide the specification for what text should be supported in the 'Raises' clause to refer to the exception type? I'm specifically wondering if the leading ~ in the above examples is valid, and whether there's other syntax other than just the exception name that should supported.

For context, pylint currently has a couple of issues preventing this example from working:

The docparams set difference highlighted by @AWhetter
The code which checks for W9006 doesn't recognize exceptions that have an attribute prefix, e.g. raise re.error('Regexp issue') isn't recognized as raising re.error.
The text ~marshmallow.exceptions.ValidationError: reason, why being raised isn't recognized as a valid 'Raises' docstring due to the leading ~.

I understand #1 and #2, but I'm not sure what to update the regexp for in #3, hence my initial question.

I found the use of '~' as part of a cross-reference syntax for sphinx documented here:

http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-syntax

Finally, here's a quick repro. Given the following input:

from re import error

def some_method():
    """summary string.

    Raises:
        ~re.error: Sometimes
    """
    raise error('message string')

Here's the command to show the error:

$ pylint --disable=C0111 --load-plugins=pylint.extensions.docparams ./eg.py

************* Module eg
eg.py:4:0: W9006: "error" not documented as being raised (missing-raises-doc)

------------------------------------------------------------------
Your code has been rated at 6.67/10 (previous run: 3.33/10, +3.33)

AWhetter commented 5 years ago

Thanks for the detailed report @jrobertson98atx

Please could you post this in a separate issue. This will require a change in pylint.extensions._check_docs_utils.possible_excs to make it return the full path to exceptions: https://github.com/PyCQA/pylint/blob/75cecdb1b88cc759223e83fd325aeafd09fec37e/pylint/extensions/_check_docs_utils.py#L102
The regex that needs changing is this one: https://github.com/PyCQA/pylint/blob/75cecdb1b88cc759223e83fd325aeafd09fec37e/pylint/extensions/_check_docs_utils.py#L224

jrobertson98atx commented 5 years ago

I've submitted PR#2656 to take care of issues #1 and #2. Let me know if it makes sense.

Regarding the regexp: I'm not sure what is and isn't permissible here, so I didn't want to update it for this PR. It sounds like the leading '~' is ok. Is there more than needs to be updated?

For reference, the following are all valid sphinx references for exception and I'm wondering if they should all be supported:

        re.error: Sometimes
        ~re.error: Sometimes
        !re.error: Sometimes
        :exc:`re.error`: Sometimes
        :exc:`~re.error`: Sometimes
        :exc:`!re.error`: Sometimes
        :py:exc:`re.error`: Sometimes
        :py:exc:`~re.error`: Sometimes
        :py:exc:`!re.error`: Sometimes

AWhetter commented 5 years ago

Yes a leading ~ is ok. A leading ! is fine also. Not allowing :exc: and other roles is intentional. It's an opinionated decision because Sphinx accepts them (the original Google style guide doesn't), but it's less readable than the plain type, and Google docstrings are all about readability.

jrobertson98atx commented 5 years ago

Thanks for the clarification. Adding support for ~ and ! should be straightforward.

Do you have a reference to the original Google style guide that includes '~'? I'm not seeing it in the top google searches for "google python style guide".

On Wed, Dec 19, 2018 at 3:53 AM Ashley Whetter notifications@github.com wrote:

Yes a leading ~ is ok. A leading ! is fine also. Not allowing :exc: and other roles is intentional. It's an opinionated decision because Sphinx accepts them (the original Google style guide doesn't), but it's less readable than the plain type, and Google docstrings are all about readability.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/PyCQA/pylint/issues/1502#issuecomment-448535694, or mute the thread https://github.com/notifications/unsubscribe-auth/ArT13fsA4Rdqe2SQZjNBpsmnCRw72gTGks5u6gytgaJpZM4NnjB2 .

pylint-dev / pylint