Title: Fix doc of Py_CompileStringExFlags
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, docs@python, python-dev, vstinner, xiang.zhang
Priority: normal Keywords: patch

Created on 2016-08-11 18:13 by xiang.zhang, last changed 2016-09-28 16:34 by berker.peksag. This issue is now closed.

File name Uploaded Description Edit
Py_CompileStringExFlags_doc.patch xiang.zhang, 2016-08-12 11:18 review
issue27740.patch xiang.zhang, 2016-08-27 19:41 review
Messages (6)
msg272468 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2016-08-11 18:13
I think the doc of Py_CompileStringExFlags has two flaws:

1. Py_CompileStringExFlags should be replaced by Py_CompileStringObject from the context. Py_CompileStringExFlags in the context is meaningless.

2. *filename* is a byte string that should be decoded but not decoded from. It is ... = decode(filename) but not filename = decode(...).
msg273130 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2016-08-19 14:53
msg273137 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-08-19 15:45
I don't understand the second part of the patch.

    *filename* is a filesystem encoding (:func:`os.fsdecode`) encoded string [...]

Do you want to document that filename should be encoded by using PyUnicode_EncodeFSDefault *before* passing it to Py_CompileStringExFlags (you will probably need to wrap it with something like PyBytes_AsString too)? If so, I think the os.fsdecode() part needs to be changed to os.fsencode().

I think the current wording is saying that filename is going to be decoded inside of Py_CompileStringExFlags (which is also correct.)
msg273139 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2016-08-19 15:55
> filename is going to be decoded inside of Py_CompileStringExFlags

Actually all I want to express is this, *filename* will be decoded inside. But now the wording looks to me is that *filename* is already a decoded string when passed. I don't want to document anything about PyUnicode_EncodeFSDefault. I should remove (:func:`os.fsdecode`). How do you think? I'm Okay if you think the current wording is correct.
msg273798 - (view) Author: Xiang Zhang (xiang.zhang) * (Python committer) Date: 2016-08-27 19:41
I am not a native speaker so I decide not to trap in the minor part. Could you just fix the first point if there is no doubt? I'm okay with the second part staying as now.
msg277645 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-09-28 16:34
New changeset ee76e84f115f by Berker Peksag in branch '3.5':
Issue #27740: Fix typo in Py_CompileStringExFlags

New changeset 2ee939b314a2 by Berker Peksag in branch '3.6':
Issue #27740: Merge from 3.5

New changeset a0b13ea75849 by Berker Peksag in branch 'default':
Issue #27740: Merge from 3.6
Date User Action Args
2016-09-28 16:34:55berker.peksagsetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.7
2016-09-28 16:34:34python-devsetnosy: + python-dev
messages: + msg277645
2016-08-27 19:41:35xiang.zhangsetfiles: + issue27740.patch

messages: + msg273798
2016-08-19 15:55:38xiang.zhangsetmessages: + msg273139
2016-08-19 15:45:35berker.peksagsetversions: + Python 3.5
nosy: + berker.peksag, vstinner

messages: + msg273137

stage: patch review
2016-08-19 14:53:30xiang.zhangsetmessages: + msg273130
2016-08-12 11:18:04xiang.zhangsetfiles: + Py_CompileStringExFlags_doc.patch
2016-08-12 11:17:50xiang.zhangsetfiles: - Py_CompileStringExFlags_doc.patch
2016-08-11 18:13:23xiang.zhangcreate