Input and Output tutorial erroneously references default encoding UTF-8

[jaraco]

BPO	24729
Nosy	@jaraco, @bitdancer, @willingc, @alessandrocucci
Files	issue24729.patch: Patch issue24729_v2.patch: Patch v2 issue24729_v3.patch: Patch v3 issue24729_v4.patch: Patch v4 issue24729_v4.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 = None
closed_at = <Date 2015-07-29.18:31:19.490>
created_at = <Date 2015-07-26.15:20:18.094>
labels = ['easy', 'expert-IO', 'docs']
title = 'Input and Output tutorial erroneously references default encoding UTF-8'
updated_at = <Date 2015-07-29.18:31:19.489>
user = 'https://github.com/jaraco'

bugs.python.org fields:

activity = <Date 2015-07-29.18:31:19.489>
actor = 'jaraco'
assignee = 'docs@python'
closed = True
closed_date = <Date 2015-07-29.18:31:19.490>
closer = 'jaraco'
components = ['Documentation', 'IO']
creation = <Date 2015-07-26.15:20:18.094>
creator = 'jaraco'
dependencies = []
files = ['40033', '40045', '40046', '40056', '40057']
hgrepos = []
issue_num = 24729
keywords = ['patch', 'easy']
message_count = 11.0
messages = ['247433', '247440', '247478', '247534', '247536', '247539', '247540', '247546', '247589', '247597', '247598']
nosy_count = 6.0
nosy_names = ['jaraco', 'r.david.murray', 'docs@python', 'python-dev', 'willingc', 'acucci']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'needs patch'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue24729'
versions = ['Python 3.4', 'Python 3.5', 'Python 3.6']

[jaraco]

In Doc/tutorial/inputoutput.rst, the docs state this about opening a file:

Normally, files are opened in :dfn:`text mode`, that means, you read and write
strings from and to the file, which are encoded in a specific encoding (the
default being UTF-8).

That statement is directly contradicted by the docs for open (Doc/library/functions.rst) which indicate:

In text mode, if encoding is not specified the encoding used is platform
dependent: locale.getpreferredencoding(False) is called to get the current
locale encoding.

The implementation matches the latter indication.

[alessandrocucci]

corrected

[bitdancer]

Hmm. It's a tutorial. It would probably be better to just say "the default is platform dependent" with a link to the open docs.

[alessandrocucci]

@r.david.murray: just like that? (see patch v2)

[bitdancer]

A direct link to open would be better ("see :func:`~functions.open`" should do it, I think).

[alessandrocucci]

tried again :)

[bitdancer]

Looks good to me assuming it renders correctly.

[willingc]

@acucci and R. David Murray: I've run the patch locally, and all renders well except for one link.

@acucci: I believe that the direct link to the open() command should be

... "see :func:`open` "

An example exists at the beginning of the section containing this line. The command in the current patch renders as plain text and not a link. If you can fix this small issue, the patch should be ready to merge (pending R David Murray's agreement). Thanks!

[alessandrocucci]

ok, this time I tested the render myself and seems ok. For rendering I used sphinx. Sorry if I didn't try the final result in the first time, but I've never had the chance to use rst files before.

[python-dev]

New changeset c9e78d91d588 by Alessandro Cucci in branch '3.4':
Issue bpo-24729: Update tutorial to match implementation.
https://hg.python.org/cpython/rev/c9e78d91d588

New changeset 20084be60761 by Jason R. Coombs in branch '3.4':
Issue bpo-24729: Correct reference to open function.
https://hg.python.org/cpython/rev/20084be60761

New changeset 575e60ed7cb8 by Jason R. Coombs in branch '3.5':
Merge with 3.4 for Issue bpo-24729
https://hg.python.org/cpython/rev/575e60ed7cb8

New changeset 47330144debd by Jason R. Coombs in branch 'default':
Merge with 3.5 for Issue bpo-24729
https://hg.python.org/cpython/rev/47330144debd

[jaraco]

Thanks for working through this Alessandro. I've applied your v3 patch and added a subsequent commit 20084be60761 to correct the open reference.