[code-quality] flake8 and per-file doctest checking

[Ian Cordasco]

On Mon, Dec 15, 2014 at 12:03 AM, Marius Gedminas <marius at gedmin.as> wrote:
> On Fri, Dec 12, 2014 at 09:19:10AM -0600, Ian Cordasco wrote:
>> On Fri, Dec 12, 2014 at 2:25 AM, Marius Gedminas <marius at gedmin.as> wrote:
>> > flake8 has the doctests option that enables doctest checking.
>> > Unfortunately it's global.
>>
>> This is actually a feature of pep8. It's available in flake8 because
>> it is available in pep8.
>
> I think you meant pyflakes, not pep8.

You're right. I was confusing the fact that pep8 runs doctests on
itself with the idea that it provided the --doctest option. You'll
notice though, that neither pyflakes nor pep8 actually provide a
command-line flag for this option. This is entirely something flake8
adds even though the in-built pyflakes Checker supports this.

>> > In objgraph I have a file (objgraph.py) where the doctest syntax is used
>> > for examples, and another file (tests.py) where doctests are used for
>> > actual test code.
>> >
>> > If I set doctests = yes, I get false positives on objgraph.py about all
>> > the undefined names in my examples.
>> >
>> > If I set doctests = no, I get a false positive about 'import gc' in
>> > test.py being unused, despite gc.collect() being called in many doctests.
>> > Also, the code in my doctests doesn't get checked.
>> >
>> > Do you think it would make sense to be able to enable/disable doctest
>> > checking per file?
>>
>> Frankly, no. The current machinery we have around `# noqa` (and `#
>> flake8: noqa`) is very simplistic. Pretty much if we see either of
>> those things, we skip either the line or the file. There's no real, on
>> or off switch. Having per-file options is an oft-requested feature but
>> the maintenance and architecture of it is beyond the scope of flake8
>> as a project.
>>
>> > I'm thinking either directives inside the files
>> > themselves, say:
>> >
>> >   # flake8: +doctests
>> >
>> > or
>> >
>> >   # flake8: -doctests
>> >
>> > or perhaps a list of glob patterns in setup.cfg, e.g.
>> >
>> >   [flake8]
>> >   doctests = tests.py
>>
>> Since this is a pep8 flag, you would have to request something like
>> this for pep8. This may have a better chance of being accepted (and
>> then once pep8 is released with the feature, you would be able to use
>> it in flake8 without issue).
>
> Last time I asked for a pyflakes feature to selectively ignore some
> warnings, I was told to use flake8 and annotate those lines with '#noqa'.
> :)
>

So since this is entirely within my wheelhouse (and discretion), I am
going to try to figure out the best way to allow you to skip files and
doctests without having to skip all checks. I'm heavily leaning
towards the glob patterns in the config file (whether you use tox.ini,
setup.cfg, or the other supported options).

I've created an issue for this on Flake8's issue tracker:
https://gitlab.com/pycqa/flake8/issues/16

>> > (while keeping support for the boolean values, of course)
>> >
>> > Marius Gedminas
>
> Marius Gedminas
> --
> The death rate on Earth is: .... (computing) .... One per person.
>
> _______________________________________________
> code-quality mailing list
> code-quality at python.org
> https://mail.python.org/mailman/listinfo/code-quality
>