The documentation for PyUnicode_DecodeLocale() and PyUnicode_EncodeLocale() are wrong. The second parameter described as "int surrogateescape", but actually it is "const char *errors".

Also, the documentation for PyUnicode_DecodeLocaleAndSize() is wrong. Patch attached.

Related changeset: http://hg.python.org/cpython/rev/07802351ccad

Victor, you forgot to update the documentation.

"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

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

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

Fixed. Thanks.

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.

Really I don't know what's better. Victor, what do you think?

"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>
> _______________________________________

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

Removed bad sentence.