[docs] [issue3565] array documentation, method names not 3.x-compliant

[Matt Giuca]

Matt Giuca <matt.giuca at gmail.com> added the comment:

There are still some inconsistencies in the documentation (in particular, incorrectly using the word "string" to refer to a bytes object, which made sense in Python 2 but not 3), which I fixed in my doc-only.patch file that's coming up to its third birthday.

Most of it has been fixed with the previous change which added 'tobytes' and 'frombytes' and made tostring and fromstring aliases. But there are some places which don't make sense:

array: "If given a list or string" needs to be "If given a list, bytes or string" (since a bytes is not a string).
frombytes: "Appends items from the string" needs to be "Appends items from the bytes object", since this does not work if you give it a string.

Less importantly, I also recommended renaming "unicode string" to just "string", since in Python 3 there is no such thing as a non-unicode string. For instance, there is an example that uses a variable named "unicodestring" that could be renamed to just "string".

> Indeed, not only it would bring little benefit, but may also confuse
> users porting from 2.x (since the from/tostring methods would then
> have a totally different meaning).
Well, by that logic, you shouldn't have renamed "unicode" to "str" since that would also confuse users porting from 2.x. It generally seems like a good idea in Python 3 to rename all mentions of "string" to "bytes" and all mentions of "unicode" to "string", so as to be consistent with the new names of the types (it is better to be internally consistent than consistent with the previous version).

Though I do agree that it would be chaos to rename array.from/tounicode to from/tostring now, given that array.from/tostring already has a different meaning in Python 3.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue3565>
_______________________________________