source/configuration/reference.rst

***********************
Configuration reference
***********************

.. _config-main:

Main configuration
==================

:Location: :file:`powerline/config.json`

The main configuration file defines some common options that applies to all
extensions, as well as some extension-specific options like themes and
colorschemes.

Common configuration
--------------------

Common configuration is a subdictionary that is a value of ``common`` key in
:file:`powerline/config.json` file.

.. _config-common-term_truecolor:

``term_truecolor``
    Defines whether to output cterm indices (8-bit) or RGB colors (24-bit)
    to the terminal emulator. See the :ref:`term-feature-support-matrix` for
    information on whether used terminal emulator supports 24-bit colors.

    This variable is forced to be ``false`` if :ref:`term_escape_style
    <config-common-term_escape_style>` option is set to ``"fbterm"`` or if it is
    set to ``"auto"`` and powerline detected fbterm.

.. _config-common-term_escape_style:

``term_escape_style``
    Defines what escapes sequences should be used. Accepts three variants:

    =======  ===================================================================
    Variant  Description
    =======  ===================================================================
    auto     ``xterm`` or ``fbterm`` depending on ``$TERM`` variable value:
             ``TERM=fbterm`` implies ``fbterm`` escaping style, all other values
             select ``xterm`` escaping.
    xterm    Uses ``\e[{fb};5;{color}m`` for colors (``{fb}`` is either ``38``
             (foreground) or ``48`` (background)). Should be used for most
             terminals.
    fbterm   Uses ``\e[{fb};{color}}`` for colors (``{fb}`` is either ``1``
             (foreground) or ``2`` (background)). Should be used for fbterm:
             framebuffer terminal.
    =======  ===================================================================

.. _config-common-ambiwidth:

``ambiwidth``
    Tells powerline what to do with characters with East Asian Width Class
    Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek
    letters, Cyrillic letters). Valid values: any positive integer; it is
    suggested that this option is only set it to 1 (default) or 2.

.. _config-common-watcher:

``watcher``
    Select filesystem watcher. Variants are

    =======  ===================================
    Variant  Description
    =======  ===================================
    auto     Selects most performant watcher.
    inotify  Select inotify watcher. Linux only.
    stat     Select stat-based polling watcher.
    uv       Select libuv-based watcher.
    =======  ===================================

    Default is ``auto``.

.. _config-common-additional_escapes:

``additional_escapes``
    Valid for shell extensions, makes sense only if :ref:`term_truecolor
    <config-common-term_truecolor>` is enabled. Is to be set from command-line.
    Controls additional escaping that is needed for tmux/screen to work with
    terminal true color escape codes: normally tmux/screen prevent terminal
    emulator from receiving these control codes thus rendering powerline prompt
    colorless. Valid values: ``"tmux"``, ``"screen"``, ``null`` (default).

.. _config-common-paths:

``paths``
    Defines additional paths which will be searched for modules when using
    :ref:`function segment option <config-themes-seg-function>` or :ref:`Vim
    local_themes option <config-ext-local_themes>`. Paths defined here have
    priority when searching for modules.

.. _config-common-log:

``log_file``
    Defines how logs will be handled. There are three variants here:

    #. Absent. In this case logging will be done to stderr: equivalent to
       ``[["logging.StreamHandler", []]]`` or ``[null]``.
    #. Plain string. In this case logging will be done to the given file:
       ``"/file/name"`` is equivalent to ``[["logging.FileHandler",
       [["/file/name"]]]]`` or ``["/file/name"]``. Leading ``~/`` is expanded in
       the file name, so using ``"~/.log/foo"`` is permitted. If directory
       pointed by the option is absent, it will be created, but not its parent.
    #. List of handler definitions. Handler definition may either be ``null``,
       a string or a list with two or three elements:

       #. Logging class name and module. If module name is absent, it is
          equivalent to ``logging.handlers``.
       #. Class constructor arguments in a form ``[[args[, kwargs]]]``: accepted
          variants are ``[]`` (no arguments), ``[args]`` (e.g.
          ``[["/file/name"]]``: only positional arguments) or ``[args, kwargs]``
          (e.g. ``[[], {"host": "localhost", "port": 6666}]``: positional and
          keyword arguments, but no positional arguments in the example).
       #. Optional logging level. Overrides :ref:`log_level key
          <config-common-log_level>` and has the same format.
       #. Optional format string. Partially overrides :ref:`log_format key
          <config-common-log_format>` and has the same format. “Partially” here
          means that it may only specify more critical level.

.. _config-common-log_level:

``log_level``
    String, determines logging level. Defaults to ``WARNING``.

.. _config-common-log_format:

``log_format``
    String, determines format of the log messages. Defaults to
    ``'%(asctime)s:%(level)s:%(message)s'``.

``interval``
    Number, determines time (in seconds) between checks for changed
    configuration. Checks are done in a separate thread. Use ``null`` to check
    for configuration changes on ``.render()`` call in main thread.
    Defaults to ``None``.

``reload_config``
    Boolean, determines whether configuration should be reloaded at all.
    Defaults to ``True``.

.. _config-common-default_top_theme:

``default_top_theme``
    String, determines which top-level theme will be used as the default.
    Defaults to ``powerline_terminus`` in unicode locales and ``ascii`` in
    non-unicode locales. See `Themes`_ section for more details.

Extension-specific configuration
--------------------------------

Common configuration is a subdictionary that is a value of ``ext`` key in
:file:`powerline/config.json` file.

``colorscheme``
    Defines the colorscheme used for this extension.

.. _config-ext-theme:

``theme``
    Defines the theme used for this extension.

.. _config-ext-top_theme:

``top_theme``
    Defines the top-level theme used for this extension. See `Themes`_ section
    for more details.

.. _config-ext-local_themes:

``local_themes``
    Defines themes used when certain conditions are met, e.g. for
    buffer-specific statuslines in vim. Value depends on extension used. For vim
    it is a dictionary ``{matcher_name : theme_name}``, where ``matcher_name``
    is either ``matcher_module.module_attribute`` or ``module_attribute``
    (``matcher_module`` defaults to ``powerline.matchers.vim``) and
    ``module_attribute`` should point to a function that returns boolean value
    indicating that current buffer has (not) matched conditions. There is an
    exception for ``matcher_name`` though: if it is ``__tabline__`` no functions
    are loaded. This special theme is used for ``tabline`` Vim option.

    For shell and ipython it is a simple ``{prompt_type : theme_name}``, where
    ``prompt_type`` is a string with no special meaning (specifically it does
    not refer to any Python function). Shell has ``continuation``, and
    ``select`` prompts with rather self-explanatory names, IPython has ``in2``,
    ``out`` and ``rewrite`` prompts (refer to IPython documentation for more
    details) while ``in`` prompt is the default.

    For wm (:ref:`lemonbar <lemonbar-usage>` only) it is a dictionary
    ``{output : theme_name}`` that maps the ``xrandr`` output names to the
    local themes to use on that output.

.. _config-ext-components:

``components``
    Determines which extension components should be enabled. This key is highly
    extension-specific, here is the table of extensions and corresponding
    components:

    +---------+----------+-----------------------------------------------------+
    |Extension|Component |Description                                          |
    +---------+----------+-----------------------------------------------------+
    |vim      |statusline|Makes Vim use powerline statusline.                  |
    |         +----------+-----------------------------------------------------+
    |         |tabline   |Makes Vim use powerline tabline.                     |
    +---------+----------+-----------------------------------------------------+
    |shell    |prompt    |Makes shell display powerline prompt.                |
    |         +----------+-----------------------------------------------------+
    |         |tmux      |Makes shell report its current working directory     |
    |         |          |and screen width to tmux for tmux powerline          |
    |         |          |bindings.                                            |
    |         |          |                                                     |
    +---------+----------+-----------------------------------------------------+

    All components are enabled by default.

.. _config-ext-update_interval:

``update_interval``
    Determines how often WM status bars need to be updated, in seconds. Only
    valid for WM extensions which use ``powerline-daemon``. Defaults to
    2 seconds.

.. _config-colors:

Color definitions
=================

:Location: :file:`powerline/colors.json`

.. _config-colors-colors:

``colors``
    Color definitions, consisting of a dict where the key is the name of the
    color, and the value is one of the following:

    * A cterm color index.
    * A list with a cterm color index and a hex color string (e.g. ``[123,
      "aabbcc"]``). This is useful for colorschemes that use colors that
      aren’t available in color terminals.

``gradients``
    Gradient definitions, consisting of a dict where the key is the name of the
    gradient, and the value is a list containing one or two items, second item
    is optional:

    * A list of cterm color indices.
    * A list of hex color strings.

    It is expected that gradients are defined from least alert color to most
    alert or non-alert colors are used.

.. _config-colorschemes:

Colorschemes
============

:Location: :file:`powerline/colorschemes/{name}.json`,
           :file:`powerline/colorschemes/__main__.json`,
           :file:`powerline/colorschemes/{extension}/{name}.json`

Colorscheme files are processed in order given: definitions from each next file
override those from each previous file. It is required that either
:file:`powerline/colorschemes/{name}.json`, or
:file:`powerline/colorschemes/{extension}/{name}.json` exists.

``name``
    Name of the colorscheme.

.. _config-colorschemes-groups:

``groups``
    Segment highlighting groups, consisting of a dict where the key is the
    name of the highlighting group (usually the function name for function
    segments), and the value is either

    #) a dict that defines the foreground color, background color and
       attributes:

       ``fg``
           Foreground color. Must be defined in :ref:`colors
           <config-colors-colors>`.

       ``bg``
           Background color. Must be defined in :ref:`colors
           <config-colors-colors>`.

       ``attrs``
           List of attributes. Valid values are one or more of ``bold``,
           ``italic`` and ``underline``. Note that some attributes may be
           unavailable in some applications or terminal emulators. If no
           attributes are needed this list should be left empty.

    #) a string (an alias): a name of existing group. This group’s definition
       will be used when this color is requested.

``mode_translations``
    Mode-specific highlighting for extensions that support it (e.g. the vim
    extension). It’s an easy way of changing a color in a specific mode.
    Consists of a dict where the key is the mode and the value is a dict
    with the following options:

    ``colors``
        A dict where the key is the color to be translated in this mode, and
        the value is the new color. Both the key and the value must be defined
        in :ref:`colors <config-colors-colors>`.

    ``groups``
        Segment highlighting groups for this mode. Same syntax as the main
        :ref:`groups <config-colorschemes-groups>` option.

.. _config-themes:

Themes
======

:Location: :file:`powerline/themes/{top_theme}.json`,
           :file:`powerline/themes/{extension}/__main__.json`,
           :file:`powerline/themes/{extension}/{name}.json`

Theme files are processed in order given: definitions from each next file
override those from each previous file. It is required that file
:file:`powerline/themes/{extension}/{name}.json` exists.

`{top_theme}` component of the file name is obtained either from :ref:`top_theme
extension-specific key <config-ext-top_theme>` or from :ref:`default_top_theme
common configuration key <config-common-default_top_theme>`. Powerline ships
with the following top themes:

.. _config-top_themes-list:

==========================  ====================================================
Theme                       Description
==========================  ====================================================
powerline                   Default powerline theme with fancy powerline symbols
powerline_unicode7          Theme with powerline dividers and unicode-7 symbols
unicode                     Theme without any symbols from private use area
unicode_terminus            Theme containing only symbols from terminus PCF font
unicode_terminus_condensed  Like above, but occupies as less space as possible
powerline_terminus          Like unicode_terminus, but with powerline symbols
ascii                       Theme without any unicode characters at all
==========================  ====================================================

``name``
    Name of the theme.

.. _config-themes-default_module:

``default_module``
    Python module where segments will be looked by default. Defaults to
    ``powerline.segments.{ext}``.

``spaces``
    Defines number of spaces just before the divider (on the right side) or just
    after it (on the left side). These spaces will not be added if divider is
    not drawn.

``use_non_breaking_spaces``
    Determines whether non-breaking spaces should be used in place of the
    regular ones. This option is needed because regular spaces are not displayed
    properly when using powerline with some font configuration. Defaults to
    ``True``.

    .. note::
       Unlike all other options this one is only checked once at startup using
       whatever theme is :ref:`the default <config-ext-theme>`. If this option
       is set in the local themes it will be ignored. This option may also be
       ignored in some bindings.

``outer_padding``
    Defines number of spaces at the end of output (on the right side) or at
    the start of output (on the left side). Defaults to ``1``.


``dividers``
    Defines the dividers used in all Powerline extensions.

    The ``hard`` dividers are used to divide segments with different
    background colors, while the ``soft`` dividers are used to divide
    segments with the same background color.

.. _config-themes-cursor_space:

``cursor_space``
    Space reserved for user input in shell bindings. It is measured in per
    cents.

``cursor_columns``
    Space reserved for user input in shell bindings. Unlike :ref:`cursor_space
    <config-themes-cursor_space>` it is measured in absolute amount of columns.

.. _config-themes-segment_data:

``segment_data``
    A dict where keys are segment names or strings ``{module}.{function}``. Used
    to specify default values for various keys:
    :ref:`after <config-themes-seg-after>`,
    :ref:`before <config-themes-seg-before>`,
    :ref:`contents <config-themes-seg-contents>` (only for string segments
    if :ref:`name <config-themes-seg-name>` is defined),
    :ref:`display <config-themes-seg-display>`.

    Key :ref:`args <config-themes-seg-args>` (only for function and
    segment_list segments) is handled specially: unlike other values it is
    merged with all other values, except that a single ``{module}.{function}``
    key if found prevents merging all ``{function}`` values.

    When using :ref:`local themes <config-ext-local_themes>` values of these
    keys are first searched in the segment description, then in ``segment_data``
    key of a local theme, then in ``segment_data`` key of a :ref:`default theme
    <config-ext-theme>`. For the :ref:`default theme <config-ext-theme>` itself
    step 2 is obviously avoided.

    .. note:: Top-level themes are out of equation here: they are merged
        before the above merging process happens.

.. _config-themes-segments:

``segments``
    A dict with a ``left`` and a ``right`` lists, consisting of segment
    dictionaries. Shell themes may also contain ``above`` list of dictionaries.
    Each item in ``above`` list may have ``left`` and ``right`` keys like this
    dictionary, but no ``above`` key.

    .. _config-themes-above:

    ``above`` list is used for multiline shell configurations.

    ``left`` and ``right`` lists are used for segments that should be put on the
    left or right side in the output. Actual mechanizm of putting segments on
    the left or the right depends on used renderer, but most renderers require
    one to specify segment with :ref:`width <config-themes-seg-width>` ``auto``
    on either side to make generated line fill all of the available width.

    Each segment dictionary has the following options:

    .. _config-themes-seg-type:

    ``type``
        The segment type. Can be one of ``function`` (default), ``string`` or
        ``segment_list``:

        ``function``
            The segment contents is the return value of the function defined in
            the :ref:`function option <config-themes-seg-function>`.

            List of function segments is available in :ref:`Segment reference
            <config-segments>` section.

        ``string``
            A static string segment where the contents is defined in the
            :ref:`contents option <config-themes-seg-contents>`, and the
            highlighting group is defined in the :ref:`highlight_groups option
            <config-themes-seg-highlight_groups>`.

        ``segment_list``
            Sub-list of segments. This list only allows :ref:`function
            <config-themes-seg-function>`, :ref:`segments
            <config-themes-seg-segments>` and :ref:`args
            <config-themes-seg-args>` options.

            List of lister segments is available in :ref:`Lister reference
            <config-listers>` section.

    .. _config-themes-seg-name:

    ``name``
        Segment name. If present allows referring to this segment in
        :ref:`segment_data <config-themes-segment_data>` dictionary by this
        name. If not ``string`` segments may not be referred there at all and
        ``function`` and ``segment_list`` segments may be referred there using
        either ``{module}.{function_name}`` or ``{function_name}``, whichever
        will be found first. Function name is taken from :ref:`function key
        <config-themes-seg-function>`.

        .. note::
            If present prevents ``function`` key from acting as a segment name.

    .. _config-themes-seg-function:

    ``function``
        Function used to get segment contents, in format ``{module}.{function}``
        or ``{function}``. If ``{module}`` is omitted :ref:`default_module
        option <config-themes-default_module>` is used.

    .. _config-themes-seg-highlight_groups:

    ``highlight_groups``
        Highlighting group for this segment. Consists of a prioritized list of
        highlighting groups, where the first highlighting group that is
        available in the colorscheme is used.

        Ignored for segments that have ``function`` type.

    .. _config-themes-seg-before:

    ``before``
        A string which will be prepended to the segment contents.

    .. _config-themes-seg-after:

    ``after``
        A string which will be appended to the segment contents.

    .. _config-themes-seg-contents:

    ``contents``
        Segment contents, only required for ``string`` segments.

    .. _config-themes-seg-args:

    ``args``
        A dict of arguments to be passed to a ``function`` segment.

    .. _config-themes-seg-align:

    ``align``
        Aligns the segments contents to the left (``l``), center (``c``) or
        right (``r``). Has no sense if ``width`` key was not specified or if
        segment provides its own function for ``auto`` ``width`` handling and
        does not care about this option.

    .. _config-themes-seg-width:

    ``width``
        Enforces a specific width for this segment.

        This segment will work as a spacer if the width is set to ``auto``.
        Several spacers may be used, and the space will be distributed
        equally among all the spacer segments. Spacers may have contents,
        either returned by a function or a static string, and the contents
        can be aligned with the ``align`` property.

    .. _config-themes-seg-priority:

    ``priority``
        Optional segment priority. Segments with priority ``None`` (the default
        priority, represented by ``null`` in json) will always be included,
        regardless of the width of the prompt/statusline.

        If the priority is any number, the segment may be removed if the
        prompt/statusline width is too small for all the segments to be
        rendered. A lower number means that the segment has a higher priority.

        Segments are removed according to their priority, with low priority
        segments (i.e. with a greater priority number) being removed first.

    .. _config-themes-seg-draw_divider:

    ``draw_hard_divider``, ``draw_soft_divider``
        Whether to draw a divider between this and the adjacent segment. The
        adjacent segment is to the *right* for segments on the *left* side, and
        vice versa. Hard dividers are used between segments with different
        background colors, soft ones are used between segments with same
        background. Both options default to ``True``.

    .. _config-themes-seg-draw_inner_divider:

    ``draw_inner_divider``
        Determines whether inner soft dividers are to be drawn for function
        segments. Only applicable for functions returning multiple segments.
        Defaults to ``False``.

    .. _config-themes-seg-exclude_modes:

    ``exclude_modes``, ``include_modes``
        A list of modes where this segment will be excluded: the segment is not
        included or is included in all modes, *except* for the modes in one of
        these lists respectively. If ``exclude_modes`` is not present then it
        acts like an empty list (segment is not excluded from any modes).
        Without ``include_modes`` it acts like a list with all possible modes
        (segment is included in all modes). When there are both
        ``exclude_modes`` overrides ``include_modes``.

    .. _config-themes-seg-exclude_function:

    ``exclude_function``, ``include_function``
        Function name in a form ``{name}`` or ``{module}.{name}`` (in the first
        form ``{module}`` defaults to ``powerline.selectors.{ext}``). Determines
        under which condition specific segment will be included or excluded. By
        default segment is always included and never excluded.
        ``exclude_function`` overrides ``include_function``.

        .. note::
            Options :ref:`exclude_/include_modes
            <config-themes-seg-exclude_modes>` complement
            ``exclude_/include_functions``: segment will be included if it is
            included by either ``include_mode`` or ``include_function`` and will
            be excluded if it is excluded by either ``exclude_mode`` or
            ``exclude_function``.

    .. _config-themes-seg-display:

    ``display``
        Boolean. If false disables displaying of the segment.
        Defaults to ``True``.

    .. _config-themes-seg-segments:

    ``segments``
        A list of subsegments.