classification
Title: Tutorial documentation contains undefined reference to #!
Type: Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Mariatta Nosy List: Jim Fasarakis-Hilliard, Mariatta, docs@python, marco.buttu, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2017-01-27 17:20 by Jim Fasarakis-Hilliard, last changed 2017-02-02 06:00 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
interpreter_tut.patch Jim Fasarakis-Hilliard, 2017-01-27 17:20 review
interpreter_tut2.7.patch Jim Fasarakis-Hilliard, 2017-01-27 17:20 review
issue29381.patch Mariatta, 2017-01-30 02:13 review
issue29381v2.patch Mariatta, 2017-01-30 03:33 review
issue29381v3.patch Mariatta, 2017-01-31 01:44 review
Messages (22)
msg286378 - (view) Author: Jim Fasarakis-Hilliard (Jim Fasarakis-Hilliard) * Date: 2017-01-27 17:20
After moving a certain chunk of the 'interpreter.rst' contents to 'appendix.rst' in issue16827 the reference to #! in the section '2.2.3. Source Code Encoding' is currently confusing for new readers.

Attached patches reword the sentence to remove that reference for 3.4+ and 2.7.
msg286388 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-01-27 22:25
Mariatta, could you check this patch and tell us your recommendation about whether it should be applied, modified, or rejected?
msg286410 - (view) Author: Jim Fasarakis-Hilliard (Jim Fasarakis-Hilliard) * Date: 2017-01-28 12:09
Hi, Raymond. Is Mariatta responsible for reviewing Documentation submissions? If so, should I nosy Mariatta in any future documentation issues?
msg286414 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-01-28 16:39
You wrote: "It is also possible to specify a different encoding for source files. In order to do this, you can use a special comment line that defines the source file encoding::". I think that is not true, because the line have to be the first line, or right below a comment (just one, as in the case of the shebang). For instance, in this case Python apply the declared coding:

  $ cat foo.py
  # The first line is a comment
  # -*- coding: ascii -*-
  print('è')  # Encoded in UTF-8
  $ python foo.py
     ...
  SyntaxError: encoding problem: ascii


In this case it does not:

  $ cat foo.py
  # The first line is a comment
  # and also the sencond line
  # -*- coding: ascii -*-
  print('è')  # Encoded in UTF-8
  $ python foo.py 
  è

But I think you are right that the current doc is confusing. Maybe yon can write something like this: 

"It is also possible to specify a different encoding for source files. In order to do this, put one special comment line to define the source file encoding:

# -*- coding: encoding -*-

This coding comment has to be the first line of the file, or the second line in case the first one is the #! line."
msg286415 - (view) Author: Jim Fasarakis-Hilliard (Jim Fasarakis-Hilliard) * Date: 2017-01-28 16:55
Indeed, this does create an issue. 

The last sentence in the documentation actually specifies where the encoding comment can be but doesn't strictly specify it can be on the second line if and only if preceded by `#!`.

I'm thinking the last sentence should contain the additional change, that is, change it from :

    The special encoding comment must be in the first or second line within the file.

to:

    The special encoding comment must be in the first line, or, if the first line is used to create an executable Python script, the second line within the file.

linking to (https://docs.python.org/3/tutorial/appendix.html#executable-python-scripts) accordingly. 

Let's see what Mariatta says about these proposals. Thanks for noticing.
msg286424 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-01-29 01:25
> Is Mariatta responsible for reviewing Documentation submissions?

No, she is a new core developer and this is a good issue for her to do the initial review and post any thoughts on the subject.  We've all got to start somewhere.

> If so, should I nosy Mariatta in any future documentation issues?

You did everything just right.  Just marking this as a doc patch is sufficient.
msg286465 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-01-30 02:13
There are certain rules about the encoding declaration line.
It has to be the first line of the source code, or in the case that the file starts with a unix "shebang" line, then the encoding declaration has to be on the second line. In fact, the first or the second lines of the source code has to follow a certain regular expression. This is all described in PEP 263, but we don't have to repeat all of those here. IMO we can just refer the reader to the PEP.

I've prepared a patch that addresses this. Please review, and let me know if you have additional feedback.

Thanks :)
msg286468 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-01-30 03:03
Suggestions:

* Please add a cross-link to from '''UNIX “shebang” line"''' to 16.1.2. Executable Python Scripts.

* Instead of a link to a PEP (which is outside the main documentation), let's just add an example:

   # /usr/bin/env python3
   # -*- coding: cp-1252 -*-
msg286470 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-01-30 03:33
Thanks for the feedback, Raymond. I adjusted my patch.
msg286481 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-01-30 10:17
The patch LGTM. I think there is just one type (see review). 

By the way, looking at the PEP 0263, the sentence "To define a source code encoding, a magic comment must be placed into the source files either as first or second line in the file" actually is not true. Also because I did not see any point in the PEP that clarifies that the fist line has to be a comment. Maybe it could be deduced by the examples (all using the shebang), but maybe not, and the user could think this is a valid declaration:

print('très jolie')
# -*- coding: ascii -*-

If you think is worth to clarify, I open an issue with a patch for the PEP 0263.
msg286488 - (view) Author: Jim Fasarakis-Hilliard (Jim Fasarakis-Hilliard) * Date: 2017-01-30 12:14
Added a comment too. Other than that and the comment by Marco it looks fine to me too.
msg286502 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-01-31 01:44
Thanks all for the feedback. I updated the patch.

Marco, IMO it's not necessary to update the PEP.
This section of the documentation serves as a tutorial for it, and the update in this patch clarifies the situation.
msg286508 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-01-31 03:22
It looks like everyone is happy and the patch is ready for Mariatta to apply.

The procedure is:
 $ hg pull -u
 $ hg diff                      # Verify it has only your intended patch
 $ hg update 3.6
 $ cd Doc
 $ make html
 $ open build/html/index.html   # Now review generated HTML
 $ hg commit -m "Issue #29381: Clarify ordering of UNIX shebang line as source encoding line"
 $ hg update default
 $ hg merge 3.6
 $ hg diff                      # Verify it has only your intended patch
 $ hg commit -m "merge"
 $ hg push

Then return to this issue, verify the bot has posted the commit.

Write a comment thanking the OP and reviewers.  Then mark the status as "closed" and resolution as "fixed".
msg286509 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-01-31 03:23
I would only post this to 2.7, 3.6 and 3.7.   Also, no Misc/NEWS entry is needed.
msg286736 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-02 04:21
New changeset 3d712292f2fa by Mariatta Wijaya in branch '3.6':
Issue #29381: Clarify ordering of UNIX shebang line as source encoding line
https://hg.python.org/cpython/rev/3d712292f2fa
msg286737 - (view) Author: Roundup Robot (python-dev) (Python triager) Date:
New changeset abfa17511f7ce8f1a6394f28f82ffb9a916fcf03 by Mariatta Wijaya in branch '3.6':
Issue #29381: Clarify ordering of UNIX shebang line as source encoding line
https://github.com/python/cpython/commit/abfa17511f7ce8f1a6394f28f82ffb9a916fcf03
msg286738 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-02 05:04
New changeset 483d9133fd7e by Mariatta Wijaya in branch '3.6':
Issue #29381: Clarify ordering of UNIX shebang line as source encoding line
https://hg.python.org/cpython/rev/483d9133fd7e

New changeset 762a93935afd by Mariatta Wijaya in branch 'default':
Issue #29381: merge with 3.6
https://hg.python.org/cpython/rev/762a93935afd
msg286742 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2017-02-02 05:21
New changeset df356d3c916e by Mariatta Wijaya in branch '2.7':
Issue #29381: Clarify ordering of UNIX shebang line as source encoding line
https://hg.python.org/cpython/rev/df356d3c916e
msg286743 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-02-02 05:42
Thanks, Jim, Marco, and Raymond :)
msg286744 - (view) Author: Roundup Robot (python-dev) (Python triager) Date:
New changeset 848eeb1debc94a82660bf5af4e3d554b02b81c2e by Mariatta Wijaya in branch '3.6':
Issue #29381: Clarify ordering of UNIX shebang line as source encoding line
https://github.com/python/cpython/commit/848eeb1debc94a82660bf5af4e3d554b02b81c2e
msg286745 - (view) Author: Roundup Robot (python-dev) (Python triager) Date:
New changeset 3f5b24dd4b38bf885a80f4bb5f605cd6b0c49ead by Mariatta Wijaya in branch '2.7':
Issue #29381: Clarify ordering of UNIX shebang line as source encoding line
https://github.com/python/cpython/commit/3f5b24dd4b38bf885a80f4bb5f605cd6b0c49ead
msg286746 - (view) Author: Roundup Robot (python-dev) (Python triager) Date:
New changeset abfa17511f7ce8f1a6394f28f82ffb9a916fcf03 by Mariatta Wijaya in branch 'master':
Issue #29381: Clarify ordering of UNIX shebang line as source encoding line
https://github.com/python/cpython/commit/abfa17511f7ce8f1a6394f28f82ffb9a916fcf03

New changeset 848eeb1debc94a82660bf5af4e3d554b02b81c2e by Mariatta Wijaya in branch 'master':
Issue #29381: Clarify ordering of UNIX shebang line as source encoding line
https://github.com/python/cpython/commit/848eeb1debc94a82660bf5af4e3d554b02b81c2e

New changeset 35519d021ece942efc4a710ea3e94bcc5c06b130 by Mariatta Wijaya in branch 'master':
Issue #29381: merge with 3.6
https://github.com/python/cpython/commit/35519d021ece942efc4a710ea3e94bcc5c06b130
History
Date User Action Args
2017-02-02 06:00:28python-devsetmessages: + msg286746
2017-02-02 06:00:24python-devsetmessages: + msg286745
2017-02-02 06:00:22python-devsetmessages: + msg286744
2017-02-02 05:42:58Mariattasetmessages: + msg286743
2017-02-02 05:21:16python-devsetmessages: + msg286742
2017-02-02 05:04:01python-devsetmessages: + msg286738
2017-02-02 05:00:23python-devsetstage: resolved
2017-02-02 05:00:23python-devsetresolution: fixed
2017-02-02 05:00:23python-devsetstatus: open -> closed
2017-02-02 05:00:22python-devsetmessages: + msg286737
2017-02-02 04:21:39python-devsetnosy: + python-dev
messages: + msg286736
2017-01-31 03:23:42rhettingersetmessages: + msg286509
versions: - Python 3.4, Python 3.5
2017-01-31 03:22:15rhettingersetmessages: + msg286508
2017-01-31 01:45:01Mariattasetfiles: + issue29381v3.patch

messages: + msg286502
2017-01-30 12:14:29Jim Fasarakis-Hilliardsetmessages: + msg286488
2017-01-30 10:17:23marco.buttusetmessages: + msg286481
2017-01-30 03:33:40Mariattasetfiles: + issue29381v2.patch

messages: + msg286470
2017-01-30 03:03:02rhettingersetmessages: + msg286468
2017-01-30 02:13:42Mariattasetfiles: + issue29381.patch

messages: + msg286465
2017-01-29 01:25:25rhettingersetmessages: + msg286424
2017-01-28 16:55:13Jim Fasarakis-Hilliardsetmessages: + msg286415
2017-01-28 16:39:15marco.buttusetnosy: + marco.buttu
messages: + msg286414
2017-01-28 12:09:12Jim Fasarakis-Hilliardsetmessages: + msg286410
2017-01-27 22:25:15rhettingersetassignee: docs@python -> Mariatta

messages: + msg286388
nosy: + Mariatta, rhettinger
2017-01-27 17:20:26Jim Fasarakis-Hilliardsetfiles: + interpreter_tut2.7.patch
title: Tutorial documentation contains undefined reference -> Tutorial documentation contains undefined reference to #!
2017-01-27 17:20:02Jim Fasarakis-Hilliardcreate