| msg68848 - (view) |
Author: Terry J. Reedy (terry.reedy) *  |
Date: 2008-06-27 19:47 |
| 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)) " |
|
|
| msg69064 - (view) |
Author: Georg Brandl (georg.brandl) * |
Date: 2008-07-01 20:08 |
| > 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. |
|
|