Pyflakes

Bug #1178807
Comment #6

Comment 6 for bug 1178807

Revision history for this message

John Vandenberg (jayvdb) wrote on 2015-11-22:

I'd like to explore whether it is necessary to run doctests as a top level scope.

I've been working towards:
1. processing the doctest scope so it can use the module scope (sloppy use of doctest, but very common)
2. ensuring that the doctest scope does not report errors if it does not use the module scope (good use of doctest)
3. reporting errors when the module scope relies on the doctest scope (very very bad use of doctest)

The doctest scope currently can re-import names also imported in the module scope, without error. I believe that is very very close to the request in #3, that doctest have their own 'module scope'.
e.g. test_importInDoctestAndAfter : https://github.com/pyflakes/pyflakes/blob/master/pyflakes/test/test_doctests.py#L217

Note that `test_importBeforeAndInDoctest` above `test_importInDoctestAndAfter` is a bit misleading, being marked as 'todo'. The code sample in that test does not report any errors, as it is effectively equivalent to `test_importInDoctestAndAfter`.

IMO, broadly speaking, doctests shouldnt re-use names existing in the module scope, with imports being the obvious exception. If there is a case were re-importing in the doctest scope causes an error, IMO that needs to be fixed.
Are there other situations where doctest re-using names from the module scope is preferable or even necessary?

On the structural problems mentioned in #1, a recent checkin (https://github.com/pyflakes/pyflakes/commit/93aa3c435505b8541b151c3e4b24c0ec4333f0bb) changed it so that a doctest is a module scope instead of a function scope. This is still not perfect, as the doctest scope should reside in the module scope, but it is currently deeply nested and resides with the object's scope where the docstring exists. That means currently it could inherit variables from any scope where the docstring resides; clearly a source of bugs, and this fix has been included in two of my pull requests. Maybe I should pull it out into a separate pull request with dedicated tests.

The other outstanding problem I am aware of is that a module level import which is only used in doctests is not reported as an error. I have a fix for that (https://github.com/jayvdb/pyflakes/commit/a8ccb1cef8ec005b07ea347823c4987d995d29c8), but it is waiting on a few other patches to be merged.

The unclear case that I am aware of is 'from x import foo' in module scope being shadowed by a 'from y import foo' in doctest scope. I suspect we'll need to declare that problem as unsolvable by pyflakes, as doctests should show recommended importation for clients, whereas the module level imports of the same names are sometimes different (more complex) due to internal mess/structure being hidden from the end-user.

I'd like to explore whether it is necessary to run doctests as a top level scope.

The doctest scope currently can re-import names also imported in the module scope, without error.  I believe that is very very close to the request in #3, that doctest have their own 'module scope'.
e.g. test_importInDoctestAndAfter : https://github.com/pyflakes/pyflakes/blob/master/pyflakes/test/test_doctests.py#L217

Note that `test_importBeforeAndInDoctest` above `test_importInDoctestAndAfter` is a bit misleading, being marked as 'todo'.  The code sample in that test does not report any errors, as it is effectively equivalent to `test_importInDoctestAndAfter`.

IMO, broadly speaking, doctests shouldnt re-use names existing in the module scope, with imports being the obvious exception.  If there is a case were re-importing in the doctest scope causes an error, IMO that needs to be fixed.
Are there other situations where doctest re-using names from the module scope is preferable or even necessary?

On the structural problems mentioned in #1, a recent checkin (https://github.com/pyflakes/pyflakes/commit/93aa3c435505b8541b151c3e4b24c0ec4333f0bb) changed it so that a doctest is a module scope instead of a function scope.  This is still not perfect, as the doctest scope should reside in the module scope, but it is currently deeply nested and resides with the object's scope where the docstring exists.  That means currently it could inherit variables from any scope where the docstring resides; clearly a source of bugs, and this fix has been included in two of my pull requests.  Maybe I should pull it out into a separate pull request with dedicated tests.

The other outstanding problem I am aware of is that a module level import which is only used in doctests is not reported as an error.  I have a fix for that (https://github.com/jayvdb/pyflakes/commit/a8ccb1cef8ec005b07ea347823c4987d995d29c8), but it is waiting on a few other patches to be merged.

The unclear case that I am aware of is 'from x import foo' in module scope being shadowed by a 'from y import foo' in doctest scope.  I suspect we'll need to declare that problem as unsolvable by pyflakes, as doctests should show recommended importation for clients, whereas the module level imports of the same names are sometimes different (more complex) due to internal mess/structure being hidden from the end-user.