[New-bugs-announce] [issue3220] Improve Bytes and Byte Array Methods doc
Terry J. Reedy
report at bugs.python.org
Fri Jun 27 21:47:12 CEST 2008
New submission from Terry J. Reedy <tjreedy at udel.edu>:
Lib Ref/Built-in Types/Sequence Types/Bytes and Byte Array Methods
The following set/frozenset and dict sections repeat (and for dicts,
expands upon) the constructor interface from the Built-in Functions
section. The sequence type sections do not. There should as least be a
reference back. "For the constructor interface, see xxx"
Similarly there is no mention here of the difference between bytes and
bytearray, as there is below for the difference between set and
frozenset. I think there should be here, in this section, even though
there is back in Built-in Functions.
(Sets/frozenset have the opposite problem in that Built-in Functions
makes no mention that one is mutable and the other is not. I also think
just one word for each should be added there too.)
"The bytes and bytearray types have an additional class method:
bytes.fromhex(string) " should be followed by
"This bytes class method returns a bytes object," changed to
"These class methods return a bytes or bytearray object,"
I don't think the line 'Example:' is needed.
A thread today on the Py3 lists again brought up the issue that just as
bytes can be created by either a literal or class call, they could be
represented on output by either, with possible confusion.
> Only if you didn't know that b'' is an alternative to bytes(). The b''
> notation is so much more compact and so much more helpful that I
> really don't want to go back to it. We will somehow have to deal with
> this through education and documentation.
I suggest adding at the end:
"Just as a bytes objects can be constructed either with a literal or a
class constructor call, they could be represented on output either by a
literal or class constructor call. The literal was chosen as being
shorter, generally more useful, and consistent with how other classes
are displayed. Similarly, the display of bytearrays uses the
corresponding bytes literal. If you want to see the bytes of either
class as integers, use tuple.
>>> a, b = b'abc', bytes((1,2,3))
>>> tuple(a), tuple(b)
((97, 98, 99), (1, 2, 3))
>>> c = bytearray(a)
>>> c, tuple(c)
(bytearray(b'abc'), (97, 98, 99))
nosy: georg.brandl, tjreedy
title: Improve Bytes and Byte Array Methods doc
versions: Python 3.0
Python tracker <report at bugs.python.org>
More information about the New-bugs-announce