flake8 and per-file doctest checking

flake8 has the doctests option that enables doctest checking. Unfortunately it's global. 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? 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 (while keeping support for the boolean values, of course) Marius Gedminas -- We have enough youth, how about a fountain of SMART?

On Fri, Dec 12, 2014 at 2:25 AM, Marius Gedminas <marius@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.
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).
(while keeping support for the boolean values, of course)
Marius Gedminas -- We have enough youth, how about a fountain of SMART?
_______________________________________________ code-quality mailing list code-quality@python.org https://mail.python.org/mailman/listinfo/code-quality

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@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.
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'. :)
(while keeping support for the boolean values, of course)
Marius Gedminas
Marius Gedminas -- The death rate on Earth is: .... (computing) .... One per person.

On Mon, Dec 15, 2014 at 12:03 AM, Marius Gedminas <marius@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@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@python.org https://mail.python.org/mailman/listinfo/code-quality
participants (2)
-
Ian Cordasco
-
Marius Gedminas