classification
Title: bytes and bytearray methods are not documented
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, berker.peksag, docs@python, eric.araujo, ezio.melotti, ncoghlan, terry.reedy, xuanji
Priority: normal Keywords:

Created on 2010-12-14 17:26 by belopolsky, last changed 2014-09-27 20:09 by berker.peksag. This issue is now closed.

Messages (5)
msg123960 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-12-14 17:26
Library reference manual has a section dedicated to string methods [1], but similar methods of bytes and bytearray types are not documented.  Adding two new sections would probably be too repetitious, so I wonder if it would make sense to add notes about byte/bytearray methods to the matching string methods' entries.  See also issue10587.

[1] http://docs.python.org/dev/py3k/library/stdtypes.html#string-methods
msg124053 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-15 19:36
I was persuaded there was already a bug open with a patch adding bytes and bytearray in the sequence methods table, but I can’t find it.
msg124060 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-12-15 20:05
> I was persuaded there was already a bug open with a patch adding
> bytes and bytearray in the sequence methods table, but I can’t find it.

I can't find it either, but this issue is different.  I propose renaming "String Methods" to "String, bytes and bytearray methods" and 


str.capitalize()
bytes.capitalize()
bytearray.capitalize()

Return a copy of the string with its first character capitalized and the rest lowercased.  [Discuss Unicode vs bytes details.]

BTW, the "For 8-bit strings, this method is locale-dependent." part is probably out of date because bytes.capitalize() seems to pass non-ASCII bytes through:

>>> bytes([ord('è')]).capitalize()[0] == ord('è')
True

and for unicode strings the operation is *not* locale dependent.
msg124353 - (view) Author: Xuanji Li (xuanji) * Date: 2010-12-19 14:14
Hi, it seems to me that section 4.6.5. Bytes and Byte Array Methods covers this already. It says:

Bytes and bytearray objects, being “strings of bytes”, have all methods found on strings, with the exception of encode(), format() and isidentifier(), which do not make sense with these types. For converting the objects to strings, they have a decode() method.

Wherever one of these methods needs to interpret the bytes as characters (e.g. the is...() methods), the ASCII character set is assumed.

This section covers belpolsky's needs, ie a reader can, from this, understand that bytes have a capitalize method. However, I support

1) Expanding this section to explain more clearly what the methods do to bytes
2) Discuss unicode vs bytes details
3) Mention bytes and bytearrays in 4.6.1 String Methods, because it is quite far away from 4.6.5

As for the suggestion of renaming, if we rename the section, we have to decide what to call a string/byte/bytearray object because it now says, for example, str.something(); also we have to document the encode and decode methods seperately because they are not common to strings and bytes.
msg227720 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-09-27 20:09
Fixed in issue 21777.
History
Date User Action Args
2014-09-27 20:09:20berker.peksagsetstatus: open -> closed

nosy: + berker.peksag
messages: + msg227720

resolution: out of date
stage: needs patch -> resolved
2012-08-09 13:28:02ezio.melottisetnosy: + ncoghlan, ezio.melotti
stage: needs patch
type: enhancement

versions: + Python 3.3, Python 3.4
2010-12-19 14:14:25xuanjisetnosy: terry.reedy, belopolsky, eric.araujo, docs@python, xuanji
messages: + msg124353
2010-12-19 13:27:37xuanjisetnosy: + xuanji
2010-12-17 23:31:46terry.reedysetnosy: + terry.reedy
2010-12-15 20:05:00belopolskysetnosy: belopolsky, eric.araujo, docs@python
messages: + msg124060
2010-12-15 19:36:10eric.araujosetnosy: + eric.araujo
messages: + msg124053
2010-12-14 17:26:03belopolskycreate