Besides the functionality that click provides to interface with argument parsing and handling, it also provides a bunch of addon functionality that is useful for writing command line utilities.

Printing to Stdout

The most obvious helper is the echo() function which in many ways works like the Python print statement or function. The main difference is that it works the same on Python 2 and 3 and it intelligently detects misconfigured output streams and will never fail (except on Python 3, for more information see Python 3 Limitations).


import click

click.echo('Hello World!')

Most importantly it can print both unicode and binary data, unlike the builtin print function on Python 3 which cannot output any bytes. It will however emit a trailing newline by default which needs to be supressed by passing nl=False:

click.echo(b'\xe2\x98\x83', nl=False)

Printing Filenames

Because filenames might not be unicode formatting them can be a bit tricky. Generally this is easier on Python 2 than 3 as you can just write the bytes to stdout with the print function, but at least on Python 3 you will need to always operate in unicode.

The way this works with click is through the format_filename() function. It does a best effort conversion of the filename to Unicode and will never fail. This makes it possible to use these filenames in the context of a full unicode string.


click.echo('Path: %s' % click.format_filename(b'foo.txt'))

Standard Streams

For command line utilities it’s very important to get access to input and output streams reliably. Python generally provides access to these streams through sys.stdout and friends, but unfortunately there are API differences between 2.x and 3.x. Especially in regards to how these streams respond to unicode and binary data there are wide differences.

Because of this click provides the get_binary_stream() and get_text_stream() which produce consistent results with different Python versions and for widely misconfigured terminals.

The end result is that these functions will always return a functional stream object (except in very odd cases on Python 3, see Python 3 Limitations).


import click

stdin_text = click.get_text_stream('stdin')
stdout_binary = click.get_binary_stream('stdout')