extensions.rst

Creating new powerline extension

Powerline extension is a code that tells powerline how to highlight and display segments in some set of applications. Specifically this means

1. Creating a :pypowerline.Powerline subclass that knows how to obtain local configuration overrides <local-configuration-overrides>. It also knows how to load local themes, but not when to apply them.

   Instance of this class is the only instance that interacts directly with bindings code, so it has a proxy :pypowerline.Powerline.render and :pypowerline.Powerline.shutdown methods and other methods which may be useful for bindings.

   This subclass must be placed directly in powerline directory (e.g. in powerline/vim.py) and named like VimPowerline (version of the file name without directory and extension and first capital letter
   • Powerline). There is no technical reason for naming classes like this.

2. Creating a :pypowerline.renderer.Renderer subclass that knows how to highlight a segment or reset highlighting to the default value (only makes sense in prompts). It is also responsible for selecting local themes and computing text width.

   This subclass must be placed directly in powerline/renderers directory (for powerline extensions developed for a set of applications use powerline/renderers/{ext}/*.py) and named like ExtRenderer or AppPromptRenderer. For technical reasons the class itself must be referenced in renderer module attribute thus allowing only one renderer per one module.

3. Creating an extension bindings. These are to be placed in powerline/bindings/{ext} and may contain virtually anything which may be required for powerline to work inside given applications, assuming it does not fit in other places.

Powerline class

powerline.Powerline

Renderer class

powerline.renderer.Renderer