A diff would be great.

We try to use warnings sparingly, and I don't think this is a case that warrants it.  Possibly a .. note is worthwhile, perhaps with an example for the bytes case, but even that may be too much.

I also wouldn't use the wording "is totally different from what you would expect", since by now I do expect it :).  How about something like "the result will not be the decoded version of the bytes, but instead will be the repr of the object", with a cross link to repr.