Disable doctest checking unless an option is passed

[Jeffrey Tratner]

It would be really great to be able to ignore/filter doctest errors. E.g.::

---

def something(f):
    """
    >>> a + 1
    """
    return f + 1

---

And you could choose to ignore the error about 'a' not being defined.

[Jean-Paul Calderone (exarkun)]

I'd love for this regression to be fixed. It is dumping a lot of spurious warnings into pyflakes output for my project.

[Jeffrey Tratner (jtratner)]

It turns out there's an environment variable you can set PYFLAKES_NODOCTEST that magically turns this off, would be nice if it were documented.

[Glyph Lefkowitz (glyph)]

"Don't check doctests" should really be the default behavior. Checking doctests by default in this manner is a regression, since it causes false positives.

If you have doctests and you want them checked, you know it, and you can easily pass an additional option. Many examples in code that use a >>> prefix are not doctests and should not be treated as such.

(Honestly I think it's weird that this feature got added at all: Pyflakes' whole raison d'être is to be simple and fast and err on the side of checking only things that are clearly invalid; if you want to lint every possible insane thing, pychecker and pylint are already endlessly configurable to do things like this, aren't they?)

[Glyph Lefkowitz (glyph)]

Changed the subject since apparently PYFLAKES_NODOCTEST is already an option, but I'd still like it if it were the default.

[Marius Gedminas (mgedmin)]

To satisfy your curiosity: there are large codebases out there (mostly from the Zope project) that have large numbers of doctests, and not checking them causes large numbers of false positives for names imported at the top of the module and used in multiple doctests, e.g. ::

    from zope.foo import bar

    def doctest_bar_does_x():
        """
            >>> bar('x')
            42
        """

    def doctest_bar_does_y():
        """
            >>> bar('y')
            -42
        """

It never occurred to me that people would write invalid code in doctests.

*shrug*

I'm not against flipping the default setting of the option, provided that I can enable it by specifying something in setup.cfg to indicate that this project uses doctests and would like to verify their correctness.

[Jeffrey Tratner (jtratner)]

Should your example cause an error or not? I'm unclear on how namespacing
works in doctests.

[asmeurer (asmeurer)]

I think the default (python -m doctest) uses the module namespace in the doctest, but this is bad form IMHO, because doctests, as examples to the user, should be self-contained. For the SymPy doctest runner we changed the behavior to make doctests independently scoped (https://github.com/sympy/sympy/blob/master/sympy/utilities/runtests.py#L1205). An option to change the scoping would be nice. I think there's a separate issue open for this, though.

[Jean-Paul Calderone (exarkun)]

See https://github.com/pyflakes/pyflakes/pull/25

[Florent (florent.x)]

This pull request is now merged in the trunk.

Thank you.