<commit_before>Utilities
=========

.. currentmodule:: click

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 :func:`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 :ref:`python3-limitations`).

Example::

    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)


.. _ansi-colors:

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.

Primarily this means that:

-   click's echo function will automatically strip ANSI color codes if the
    stream is not connected to a terminal.
-   the echo function will transparently connect to the terminal on
    Windows and translate ANSI codes to terminal API calls.  This means
    that colors will work on Windows the same way they do on other
    operating systems.

Note for colorama support: click will automatically detect when `colorama`
is available and use it.  Do *not* call ``colorama.init()``!

To install colorama run this command::

    $ pip install colorama

For styling a string the :func:`style` function can be used::

    import click

    click.echo(click.style('Hello World!', fg='green'))
    click.echo(click.style('Some more text', bg='blue', fg='white'))
    click.echo(click.style('ATTENTION', blink=True))

The combination of :func:`echo` and :func:`style` is also available in
a single function called :func:`secho`::

    click.secho('Hello World!', fg='green')
    click.secho('Some more text', bg='blue', fg='white')
    click.secho('ATTENTION', blink=True)


.. _colorama: https://pypi.python.org/pypi/colorama


Screen Clearing
---------------

.. versionadded:: 2.0

To clear the terminal screen you can use the :func:`clear` function that
is provided starting with Click 2.0.  It does what the name suggests: it
clears the entire visible screen in a platform agnostic way:

::

    import click
    click.clear()


Getting Characters from Terminal
--------------------------------

.. versionadded:: 2.0

Normally when reading input from the terminal you would use reading from
standard input.  However this is buffered input and will not show up until
the line has been terminated.  In certain circumstances you might not want
to do that and instead read individual characters as they are being
written.

For this click provides the :func:`getchar` function which reads a single
character from the terminal buffer and returns it as unicode character.

Note that this function will always read from the terminal, even if stdin
is instead a pipe.

Example::

    import click

    click.echo('Continue? [yn] ', nl=False)
    c = click.getchar()
    click.echo()
    if c == 'y':
        click.echo('We will go on')
    elif c == 'n':
        click.echo('Abort!')
    else:
        click.echo('Invalid input :(')


Launching Editors
-----------------

.. versionadded:: 2.0

Click supports launching editors automatically through :func:`edit`.  This
is very useful for asking users for multi-line input.  It will
automatically open the user's defined editor or fall back to a sensible
default.  If the user closes the editor without saving the return value
will be `None` otherwise the entered text.

Example usage::

    import click

    def get_commit_message():
        MARKER = '# Everything below is ignored\n'
        message = click.edit('\n\n' + MARKER)
        if message is not None:<commit_msg>Added notes on keyboard interrupts<commit_after>Utilities
=========

.. currentmodule:: click

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 :func:`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 :ref:`python3-limitations`).

Example::

    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)


.. _ansi-colors:

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.

Primarily this means that:

-   click's echo function will automatically strip ANSI color codes if the
    stream is not connected to a terminal.
-   the echo function will transparently connect to the terminal on
    Windows and translate ANSI codes to terminal API calls.  This means
    that colors will work on Windows the same way they do on other
    operating systems.

Note for colorama support: click will automatically detect when `colorama`
is available and use it.  Do *not* call ``colorama.init()``!

To install colorama run this command::

    $ pip install colorama

For styling a string the :func:`style` function can be used::

    import click

    click.echo(click.style('Hello World!', fg='green'))
    click.echo(click.style('Some more text', bg='blue', fg='white'))
    click.echo(click.style('ATTENTION', blink=True))

The combination of :func:`echo` and :func:`style` is also available in
a single function called :func:`secho`::

    click.secho('Hello World!', fg='green')
    click.secho('Some more text', bg='blue', fg='white')
    click.secho('ATTENTION', blink=True)


.. _colorama: https://pypi.python.org/pypi/colorama


Screen Clearing
---------------

.. versionadded:: 2.0

To clear the terminal screen you can use the :func:`clear` function that
is provided starting with Click 2.0.  It does what the name suggests: it
clears the entire visible screen in a platform agnostic way:

::

    import click
    click.clear()


Getting Characters from Terminal
--------------------------------

.. versionadded:: 2.0

Normally when reading input from the terminal you would use reading from
standard input.  However this is buffered input and will not show up until
the line has been terminated.  In certain circumstances you might not want
to do that and instead read individual characters as they are being
written.

For this click provides the :func:`getchar` function which reads a single
character from the terminal buffer and returns it as unicode character.

Note that this function will always read from the terminal, even if stdin
is instead a pipe.

Example::

    import click

    click.echo('Continue? [yn] ', nl=False)
    c = click.getchar()
    click.echo()
    if c == 'y':
        click.echo('We will go on')
    elif c == 'n':
        click.echo('Abort!')
    else:
        click.echo('Invalid input :(')

Note that this reads raw input which means that things like arrow keys
will show up in the platform's native escape format.  The only characters
translated are ``^C`` and ``^D`` which are converted into keyboard
interrupt and end of file exceptions.  This is done because otherwise it's
too easy to forget about that and to create scripts that cannot be
properly exited.


Launching Editors
-----------------

.. versionadded:: 2.0

Click supports launching editors automatically through :func:`edit`.  This
is very useful for asking users for multi-line input.  It will
automatically open the user's defined editor or fall back to a sensible
default.  If the user closes the editor without saving the return value
will be `None` otherwise the entered text.

Example usage::

    import click

    def get_commit_message():
        MARKER = '# Everything below is ignored\n'
        message = click.edit('\n\n' + MARKER)
        if message is not None:
{'fraction_non_alphanumeric': 0.09479574706211527, 'fraction_numerical': 0.004924454392837157, 'mean_word_length': 3.474712068102153, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6386026', 'n_tokens_mistral': 2414, 'n_tokens_neox': 2312, 'n_words': 1166}