terrencepreilly
Numpy Stability Tracking Issue
Issues with the Numpy parser and reporter should be added here for the moment. Once it has stabilized, or a couple weeks have passed, I'll close this bug.
Annotations are dropped in rightmost child for arguments-section AST. At some point, the item name is the only node, and everything is elided up until it's placed in the argument section. Annotations will be dropped in this case.
EmptyDescriptionError cannot be implemented for this docstring format (at least not consistently) without this being handled.
For example, when a docstring is terminated by a newline, it works:
But if it's not terminated by a newline, then the production is elided up to the arguments section without the annotation:
Maybe, rather than annotations being able to modify a particular production, they should be able to modify the children in a production.
With this code
"""
Module description
"""
from abc import ABC, abstractmethod
class MyClass(ABC):
"""
Description of MyClass
"""
@abstractmethod
def my_method(self, my_parameter):
"""
Do something
Parameters
----------
my_parameter: str
A parameter
Returns # noqa: DAR202
-------
str
something
"""
I get this error: test.py: my_method:14: DAR101: - my_parameter
On the contrary without the Returns + DAR202, I do not get the error. May I have to write the documentation for this scenario in a different way?
Unfortunately it is currently not working for me.
script.py
def foo(bar: int) -> str:
"""Foo bar.
Not very pythonic.
"""
return str(bar)
Running
$ darglint -s numpy -z short script.py
prints nothing, although I am expecting Missing return and Missing argument, like when I do
$ darglint -z short script.py
script.py:foo:1: DAR101: - bar
script.py:foo:1: DAR201: - return
The following also works
$ darglint -s numpy script.py
script.py:foo:1: DAR101: - bar
script.py:foo:1: DAR201: - return
Here is some version information
$ python --version
Python 3.7.7
$ darglint --version
1.4.1
I am getting the following error DAR000: Unexpected exception in darglint: Unsupported section type, Sections.VARIABLES_SECTION whenever I am trying to use docstring_style = numpy. For reference taking the numpy style example from sphinx napolean.
class ExampleClass(object):
"""The summary line for a class docstring should fit on one line.
If the class has public attributes, they may be documented here
in an ``Attributes`` section and follow the same formatting as a
function's ``Args`` section. Alternatively, attributes may be documented
inline with the attribute's declaration (see __init__ method below).
Properties created with the ``@property`` decorator should be documented
in the property's getter method.
Attributes
----------
attr1 : str
Description of `attr1`.
attr2 : :obj:`int`, optional
Description of `attr2`.
"""
def __init__(self, param1, param2, param3):
"""Example of docstring on the __init__ method.
The __init__ method may be documented in either the class level
docstring, or as a docstring on the __init__ method itself.
Either form is acceptable, but the two should not be mixed. Choose one
convention to document the __init__ method and be consistent with it.
Note
----
Do not include the `self` parameter in the ``Parameters`` section.
Parameters
----------
param1 : str
Description of `param1`.
param2 : :obj:`list` of :obj:`str`
Description of `param2`. Multiple
lines are supported.
param3 : :obj:`int`, optional
Description of `param3`.
"""
self.attr1 = param1
self.attr2 = param2
self.attr3 = param3 #: Doc comment *inline* with attribute
#: list of str: Doc comment *before* attribute, with type specified
self.attr4 = ["attr4"]
self.attr5 = None
"""str: Docstring *after* attribute, with type specified."""
@property
def readonly_property(self):
"""str: Properties should be documented in their getter method."""
return "readonly_property"
@property
def readwrite_property(self):
""":obj:`list` of :obj:`str`: Properties with both a getter and setter
should only be documented in their getter method.
If the setter method contains notable behavior, it should be
mentioned here.
"""
return ["readwrite_property"]
@readwrite_property.setter
def readwrite_property(self, value):
value
def example_method(self, param1, param2):
"""Class methods are similar to regular functions.
Note
----
Do not include the `self` parameter in the ``Parameters`` section.
Parameters
----------
param1
The first parameter.
param2
The second parameter.
Returns
-------
bool
True if successful, False otherwise.
"""
return True
def __special__(self):
"""By default special members with docstrings are not included.
Special members are any methods or attributes that start with and
end with a double underscore. Any special member with a docstring
will be included in the output, if
``napoleon_include_special_with_doc`` is set to True.
This behavior can be enabled by changing the following setting in
Sphinx's conf.py::
napoleon_include_special_with_doc = True
"""
pass
def __special_without_docstring__(self):
pass
def _private(self):
"""By default private members are not included.
Private members are any methods or attributes that start with an
underscore and are *not* special. By default they are not included
in the output.
This behavior can be changed such that private members *are* included
by changing the following setting in Sphinx's conf.py::
napoleon_include_private_with_doc = True
"""
pass
def _private_without_docstring(self):
pass
Please let me know if I am missing something. Thanks.
@e0lithic, I wasn't able to reproduce this for v1.5.2. (For reference, I copied your example above into example_numpy.py, and ran darglint -s numpy example_numpy.py. I got the errors
example_numpy.py:readonly_property:57: DAR201: - return
example_numpy.py:readwrite_property:62: DAR201: - return
Could you give me a minimal example, and the command you're running against it?
@terrencepreilly I can confirm that running darglint in a standalone manner is not creating the issue. In my setup darglint is being invoked by a pre-commit inside a nox session. Once I get some free time, I would create a reproducible example.
Here's the steps to reproduce the scenario.
# Download a python package template. Accept the defaults
cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python --checkout=2020.7.15
cd hypermodern-python
# Add the above ExampleClass as test.py to the src/hypermodern_python/
git init
git add .
nox -rs pre-commit
The above runs properly as darglint seems to be functional.
src/hypermodern_python/test.py:19:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:25:1: DAR101 Missing parameter(s) in Docstring: - param1
src/hypermodern_python/test.py:25:1: DAR101 Missing parameter(s) in Docstring: - param2
src/hypermodern_python/test.py:25:1: DAR101 Missing parameter(s) in Docstring: - param3
src/hypermodern_python/test.py:42:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:42:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:44:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:65:1: D205 1 blank line required between summary line and description
src/hypermodern_python/test.py:65:1: D415 First line should end with a period, question mark, or exclamation point
src/hypermodern_python/test.py:65:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:65:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:66:1: DAR201 Missing "Returns" in Docstring: - return
src/hypermodern_python/test.py:78:1: DAR101 Missing parameter(s) in Docstring: - param1
src/hypermodern_python/test.py:78:1: DAR101 Missing parameter(s) in Docstring: - param2
src/hypermodern_python/test.py:78:1: DAR201 Missing "Returns" in Docstring: - return
src/hypermodern_python/test.py:115:1: D105 Missing docstring in magic method
So lets now force the numpy styling using .darglint
[darglint]
docstring_style = numpy
strictness = short
Now when we run using nox -rs pre-commit we get the unexpected DAR000 errors
noxfile.py:1:1: DAR000: Unexpected exception in darglint: Unsupported section type, Sections.VARIABLES_SECTION
tests/test_main.py:1:1: DAR000: Unexpected exception in darglint: Unsupported section type, Sections.VARIABLES_SECTION
src/hypermodern_python/__main__.py:1:1: DAR000: Unexpected exception in darglint: Unsupported section type, Sections.VARIABLES_SECTION
src/hypermodern_python/test.py:1:1: DAR000: Unexpected exception in darglint: Unsupported section type, Sections.VARIABLES_SECTION
src/hypermodern_python/test.py:19:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:42:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:42:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:44:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:65:1: D205 1 blank line required between summary line and description
src/hypermodern_python/test.py:65:1: D415 First line should end with a period, question mark, or exclamation point
src/hypermodern_python/test.py:65:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:65:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:115:1: D105 Missing docstring in magic method
On further experimentation i realized that if I just specify .darglint as
[darglint]
docstring_style = numpy
It does work properly with the following log
noxfile.py:28:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:34:1: DAR101 Missing parameter(s) in Docstring: - *args
noxfile.py:34:1: DAR301 Missing "Yields" in Docstring: - yield
noxfile.py:54:1: DAR201 Missing "Returns" in Docstring: - return
noxfile.py:65:1: DAR101 Missing parameter(s) in Docstring: - *args
noxfile.py:74:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:99:1: DAR101 Missing parameter(s) in Docstring: - *args
noxfile.py:99:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:115:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:168:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:191:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:200:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:211:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:222:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:237:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:245:1: DAR101 Missing parameter(s) in Docstring: - session
noxfile.py:254:1: DAR101 Missing parameter(s) in Docstring: - session
tests/test_main.py:11:1: DAR201 Missing "Returns" in Docstring: - return
tests/test_main.py:15:1: DAR101 Missing parameter(s) in Docstring: - runner
src/hypermodern_python/test.py:19:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:42:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:42:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:44:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:61:1: DAR201 Missing "Returns" in Docstring: - return
src/hypermodern_python/test.py:65:1: D205 1 blank line required between summary line and description
src/hypermodern_python/test.py:65:1: D415 First line should end with a period, question mark, or exclamation point
src/hypermodern_python/test.py:65:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:65:1: RST304 Unknown interpreted text role "obj".
src/hypermodern_python/test.py:66:1: DAR201 Missing "Returns" in Docstring: - return
src/hypermodern_python/test.py:115:1: D105 Missing docstring in magic method
Please let me know if you need any clarification or if I am missing something.
DAR000 when called using flake8 with numpy docstring style and short strictness
Hi @terrencepreilly , thank you so much for your work. It's been so useful.
I'm getting similar issues to @e0lithic . For me the issue only arises when using the flake8—not the darglint command.
A minimal example:
.darglint
[darglint]
docstring_style=numpy
strictness = short
.flake8
[flake8]
select = DAR
scratch.py
"""Testing."""
def foo(x: int, y: int) -> str:
"""Docstring."""
return "hello"
What I expect
Nothing to be raised. The strictness is set to short, so I expect one line docstrings to pass. My expectations are met if I run the darglint command.
% darglint scratch.py
What happens
When run through the flake8 command, DAR000 is raised.
% flake8 scratch.py
scratch.py:1:1: DAR000: Unexpected exception in darglint: Unsupported section type, Sections.VARIABLES_SECTION
Additional information
If we modify .darglint to
[darglint]
strictness = short
% flake8 scratch.py
If we modify it to be
[darglint]
docstring_style=numpy
% flake8 scratch.py
scratch.py:5:1: DAR201 Missing "Returns" in Docstring: - return
scratch.py:5:1: DAR101 Missing parameter(s) in Docstring: - x
scratch.py:5:1: DAR101 Missing parameter(s) in Docstring: - y
Thanks for the great project!
False negatives when numpy docstring style is used with short strictness
Separate issue than my previous comment: seems darglint gives some false negatives the numpy docstring is used along with short strictness.
With file scratch.py
"""Testing."""
def foo(x: int, y: int) -> str:
"""
Docstring.
Not very Pythonic
"""
return "hello"
What I expect
I expect DAR201 and DAR101 to be raised. Which is what happens when I run
❯ darglint -s numpy scratch.py
scratch.py:foo:4: DAR201: - return
scratch.py:foo:4: DAR101: - x
scratch.py:foo:4: DAR101: - y
What happens
When paired with -z short, nothing is raised.
❯ darglint -s numpy -z short scratch.py
No errors on strictness type long and short
Encountered issue with darglint version 1.5.4 and python 3.8 something similar to @cbows. I was trying to use numpy docstring convention with long and short strictness.
Here is a sample python code, that i placed in file test_docstring_linting.py:
def main(arg1: int, arg2: int) -> None:
"""
Sample function.
Parameters
----------
arg1 : float
Argument 1 description
"""
pass
Command
PS > darglint -s numpy -z long .\test_docstring_linting.py
PS > darglint -s numpy -z short .\test_docstring_linting.py
Results for both commands above is empty.
I was expecting output similar to full strictness. Result of full check for the same sample code is
PS > darglint -s numpy .\test_docstring_linting.py
.\test_docstring_linting.py:main:16: DAR103: ~arg1: expected int but was float
.\test_docstring_linting.py:main:16: DAR101: - arg2
DAR000 when docstring have type hint multiline
test.py
def my_func(arg) -> dict:
"""Return dict
Returns
-------
Dict[
str,
Tuple[
datetime,
str,
Union[str, dict]
]
]
Retrun dict
"""
return arg
check via flake8
flake8 --docstring-style=numpy tests.py
output
tests.py:1:1: DAR000: Unexpected exception in darglint: Multiple types should be combined into a Union
