Darglint

Added

- Added a mechanism for raising more specific style errors from the
parser. Unfortunately, the parser does not have access to the
functions whose docstrings are being parsed. (These two halves are
put together in the `IntegrityChecker`.) The parser cannot raise
specific error messages, then, since it can't access the function.
So, currently, the `ParserException` takes an optional, more
specific error, which can be created by the `IntegrityChecker`.

Fixed

- Fixed broken unit test.

Fixed

- Made error handling more robust. If darglint is unable to parse, now,
it will display an error message for that function. This error message
is taken from the assert statements in the parser, or is a general
message. This, at least, prevents an ugly stack trace and provides a
model for how to handle style errors in the future.
- Fixed a couple of type errors. Typing is either going to be removed
or moved to a different format to allow for < Python3.6.
- Previously, returns in inner functions would raise errors for missing
returns sections in the docstring, even if (for example), the parent
function yielded values. For example:
- Broken tests were fixed. (The `ast` module does not return functions
in any particular order, but tests were relying on a specific order.)


def walk(root):
"""Walk the tree, yielding active nodes.

Args:
root: The root of the tree.

Yields:
Active nodes.

"""
def skip(node):
return node.inactive
queue = deque()
queue.append(root)
while len(queue) > 0:
curr = queue.pop()
if skip(curr):
continue
yield curr
queue.extend(curr.children)


This function previously would have raised a missing return error
(I201), and would have required a noqa. That is no longer the case.

Changed

- Renamed "darglint.py" to a more appropriate name: "function_description.py".

Added

- `ParserException` is thrown if there is no colon after the type annotation
or argument/exception in the description.

For example, the following function would raise the `ParserException`:


def hello(name):
"""Say hello to the person.

Args:
name: The name of the person to
whom we are saying hello.

"""
print('hello, {}'.format(name))


- Added optional hint to the function `_expect_type` in `darglint/parse.py`.
This will be displayed after the default message. We'll have to add
an option for hints in the configuration, and show or hide them accordingly.

- Added check to ensure that a description exists after an item in the
argument descriptions or exception descriptions (or any multi-section).
At some point, this should probably be optional, but it is currently
raises a `ParserException` (which is too general to really want to
exclude.)

Added

- `GenericSyntaxError` for any `ParserException`s which are raised when
parsing. Ideally, we would add the offset for the lines in the
docstring so that we could get a more accurate indication of where the
actual error occurred. (This would be useful for when we integrate with
ALE or Syntastic or something.)
- `get_logger()` function to the config file. This will help us to get a
fully configured logger. It'll also be a nice way to request a preconfigured
logger (say, "darglint.parser" or something if we want to log from the
parser.) Then we could parse the same configuration to every logger.
- Added check for bare raises. For example, if we had a function such as:


def do_something_dangerous():
try:
dangerous_action()
except CertainDoom:
raise


This would previously caused an error. Now, no checks are made for it.
A "TODO" was left in the code as a reminder that we could handle this better
in the future.

Added

- Added configuration files. Configuration files use the normal Python
`configparser` and TOML format. Configuration files for *darglint*
should have one of the following names:

- `.darglint`
- `setup.cfg`
- `tox.ini`

In addition, the settings for *darglint* must be in a section described
by `[darglint]`. The configuration takes a single key, `ignore`,
and a list of error codes to ignore as a value. For example, if we
would like to ignore the errors "I101" and "I102", then we would
could write the following section in our *tox.ini* file:


[darglint]
ignore=I101,I102


*darglint* will look for a config file stating at the current directory
and working its way up to the root directory.

Fixed

- Fixed star arguments not being treated correctly.

Changed

- Simplified error messages.

There are now only two verbosity levels, 1 and 2. I've kept it as an
integer argument so that, in the future, we can add other levels if
necessary. The default level, now, is 1. At that level, the error
message is something like:

<filename>:<function>:<linenumber>: <error-code>: <message>

Where message is an abbreviated version. (It uses symbols primarily.
For example "- word" denotes a missing parameter in a docstring. "+
word" denotes an extra parameter in the docstring.

Using a level 2 verbosity also prints out the general error message.
(This describes what the error is. So, if level 1 is too cryptic, we
can switch to level 2.) This will look like:

<filename>:<function>:<linenumber>: <error-code>: <description>: <message>

This gets pretty long, so that's why it's not the default.

Added

- Verifies types specified in the docstring against type hints
on the function. Also added `noqa` for these errors.

For example, if we have a function with a mismatched type,
such as:


def mismatched_type(x: int) -> str:
"""Return the string representation of the number.

Args:
x (float): The float to represent.

Returns:
str: The string representation of the number.

"""
return str(x)


Then it would raise a `TypeMismatchError`, since the parameter,
`x`, has a type hint of `int`, while the docstring documents
it as being of type `float`. We could prevent this error
by either adding ` noqa: I103` or ` noqa: I103 x`.