Common segments¶
VCS submodule¶
-
class
powerline.segments.common.vcs.
VCSInfoSegment
[source]¶
-
powerline.segments.common.vcs.
vcsinfo
(name, ignore_statuses=(), status_colors=False)¶ Return the current revision info
Parameters: - name (str) –
Determines what property should be used. Valid values:
Name Description branch Current branch name. short Current commit revision abbreviated hex or revno. summary Current commit summary. name Human-readable name of the current revision. bookmark Current bookmark (mercurial) or branch (otherwise). status Current repository status. - status_colors (bool) – Determines whether repository status will be used to determine highlighting. Default: False.
- ignore_statuses (list) – List of statuses which will not result in repo being marked as dirty. Most
useful is setting this option to
["U"]
: this will ignore repository which has just untracked files (i.e. repository with modified, deleted or removed files will be marked as dirty, while just untracked files will make segment show clean repository). Only applicable ifstatus_colors
option is True.
Highlight groups used:
vcsinfo:clean
,vcsinfo:dirty
,vcsinfo
.Additionally
vcsinfo:{name}
is used.- name (str) –
System properties¶
-
powerline.segments.common.sys.
cpu_load_percent
(interval=1, threshold=None, format="{0:.0f}%", update_first=True)¶ Return the average CPU load as a percentage.
Requires the
psutil
module.Parameters: - format (str) – Output format. Accepts measured CPU load as the first argument.
- threshold (int) – Minimum load to display the segment (in percent)
Highlight groups used:
cpu_load_percent_gradient
(gradient) orcpu_load_percent
.Click values supplied:
cpu_load
(string),cpu_load_raw
(int)
-
powerline.segments.common.sys.
memory_usage
(auto_shrink=False, short_format="{percent:.1f}%", threshold_bad=80, threshold_good=20, format="{percent:.1f}% {absolute:.1f}G/{total:.1f}G")[source]¶ Return memory usage
Requires the
psutil
moduleParameters: - format (str) – format string, receives
percent
,absolute
, andtotal
as arguments - short_format (string) – optional shorter format when the powerline needs to shrink segments
- auto_shrink (bool) – if set to true, this segment will use
short_format
per default, only usingformat
when any message is present on thememory_usage
message channel. - threshold_good (float) – threshold for gradient level 0: any memory usage percentage below this value will have this gradient level.
- threshold_bad (float) – threshold for gradient level 100: any memory usage percentage above this
value will have this gradient level. Load averages between
threshold_good
andthreshold_bad
receive gradient level that indicates relative position in this interval: (100 * (cur-good) / (bad-good)
).
Highlight groups used:
memory_usage_gradient
(gradient) ormemory_usage
.Click values supplied:
memory_usage
(string),percent
(float),absolute
(float),total
(float)- format (str) – format string, receives
-
powerline.segments.common.sys.
system_load
(short=False, track_cpu_count=False, threshold_bad=2, threshold_good=1, format="{avg:.1f}")[source]¶ Return system load average.
Highlights using
system_load_good
,system_load_bad
andsystem_load_ugly
highlighting groups, depending on the thresholds passed to the function.Parameters: - format (str) – format string, receives
avg
as an argument - threshold_good (float) – threshold for gradient level 0: any normalized load average below this value will have this gradient level.
- threshold_bad (float) – threshold for gradient level 100: any normalized load average above this
value will have this gradient level. Load averages between
threshold_good
andthreshold_bad
receive gradient level that indicates relative position in this interval: (100 * (cur-good) / (bad-good)
). Note: both parameters are checked against normalized load averages. - track_cpu_count (bool) – if True powerline will continuously poll the system to detect changes in the number of CPUs.
- short (bool) – if True only the sys load over last 1 minute will be displayed.
Divider highlight group used:
background:divider
.Highlight groups used:
system_load_gradient
(gradient) orsystem_load
.Click values supplied:
avg
(string),avg_raw
(int)- format (str) – format string, receives
-
powerline.segments.common.sys.
temp
(hightemp=80, lowtemp=20, accuracy=0.001, path="/sys/class/thermal/thermal_zone0/temp", format="{:.1f}°C")[source]¶ Returns the temperature
Parameters: - format (string) – Output format
- path (string) – Path of the file containing the temperature
- accuracy (int) – Accuracy to read
Click values supplied:
temp
(string),temp_raw
(int)
-
powerline.segments.common.sys.
uptime
(shorten_len=3, format=None, seconds_format=" {seconds:d}s", minutes_format=" {minutes:d}m", hours_format=" {hours:d}h", days_format="{days:d}d")[source]¶ Return system uptime.
Parameters: - days_format (str) – day format string, will be passed
days
as the argument - hours_format (str) – hour format string, will be passed
hours
as the argument - minutes_format (str) – minute format string, will be passed
minutes
as the argument - seconds_format (str) – second format string, will be passed
seconds
as the argument - shorten_len (int) – shorten the amount of units (days, hours, etc.) displayed
Divider highlight group used:
background:divider
.- days_format (str) – day format string, will be passed
Network¶
-
powerline.segments.common.net.
external_ip
(interval=300, query_url="http://ipv4.icanhazip.com/")¶ Return external IP address.
Parameters: query_url (str) – URI to query for IP address, should return only the IP address as a text string
Suggested URIs:
- http://ipv4.icanhazip.com/
- http://ipv6.icanhazip.com/
- http://icanhazip.com/ (returns IPv6 address if available, else IPv4)
Divider highlight group used:
background:divider
.Click values supplied:
external_ip
(string)
-
powerline.segments.common.net.
hostname
(exclude_domain=False, only_if_ssh=False)[source]¶ Returns the current hostname.
Parameters: - only_if_ssh (bool) – only return the hostname if currently in an SSH session
- exclude_domain (bool) – return the hostname without domain if there is one
No special highlight groups used.
-
powerline.segments.common.net.
internal_ip
(ipv=4, interface="auto")[source]¶ Return internal IP address
Requires
netifaces
module to work properly.Parameters: - interface (str) –
Interface on which IP will be checked. Use
auto
to automatically detect interface. In this case interfaces with lower numbers will be preferred over interfaces with similar names. Order of preference based on names:eth
andenp
followed by number or the end of string.ath
,wlan
andwlp
followed by number or the end of string.teredo
followed by number or the end of string.- Any other interface that is not
lo*
. lo
followed by number or the end of string.
Use
default_gateway
to detect the interface based on the machine’s default gateway (i.e., the router to which it is connected). - format (string) – Format string. Use
addr
to show the address,netmask
to show the subnet mask, andcidr
to show the subnet in CIDR notation - ipv (int) – 4 or 6 for ipv4 and ipv6 respectively, depending on which IP address you need exactly.
- interface (str) –
-
powerline.segments.common.net.
network_load
(interval=1, update_first=True, interface="auto", si_prefix=False, suffix="B/s", sent_format="UL {value:>8}", recv_format="DL {value:>8}")¶ Return the network load.
Uses the
psutil
module if available for multi-platform compatibility, falls back to reading/sys/class/net/interface/statistics/rx,tx_bytes
.Parameters: - interface (str) – Network interface to measure (use the special value “auto” to have powerline try to auto-detect the network interface).
- suffix (str) – String appended to each load string.
- si_prefix (bool) – Use SI prefix, e.g. MB instead of MiB.
- recv_format (str) – Format string that determines how download speed should look like. Receives
value
as argument. - sent_format (str) – Format string that determines how upload speed should look like. Receives
value
as argument. - recv_max (float) – Maximum number of received bytes per second. Is only used to compute gradient level.
- sent_max (float) – Maximum number of sent bytes per second. Is only used to compute gradient level.
Divider highlight group used:
network_load:divider
.Highlight groups used:
network_load_sent_gradient
(gradient) ornetwork_load_recv_gradient
(gradient) ornetwork_load_gradient
(gradient),network_load_sent
ornetwork_load_recv
ornetwork_load
.
-
powerline.segments.common.net.
network_manager
(interval=100, device_types=None, auto_shrink=False, format_down=None, short_format="", format="{device} {type} {connection}", device=None, name="status")¶ Return what NetworkManager knows about the current connection. Requires
nmcli
Parameters: - name (string) –
the name of the segment, defaults to
status
. Setting this value changes the highlight groups used.Name Highlight Groups Used status net:status
wifi wireless:quality
, net:wifi orwireless:down
,net:wifi
ethernet ethernet:up
,ethernet:down
- device (string) – the device to use. Per default this segment will list data for all active devices.
- format (string) – the output format
- short_format (string) – optional shorter format when the powerline needs to shrink segments
- format_down (string) – if set to any other value than
None
, it will be shown when no connection is present on the specified device - auto_shrink (bool) – if set to true, this segment will use
short_format
per default, only usingformat
when any message is present on thenet.nm_<name>
message channel. - device_types (list) – filter for the given device types. May include
wifi
,ethernet
,gsm
,lo
, etc Consultman nmcli
for a comprehensive list.
Highlight groups used:
ethernet:up
ornet:ethernet
,ethernet:down
ornet:ethernet
,wireless:quality
(gradient) ornet:wifi
,wireless:down
ornet:wifi
,net:status
Click values supplied: (any value available in format)
- name (string) –
-
powerline.segments.common.net.
wireless
(auto_shrink=False, format_down=None, short_format="{quality:3.0%}", format="{quality:3.0%} at {essid}", device=None)[source]¶ Returns the current connection quality.
Parameters: - device (string) – the device to use. Per default this segment will try to be smart.
- format (string) – the output format
- short_format (string) – optional shorter format when the powerline needs to shrink segments
- format_down (string) – if set to any other value than
None
, it will be shown when no wireless connection is present. - auto_shrink (bool) – if set to true, this segment will use
short_format
per default, only usingformat
when any message is present on thenet.wireless
message channel.
Highlight groups used:
wireless:quality
(gradient),wireless:down
alternativelywireless:quality
(gradient)Click values supplied:
quality
(int),essid
(string)
-
powerline.segments.common.bluetooth.
bluetooth
(auto_shrink=False, ignore_unconnected=True, format_battery=None, format_down=None, short_format="BT{count_connected:2}", format="BT {name}")[source]¶ Return the connected Bluetooth devices. Requires
dbus
.Parameters: - format (string) – Format
- short_format (string) – Short format
- format_down (string) – Format when no device is connected
- format_battery (string) – Format used to display the battery status of the connected device.
- ignore_unconnected (boolean) – When listing devices, ignore
- auto_shrink (boolean) – if set to true, this segment will use
short_format
per default, only usingformat
when any message is present on thebluetooth
message channel.
Highlight groups used:
bluetooth
orbluetooth:down
Click values supplied: (any value available in format)
Current environment¶
-
class
powerline.segments.common.env.
CwdSegment
[source]¶
-
powerline.segments.common.env.
clip
(cutoff=10, hide_empty=True)[source]¶ Return the current clipboard content using xsel.
Parameters: - hide_empty (bool) – Hide the segment if the clipboard is empty.
- cutoff (int) – Max. number of characters to display.
Highlight groups used:
clip
.
-
powerline.segments.common.env.
cwd
(ellipsis="...", use_path_separator=False, dir_limit_depth=None, dir_shorten_len=None, shorten_home=True)¶ Return the current working directory.
Returns a segment list to create a breadcrumb-like effect.
Parameters: - dir_shorten_len (int) – shorten parent directory names to this length (e.g.
/long/path/to/powerline
→/l/p/t/powerline
) - dir_limit_depth (int) – limit directory depth to this number (e.g.
/long/path/to/powerline
→⋯/to/powerline
) - use_path_separator (bool) – Use path separator in place of soft divider.
- shorten_home (bool) – Shorten home directory to
~
. - ellipsis (str) – Specifies what to use in place of omitted directories. Use None to not show this subsegment at all.
Divider highlight group used:
cwd:divider
.Highlight groups used:
cwd:current_folder
orcwd
. It is recommended to define all highlight groups.- dir_shorten_len (int) – shorten parent directory names to this length (e.g.
-
powerline.segments.common.env.
environment
(variable=None)[source]¶ Return the value of any defined environment variable
Parameters: variable (string) – The environment variable to return if found
-
powerline.segments.common.env.
user
(hide_domain=False, hide_user=None)[source]¶ Return the current user.
Parameters: - hide_user (str) – Omit showing segment for users with names equal to this string.
- hide_domain (bool) – Drop domain component if it exists in a username (delimited by ‘@’).
Highlights the user with the
superuser
if the effective user ID is 0.Highlight groups used:
superuser
oruser
. It is recommended to define all highlight groups.
-
powerline.segments.common.env.
virtualenv
(ignored_names=('venv', '.venv'), ignore_conda=False, ignore_venv=False)[source]¶ Return the name of the current Python or conda virtualenv. :param list ignored_names:
Names of venvs to ignore. Will then get the name of the venv by ascending to the parent directoryParameters: - ignore_venv (bool) – Whether to ignore virtual environments. Default is False.
- ignore_conda (bool) – Whether to ignore conda environments. Default is False.
Battery¶
-
powerline.segments.common.bat.
battery
(full_design=-1, original_health=False, bat=0, gamify_steps=5, rem_time_format="%H:%M", format="{capacity:3.0%}", icons={'online': 'CHR', 'offline': 'BAT', 'full': ''}, name="capacity")[source]¶ Return batteries’ charge status.
Parameters: - name (str) –
Determines the information displayed. Valid values:
Name Description capacity The remaining capacity of the battery as a float btw 0 and 1. gamify Rem. cap. encoded in a string of gamify_steps chars from icons. status Current adapter status (Charging, Discharging or Full). icon Icon depicting current battery status/capacity. rem_time Remaining time till the battery is full or empty. - icons (dict) – Icons used to display the adapter status. Possible entries are
online
,offline
andfull
for statuses,0
,25
,50
,75
and100
for use with gamify. Ifonline
,offline
orfull
are absent, icon will try to use appropriate icons from gamify. - format (string) – Format used to display the capacity.
- rem_time_format (string) – Format used to display the remaining time (as a strftime format string)
- gamify_steps (int) – Number of discrete steps to show between 0% and 100% capacity if gamify occurs in format. The single one step that is neither completely full nor completely empty will use the icon corresponding to the percentage that part is empty.
- bat (int) – Specifies the battery to display information for.
- original_health (bool) – Use the original battery health as base value. (Experimental)
- full_design (int) – Specifies the design capacity of the battery. You will need this only if this value happens to read wrong. (Experimental)
battery_gradient
andbattery
groups are used in any case, first is preferred.Highlight groups used:
battery
orbattery_gradient
(gradient) orbattery:100
orbattery:50
orbattery:0
orbattery:full
orbattery:online
orbattery:offline
.Click values supplied:
capacity
(int),rem_time
(string),status
(string).- name (str) –
Weather¶
-
powerline.segments.common.wthr.
weather
(interval=600, update_first=True, location_query=None, temp_hottest=40, temp_coldest=-30, temp_format=None, unit="C", icons=None)¶ Return weather from OpenWeatherMaps.
Uses GeoIP lookup from https://freegeoip.app to automatically determine your current location. This should be changed if you’re in a VPN or if your IP address is registered at another location.
Returns a list of colorized icon and temperature segments depending on weather conditions.
Parameters: - unit (str) – temperature unit, can be one of
F
,C
orK
- location_query (str) – location query for your current location, e.g.
oslo, norway
- icons (dict) – dict for overriding default icons, e.g.
{'heavy_snow' : u'❆'}
- temp_format (str) – format string, receives
temp
as an argument. Should also hold unit. - temp_coldest (float) – coldest temperature. Any temperature below it will have gradient level equal to zero.
- temp_hottest (float) – hottest temperature. Any temperature above it will have gradient level equal
to 100. Temperatures between
temp_coldest
andtemp_hottest
receive gradient level that indicates relative position in this interval (100 * (cur-coldest) / (hottest-coldest)
).
Divider highlight group used:
background:divider
.Highlight groups used:
weather_conditions
orweather
,weather_temp_gradient
(gradient) orweather
. Also usesweather_conditions_{condition}
for all weather conditions supported by OpenWeatherMap.- unit (str) – temperature unit, can be one of
Date and time¶
-
powerline.segments.common.time.
date
(rel_names=['4', 'Off', '1', '2', '3'], timezone=None, istime=False, format="%Y-%m-%d")[source]¶ Return the current date.
Parameters: - format (string) – strftime-style date format string
- istime (bool) – If true then segment uses
time
highlight group. - timezone (string) – Specify a timezone to use as
+HHMM
or-HHMM
. (Defaults to system defaults.)
Divider highlight group used:
time:divider
.Highlight groups used:
time
ordate
.Click values supplied:
contents
(string)
-
powerline.segments.common.time.
fuzzy_time
(special_case_str={'(23, 58)': 'round about midnight', '(23, 59)': 'round about midnight', '(0, 0)': 'midnight', '(0, 1)': 'round about midnight', '(0, 2)': 'round about midnight', '(12, 0)': 'noon'}, minute_str={'0': "o'clock", '5': 'five past', '10': 'ten past', '15': 'quarter past', '20': 'twenty past', '25': 'twenty-five past', '30': 'half past', '35': 'twenty-five to', '40': 'twenty to', '45': 'quarter to', '50': 'ten to', '55': 'five to'}, hour_str=['twelve', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven'], timezone=None, unicode_text=False, format="{minute_str} {hour_str}")[source]¶ Display the current time as fuzzy time, e.g. “quarter past six”.
Parameters: - format (string) – Format used to display the fuzzy time. (Ignored when a special time is displayed.)
- unicode_text (bool) – If true then hyphenminuses (regular ASCII
-
) and single quotes are replaced with unicode dashes and apostrophes. - timezone (string) – Specify a timezone to use as
+HHMM
or-HHMM
. (Defaults to system defaults.) - list hour_str (string) – Strings to be used to display the hour, starting with midnight. (This list may contain 12 or 24 entries.)
- minute_str (dict) – Dictionary mapping minutes to strings to be used to display them.
- special_case_str (dict) – Special strings for special times.
Highlight groups used:
fuzzy_time
.Click values supplied: None
Mail¶
-
powerline.segments.common.mail.
email_imap_alert
(username, password, interval=60, update_first=True, use_ssl=None, folder="INBOX", port=993, server="imap.gmail.com", max_msgs=None)¶ Return unread e-mail count for IMAP servers.
Parameters: - username (str) – login username
- password (str) – login password
- server (str) – e-mail server
- port (int) – e-mail server port
- folder (str) – folder to check for e-mails
- max_msgs (int) – Maximum number of messages. If there are more messages then max_msgs then it
will use gradient level equal to 100, otherwise gradient level is equal to
100 * msgs_num / max_msgs
. If not present gradient is not computed. - use_ssl (bool) – If
True
then use SSL connection. IfFalse
then do not use it. Default isTrue
if port is equal to 993 andFalse
otherwise.
Highlight groups used:
email_alert_gradient
(gradient),email_alert
.Click values supplied:
unread_count
(string)
Appoints submodule¶
-
powerline.segments.common.appoints.
gcalendar
(developer_key, interval=300, single_when_shrunk=True, auto_shrink=False, hide_times=[' (00:00)'], show_count=False, count=3, time_format=" (%H:%M)", short_format="{short_summary}{time}", format="{summary}{time}", range=1, credentials="/home/docs/.config/powerline/gcalendar_credentials")¶ Return the next
count
appoints found in your Google Calendar.Parameters: - format (string) – The format to use when displaying events. Valid fields are time, summary, short_summary, count, error, and location.
- short_format (string) – The format to use when displaying events with few space. Valid fields are time, summary, short_summary, count, error, and location.
- time_format (string) – The format to use when displaying times and dates.
- count (int) – Number of appoints that shall be shown
- show_count (bool) – Add an additional segment containing the number of events in the specified range.
- hide_times (list) – Times (using time_format) not to be displayed as start times.
- credentials (string) – A path to a file containing credentials to access the Google Calendar API.
- developer_key (string) – Your Google dev key.
- range (int) – Number of days into the future to check. No more than 250 events will be displayed in any case.
- auto_shrink (bool) – Use
short_format
per default unless theappoints.gcalendar
channel is full. - single_when_shrunk (bool) – Only show a single segment using
short_format
when this segment is in its short mode.
Highlight groups used:
appoint
,appoint:urgent
,appoint:count
.
Media players¶
-
class
powerline.segments.common.players.
CmusPlayerSegment
[source]¶ -
get_player_status
(pl)[source]¶ Return cmus player information.
- cmus-remote -Q returns data with multi-level information i.e.
- status playing file <file_name> tag artist <artist_name> tag title <track_title> tag .. tag n set continue <true|false> set repeat <true|false> set .. set n
For the information we are looking for we don’t really care if we’re on the tag level or the set level. The dictionary comprehension in this method takes anything in ignore_levels and brings the key inside that to the first level of the dictionary.
-
-
class
powerline.segments.common.players.
MocPlayerSegment
[source]¶ -
get_player_status
(pl)[source]¶ Return Music On Console (mocp) player information.
mocp -i
returns current information i.e.File: filename.format Title: full title Artist: artist name SongTitle: song title Album: album name TotalTime: 00:00 TimeLeft: 00:00 TotalSec: 000 CurrentTime: 00:00 CurrentSec: 000 Bitrate: 000kbps AvgBitrate: 000kbps Rate: 00kHz
For the information we are looking for we don’t really care if we have extra-timing information or bit rate level. The dictionary comprehension in this method takes anything in ignore_info and brings the key inside that to the right info of the dictionary.
-
-
class
powerline.segments.common.players.
PlayerSegment
[source]¶
-
powerline.segments.common.players.
clementine
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return clementine player information
Requires
dbus
python module.This player segment should be added like this:
{ "function": "powerline.segments.common.players.clementine", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
cmus
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return CMUS player information
Requires cmus-remote command be accessible from $PATH.
This player segment should be added like this:
{ "function": "powerline.segments.common.players.cmus", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
dbus_player
(player_name, channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return generic dbus player state
- Requires
dbus
python module. Only for players that support specific protocol - (e.g. like
spotify()
andclementine()
).
This player segment should be added like this:
{ "function": "powerline.segments.common.players.dbus_player", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known. - player_name (str) – Player name. Used in error messages only.
- bus_name (str) – Dbus bus name.
- player_path (str) – Path to the player on the given bus.
- iface_prop (str) – Interface properties name for use with dbus.Interface.
- iface_player (str) – Player name.
- Requires
-
powerline.segments.common.players.
itunes
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return iTunes now playing information
Requires
osascript
.This player segment should be added like this:
{ "function": "powerline.segments.common.players.itunes", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
mocp
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return MOC (Music On Console) player information
Requires version >= 2.3.0 and
mocp
executable in$PATH
.This player segment should be added like this:
{ "function": "powerline.segments.common.players.mocp", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
mpd
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})", port=6600, password=None, host="localhost")¶ Return Music Player Daemon information
Requires
mpd
Python module (e.g.python-mpd2
orpython-mpd
Python package) or alternatively thempc
command to be accessible from $PATH.This player segment should be added like this:
{ "function": "powerline.segments.common.players.mpd", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known. - host (str) – Host on which mpd runs.
- password (str) – Password used for connecting to daemon.
- port (int) – Port which should be connected to.
- format (str) –
-
powerline.segments.common.players.
rdio
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return rdio player information
Requires
osascript
available in $PATH.This player segment should be added like this:
{ "function": "powerline.segments.common.players.rdio", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
rhythmbox
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return rhythmbox player information
Requires
rhythmbox-client
available in $PATH.This player segment should be added like this:
{ "function": "powerline.segments.common.players.rhythmbox", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
spotify
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return spotify player information
Requires
dbus
python module.This player segment should be added like this:
{ "function": "powerline.segments.common.players.spotify", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
spotify_apple_script
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return spotify player information
Requires
osascript
available in $PATH.This player segment should be added like this:
{ "function": "powerline.segments.common.players.spotify_apple_script", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
-
powerline.segments.common.players.
spotify_dbus
(channel_name=None, auto_shrink=False, show_controls=False, auto_disable=False, progress_args={'full': '#', 'empty': '_', 'steps': 5}, state_symbols={'fallback': '', 'play': '>', 'pause': '||', 'stop': 'X', 'shuffle': '~>?', 'repeat': ':|', 'loop': ':|1', 'next': '>|', 'previous': '|<'}, short_format="{state_symbol}{short_title}", format="{state_symbol} {artist} - {title} ({total})")¶ Return spotify player information
Requires
dbus
python module.This player segment should be added like this:
{ "function": "powerline.segments.common.players.spotify", "name": "player" }
(with additional
"args": {…}
if needed).Highlight groups used:
player:fallback
orplayer
,player:play
orplayer
,player:pause
orplayer
,player:stop
orplayer
.Parameters: - format (str) –
Format used for displaying data from player. Should be a str.format-like string with the following keyword parameters:
Parameter Description state_symbol Symbol displayed for play/pause/stop states. There is also “fallback” state used in case function failed to get player state. For this state symbol is by default empty. All symbols are defined in state_symbols
argument.album Album that is currently played. artist Artist whose song is currently played title Currently played composition. elapsed Composition duration in format M:SS (minutes:seconds). total Composition length in format M:SS. - state_symbols (dict) –
Symbols used for displaying state. Must contain all of the following keys:
Key Description play Displayed when player is playing. pause Displayed when player is paused. stop Displayed when player is not playing anything. fallback Displayed if state is not one of the above or not known.
- format (str) –
Volume¶
-
powerline.segments.common.volume.
vol
(icons={'full': '=', 'cur': 'X', 'empty': '-'}, id=0, control="Master", format_muted=None, format="VL {volume:3.0%}")[source]¶ Return the current volume.
Parameters: - format (string) – The format.
- control (string) – The control.
- id (int) – The control id.
- icons (dict) – Icons for the visualization.
Highlight groups used:
volume:gradient
(gradient).Click values supplied:
volume
(int),muted
(boolean)
Generic Segments¶
-
powerline.segments.common.generic.
click_status
(format_off="OFF", format_on=None)[source]¶ Returns whether click interaction is currently paused.
Parameters: - format_on (string) – Content to display if the bar currently allows clicks.
- format_off (string) – Content to display if the bar currently does not allow clicks.
Highlicght groups used:
clicks_on
orclicks_off
.
-
powerline.segments.common.generic.
generic_growable
(channel_name, segments_short, segments_long, show_without_clicks=False)[source]¶ Returns the segments in
segments_short
if the channelchannel_name
is empty, otherwise the segments insegments_long
.Parameters: - channel_name (string) – The channel to use. This should be different across different instances of this segment if you don’t want the different instances to interact with each other.
- segments_short ((string,string_list)_list) – A list of (contents, highlight_groups) touples, the segments to be displayed in the short mode.
- segments_long ((string,string_list)_list) – A list of (contents, highlight_groups) touples, the segments to be displayed in the long mode.
- show_without_clicks (bool) – Also show the segment if click support in the bar is paused.
Interaction:
#bar;ch_<fill/clear/toggle>
fills/ clears/ toggles the specified channel.
-
powerline.segments.common.generic.
generic_shell
(command, highlight_groups=['generic_shell'])[source]¶ Execute the given command in a shell and return its result
Parameters: - command (string) – The command to execute.
- highlight_groups (string_list) – The highlight groups to use.
Click values supplied:
contents
(string)