[IMP] pylint_odoo: Add new check docstring-first-line-empty

[moylop260]

When odoo print a docstring just show the first line, but many times is empty

[pedrobaeza]

Docstring should be with triple double-quote

[moylop260]

Yes,
broken_module have allowed break all lint cases

[pedrobaeza]

But in this case you are checking the beginning of the docstring with an empty line, not the correct quote. Expected errors should be then one more?

[moylop260]

Yes,
We will can re-use this same method to create a new check.
broken_module has many lint issues for this matter.

[moylop260]

ping

[moylop260]

@nhomar
Could you check this pr?

[guewen]

I'm not sure we want to start to code the pep257 checks here. At the very least we could use https://github.com/PyCQA/pydocstyle but I'm not sure we should check pep257. I think the usage of pydocstyle could be used if wanted by a PSC but should not be a requirement. I prefer to have docstrings that do not respect pep257 (as long as we don't use them for generating documentation) than no docstrings at all, and strict rules could discourage to write them at all.

[moylop260]

Thanks for comment.

This check don't force to use docstring or check all docstyles like as pydocstyle.
This pr is much more simple.

Odoo use the method string to show docstring in log.
But even show first line.
This is a custom way to show docstring just of odoo.

This check review that if you use a docstring, you should use the first line too.

Now, we can enable this check in the plugin (to use who decide use it), but we can disable it in MQT.

What do you think?

[guewen]

Odoo use the method string to show docstring in log.
But even show first line.
This is a custom way to show docstring just of odoo.

When does it show the first line of the docstring in the logs?

[JulioSerna]

@guewen

this log of runbot Odoo shows this log

and that log is about this test

as you can see in this case the log only shows the first line of docstring

[guewen]

this log of runbot Odoo shows this log

This is not at all a custom behavior of Odoo, this is the behavior of Python's unittest2.

[moylop260]

Thats is right.
Then this pr help to avoid log empty in this cases.

[moylop260]

@guewen
If I add a validation to check just module/tests/* folder, Could you are agree?

[moylop260]

ping

[moylop260]

There is a python generic pep for this case handling-docstring-indentation

And they give us a good code:

# Since code is much more precise than words, here is an implementation of the algorithm:

def trim(docstring):
    if not docstring:
        return ''
    # Convert tabs to spaces (following the normal Python rules)
    # and split into a list of lines:
    lines = docstring.expandtabs().splitlines()
    # Determine minimum indentation (first line doesn't count):
    indent = sys.maxint
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    # Remove indentation (first line is special):
    trimmed = [lines[0].strip()]
    if indent < sys.maxint:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    # Strip off trailing and leading blank lines:
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    # Return a single string:
    return '\n'.join(trimmed)

Then I will close this one and we will work in follow issue: pylint-dev/pylint#868