[New-bugs-announce] [issue3565] array documentation, method names not 3.0 compliant

[Matt Giuca]

New submission from Matt Giuca <matt.giuca at gmail.com>:

A few weeks ago I fixed the struct module's documentation which wasn't
3.0 compliant (basically renaming "strings" to "bytes" and "unicode" to
"string"). Now I've had a look at the array module, and it's got similar
problems.

http://docs.python.org/dev/3.0/library/array.html

Unfortunately, the method names are wrong as far as Py3K is concerned.
"tostring" returns what is now called a "bytes", and "tounicode" returns
what is now called a "string".

There are a few other errors in the documentation too, like the 'c' type
code (which no longer exists, but is still documented), and examples
using Python 2 syntax. Those are trivial to fix.

I suggest a 3-step process for fixing this:
1. Update the documentation to describe the 3.0 behaviour using 3.0
terminology, even though the method names are wrong (I've done this
already).
2. Rename "tostring" and "fromstring" methods to "tobytes" and
"frombytes". I think this is quite important as the value being returned
can no longer be described as a "string".
3. Rename "tounicode" and "fromunicode" methods to "tostring" and
"fromstring". I think this is less important, as the name "unicode"
isn't ambiguous, and potentially undesirable, as we'd be re-using method
names which previously did something else.

I'm aware we've got the final beta in 4 days, and there's no way my
phase 2-3 can be done after that. I think we should aim to do phase 2,
but probably not phase 3.

I've fixed the documentation to accurately describe the current
behaviour, using Python 3 terminology. This doesn't change any behaviour
at all, so it should be able to be committed immediately.

I'll have a go at a "phase 2" patch shortly. Is it feasible to even
think about renaming a method at this stage?

Commit log:

Doc/library/array.rst, Modules/arrayobject.c:

Updated array module documentation to be Python 3.0 compliant.

* Removed references to 'c' type code (no longer valid).
* References to "string" changed to "bytes".
* References to "unicode" changed to "string".
* Updated examples to use Python 3.0 syntax (and show the output of
evaluating them).

----------
assignee: georg.brandl
components: Documentation, Interpreter Core
files: doc-only.patch
keywords: patch
messages: 71201
nosy: georg.brandl, mgiuca
severity: normal
status: open
title: array documentation, method names not 3.0 compliant
versions: Python 3.0
Added file: http://bugs.python.org/file11121/doc-only.patch

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