Sometimes developers need to write text to stdout, and it's nice to have on the fly Unicode to UTF-8 conversion (or what matches the platform), but sometimes they also need to output binary blobs, like text encoded in other codifications than the system default, binary files, etc.

Python2 does the thing more-or-less right and allows writing both text and binary. I think Python3 should also accept both.

You can do

    sys.stdout.buffer.write(b"hello")

See

    http://docs.python.org/dev/library/io.html?highlight=buffer#io.TextIOBase.buffer

The fundamental behavior here is not going to change, as maintaining a bright line between bytes and strings is central to Python3's design.

The question is, does the method for achieving your goal need better documentation?

Rephrasing R.David's question: 

ntrrgc: Did you consult any documentation (browsing or searching), and if so, where did you look?

> You can do
>    sys.stdout.buffer.write(b"hello")

Note that this might not work when sys.stdout has been replaced with something else (e.g. a StringIO).

Sorry for the late response, GMail's SPAM filter ate the replies.

The main issue is sys.stdout being opened as text instead of binary. This fact is stated in the docs. http://docs.python.org/3/library/sys.html#sys.stdout

In any case, there are some caveats worth noting:

> You can do
>    sys.stdout.buffer.write(b"hello")
This is problematic if both buffer and IOTextWrapper are used. For example:

  print("Hello", end=""); sys.stdout.buffer.write(b"World")

That line may write `WorldHello` instead of `HelloWorld` (and it does indeed, at least in Linux implementation).

Yes, an application should not do this in Python3, but using print() and writing to stdout were OK in Python2, which makes porting programs harder.

A workaround is to perform sys.stdout.flush() before sys.stdout.buffer.write().

> (from the docs)
> Using io.TextIOBase.detach(), streams can be made binary by default.
> sys.stdout = sys.stdout.detach()

This should help in cases where most output is binary, but it's worth noting that interactive shells (such as the builtin python or IPython) and debuggers (both pdb and ipdb) stop working when this is used. Also, it will probably break every function there that relies on sys.stdout being Unicode or binary depending on only the Python version.

> A workaround is to perform sys.stdout.flush() before 
> sys.stdout.buffer.write().

FWIW you can just use print(..., flush=True) from 3.3+.