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
"bytearray.fromhex(string)" and
"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.
Guido responded
> 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))
>>> a,b
(b'abc', b'\x01\x02\x03')
>>> tuple(a), tuple(b)
((97, 98, 99), (1, 2, 3))
>>> c = bytearray(a)
>>> c, tuple(c)
(bytearray(b'abc'), (97, 98, 99))
"

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

Right -- I need to reorganize that section a bit more, and this is on
the list to do.

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

The difference is mentioned under the "sequence types" heading.

> (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
> "bytearray.fromhex(string)" and
> "This bytes class method returns a bytes object," changed to
> "These class methods return a bytes or bytearray object,"

Agreed.

> I don't think the line 'Example:' is needed.

Yep.

> 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.
> Guido responded
> > 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))
> >>> a,b
> (b'abc', b'\x01\x02\x03')
> >>> tuple(a), tuple(b)
> ((97, 98, 99), (1, 2, 3))
> >>> c = bytearray(a)
> >>> c, tuple(c)
> (bytearray(b'abc'), (97, 98, 99))
> "

The same section that documents the bytes/bytearray difference also already
mentions this; I've amended it a bit to include the bit about
representation.

Committed changes as r64627.