[docs] [issue13538] Docstring of str() and/or behavior

[Guillaume Bouchard]

Guillaume Bouchard <guillaum.bouchard at gmail.com> added the comment:

> str always falls back to the repr; in general str(obj) should always return some value, otherwise the assumptions of a *lot* of Python code would be broken.

Perhaps it may raises a warning ?

ie, the only reason encoding exists if for the conversion of bytes (or something which looks like bytes) to str. Do you think it may be possible to special case the use of str for bytes (and bytesarray) with something like this:

def str(object, encoding=None, errors=None):
    if encoding is not None:
         # usual work
    else:
       if isinstance(object, (bytes, bytesarray)):
             warning('Converting bytes/bytesarray to str without encoding, it may not be what you expect')
             return object.__str__()

But by the way, adding warnings and special case everywhere seems not too pythonic.

> Do you want to propose a doc patch?

The docstring for str() should looks like something like, in my frenglish way of writing english ::

  Create a new string object from the given encoded string.

  If object is bytes, bytesarray or a buffer-like object, encoding and error
  can be set. errors can be 'strict', 'replace' or 'ignore' and defaults to
  'strict'.

  WARNING, if encoding is not set, the object is converted to a nicely
  printable representation, which is totally different from what you may expect.

Perhaps a warning may be added in the on-line documentation, such as ::

  .. warning::
     When str() converts a bytes/bytesarray or a buffer-like object and
     *encoding* is not specified, the result will an unicode nicely printable
     representation, which is totally different from the unicode representation of
     you object using a specified encoding.

Whould you like a .diff on top of the current mercurial repository ?

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13538>
_______________________________________