classification
Title: Tabs vs spaces FAQ out of date
Type: Stage: patch review
Components: Documentation, Windows Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Mariatta Nosy List: JDLH, Jim Fasarakis-Hilliard, Mariatta, docs@python, marco.buttu, martin.panter, paul.moore, steve.dower, terry.reedy, tim.golden, xiang.zhang, zach.ware
Priority: normal Keywords: patch

Created on 2017-01-29 23:53 by martin.panter, last changed 2017-03-14 20:54 by Mariatta.

Files
File name Uploaded Description Edit
tabnanny.patch martin.panter, 2017-01-29 23:53
Pull Requests
URL Status Linked Edit
PR 41 JDLH, 2017-02-12 06:45
Messages (14)
msg286460 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-01-29 23:53
The Windows FAQ <https://docs.python.org/release/3.5.2/faq/windows.html#how-do-i-keep-editors-from-inserting-tabs-into-my-python-source> mentions the “python -t” command-line option, but in Python 3 this option is undocumented (and I understand has no effect):

/media/disk/home/proj/python/cpython/Doc/faq/windows.rst:303: WARNING: unknown option: -t

Also, the reference to the tabnanny script is wrong. It exists as a module (Lib/tabnanny.py), not in Tools/scripts/. This aspect also applies to 2.7.
msg286537 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-01-31 15:09
Hi Martin, why did you write "Python should report an error if mixed tabs and spaces are causing problems in leading whitespace."? 
Python for sure reports an error in that case. 

Maybe "Python reports an error if..." is a better choice. But my English is really poor, so I can be wrong... I have just this doubt, otherwise the patch is OK to me.
msg286854 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2017-02-03 10:11
LGTM. -t is not removed but only ignored in Py3 for backwards compatibility. And I am fine with the wording.
msg286896 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-02-03 22:30
I agree with Marco in that I do not understand the 'should'.  Py 3 has a definite rule for when it raises.  (I don't remember the exact details as I don't use tabs.)  "Python raises xxxError if one mixes tabs and spaces in the same file." (Or whatever the rule is.)
msg286929 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-02-04 08:33
Marco: I agree “Python reports an error” would have been simpler. That is what I meant to say. Anyway, perhaps we should put

Python raises :exc:`IndentationError` if mixed tabs and spaces are causing problems in leading whitespace.

In general, the exception seems to be IndentationError. TabError is a subclass, but is not raised in all circumstances. It seems the compiler assumes a particular tab model, so the exact exception depends on the amount of tabs and spaces:

>>> exec("if True:\n" + " "*8 + "1\n" "\t2\n")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 3
    2
    ^
TabError: inconsistent use of tabs and spaces in indentation
>>> exec("if True:\n" + " "*9 + "1\n" "\t2\n")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 3
    2
    ^
IndentationError: unindent does not match any outer indentation level
msg286976 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-02-04 16:51
I think you are right about the TAB model (Parser/tokenizer.c:40 and Lib/tokenize.py:215), that is why the difference between the two cases.

In any case, I am not sure whether expliciting the type of the exeption is the best choice. So, to me +1 to just change "should report" with "reports" in the proposed patch, and +0 to indicate the exeption type.
msg286980 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-02-04 17:24
I would add the exception type after testing all versions patched.
msg287499 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-10 09:46
I just created Pull Request 76 https://github.com/python/cpython/pull/76  to address http://bugs.python.org/issue29521 . 

In faq/windows.rst, I've used your wording from the discussion in of this bug. I may have address this issue completely, in fact.  I did not do the more careful "testing all versions patched" which Terry suggested.
msg287505 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-02-10 10:27
Thanks Jim. I tested thise exec() in Py2.7 and Py3 (3.5 - 3.7):

exec("if True:\n" + " "*width + "1\n" + "\t2\n")

* width == 0 raises a IndentationError both in Py2 and Py3
* width in range(1, 8) raises an IndentationError in Py2 and TabError in Py3
* width == 8 is OK in Py2, and raises a TabError in Python 3
* width > 8 is the same as width == 0

I think the most important case, is when width==4 or width==8, because they are the usual widths of the TAB. In these cases, the editor will show a "correct" level of indentation, but Python will raise an exception and a beginner user will not understand the reason. IMO is here that Lib/tabnanny.py really comes in handy. And in these cases (width== 4 or 8), Python 3 raises a TabError, but if we write in the doc that it raises an IndentationError, IMO the user perhaps will think there is an error in the doc, because IMO on the average he/she will not spot that TabError is a subclass of IndentationError. Thats why I think it is better to not specity the exeption type.

Anyway, it is really a minor issue, and currently is also related to other issues, so there is no need to discuss to much for such a detail. Finally, the wording in the pull request is good enough for me :) Thanks
msg287633 - (view) Author: Jim DeLaHunt (JDLH) * Date: 2017-02-12 06:45
PR https://github.com/python/cpython/pull/41 to the new Github repo contains the following wording in Doc/faq/windows.rst:

Python raises :exc:`IndentationError` or :exc:`TabError` if mixed tabs 
and spaces are causing problems in leading whitespace.
You may also run the :mod:`tabnanny` module to check a directory tree 
in batch mode.

This is parallel wording with the contents of Martin's patch.

The PR may be enough to fix this issue.
msg289593 - (view) Author: Jim Fasarakis-Hilliard (Jim Fasarakis-Hilliard) * Date: 2017-03-14 14:42
Shouldn't this issue get closed now that the PR was merged?
msg289614 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2017-03-14 17:52
Just a question, does this need backport to 2.7?
It's only been backported to 3.5 and 3.6.
msg289617 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-03-14 20:37
The “tabnanny” script was removed from Tools/scripts/ in 2.0: <https://github.com/python/cpython/commit/a02c898>. So the 2.7 FAQ also has the wrong location.
msg289618 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2017-03-14 20:54
Thanks, Martin, and thanks Jim for the ping.
I'll backport the change to 2.7 later today, and then this issue can be closed :)
History
Date User Action Args
2017-03-14 20:54:35Mariattasetassignee: docs@python -> Mariatta
messages: + msg289618
2017-03-14 20:37:05martin.pantersetmessages: + msg289617
2017-03-14 17:52:45Mariattasetnosy: + Mariatta
messages: + msg289614
2017-03-14 14:42:42Jim Fasarakis-Hilliardsetnosy: + Jim Fasarakis-Hilliard
messages: + msg289593
2017-02-12 06:45:29JDLHsetmessages: + msg287633
pull_requests: + pull_request44
2017-02-10 10:27:00marco.buttusetmessages: + msg287505
2017-02-10 09:46:48JDLHsetnosy: + JDLH
messages: + msg287499
2017-02-10 08:50:10martin.panterlinkissue29521 dependencies
2017-02-04 17:24:45terry.reedysetmessages: + msg286980
2017-02-04 16:51:39marco.buttusetmessages: + msg286976
2017-02-04 08:33:17martin.pantersetmessages: + msg286929
2017-02-03 22:30:25terry.reedysetnosy: + terry.reedy
messages: + msg286896
2017-02-03 10:11:51xiang.zhangsetnosy: + xiang.zhang
messages: + msg286854
2017-01-31 15:09:51marco.buttusetnosy: + marco.buttu
messages: + msg286537
2017-01-29 23:53:58martin.pantercreate