classification
Title: Wrong C API documentation for locale encoding
Type: behavior Stage: resolved
Components: Documentation, Unicode Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: asvetlov, berker.peksag, docs@python, ezio.melotti, python-dev, serhiy.storchaka, vstinner
Priority: normal Keywords: patch

Created on 2012-10-25 13:57 by serhiy.storchaka, last changed 2012-11-29 13:25 by asvetlov. This issue is now closed.

Files
File name Uploaded Description Edit
issue16323.patch berker.peksag, 2012-10-27 17:37 review
issue16323_v2.patch berker.peksag, 2012-10-28 18:16 review
Messages (12)
msg173760 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-10-25 13:57
The documentation for PyUnicode_DecodeLocale() and PyUnicode_EncodeLocale() are wrong. The second parameter described as "int surrogateescape", but actually it is "const char *errors".
msg173949 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2012-10-27 17:37
Also, the documentation for PyUnicode_DecodeLocaleAndSize() is wrong. Patch attached.

Related changeset: http://hg.python.org/cpython/rev/07802351ccad
msg173954 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-10-27 18:08
Victor, you forgot to update the documentation.
msg173962 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2012-10-27 19:06
"Encode a Unicode object to the current locale encoding. The encoder is strict if *errors* is equal to ``strict``, otherwise it uses the ``'surrogateescape'`` error handler (:pep:`383`)."

Hum, this is not correct. There are three valid values:
 - NULL: strict
 - "strict": strict
 - "surrogateescape": use PEP 383
msg174066 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2012-10-28 18:16
> Hum, this is not correct. There are three valid values:
>  - NULL: strict
>  - "strict": strict
>  - "surrogateescape": use PEP 383

Thanks for the correction, Victor. Here's the updated patch.
msg176530 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-28 10:34
New changeset 11629c14ce1f by Andrew Svetlov in branch '3.3':
Issue #16323: Fix wrong C API documentation for locale encoding.
http://hg.python.org/cpython/rev/11629c14ce1f

New changeset 6f3d3003acf3 by Andrew Svetlov in branch 'default':
Merge issue #16323: Fix wrong C API documentation for locale encoding.
http://hg.python.org/cpython/rev/6f3d3003acf3
msg176531 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-11-28 10:35
Fixed. Thanks.
msg176535 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-11-28 12:22
I think the sentence "If a byte sequence can be decoded as a surrogate character and *errors* is not ``"strict"``, then the byte sequence is escaped using the ``"surrogateescape"`` error handler instead of being decoded." is redundant.
msg176539 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-11-28 12:37
Really I don't know what's better. Victor, what do you think?
msg176547 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2012-11-28 15:00
"If a byte sequence can be decoded as a surrogate character and
*errors* is not ``"strict"``, then the byte sequence is escaped using
the ``"surrogateescape"`` error handler instead of being decoded."

I don't understand this sentence but it sounds to be wrong. The
"surrogateescape" is only used if errors="surrogateescape"...

If errors is set and is different to "strict" and "surrogateescape",
an error is raised.

2012/11/28 Andrew Svetlov <report@bugs.python.org>:
>
> Andrew Svetlov added the comment:
>
> Really I don't know what's better. Victor, what do you think?
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue16323>
> _______________________________________
msg176647 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-29 13:23
New changeset af45e9ec35f0 by Andrew Svetlov in branch '3.3':
Remove redundant sentence from c-api docs (issue #16323)
http://hg.python.org/cpython/rev/af45e9ec35f0

New changeset efedd0f62a7e by Andrew Svetlov in branch 'default':
Merge: remove redundant sentence from c-api docs (issue #16323)
http://hg.python.org/cpython/rev/efedd0f62a7e
msg176648 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-11-29 13:25
Removed bad sentence.
History
Date User Action Args
2012-11-29 13:25:08asvetlovsetmessages: + msg176648
2012-11-29 13:23:55python-devsetmessages: + msg176647
2012-11-28 15:00:06vstinnersetmessages: + msg176547
2012-11-28 12:37:30asvetlovsetmessages: + msg176539
2012-11-28 12:22:38serhiy.storchakasetmessages: + msg176535
2012-11-28 10:35:05asvetlovsetstatus: open -> closed

nosy: + asvetlov
messages: + msg176531

resolution: fixed
stage: patch review -> resolved
2012-11-28 10:34:39python-devsetnosy: + python-dev
messages: + msg176530
2012-11-16 17:25:08serhiy.storchakasetstage: needs patch -> patch review
2012-10-28 18:16:14berker.peksagsetfiles: + issue16323_v2.patch

messages: + msg174066
2012-10-27 19:06:53vstinnersetmessages: + msg173962
2012-10-27 18:08:13serhiy.storchakasetnosy: + vstinner
messages: + msg173954
2012-10-27 17:37:58berker.peksagsetfiles: + issue16323.patch

nosy: + berker.peksag
messages: + msg173949

keywords: + patch
2012-10-25 13:57:34serhiy.storchakacreate