[docs] Improve doc for str(bytesobject) (issue 13538)

[chris.jerdonek at gmail.com]

Thanks for the positive feedback, Éric! :)  The patch has gone through
several iterations and Ezio deserves a fair bit of credit, too.



http://bugs.python.org/review/13538/diff/6630/Doc/library/functions.rst
File Doc/library/functions.rst (right):

http://bugs.python.org/review/13538/diff/6630/Doc/library/functions.rst#newcode537
Doc/library/functions.rst:537: effect as calling :func:`str(value)
<str>`.
On 2012/11/20 05:12:21, eric.araujo wrote:
> FYI: In a recent-ish discussion, Georg indicated his distaste for
mixing func
> and code markup like this.  For this instance it looks okay, if there
are no
> other links to str in the surrounding text.

In this case, including the code is important because it specifies which
form of the str() invocation takes effect.  In any case, I would be
curious to learn more about Georg's opinions and rationale on that.

http://bugs.python.org/review/13538/diff/6630/Doc/library/functions.rst#newcode1258
Doc/library/functions.rst:1258: str(object=b'', encoding='utf-8',
errors='strict')
On 2012/11/20 05:12:21, eric.araujo wrote:
> Shouldn’t the default value be '' here?

No, because that would throw a TypeError:

 >>> str('', encoding='utf-8')
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
 TypeError: decoding str is not supported

The default value in the second signature is a good visual cue that the
second form of the invocation requires a bytes/bytearray/etc object.

http://bugs.python.org/review/13538/diff/6630/Doc/library/functions.rst#newcode1258
Doc/library/functions.rst:1258: str(object=b'', encoding='utf-8',
errors='strict')
On 2012/11/20 05:12:21, eric.araujo wrote:
> I think the doc should say whether keyword args are supported.

I will add this.

http://bugs.python.org/review/13538/diff/6630/Doc/library/functions.rst#newcode1267
Doc/library/functions.rst:1267: the string itself.  If *object* does not
have an :meth:`object.__str__`
On 2012/11/20 05:12:21, eric.araujo wrote:
> People are going to comment on “a __str__ method” vs. “an __str__
method”,
> depending on whether and how you pronounce the underscores :)

Indeed.  I remember this python-dev thread quite clearly :)

http://mail.python.org/pipermail/python-dev/2012-August/121214.html

Personally, I think of it yet another way: "an object dot str method."
:)

http://bugs.python.org/review/13538/diff/6630/Doc/library/stdtypes.rst
File Doc/library/stdtypes.rst (right):

http://bugs.python.org/review/13538/diff/6630/Doc/library/stdtypes.rst#newcode2085
Doc/library/stdtypes.rst:2085: the :ref:`buffer protocol
<bufferobjects>` to access the memory of other
On 2012/11/20 05:12:21, eric.araujo wrote:
> Do you think a glossary entry would help?

I do!  But I know other core developers feel strongly about limiting
what words we add.  Perhaps we can create a new issue for this?  From
what I observed, I also know "buffer protocol" could use some more
internal linking, indexing, etc.

http://bugs.python.org/review/13538/