Tabs vs spaces FAQ out of date

[vadmium]

BPO	29387
Nosy	@terryjreedy, @pfmoore, @tjguk, @vadmium, @zware, @marco-buttu, @zooba, @zhangyangyu, @DimitrisJim, @Mariatta, @JDLH
PRs	bpo-29521 Fix two minor documentation build warnings #41
Files	tabnanny.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/Mariatta'
closed_at = <Date 2017-04-20.16:13:49.538>
created_at = <Date 2017-01-29.23:53:58.749>
labels = ['3.7', 'OS-windows', 'docs']
title = 'Tabs vs spaces FAQ out of date'
updated_at = <Date 2017-04-20.16:13:49.537>
user = 'https://github.com/vadmium'

bugs.python.org fields:

activity = <Date 2017-04-20.16:13:49.537>
actor = 'Mariatta'
assignee = 'Mariatta'
closed = True
closed_date = <Date 2017-04-20.16:13:49.538>
closer = 'Mariatta'
components = ['Documentation', 'Windows']
creation = <Date 2017-01-29.23:53:58.749>
creator = 'martin.panter'
dependencies = []
files = ['46450']
hgrepos = []
issue_num = 29387
keywords = ['patch']
message_count = 14.0
messages = ['286460', '286537', '286854', '286896', '286929', '286976', '286980', '287499', '287505', '287633', '289593', '289614', '289617', '289618']
nosy_count = 12.0
nosy_names = ['terry.reedy', 'paul.moore', 'tim.golden', 'docs@python', 'martin.panter', 'zach.ware', 'marco.buttu', 'steve.dower', 'xiang.zhang', 'Jim Fasarakis-Hilliard', 'Mariatta', 'JDLH']
pr_nums = ['41']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue29387'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7']

[vadmium]

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.

[marco-buttu]

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.

[zhangyangyu]

LGTM. -t is not removed but only ignored in Py3 for backwards compatibility. And I am fine with the wording.

[terryjreedy]

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.)

[vadmium]

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

[marco-buttu]

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.

[terryjreedy]

I would add the exception type after testing all versions patched.

[jdlh]

I just created Pull Request 76 #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.

[marco-buttu]

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

[jdlh]

PR #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.

[DimitrisJim]

Shouldn't this issue get closed now that the PR was merged?