On Sun, Jul 13, 2014 at 7:00 PM, Nick Coghlan <report@bugs.python.org>
wrote:

>
> Nick Coghlan added the comment:
>
> On 13 Jul 2014 18:39, "Marc-Andre Lemburg" <report@bugs.python.org> wrote:
> >
> >
> > Marc-Andre Lemburg added the comment:
> >
> > Why are you removing guarantees like these from the str docs:
> >
> > "The original string is returned if *width* is less than or equal to
> ``len(s)``."
>
> Because it's untrue for bytearray, and possible object reuse is a general
> characteristic of immutability for str and bytes. If another implementation
> makes a copy for some reason, it would still be considered "Python".
>
> Since the sentence thus conveys no useful information, I removed it from
> both the text and binary variants rather than coming up with appropriate
> wording to indicate that the behaviour of returning a new reference to the
> existing object when no content changes are needed doesn't apply to the
> mutable bytearray.
>

That feels like overreacting. It *is* useful to know about this guarantee,
and it would be better if we could somehow require it rather than claim it
doesn't matter. And before you counter with examples of other CPython
behaviors that *shouldn't* be guaranteed across implementations, I am
talking about this specific case, and every case needs to be examined on
its merits separately. It is possible that in the end we'll decide this
particular guarantee is not worth having -- but I think that should not be
decided by a refactoring of the docs.