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
- 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.
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.