Writing segments

Each powerline segment is a callable object. It is supposed to be either a Python function or powerline.segments.Segment class. As a callable object it should receive the following arguments:

Note

All received arguments are keyword arguments.

pl
A powerline.PowerlineLogger instance. It must be used every time you need to log something.
segment_info

A dictionary. It is only received if callable has powerline_requires_segment_info attribute.

Refer to segment_info detailed description for further details.

create_watcher
Function that will create filesystem watcher once called. Which watcher will be created exactly is controlled by watcher configuration option.

And also any other argument(s) specified by user in args key (no additional arguments by default).

Object representing segment may have the following attributes used by powerline:

powerline_requires_segment_info
This attribute controls whether segment will receive segment_info argument: if it is present argument will be received.
powerline_requires_filesystem_watcher
This attribute controls whether segment will receive create_watcher argument: if it is present argument will be received.
powerline_segment_datas
This attribute must be a dictionary containing top_theme: segment_data mapping where top_theme is any theme name (it is expected that all of the names from top-level themes list are present) and segment_data is a dictionary like the one that is contained inside segment_data dictionary in configuration. This attribute should be used to specify default theme-specific values for third-party segments: powerline theme-specific values go directly to top-level themes.
startup

This attribute must be a callable which accepts the following keyword arguments:

  • pl: powerline.PowerlineLogger instance which is to be used for logging.
  • shutdown_event: Event object which will be set when powerline will be shut down.
  • Any arguments found in user configuration for the given segment (i.e. args key).

This function is called at powerline startup when using long-running processes (e.g. powerline in vim, in zsh with libzpython, in ipython or in powerline daemon) and not called when powerline-render executable is used (more specific: when powerline.Powerline constructor received true run_once argument).

shutdown

This attribute must be a callable that accepts no arguments and shuts down threads and frees any other resources allocated in startup method of the segment in question.

This function is not called when startup method is not called.

expand

This attribute must be a callable that accepts the following keyword arguments:

  • pl: powerline.PowerlineLogger instance which is to be used for logging.

  • amount: integer number representing amount of display cells result must occupy.

    Warning

    “Amount of display cells” is not number of Unicode codepoints, string length, or byte count. It is suggested that your function should look something like return (' ' * amount) + segment['contents'] where ' ' may be replaced with anything that is known to occupy exactly one display cell.

  • segment: segment dictionary.

  • Any arguments found in user configuration for the given segment (i.e. args key).

It must return new value of contents key.

truncate

Like expand function, but for truncating segments. Here amount means the number of display cells which must be freed.

This function is called for all segments before powerline starts purging them to free space.

This callable object should may return either a string (unicode in Python2 or str in Python3, not str in Python2 or bytes in Python3) object or a list of dictionaries. String object is a short form of the following return value:

[{
    'contents': original_return,
    'highlight_group': [segment_name],
}]

Returned list is a list of segments treated independently, except for draw_inner_divider key.

All keys in segments returned by the function override those obtained from configuration and have the same meaning.

Detailed description of used dictionary keys:

contents
Text displayed by segment. Should be a unicode (Python2) or str (Python3) instance.
draw_hard_divider, draw_soft_divider, draw_inner_divider
Determines whether given divider should be drawn. All have the same meaning as the similar keys in configuration (draw_inner_divider).
highlight_group

Determines segment highlighting. Refer to themes documentation for more details.

Defaults to the name of the segment.

Note

If you want to include your segment in powerline you must specify all highlighting groups used in the segment documentation in the form:

Highlight groups used: ``g1``[ or ``g2``]*[, ``g3`` (gradient)[ or ``g4``]*]*.

I.e. use:

Highlight groups used: ``foo_gradient`` (gradient) or ``foo``, ``bar``.

to specify that your segment uses either foo_gradient group or foo group and bar group meaning that powerline-lint will check that at least one of the first two groups is defined (and if foo_gradient is defined it must use at least one gradient color) and third group is defined as well.

You must specify all groups on one line.

divider_highlight_group

Determines segment divider highlight group. Only applicable for soft dividers: colors for hard dividers are determined by colors of adjacent segments.

Note

If you want to include your segment in powerline you must specify used groups in the segment documentation in the form:

Divider highlight group used: ``group``.

This text must not wrap and you are supposed to end all divider highlight group names with :divider: e.g. cwd:divider.

gradient_level

First and the only key that may not be specified in user configuration. It determines which color should be used for this segment when one of the highlighting groups specified by highlight_group was defined to use the color gradient.

This key may have any value from 0 to 100 inclusive, value is supposed to be an int or float instance.

No error occurs if segment has this key, but no used highlight groups use gradient color.

_*
Keys starting with underscore are reserved for powerline and must not be returned.
__*
Keys starting with two underscores are reserved for the segment functions, specifically for expand function.

Segment dictionary

Segment dictionary contains the following keys:

  • All keys returned by segment function (if it was used).

  • All of the following keys:

    name

    Segment name: value of the name key or function name (last component of the function key). May be None.

    type

    Segment type. Always represents actual type and is never None.

    highlight_group, divider_highlight_group

    Used highlight groups. May be None.

    highlight_group_prefix

    If this key is present then given prefix will be prepended to each highlight group (both regular and divider) used by this segment in a form {prefix}:{group} (note the colon). This key is mostly useful for segment listers.

    before, after

    Value of before or after configuration options. May be None as well as an empty string.

    contents_func

    Function used to get segment contents. May be None.

    contents

    Actual segment contents, excluding dividers and before/after. May be None.

    priority

    Segment priority. May be None for no priority (such segments are always shown).

    draw_soft_divider, draw_hard_divider, draw_inner_divider

    Divider control flags.

    side

    Segment side: right or left.

    display_condition`

    Contains function that takes three position parameters: powerline.PowerlineLogger instance, segment_info dictionary and current mode and returns either True or False to indicate whether particular segment should be processed.

    This key is constructed based on exclude_/include_modes keys and exclude_/include_function keys.

    width, align

    Width and align options. May be None.

    expand, truncate

    Partially applied expand or truncate function. Accepts pl, amount and segment positional parameters, keyword parameters from args key were applied.

    startup

    Partially applied startup function. Accepts pl and shutdown_event positional parameters, keyword parameters from args key were applied.

    shutdown

    Shutdown function. Accepts no argument.

Segments layout

Powerline segments are all located in one of the powerline.segments submodules. For extension-specific segments powerline.segments.{ext} module should be used (e.g. powerline.segments.shell), for extension-agnostic there is powerline.segments.common.

Plugin-specific segments (currently only those that are specific to vim plugins) should live in powerline.segments.{ext}.plugin.{plugin_name}: e.g. powerline.segments.vim.plugin.gundo.

Segment information used in various extensions

Each segment_info value should be a dictionary with at least the following keys:

environ

Current environment, may be an alias to os.environ. Is guaranteed to have __getitem__ and get methods and nothing more.

Warning

You must not ever use os.environ. If your segment is run in daemon you will get daemon’s environment which is not correct. If your segment is run in Vim or in zsh with libzpython you will get Vim or zsh environment at python startup.

getcwd
Function that returns current working directory being called with no arguments. You must not use os.getcwd for the same reasons you must not use os.environ, except that current working directory is valid in Vim and zsh (but not in daemon).
home
Current home directory. May be false.

Vim

Vim segment_info argument is a dictionary with the following keys:

window
vim.Window object. You may obtain one using vim.current.window or vim.windows[number - 1]. May be a false object, in which case you should not use any of this objects’ properties.
winnr
Window number. Same as segment_info['window'].number assuming Vim is new enough for vim.Window object to have number attribute.
window_id
Internal powerline window id, unique for each newly created window. You should assume that this ID is hashable and supports equality comparison, but you must not use any other assumptions about it. Currently uses integer numbers incremented each time window is created.
buffer
vim.Buffer object. You may obtain one using vim.current.buffer, segment_info['window'].buffer or vim.buffers[some_number]. Note that in the latter case depending on vim version some_number may be bufnr or the internal Vim buffer index which is not buffer number. For this reason to get vim.Buffer object other then stored in segment_info dictionary you must iterate over vim.buffers and check their number attributes.
bufnr
Buffer number.
tabpage
vim.Tabpage object. You may obtain one using vim.current.tabpage or vim.tabpages[number - 1]. May be a false object, in which case you should not use any of this objects’ properties.
tabnr
Tabpage number.
mode
Current mode.
encoding
Value of &encoding from the time when powerline was initialized. It should be used to convert return values.

Note

Your segment generally should not assume that it is run for the current window, current buffer or current tabpage. “Current window” and “current buffer” restrictions may be ignored if you use window_cached decorator, “current tabpage” restriction may be safely ignored if you do not plan to ever see your segment in the tabline.

Warning

Powerline is being tested with vim-7.2 and will be tested with it until travis changes used vim version. This means that you may not use most of the functionality like vim.Window.number, vim.*.vars, vim.*.options or even dir(vim object) if you want your segment to be included in powerline.

Shell

args

Parsed shell arguments: a argparse.Namespace object. Check out powerline-render --help for the list of all available arguments. Currently it is expected to contain at least the following attributes:

last_exit_code
Exit code returned by last shell command.
last_pipe_status
List of exit codes returned by last programs in the pipe or some false object. Only available in zsh.
jobnum
Number of background jobs.
renderer_arg

Dictionary containing some keys that are additional arguments used by shell bindings. You must not use this attribute directly: all arguments from this dictionary are merged with segment_info dictionary. Known to have at least the following keys:

client_id

Identifier unique to one shell instance. Is used to record instance state by powerline daemon.

It is not guaranteed that existing client ID will not be retaken when old shell with this ID quit: usually process PID is used as a client ID.

It is also not guaranteed that client ID will be process PID, number or something else at all. It is guaranteed though that client ID will be some hashable object which supports equality comparison.

local_theme
Local theme that will be used by shell. One should not rely on the existence of this key.

Other keys, if any, are specific to segments.

Ipython

ipython

Some object which has prompt_count attribute. Currently it is guaranteed to have only this attribute.

Attribute prompt_count contains the so-called “history count” (equivalent to \N in in_template).

Segment class

class powerline.segments.Segment[source]

Base class for any segment that is not a function

Required for powerline.lint.inspect to work properly: it defines methods for omitting existing or adding new arguments.

Note

Until python-3.4 inspect.getargspec does not support querying callable classes for arguments of their __call__ method, requiring to use this method directly (i.e. before 3.4 you should write getargspec(obj.__call__) in place of getargspec(obj)).

static additional_args()[source]

Returns a list of (additional argument name[, default value]) tuples.

argspecobjs()[source]

Return a list of valid arguments for inspect.getargspec

Used to determine function arguments.

omitted_args(name, method)[source]

List arguments which should be omitted

Returns a tuple with indexes of omitted arguments.

PowerlineLogger class

class powerline.PowerlineLogger(use_daemon_threads, logger, ext)[source]

Proxy class for logging.Logger instance

It emits messages in format {ext}:{prefix}:{message} where

{ext}
is a used powerline extension (e.g. “vim”, “shell”, “ipython”).
{prefix}
is a local prefix, usually a segment name.
{message}
is the original message passed to one of the logging methods.

Each of the methods (critical, exception, info, error, warn, debug) expects to receive message in an str.format format, not in printf-like format.

Log is saved to the location specified by user.

critical(msg, *args, **kwargs)[source]
debug(msg, *args, **kwargs)[source]
error(msg, *args, **kwargs)[source]
exception(msg, *args, **kwargs)[source]
info(msg, *args, **kwargs)[source]
warn(msg, *args, **kwargs)[source]