surrogateescape documentation

[abadger]

I got excited when I saw that python-future had surrogateescape support (something that is sorely missing in six). However, the documentation is mostly spotty about this and sometimes wrong.

• http://python-future.org/faq.html#which-versions-of-python-does-python-future-support Lists surrogateescape as a feature unimplemented on python2.6 but in my testing on a rhel6 box with python2.6.6 it seems to work.
• str(u'\udcff').encode('utf-8', 'surrogateescape') seems to work out of the box but bytes(b'\xff').decode('utf-8', 'surrogateescape') needs a prior call to future.utils.surrogateescape.register_surrogateescape() before it works.

This was all tested with future 0.14.1.

[edschofield]

Toshio, thanks for your feedback! I wasn't satisfied before that this was implemented satisfactorily, but if it's useful to you, it may be useful to others in its current form. So I've also enabled the surrogateescape handler for bytes decoding and documented it in v0.15.0, although it's currently labelled "alpha" quality .