classification
Title: Wrong documentation for PyUnicode_FromObject() and PyUnicode_FromEncodedObject()
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: martin.panter Nosy List: docs@python, ezio.melotti, kyle.roberts, martin.panter, paul.moore, python-dev, r.david.murray, serhiy.storchaka, steve.dower, supriyanto maftuh, tim.golden, vstinner, zach.ware
Priority: normal Keywords: easy, patch

Created on 2012-09-20 16:18 by serhiy.storchaka, last changed 2016-04-15 04:48 by martin.panter. This issue is now closed.

Files
File name Uploaded Description Edit
from_object.patch kyle.roberts, 2013-04-07 04:27 review
from_object_v2.patch kyle.roberts, 2013-05-01 02:23 review
from_object_v3.patch martin.panter, 2016-04-10 04:10 review
from_object_v4.patch martin.panter, 2016-04-13 11:18 review
Messages (17)
msg170821 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-09-20 16:18
In the documentation it is written that PyUnicode_FromObject() is a shortcut for PyUnicode_FromEncodedObject(). But PyUnicode_FromObject() is not call PyUnicode_FromEncodedObject() direct nor indirect. PyUnicode_FromObject() works only with unicode and unicode subclass objects, PyUnicode_FromEncodedObject() is not works with unicode objects.
msg173661 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-10-24 09:43
This is a bug of 2 -> 3 transition.
msg186177 - (view) Author: Kyle Roberts (kyle.roberts) Date: 2013-04-07 04:27
I made a change to the documentation to reflect PyUnicode_FromObject()'s change in implementation details. Let me know if the wording is off or more information is needed. Thanks!
msg188172 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2013-04-30 17:20
In the "Otherwise it coerces" sentence, obj should probably be ``obj``.
msg188176 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-04-30 19:03
So (speaking from C API ignorance here), if you pass it a unicode subclass you get back an instance of the base unicode type?  Is that what coercion means here?
msg188179 - (view) Author: Kyle Roberts (kyle.roberts) Date: 2013-04-30 19:30
Thanks for the quick responses.

Brian: Nice catch, I'll add the ``obj`` shortly.

R. David: You're correct, that's exactly what happens, and what coercion means here. The language is almost the same as PyUnicode_FromEncodedObject()'s documentation, but if it's unclear I don't mind changing both. The code's comment offers another way of describing the "type modification":

/* For a Unicode subtype that's not a Unicode object, return a true Unicode object with the same data. */
msg188180 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-04-30 19:43
Perhaps we should correct a documentation for PyUnicode_FromEncodedObject() too. Coercing doesn't look as right term for decoding.
msg188201 - (view) Author: Kyle Roberts (kyle.roberts) Date: 2013-05-01 02:23
I've uploaded a new patch with the obj argument properly marked up. Brian, I think *obj* is what we want based on other examples in that file. It looks like italics is typically used when discussing parameters since each parameter is italicized in the signature.

R.David and Serhiy, I thought about the use of "coercion" some more and I think the current wording is fine. "Type coercion/conversion" is a commonly used phrase with some languages, so I think the phrase is applicable here as well (for a python example: http://docs.python.org/release/2.5.2/ref/coercion-rules.html). Let me know if you'd still like to see it changed. Thanks.
msg188303 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-05-03 15:16
Well, while 'coercion' does refer to changing from one type to another, and technically we are doing that here, in OO we generally think of subclasses as more-or-less being of the same type as the superclass.  So I think it would be clearer to spell out that we are changing the object type to be that of the superclass.
msg188310 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-05-03 17:24
In other languages usually the world "coercion" is used for implicit conversion, i.e. int->long, int->float, float->complex. str->unicode in Python 2 (that's what PyUnicode_FromObject() does). But the last conversion is not supported in Python 3. The term "coercion" has also been used in Python 2 in the narrow sense (see the __coerce__() method), and in this sense Python 3 does not support "coercion". Therefore, I believe that it is better to avoid the use of this term.
msg263123 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-10 03:55
Here is a modified patch that avoids “coercion” and is hopefully more explicit. I also fixed the comment in Include/unicodeobject.h.
msg263129 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-04-10 11:07
Added a comment on Rietveld.
msg263325 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-13 11:18
Here is a new version where I use the phrase “true Unicode object”.
msg263329 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-04-13 11:57
LGTM. Thank you Martin for this improvement.
msg263399 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2016-04-14 12:25
from_object_v4.patch LGTM, nice enhancement.
msg263439 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-04-15 03:35
New changeset af655e73f7bd by Martin Panter in branch '3.5':
Issue #15984: Correct PyUnicode_FromObject() and _FromEncodedObject() docs
https://hg.python.org/cpython/rev/af655e73f7bd

New changeset 570ada02d0f0 by Martin Panter in branch 'default':
Issue #15984: Merge PyUnicode doc from 3.5
https://hg.python.org/cpython/rev/570ada02d0f0
msg263446 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-15 04:48
I also tweaked the PyUnicode_FromEncodedObject() documentation to avoid the word “coerce” and to fix up outdated stuff.
History
Date User Action Args
2016-04-15 04:48:08martin.pantersetstatus: open -> closed
resolution: fixed
messages: + msg263446

stage: commit review -> resolved
2016-04-15 03:35:29python-devsetnosy: + python-dev
messages: + msg263439
2016-04-14 12:25:57vstinnersetmessages: + msg263399
2016-04-13 11:57:41serhiy.storchakasetassignee: docs@python -> martin.panter
messages: + msg263329
stage: patch review -> commit review
2016-04-13 11:18:43martin.pantersetfiles: + from_object_v4.patch

messages: + msg263325
2016-04-12 19:05:58zach.waresethgrepos: - hgrepo341
2016-04-12 16:42:39berker.peksagsetcomponents: - Build, Tests, Unicode, Windows, XML
2016-04-12 15:59:06brian.curtinsetnosy: - brian.curtin
2016-04-12 15:58:43supriyantomaftuhsetnosy: + paul.moore, ezio.melotti, supriyanto maftuh, tim.golden, zach.ware, steve.dower

components: + Build, Tests, Unicode, Windows, XML
hgrepos: + hgrepo341
2016-04-10 11:07:45serhiy.storchakasetmessages: + msg263129
2016-04-10 04:10:05martin.pantersetfiles: + from_object_v3.patch
2016-04-10 04:08:20martin.pantersetfiles: - from_object_v3.patch
2016-04-10 03:55:08martin.pantersetfiles: + from_object_v3.patch
versions: + Python 3.5, Python 3.6, - Python 3.3, Python 3.4
nosy: + martin.panter

messages: + msg263123

stage: needs patch -> patch review
2013-05-03 17:24:22serhiy.storchakasetmessages: + msg188310
2013-05-03 15:16:41r.david.murraysetmessages: + msg188303
2013-05-02 21:20:30vstinnersetnosy: + vstinner
2013-05-01 02:23:12kyle.robertssetfiles: + from_object_v2.patch

messages: + msg188201
2013-04-30 19:43:48serhiy.storchakasetmessages: + msg188180
title: Wrong documentation for PyUnicode_FromObject() -> Wrong documentation for PyUnicode_FromObject() and PyUnicode_FromEncodedObject()
2013-04-30 19:30:47kyle.robertssetmessages: + msg188179
2013-04-30 19:03:40r.david.murraysetnosy: + r.david.murray
messages: + msg188176
2013-04-30 17:23:14terry.reedysetversions: - Python 3.2
2013-04-30 17:20:23brian.curtinsetnosy: + brian.curtin
messages: + msg188172
2013-04-07 04:27:25kyle.robertssetfiles: + from_object.patch

nosy: + kyle.roberts
messages: + msg186177

keywords: + patch
2013-01-15 18:30:15serhiy.storchakasetkeywords: + easy
2012-10-24 09:43:12serhiy.storchakasettype: enhancement
messages: + msg173661
versions: + Python 3.2, Python 3.4
2012-10-24 09:39:47serhiy.storchakasetstage: needs patch
2012-09-20 16:18:26serhiy.storchakacreate