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.
A dictionary. It is only received if callable has powerline_requires_segment_info attribute.
Refer to segment_info detailed description for further details.
And also any other argument(s) specified by user in args key (no additional arguments by default).
Note
For powerline-lint to work properly the following things may be needed:
Object representing segment may have the following attributes used by powerline:
This attribute must be a callable which accepts the following keyword arguments:
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).
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.
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 this 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.
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_groups': [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:
Text that needs to be output literally (i.e. without passing through powerline.renderer.strwidth() to determine length, through powerline.renderer.escape() to escape special characters and through powerline.renderer.hl() to highlight it). Should be a tuple (contents_length, contents) where contents_length is an integer and contents is a unicode (Python2) or str (Python3) instance.
If this key is present and its second value is true then other contents keys (contents, after, before) will be ignored.
Note
If target is inclusion of the segment in powerline upstream all segment functions that output only subsegments with literal_contents key must contain the following string in documentation:
No highlight groups are used (literal segment).
String must be present on the separate line.
Determines segment highlighting. Refer to themes documentation for more details.
Defaults to the name of the segment.
Note
If target is inclusion of the segment in powerline upstream all used highlighting groups must be specified 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 the 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.
All groups must be specified on one line.
Determines segment divider highlight group. Only applicable for soft dividers: colors for hard dividers are determined by colors of adjacent segments.
Note
If target is inclusion of the segment in powerline upstream used divider highlight group must be specified in the segment documentation in the form:
Divider highlight group used: ``group``.
This text must not wrap and all divider highlight group names are
supposed to end with ``:divider``: e.g. ``cwd:divider``.
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_groups 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.
Segment dictionary contains the following keys:
All keys returned by segment function (if it was used).
All of the following keys:
Segment name: value of the name key or function name (last component of the function key). May be None.
Segment type. Always represents actual type and is never None.
Used highlight groups. May be None.
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.
Value of before or after configuration options. May be None as well as an empty string.
Function used to get segment contents. May be None.
Actual segment contents, excluding dividers and before/after. May be None.
Segment priority. May be None for no priority (such segments are always shown).
Segment side: right or left.
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 and align options. May be None.
Partially applied expand or truncate function. Accepts pl, amount and segment positional parameters, keyword parameters from args key were applied.
Partially applied startup function. Accepts pl and shutdown_event positional parameters, keyword parameters from args key were applied.
Shutdown function. Accepts no argument.
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.
Each segment_info value should be a dictionary with at least the following keys:
Current environment, may be an alias to os.environ. Is guaranteed to have __getitem__ and get methods and nothing more.
Warning
os.environ must not ever be used:
Vim segment_info argument is a dictionary with the following keys:
Note
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 window_cached decorator is used, “current tabpage” restriction may be safely ignored if segment is not supposed to be used in tabline.
Warning
Powerline is being tested with vim-7.0.112 (some minor sanity check) and latest Vim. This means that most of the functionality like vim.Window.number, vim.*.vars, vim.*.options or even dir(vim object) should be avoided in segments that want to be included in the upstream.
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:
Dictionary containing some keys that are additional arguments used by shell bindings. This attribute must not be used directly: all arguments from this dictionary are merged with segment_info dictionary. Known to have at least the following keys:
Identifier unique to one shell instance. Is used to record instance state by powerline daemon. In tmux this is the same as pane_id.
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.
Other keys, if any, are specific to segments.
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).
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)).
Returns a list of (additional argument name[, default value]) tuples.
Proxy class for logging.Logger instance
It emits messages in format {ext}:{prefix}:{message} where
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.