diff options
Diffstat (limited to 'docs/utils.rst')
| -rw-r--r-- | docs/utils.rst | 34 |
1 files changed, 12 insertions, 22 deletions
diff --git a/docs/utils.rst b/docs/utils.rst index 7dd8dbb..6338df9 100644 --- a/docs/utils.rst +++ b/docs/utils.rst @@ -13,9 +13,7 @@ Printing to Stdout The most obvious helper is the :func:`echo` function, which in many ways works like the Python ``print`` statement or function. The main difference is -that it works the same in Python 2 and 3, it intelligently detects -misconfigured output streams, and it will never fail (except in Python 3; for -more information see :ref:`python3-limitations`). +that it works the same in many different terminal environments. Example:: @@ -23,10 +21,8 @@ Example:: click.echo('Hello World!') -Most importantly, it can print both Unicode and binary data, unlike the -built-in ``print`` function in Python 3, which cannot output any bytes. It -will, however, emit a trailing newline by default, which needs to be -suppressed by passing ``nl=False``:: +It can output both text and binary data. It will emit a trailing newline +by default, which needs to be suppressed by passing ``nl=False``:: click.echo(b'\xe2\x98\x83', nl=False) @@ -34,19 +30,17 @@ Last but not least :func:`echo` uses click's intelligent internal output streams to stdout and stderr which support unicode output on the Windows console. This means for as long as you are using `click.echo` you can output unicode characters (there are some limitations on the default font -with regards to which characters can be displayed). This functionality is -new in Click 6.0. +with regards to which characters can be displayed). .. versionadded:: 6.0 -Click now emulates output streams on Windows to support unicode to the +Click emulates output streams on Windows to support unicode to the Windows console through separate APIs. For more information see :doc:`wincmd`. .. versionadded:: 3.0 -Starting with Click 3.0 you can also easily print to standard error by -passing ``err=True``:: +You can also easily print to standard error by passing ``err=True``:: click.echo('Hello World!', err=True) @@ -58,11 +52,10 @@ ANSI Colors .. versionadded:: 2.0 -Starting with Click 2.0, the :func:`echo` function gained extra -functionality to deal with ANSI colors and styles. Note that on Windows, -this functionality is only available if `colorama`_ is installed. If it -is installed, then ANSI codes are intelligently handled. Note that in Python -2, the echo function doesn't parse color code information from bytearrays. +The :func:`echo` function gained extra functionality to deal with ANSI +colors and styles. Note that on Windows, this functionality is only +available if `colorama`_ is installed. If it is installed, then ANSI +codes are intelligently handled. Primarily this means that: @@ -252,9 +245,7 @@ Printing Filenames ------------------ Because filenames might not be Unicode, formatting them can be a bit -tricky. Generally, this is easier in Python 2 than on 3, as you can just -write the bytes to stdout with the ``print`` function, but in Python 3, you -will always need to operate in Unicode. +tricky. The way this works with click is through the :func:`format_filename` function. It does a best-effort conversion of the filename to Unicode and @@ -280,8 +271,7 @@ Because of this, click provides the :func:`get_binary_stream` and different Python versions and for a wide variety of terminal configurations. The end result is that these functions will always return a functional -stream object (except in very odd cases in Python 3; see -:ref:`python3-limitations`). +stream object (except in very odd cases; see :doc:`/unicode-support`). Example:: |