Module reference¶

Module overview:

System:	clock - cpu_freq - cpu_usage - disk - keyboard_locks - load - mem - uname - uptime - xkblayout
Audio:	alsa - pulseaudio
Hardware:	backlight - battery - temp
Network:	net_speed - network - online - openstack_vms - openvpn
Music:	cmus - mpd - now_playing - pianobar - spotify
Websites:	bitcoin - dota2wins - github - modsde - parcel - reddit - weather - whosonlocation
Other:	anybar - mail - pomodoro - pyload - text - updates
Advanced:	file - regex - makewatch - runwatch - shell

Module list:

class i3pystatus.abc_radio.ABCRadio[source]¶

Streams ABC Australia radio - https://radio.abc.net.au/. Currently uses VLC to do the actual streaming.

Requires the PyPI packages python-vlc, python-dateutil and requests. Also requires VLC - https://www.videolan.org/vlc/index.html

Available formatters

{station} — Current station
{title} — Title of current show
{url} — Show’s URL
{remaining} — Time left for current show
{player_state} — Unicode icons representing play, pause and stop

Settings

format (default: {station} {title} {player_state}) – format string for when the player is inactive
format_playing (default: {station} {title} {remaining} {player_state}) – format string for when the player is playing
target_stations (default: []) – list of station ids to select from. Station ids can be obtained from the following XML - http://www.abc.net.au/radio/data/stations_apps_v3.xml. If the list is empty, all stations will be accessible.
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: toggle_play) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: ['cycle_stations', 1]) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: ['cycle_stations', -1]) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: display_notification) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.alsa.ALSA[source]¶

Shows volume of ALSA mixer. You can also use this for inputs, btw.

Requires pyalsaaudio

Available formatters

{volume} — the current volume in percent
{muted} — the value of one of the muted or unmuted settings
{card} — the associated soundcard
{mixer} — the associated ALSA mixer

Settings

format (default: ♪: {volume})
format_muted (default: empty) – optional format string to use when muted
mixer (default: Master) – ALSA mixer
mixer_id (default: 0) – ALSA mixer id
card (default: 0) – ALSA sound card
increment (default: 5) – integer percentage of max volume to in/decrement volume on mousewheel
muted (default: M)
unmuted (default: empty)
color_muted (default: #AAAAAA)
color (default: #FFFFFF)
channel (default: 0)
map_volume (default: False) – volume display/setting as in AlsaMixer. increment option is ignored then.
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: switch_mute) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: switch_mute) – Callback called on right click (see Callbacks)
on_upscroll (default: increase_volume) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: decrease_volume) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.anybar.AnyBar[source]¶

This module shows dot with given color in your panel. What color means is up to you. When to change color is also up to you. It’s a port of https://github.com/tonsky/AnyBar to i3pystatus. Color can be changed by sending text to UDP port. Check the original repo how to do it.

Settings

port (default: 1738) – UDP port to listen
color (default: #444444) – initial color
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

main_loop()[source]¶: Mainloop blocks so we thread it.

class i3pystatus.backlight.Backlight[source]¶

Screen backlight info

(Optional) requires xbacklight to change the backlight brightness with the scollwheel.

Available formatters

{brightness} — current brightness relative to max_brightness
{max_brightness} — maximum brightness value
{percentage} — current brightness in percent

Settings

format (default: {brightness}/{max_brightness}) – format string, formatters: brightness, max_brightness, percentage
backlight (default: acpi_video0) – backlight, see /sys/class/backlight/
color (default: #FFFFFF)
components (default: {'brightness': (<class 'int'>, 'brightness'), 'max_brightness': (<class 'int'>, 'max_brightness')})
transforms (default: {'percentage': <function Backlight.<lambda> at 0x7f8bb31da620>})
base_path (default: /sys/class/backlight/{backlight}/)
interval (default: 5)
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: lighter) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: darker) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.battery.BatteryChecker[source]¶

This class uses the /sys/class/power_supply/…/uevent interface to check for the battery status.

Setting battery_ident to ALL will summarise all available batteries and aggregate the % as well as the time remaining on the charge. This is helpful when the machine has more than one battery available.

Available formatters

{remaining} — remaining time for charging or discharging, uses TimeWrapper formatting, default format is %E%h:%M
{percentage} — battery percentage relative to the last full value
{percentage_design} — absolute battery charge percentage
{consumption (Watts)} — current power flowing into/out of the battery
{status}
{no_of_batteries} — The number of batteries included
{battery_ident} — the same as the setting
{bar} —bar displaying the relative percentage graphically
{bar_design} —bar displaying the absolute percentage graphically

This module supports the formatp extended string format syntax. By setting the FULL status to an empty string, and including brackets around the {status} formatter, the text within the brackets will be hidden when the battery is full, as can be seen in the below example:

from i3pystatus import Status

status = Status()

status.register(
    'battery',
    interval=5,
    format='{battery_ident}: [{status} ]{percentage_design:.2f}%',
    alert=True,
    alert_percentage=15,
    status = {
        'DPL': 'DPL',
        'CHR': 'CHR',
        'DIS': 'DIS',
        'FULL': '',
    }
)

status.run()

Settings

battery_ident (default: ALL) – The name of your battery, usually BAT0 or BAT1
format (default: {status} {remaining})
not_present_text (default: Battery {battery_ident} not present) – Text displayed if the battery is not present. No formatters are available
alert (default: False) – Display a libnotify-notification on low battery
critical_level_command (default: empty) – Runs a shell command in the case of a critical power state
critical_level_percentage (default: 1)
alert_percentage (default: 10)
alert_format_title (default: Low battery) – The title of the notification, all formatters can be used
alert_format_body (default: Battery {battery_ident} has only {percentage:.2f}% ({remaining:%E%hh:%Mm}) remaining!) – The body text of the notification, all formatters can be used
path (default: empty) – Override the default-generated path and specify the full path for a single battery
base_path (default: /sys/class/power_supply) – Override the default base path for searching for batteries
battery_prefix (default: BAT) – Override the default battery prefix
status (default: {'FULL': 'FULL', 'DIS': 'DIS', 'CHR': 'CHR', 'DPL': 'DPL'}) – A dictionary mapping (‘DPL’, ‘DIS’, ‘CHR’, ‘FULL’) to alternative names
color (default: #ffffff) – The text color
full_color (default: #00ff00) – The full color
charging_color (default: #00ff00) – The charging color
critical_color (default: #ff0000) – The critical color
not_present_color (default: #ffffff) – The not present color.
no_text_full (default: False) – Don’t display text when battery is full - 100%
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.bitcoin.Bitcoin[source]¶

This module fetches and displays current Bitcoin market prices and optionally monitors transactions to and from a list of user-specified wallet addresses. Market data is pulled from the BitcoinAverage Price Index API <https://bitcoinaverage.com> and it is possible to specify the exchange to be monitored. Transaction data is pulled from blockchain.info <https://blockchain.info/api/blockchain_api>.

Available formatters

{last_price}
{ask_price}
{bid_price}
{daily_average}
{volume}
{volume_thousend}
{volume_percent}
{age}
{status}
{last_tx_type}
{last_tx_addr}
{last_tx_value}
{balance_btc}
{balance_fiat}
{symbol}

Settings

format (default: {symbol} {status}{last_price}) – Format string used for output.
currency (default: USD) – Base fiat currency used for pricing.
wallet_addresses (default: empty) – List of wallet address(es) to monitor.
color (default: #FFFFFF) – Standard color
exchange (default: empty) – Get ticker from a custom exchange instead
colorize (default: False) – Enable color change on price increase/decrease
color_up (default: #00FF00) – Color for price increases
color_down (default: #FF0000) – Color for price decreases
interval (default: 600) – Update interval.
symbol (default: ฿) – Symbol for bitcoin sign
status (default: {'price_up': '▲', 'price_down': '▼'})
on_leftclick (default: electrum) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: ['open_something', 'https://bitcoinaverage.com/']) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

open_something(url_or_command)[source]¶: Wrapper function, to pass the arguments to user_open

class i3pystatus.clock.Clock[source]¶

This class shows a clock.

Note

Optionally requires pytz for time zone data when using time zones other than local time.

Format can be passed in four different ways:

single string, no timezone, just the strftime-format
one two-tuple, first is the format, second the timezone
list of strings - no timezones
list of two tuples, first is the format, second is timezone

Use mousewheel to cycle between formats.

For complete time format specification see:

man strftime

All available timezones are located in directory:

/usr/share/zoneinfo/

Format examples

# one format, local timezone
format = '%a %b %-d %b %X'
# multiple formats, local timezone
format = [ '%a %b %-d %b %X', '%X' ]
# one format, specified timezone
format = ('%a %b %-d %b %X', 'Europe/Bratislava')
# multiple formats, specified timezones
format = [ ('%a %b %-d %b %X', 'America/New_York'), ('%X', 'Etc/GMT+9') ]

Settings

format (default: empty) – None means to use the default, locale-dependent format.
color (default: #ffffff) – RGB hexadecimal code color specifier, default to #ffffff
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: ['scroll_format', 1]) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: ['scroll_format', -1]) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.cmus.Cmus[source]¶

Gets the status and current song info using cmus-remote

Available formatters

{status} — current status icon (paused/playing/stopped)
{song_elapsed} — song elapsed time (mm:ss format)
{song_length} — total song duration (mm:ss format)
{artist} — artist
{title} — title
{album} — album
{tracknumber} — tracknumber
{file} — file or url name
{stream} — song name from stream
{bitrate} — bitrate

Settings

format (default: {status} {song_elapsed}/{song_length} {artist} - {title}) – formatp string
format_not_running (default: Not running) – Text to show if cmus is not running
color (default: #ffffff) – The color of the text
color_not_running (default: #ffffff) – The color of the text, when cmus is not running
status (default: {'stopped': '◾', 'playing': '▶', 'paused': '▷'}) – Dictionary mapping status to output
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: playpause) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: next_song) – Callback called on right click (see Callbacks)
on_upscroll (default: next_song) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: previous_song) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.cpu_freq.CpuFreq[source]¶

class uses by default /proc/cpuinfo to determine the current cpu frequency

Available formatters

{avg} - mean from all cores in MHz 4.3f
{avgg} - mean from all cores in GHz 1.2f
{coreX} - frequency of core number X in MHz (format 4.3f), where 0 <= X <= number of cores - 1
{coreXg} - frequency of core number X in GHz (fromat 1.2f), where 0 <= X <= number of cores - 1

Settings

format (default: {avgg})
color (default: #FFFFFF) – The text color
file (default: /proc/cpuinfo) – override default path
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

createvaluesdict()[source]¶: function processes the /proc/cpuinfo file :return: dictionary used as the full-text output for the module

class i3pystatus.cpu_usage.CpuUsage[source]¶

Shows CPU usage. The first output will be inacurate.

Linux only

Available formatters

{usage} — usage average of all cores
{usage_cpu*} — usage of one specific core. replace “*” by core number starting at 0
{usage_all} — usage of all cores separate. usess natsort when available(relevant for more than 10 cores)

Settings

format (default: {usage:02}%) – format string.
format_all (default: {core}:{usage:02}%) – format string used for {usage_all} per core. Available formaters are {core} and {usage}.
exclude_average (default: False) – If True usage average of all cores will not be in format_all.
color (default: empty) – HTML color code #RRGGBB
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

calculate_usage(cpu, total, busy)[source]¶: calculates usage

gen_format_all(usage)[source]¶: generates string for format all

get_cpu_timings()[source]¶: reads and parses /proc/stat returns dictionary with all available cores including global average

get_usage()[source]¶: parses /proc/stat and calcualtes total and busy time (more specific USER_HZ see man 5 proc for further informations )

class i3pystatus.cpu_usage_bar.CpuUsageBar[source]¶

Shows CPU usage as a bar (made with unicode box characters). The first output will be inacurate.

Linux only

Requires the PyPI package colour.

Available formatters

{usage_bar} — usage average of all cores
{usage_bar_cpu*} — usage of one specific core. replace “*” by core number starting at 0

Settings

format (default: {usage_bar}) – format string
bar_type (default: horizontal) – whether the bar should be vertical or horizontal. Allowed values: vertical or horizontal
cpu (default: usage_cpu) – cpu to base the colors on. Choices are ‘usage_cpu’ for all or ‘usage_cpu*’. Replace ‘*’ by core number starting at 0.
start_color (default: #00FF00) – Hex or English name for start of color range, eg ‘#00FF00’ or ‘green’
end_color (default: red) – Hex or English name for end of color range, eg ‘#FF0000’ or ‘red’
format_all (default: {core}:{usage:02}%) – format string used for {usage_all} per core. Available formaters are {core} and {usage}.
exclude_average (default: False) – If True usage average of all cores will not be in format_all.
color (default: empty) – HTML color code #RRGGBB
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.cpu_usage_graph.CpuUsageGraph[source]¶

Shows CPU usage as a Unicode graph. The first output will be inacurate.

Depends on the PyPI colour module - https://pypi.python.org/pypi/colour/0.0.5

Linux only

Available formatters

{cpu_graph} — graph of cpu usage.
{usage} — usage average of all cores
{usage_cpu*} — usage of one specific core. replace “*” by core number starting at 0
{usage_all} — usage of all cores separate. usess natsort when available(relevant for more than 10 cores)

Settings

cpu (default: usage_cpu) – cpu to monitor, choices are ‘usage_cpu’ for all or ‘usage_cpu*’. Replace ‘*’ by core number starting at 0.
start_color (default: #00FF00) – Hex or English name for start of color range, eg ‘#00FF00’ or ‘green’
end_color (default: red) – Hex or English name for end of color range, eg ‘#FF0000’ or ‘red’
graph_width (default: 15) – Width of the cpu usage graph
graph_style (default: blocks) – Graph style (‘blocks’, ‘braille-fill’, ‘braille-peak’, or ‘braille-snake’)
format (default: {cpu_graph}) – format string.
format_all (default: {core}:{usage:02}%) – format string used for {usage_all} per core. Available formaters are {core} and {usage}.
exclude_average (default: False) – If True usage average of all cores will not be in format_all.
color (default: empty) – HTML color code #RRGGBB
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.disk.Disk[source]¶

Gets {used}, {free}, {avail} and {total} amount of bytes on the given mounted filesystem.

These values can also be expressed as percentages with the {percentage_used}, {percentage_free} and {percentage_avail} formats.

Settings

format (default: {free}/{avail})
path (required)
divisor (default: 1073741824) – divide all byte values by this value, default is 1024**3 (gigabyte)
display_limit (default: inf) – if more space is available than this limit the module is hidden
critical_limit (default: 0) – critical space limit (see critical_color)
critical_color (default: #FF0000) – the critical color
color (default: #FFFFFF) – the common color
round_size (default: 2) – precision, None for INT
mounted_only (default: False) – display only if path is a valid mountpoint
format_not_mounted (default: empty)
color_not_mounted (default: #FFFFFF)
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.dota2wins.Dota2wins[source]¶

Displays the win/loss ratio of a given Dota account. Requires: dota2py

Settings

matches (default: 25) – Number of recent matches to calculate
steamid (required) – Steam ID or username to track
steam_api_key (required) – Steam API key (http://steamcommunity.com/dev/apikey)
good_threshold (default: 50) – Win percentage (or higher) which you are happy with
bad_threshold (default: 45) – Win percentage you want to be alerted (difference between good_threshold and bad_threshold is cautious_threshold)
interval (default: 1800) – Update interval (games usually last at least 20 min).
good_color (default: #00FF00) – Color of text while win percentage is above good_threshold
bad_color (default: #FF0000) – Color of text while win percentage is below bad_threshold
caution_color (default: #FFFF00) – Color of text while win precentage is between good and bad thresholds
screenname (default: retrieve) – If set to ‘retrieve’, requests for the users’s screenname via API calls. Else, use the supplied string as the user’s screename
format (default: {screenname} {wins}W:{losses}L {win_percent:.2f}%)
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.dpms.DPMS[source]¶

Shows and toggles status of DPMS which prevents screen from blanking.

Available formatters

{status} — the current status of DPMS

@author Georg Sieber <g.sieber AT gmail.com>

Settings

format (default: DPMS: {status})
format_disabled (default: DPMS: {status})
color (default: #FFFFFF)
color_disabled (default: #AAAAAA)
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: toggle_dpms) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.file.File[source]¶

Rip information from text files

components is a dict of pairs of the form:

name => (callable, file)

Where name is a valid identifier, which is used in the format string to access the value of that component.
callable is some callable to convert the contents of file. A common choice is float or int.
file names a file, relative to base_path.

transforms is a optional dict of callables taking a single argument (a dictionary containing the values of all components). The return value is bound to the key.

Settings

format (required)
components (required)
transforms (default: {})
base_path (default: /)
color (default: #FFFFFF)
interval (default: 5)
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.github.Github[source]¶

Check GitHub for pending notifications. Requires requests

Availables authentication methods:

username + password
access_token (manually generate a new token at https://github.com/settings/tokens)

See https://developer.github.com/v3/#authentication for more informations.

Formatters:

{unread} — contains the value of unread_marker when there are pending notifications
{unread_count} — number of unread notifications, empty if 0

Settings

format (default: {unread}) – format string
keyring_backend (default: empty) – alternative keyring backend for retrieving credentials
unread_marker (default: ●) – sets the string that the “unread” formatter shows when there are pending notifications
username (default: empty)
password (default: empty)
access_token (default: empty) – see https://developer.github.com/v3/#authentication
color (default: #78EAF2)
interval (default: 600) – interval in seconds between module updates
on_leftclick (default: open_github) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.google_calendar.GoogleCalendar[source]¶

Simple module for displaying next Google Calendar event.

Requires the Google Calendar API package - https://developers.google.com/google-apps/calendar/quickstart/python. Additionally requires the colour, httplib2, oauth2client, pytz, apiclient and dateutil modules.

All top level keys returned by the Google Calendar API can be used as formatters. Some examples include:

Available formatters

{kind} — type of event
{status} — eg, confirmed
{summary} — essentially the title
{remaining_time} - how long remaining until the event
{start_time} - when this event starts
{htmlLink} — link to the calendar event

Settings

format (default: {summary} ({remaining_time})) – format string
credential_path (required) – Path to credentials
skip_recurring (default: True) – Skip recurring events.
days (default: 1) – Only show events between now and this many days in the future
urgent_seconds (default: 300) – Add urgent hint when this many seconds until event startTime
start_color (default: #00FF00) – Hex or English name for start of color range, eg ‘#00FF00’ or ‘green’
end_color (default: red) – Hex or English name for end of color range, eg ‘#FF0000’ or ‘red’
interval (default: 30) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.gpu_mem.GPUMemory[source]¶

Shows GPU memory load

Currently Nvidia only and nvidia-smi required

Available formatters

{avail_mem}
{percent_used_mem}
{used_mem}
{total_mem}

Settings

format (default: {avail_mem} MiB) – format string used for output.
divisor (default: 1) – divide all megabyte values by this value, default is 1 (megabytes)
warn_percentage (default: 50) – minimal percentage for warn state
alert_percentage (default: 80) – minimal percentage for alert state
color (default: #00FF00) – standard color
warn_color (default: #FFFF00) – defines the color used when warn percentage is exceeded
alert_color (default: #FF0000) – defines the color used when alert percentage is exceeded
round_size (default: 1) – defines number of digits in round
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.gpu_temp.GPUTemperature[source]¶

Shows GPU temperature

Currently Nvidia only and nvidia-smi required

Available formatters

{temp} — the temperature in integer degrees celsius

Settings

format (default: {temp} °C) – format string used for output. {temp} is the temperature in integer degrees celsius
display_if (default: True) – snippet that gets evaluated. if true, displays the module output
color (default: #FFFFFF)
alert_temp (default: 90)
alert_color (default: #FF0000)
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.iinet.IINet[source]¶

Check IINet Internet usage. Requires requests and colour

Formatters:

{percentage_used} — percentage of your quota that is used
{percentage_available} — percentage of your quota that is available

Settings

format (default: {percent_used})
username (default: empty) – Username for IINet
password (default: empty) – Password for IINet
start_color (default: #00FF00) – Beginning color for color range
end_color (default: #FF0000) – End color for color range
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.keyboard_locks.Keyboard_locks[source]¶

Shows the status of CAPS LOCK, NUM LOCK and SCROLL LOCK

Available formatters

{caps} — the current status of CAPS LOCK
{num} — the current status of NUM LOCK
{scroll} — the current status of SCROLL LOCK

Settings

format (default: {caps} {num} {scroll}) – Format string
caps_on (default: CAP) – String to show in {caps} when CAPS LOCK is on
caps_off (default: ___) – String to show in {caps} when CAPS LOCK is off
num_on (default: NUM) – String to show in {num} when NUM LOCK is on
num_off (default: ___) – String to show in {num} when NUM LOCK is off
scroll_on (default: SCR) – String to show in {scroll} when SCROLL LOCK is on
scroll_off (default: ___) – String to show in {scroll} when SCROLL LOCK is off
color (default: #FFFFFF)
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.lastfm.LastFM[source]¶

Displays currently playing song as reported by last.fm. Get your API key from http://www.last.fm/api.

Settings

apikey (required) – API key used to make calls to last.fm.
user (required) – Name of last.fm user to track.
playing_format (default: {artist} - {track}) – Output format when a song is playing
stopped_format (default: empty) – Output format when nothing is playing
playing_color (default: FFFFFF)
stopped_color (default: 000000)
interval (default: 5)
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.load.Load[source]¶

Shows system load

Available formatters

{avg1} — the load average of the last minute
{avg5} — the load average of the last five minutes
{avg15} — the load average of the last fifteen minutes
{tasks} — the number of tasks (e.g. 1/285, which indiciates that one out of 285 total tasks is runnable)

Settings

format (default: {avg1} {avg5})
color (default: #ffffff) – The text color
critical_limit (default: 4) – Limit above which the load is considered critical, defaults to amount of cores.
critical_color (default: #ff0000) – The critical color
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.mail.Mail[source]¶

Generic mail checker

The backends setting determines the backends to use. For available backends see Mail Backends.

Settings

backends (required) – List of backends (instances of i3pystatus.mail.xxx.zzz, e.g. imap.IMAP)
color (default: #ffffff)
color_unread (default: #ff0000)
format (default: {unread} new email)
format_plural (default: {account} : {current_unread}/{unread} new emails)
hide_if_null (default: True) – Don’t output anything if there are no new mails
email_client (default: empty) – The command to run on left click. For example, to launch Thunderbird set email_client` to ``thunderbird. Alternatively, to bring Thunderbird into focus, set email_client to i3-msg -q [class="^Thunderbird$"] focus. Hint: To discover the X window class of your email client run ‘xprop | grep -i class’ and click on it’s window
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: open_client) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: ['scroll_backend', 1]) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: ['scroll_backend', -1]) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

run()[source]¶: Returns the sum of unread messages across all registered backends

class i3pystatus.makewatch.MakeWatch[source]¶

Watches for make jobs and notifies when they are completed. requires: psutil

Settings

name (default: make) – Listen for a job other than ‘make’ jobs
running_color (default: #FF0000) – Text color while the job is running
idle_color (default: #00FF00) – Text color while the job is not running
format (default: {name}: {status})
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.mem.Mem[source]¶

Shows memory load

Available formatters

{avail_mem}
{percent_used_mem}
{used_mem}
{total_mem}

Requires psutil (from PyPI)

Settings

format (default: {avail_mem} MiB) – format string used for output.
divisor (default: 1048576) – divide all byte values by this value, default is 1024**2 (megabytes)
warn_percentage (default: 50) – minimal percentage for warn state
alert_percentage (default: 80) – minimal percentage for alert state
color (default: #00FF00) – standard color
warn_color (default: #FFFF00) – defines the color used when warn percentage is exceeded
alert_color (default: #FF0000) – defines the color used when alert percentage is exceeded
round_size (default: 1) – defines number of digits in round
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.mem_bar.MemBar[source]¶

Shows memory load as a bar.

Available formatters

{used_mem_bar}

Requires psutil and colour (from PyPI)

Settings

format (default: {used_mem_bar}) – format string used for output.
warn_percentage (default: 50) – minimal percentage for warn state
alert_percentage (default: 80) – minimal percentage for alert state
color (default: #00FF00) – standard color
warn_color (default: #FFFF00) – defines the color used when warn percentage is exceeded
alert_color (default: #FF0000) – defines the color used when alert percentage is exceeded
multi_colors (default: False) – whether to use range of colors from ‘color’ to ‘alert_color’ based on memory usage.
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.modsde.ModsDeChecker[source]¶

This class returns i3status parsable output of the number of unread posts in any bookmark in the mods.de forums.

Settings

format (default: {unread} new posts in bookmarks) – Use {unread} as the formatter for number of unread posts
keyring_backend (default: empty) – alternative keyring backend for retrieving credentials
offset (default: 0) – subtract number of posts before output
color (default: #7181fe)
username (required)
password (required)
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: open_browser) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.moon.MoonPhase[source]¶

Available Formatters

status: Allows for mapping of current moon phase - New Moon: - Waxing Crescent: - First Quarter: - Waxing Gibbous: - Full Moon: - Waning Gibbous: - Last Quarter: - Waning Crescent:

Settings

format (default: {illum} {status})
status (default: {'Waxing Crescent': 'WaxCres', 'First Quarter': 'FQ', 'New Moon': 'NM', 'Full Moon': 'FM', 'Waxing Gibbous': 'WaxGib', 'Last Quarter': 'LQ', 'Waning Crescent': 'WanCres', 'Waning Gibbous': 'WanGib'}) – Current moon phase
illum (default: <function MoonPhase.illum at 0x7f8bb1ba4bf8>) – Percentage that is illuminated
color (default: {'Waxing Crescent': '#138DD8', 'First Quarter': '#265ECC', 'New Moon': '#00BDE5', 'Full Moon': '#4C00B3', 'Waxing Gibbous': '#392FBF', 'Last Quarter': '#C32250', 'Waning Crescent': '#FF341F', 'Waning Gibbous': '#871181'}) – Set color
interval (default: 7200) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.mpd.MPD[source]¶

Displays various information from MPD (the music player daemon)

Available formatters (uses formatp)

{title} — (the title of the current song)
{album} — (the album of the current song, can be an empty string (e.g. for online streams))
{artist} — (can be empty, too)
{filename} — (file name with out extension and path; empty unless title is empty)
{song_elapsed} — (Position in the currently playing song, uses TimeWrapper, default is %m:%S)
{song_length} — (Length of the current song, same as song_elapsed)
{pos} — (Position of current song in playlist, one-based)
{len} — (Songs in playlist)
{status} — (play, pause, stop mapped through the status dictionary)
{bitrate} — (Current bitrate in kilobit/s)
{volume} — (Volume set in MPD)

Available callbacks

switch_playpause — Plays if paused or stopped, otherwise pauses. Emulates mpc toggle.
stop — Stops playback. Emulates mpc stop.
next_song — Goes to next track in the playlist. Emulates mpc next.
previous_song — Goes to previous track in the playlist. Emulates mpc prev.

Settings

host (default: localhost)
port (default: 6600) – MPD port. If set to 0, host will we interpreted as a Unix socket.
format (default: {title} {status}) – formatp string
status (default: {'play': '▶', 'stop': '◾', 'pause': '▷'}) – Dictionary mapping pause, play and stop to output
color (default: #FFFFFF) – The color of the text
max_field_len (default: 25) – Defines max length for in truncate_fields defined fields, if truncated, ellipsis are appended as indicator. It’s applied before max_len. Value of 0 disables this.
max_len (default: 100) – Defines max length for the hole string, if exceeding fields specefied in truncate_fields are truncated equaly. If truncated, ellipsis are appended as indicator. It’s applied after max_field_len. Value of 0 disables this.
truncate_fields (default: ('title', 'album', 'artist')) – fields that will be truncated if exceeding max_field_len or max_len.
hide_inactive (default: False) – Hides status information when MPD is not running
password (default: empty) – A password for access to MPD. (This is sent in cleartext to the server.)
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: switch_playpause) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: next_song) – Callback called on right click (see Callbacks)
on_upscroll (default: next_song) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: previous_song) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.net_speed.NetSpeed[source]¶

Attempts to provide an estimation of internet speeds. Requires: speedtest_cli

Settings

url (default: empty) – Target URL to download a file from. Uses speedtest_cli to find the ‘best’ server if none is supplied.
units (default: bits) – Valid values are B, b, bytes, or bits
format (default: {speed} ({hosting_provider}))
interval (default: 300) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.network.Network[source]¶

Displays network information for an interface. formatp support if u wanna display recv/send speed separate in dynamic color mode, please enable pango hint.

Requires the PyPI packages colour, netifaces, psutil (optional, see below) and basiciw (optional, see below).

Available formatters

Network Information Formatters:

{interface} — same as setting
{v4} — IPv4 address
{v4mask} — subnet mask
{v4cidr} — IPv4 address in cidr notation (i.e. 192.168.2.204/24)
{v6} — IPv6 address
{v6mask} — subnet mask
{v6cidr} — IPv6 address in cidr notation
{mac} — MAC of interface

Wireless Information Formatters (requires PyPI package basiciw):

{essid} — ESSID of currently connected wifi
{freq} — Current frequency
{quality} — Link quality in percent
{quality_bar} —Bar graphically representing link quality

Network Traffic Formatters (requires PyPI package psutil):

{interface} — the configured network interface
{kbs} – Float representing KiBs corresponds to graph type
{network_graph} – Unicode graph representing network usage
{bytes_sent} — bytes sent per second (divided by divisor)
{bytes_recv} — bytes received per second (divided by divisor)
{packets_sent} — bytes sent per second (divided by divisor)
{packets_recv} — bytes received per second (divided by divisor)
{rx_tot_Mbytes} — total Mbytes received
{tx_tot_Mbytes} — total Mbytes sent

Settings

format_up (default: {interface} {network_graph}{kbs}KB/s) – format string
format_down (default: {interface}: DOWN) – format string
color_up (default: #00FF00)
color_down (default: #FF0000)
interface (default: eth0) – Interface to watch, eg ‘eth0’
dynamic_color (default: True) – Set color dynamically based on network traffic. Note: this overrides color_up
start_color (default: #00FF00) – Hex or English name for start of color range, eg ‘#00FF00’ or ‘green’
end_color (default: red) – Hex or English name for end of color range, eg ‘#FF0000’ or ‘red’
graph_width (default: 15) – Width of the network traffic graph
graph_style (default: blocks) – Graph style (‘blocks’, ‘braille-fill’, ‘braille-peak’, or ‘braille-snake’)
recv_limit (default: 2048) – Expected max KiB/s. This value controls the drawing color of receive speed
sent_limit (default: 1024) – Expected max KiB/s. similar with receive_limit
separate_color (default: False) – display recv/send color separate in dynamic color mode.Note: only network speed formatters will display with range color
graph_type (default: input) – Whether to draw the network traffic graph for input or output. Allowed values ‘input’ or ‘output’
divisor (default: 1024) – divide all byte values by this value
ignore_interfaces (default: ['lo']) – Array of interfaces to ignore when cycling through on click, eg, [‘lo’]
round_size (default: empty) – defines number of digits in round
detached_down (default: True) – If the interface doesn’t exist, display it as if it were down
unknown_up (default: False) – If the interface is in unknown state, display it as if it were up
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: nm-connection-editor) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: cycle_interface) – Callback called on right click (see Callbacks)
on_upscroll (default: ['cycle_interface', 1]) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: ['cycle_interface', -1]) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

cycle_interface(increment=1)[source]¶: Cycle through available interfaces in increment steps. Sign indicates direction.

class i3pystatus.now_playing.NowPlaying[source]¶

Shows currently playing track information, supports most media players

Requires python-dbus available from every distros’ package manager.

Left click on the module play/pauses, right click goes to the next track.

Available formatters (uses formatp)

{title} — (the title of the current song)
{album} — (the album of the current song, can be an empty string (e.g. for online streams))
{artist} — (can be empty, too)
{filename} — (file name with out extension and path; empty unless title is empty)
{song_elapsed} — (position in the currently playing song, uses TimeWrapper, default is %m:%S)
{song_length} — (length of the current song, same as song_elapsed)
{status} — (play, pause, stop mapped through the status dictionary)
{volume} — (volume)

Settings

player (default: empty) – Player name. If not set, compatible players will be detected automatically.
status (default: {'play': '▶', 'stop': '◾', 'pause': '▷'}) – Dictionary mapping pause, play and stop to output text
format (default: {title} {status}) – formatp string
color (default: #ffffff) – Text color
format_no_player (default: No Player) – Text to show if no player is detected
color_no_player (default: #ffffff) – Text color when no player is detected
hide_no_player (default: True) – Hide output if no player is detected
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: playpause) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: next_song) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.online.Online[source]¶

Show internet connection status.

Settings

color (default: #ffffff) – Text color when online
color_offline (default: #ff0000) – Text color when offline
format_online (default: online) – Status text when online
format_offline (default: offline) – Status text when offline
interval (default: 10) – Update interval
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.openfiles.Openfiles[source]¶

Displays the current/max open files.

Settings

filenr_path (default: /proc/sys/fs/file-nr) – Location to file-nr (usually /proc/sys/fs/file-nr
color (default: FFFFFF)
format (default: open/max: {openfiles}/{maxfiles})
interval (default: 30) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.openstack_vms.Openstack_vms[source]¶

Displays the number of VMs in an openstack cluster in ACTIVE and non-ACTIVE states. Requires: python-novaclient

Settings

auth_url (required) – OpenStack cluster authentication URL (OS_AUTH_URL)
username (required) – Username for OpenStack authentication (OS_USERNAME)
password (required) – Password for Openstack authentication (OS_PASSWORD)
tenant_name (required) – Tenant/Project name to view (OS_TENANT_NAME)
color (default: #00FF00) – Display color when non-active VMs are =< threshold
crit_color (default: #FF0000) – Display color when non-active VMs are => threshold
threshold (default: 0) – Set critical indicators when non-active VM pass this number
horizon_url (default: empty) – When clicked, open this URL in a browser
format (default: {tenant_name}: {active_servers} up, {nonactive_servers} down)
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: openurl) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.openvpn.OpenVPN[source]¶

Monitor OpenVPN connections. Currently only supports systems that use Systemd.

Formatters:

{vpn_name} — Same as setting.
{status} — Unicode up or down symbol.
{output} — Output of status_command.
{label} — Label for this connection, if defined.

Settings

format (default: {vpn_name} {status}) – Format string
color_up (default: #00ff00) – VPN is up
color_down (default: #FF0000) – VPN is down
status_down (default: ▼) – Symbol to display when down
status_up (default: ▲) – Symbol to display when up
vpn_name (default: empty) – Name of VPN
vpn_up_command (default: sudo /bin/systemctl start openvpn@%(vpn_name)s.service) – Command to bring up the VPN - default requires editing /etc/sudoers
vpn_down_command (default: sudo /bin/systemctl stop openvpn@%(vpn_name)s.service) – Command to bring up the VPN - default requires editing /etc/sudoers
status_command (default: bash -c 'systemctl show openvpn@%(vpn_name)s | grep ActiveState=active') – command to find out if the VPN is active
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.parcel.ParcelTracker[source]¶

Used to track parcel/shipments.

Supported carriers: DHL, UPS, Itella

parcel.UPS(“<id_code>”)
parcel.DHL(“<id_code>”)
parcel.Itella(“<id_code>”[, “en”|”fi”|”sv”]) Second parameter is language. Requires beautiful soup 4 (bs4)

Requires lxml and cssselect.

Settings

instance (required) – Tracker instance, for example parcel.UPS('your_id_code')
format (default: {name}:{progress})
name (required)
interval (default: 60) – interval in seconds between module updates
on_leftclick (default: open_browser) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.pianobar.Pianobar[source]¶

Shows the title and artist name of the current music

In pianobar config file must be setted the fifo and event_command options (see man pianobar for more information)

For the event_cmd use: https://github.com/jlucchese/pianobar/blob/master/contrib/pianobar-song-i3.sh

Mouse events: - Left click play/pauses - Right click plays next song - Scroll up/down changes volume

Settings

format (default: {songtitle} -- {songartist})
songfile (required) – File generated by pianobar eventcmd
ctlfile (required) – Pianobar fifo file
color (default: #FFFFFF) – The color of the text
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: playpause) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: next_song) – Callback called on right click (see Callbacks)
on_upscroll (default: increase_volume) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: decrease_volume) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.ping.Ping[source]¶

This module display the ping value between your computer and a host.

switch_state callback can disable the Ping when desired. host propertie can be changed for set a specific host.

Available formatters

{ping} the ping value in milliseconds.

Settings

color (default: #FFFFFF)
format (default: {ping} ms)
color_disabled (default: empty) – color when disabled
color_down (default: #FF0000) – color when ping fail
format_disabled (default: empty) – format string when disabled
format_down (default: down) – format string when ping fail
host (default: 8.8.8.8) – host to ping
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: switch_state) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.plexstatus.Plexstatus[source]¶

Displays what is currently being streamed from your Plex Media Server.

Settings

apikey (required) – Your Plex API authentication key (https://support.plex.tv/hc/en-us/articles/204059436-Finding-your-account-token-X-Plex-Token) .
address (required) – Hostname or IP address of the Plex Media Server.
port (default: 32400) – Port which Plex Media Server is running on.
interval (default: 120) – Update interval (in seconds).
format_no_streams (default: empty) – String that is shown if nothing is being streamed.
format (default: {platform}: {title})
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.pomodoro.Pomodoro[source]¶

This plugin shows Pomodoro timer.

Left click starts/restarts timer. Right click stops it.

Settings

sound (required) – Path to sound file to play as alarm. Played by “aplay” utility
pomodoro_duration (default: 1500) – Working (pomodoro) interval duration in seconds
break_duration (default: 300) – Short break duration in seconds
long_break_duration (default: 900) – Long break duration in seconds
short_break_count (default: 3) – Short break count before first long break
format (default: ☯ {current_pomodoro}/{total_pomodoro} {time}) – format string, available formatters: current_pomodoro, total_pomodoro, time
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: start) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: stop) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.pulseaudio.PulseAudio[source]¶

Shows volume of default PulseAudio sink (output).

Requires amixer for toggling mute and incrementing/decrementing volume on scroll.
Depends on the PyPI colour module - https://pypi.python.org/pypi/colour/0.0.5

Available formatters

{volume} — volume in percent (0...100)
{db} — volume in decibels relative to 100 %, i.e. 100 % = 0 dB, 50 % = -18 dB, 0 % = -infinity dB (the literal value for -infinity is -∞)
{muted} — the value of one of the muted or unmuted settings
{volume_bar} — unicode bar showing volume

Settings

format (default: ♪: {volume})
format_muted (default: empty) – optional format string to use when muted
muted (default: M)
unmuted (default: empty)
color_muted (default: #FF0000)
color_unmuted (default: #FFFFFF)
step (default: 5) – percentage to increment volume on scroll
bar_type (default: vertical) – type of volume bar. Allowed values are ‘vertical’ or ‘horizontal’
multi_colors (default: False) – whether or not to change the color from ‘color_muted’ to ‘color_unmuted’ based on volume percentage
vertical_bar_width (default: 2) – how many characters wide the vertical volume_bar should be
on_leftclick (default: pavucontrol) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: switch_mute) – Callback called on right click (see Callbacks)
on_upscroll (default: increase_volume) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: decrease_volume) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: change_sink) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

context_notify_cb(context, _)[source]¶

Checks wether the context is ready

-Queries server information (server_info_cb is called) -Subscribes to property changes on all sinks (update_cb is called)

init()[source]¶: Creates context, when context is ready context_notify_cb is called

request_update(context)[source]¶: Requests a sink info update (sink_info_cb is called)

server_info_cb(context, server_info_p, userdata)[source]¶: Retrieves the default sink and calls request_update

sink_info_cb(context, sink_info_p, _, __)[source]¶: Updates self.output

update_cb(context, t, idx, userdata)[source]¶: A sink property changed, calls request_update

class i3pystatus.pyload.pyLoad[source]¶

Shows pyLoad status

Available formatters

{captcha} — see captcha_true and captcha_false, which are the values filled in for this formatter
{progress} — average over all running downloads
{progress_all} — percentage of completed files/links in queue
{speed} — kilobytes/s
{download} — downloads enabled, also see download_true and download_false
{total} — number of downloads
{free_space} — free space in download directory in gigabytes

Settings

address (default: http://127.0.0.1:8000) – Address of pyLoad webinterface
format (default: {captcha} {progress_all:.1f}% {speed:.1f} kb/s)
captcha_true (default: Captcha waiting)
captcha_false (default: empty)
download_true (default: Downloads enabled)
download_false (default: Downloads disabled)
username (required)
password (required)
keyring_backend (default: empty) – alternative keyring backend for retrieving credentials
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: open_webbrowser) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.reddit.Reddit[source]¶

This module fetches and displays posts and/or user mail/messages from reddit.com. Left-clicking on the display text opens the permalink/comments page using webbrowser.open() while right-clicking opens the URL of the submission directly. Depends on the Python Reddit API Wrapper (PRAW) <https://github.com/praw-dev/praw>.

Available formatters

{submission_title}
{submission_author}
{submission_points}
{submission_comments}
{submission_permalink}
{submission_url}
{submission_domain}
{submission_subreddit}
{message_unread}
{message_author}
{message_subject}
{message_body}
{link_karma}
{comment_karma}

Settings

format (default: [{submission_subreddit}] {submission_title} ({submission_domain})) – Format string used for output.
username (default: empty) – Reddit username.
password (default: empty) – Reddit password.
keyring_backend (default: empty) – alternative keyring backend for retrieving credentials
subreddit (default: empty) – Subreddit to monitor. Uses frontpage if unspecified.
sort_by (default: hot) – ‘hot’, ‘new’, ‘rising’, ‘controversial’, or ‘top’.
color (default: #FFFFFF) – Standard color.
colorize (default: True) – Enable color change on new message.
color_orangered (default: #FF4500) – Color for new messages.
mail_brackets (default: False) – Display unread message count in square-brackets.
title_maxlen (default: 80) – Maximum number of characters to display in title.
interval (default: 300) – Update interval.
status (default: {'new_mail': '✉', 'no_mail': ''}) – New message indicator.
on_leftclick (default: open_permalink) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.regex.Regex[source]¶

Simple regex file watcher

The groups of the regex are passed to the format string as positional arguments.

Settings

format (default: {0}) – format string used for output
regex (required)
file (required) – file to search for regex matches
flags (default: 0) – Python.re flags
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.runwatch.RunWatch[source]¶

Expands the given path using glob to a pidfile and checks if the process ID found inside is valid (that is, if the process is running). You can use this to check if a specific application, such as a VPN client or your DHCP client is running.

Available formatters

{pid}
{name}

Settings

format_up (default: {name})
format_down (default: {name})
color_up (default: #00FF00)
color_down (default: #FF0000)
path (required)
name (required)
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.scores.Scores[source]¶

This is a generic score checker, which must use at least one configured score backend.

Followed games can be scrolled through with the mouse/trackpad. Left-clicking on the module will refresh the scores, while right-clicking it will cycle through the configured backends. Double-clicking the module with the left button will launch the league-specific (MLB Gameday / NHL GameCenter / etc.) URL for the game. If there is not an active game, double-clicking will launch the league-specific scoreboard URL containing all games for the current day.

Double-clicking with the right button will reset the current backend to the first game in the scroll list. This is useful for quickly switching back to a followed team’s game after looking at other game scores.

Scores for the previous day’s games will be shown until 10am Eastern Time (US), after which time the current day’s games will be shown.

Available formatters

Formatters are set in the backend instances, see the Score Backends for more information.

This module supports the formatp extended string format syntax. This allows for values to be hidden when they evaluate as False (e.g. when a formatter is blank (an empty string). The default values for the format strings set in the score backends (format_pregame, format_in_progress, etc.) make heavy use of formatp, hiding many formatters when they are blank.

Usage example

from i3pystatus import Status
from i3pystatus.scores import mlb, nhl

status = Status()

status.register(
    'scores',
    hints={'markup': 'pango'},
    colorize_teams=True,
    favorite_icon='<span size="small" color="#F5FF00">★</span>',
    backends=[
        mlb.MLB(
            teams=['CWS', 'SF'],
            format_no_games='No games today :(',
            inning_top='⬆',
            inning_bottom='⬇',
        ),
        nhl.NHL(teams=['CHI']),
        nba.NBA(
            teams=['GSW'],
            all_games=False,
        ),
        epl.EPL(),
    ],
)

status.run()

To enable colorized team name/city/abbbreviation, colorize_teams must be set to True. This also requires that i3bar is configured to use Pango, and that the hints param is set for the module and includes a markup key, as in the example above. To ensure that i3bar is configured to use Pango, the font param in your i3 config file must start with pango:.

If a teams param is not specified for the backend, then all games for the current day will be tracked, and will be ordered by the start time of the game. Otherwise, only games from explicitly-followed teams will be tracked, and will be in the same order as listed. If ALL is part of the list, then games from followed teams will be first in the scroll list, followed by all remaining games in order of start time.

Therefore, in the above example, only White Sox and Giants games would be tracked, while in the below example all games would be tracked, with White Sox and Giants games appearing first in the scroll list and the remaining games appearing after them, in order of start time.

from i3pystatus import Status
from i3pystatus.scores import mlb

status = Status()

status.register(
    'scores',
    hints={'markup': 'pango'},
    colorize_teams=True,
    favorite_icon='<span size="small" color="#F5FF00">★</span>',
    backends=[
        mlb.MLB(
            teams=['CWS', 'SF', 'ALL'],
            team_colors={
                'NYM': '#1D78CA',
            },
        ),
    ],
)

status.run()

Troubleshooting

If the module gets stuck during an update (i.e. the refresh_icon does not go away), then the update thread probably encountered a traceback. This traceback will (by default) be logged to ~/.i3pystatus-<pid> where <pid> is the PID of the thread. However, it may be more convenient to manually set the logfile to make the location of the log data reliable and avoid clutter in your home directory. For example:

import logging
from i3pystatus import Status
from i3pystatus.scores import mlb, nhl

status = Status(
    logfile='/home/username/var/i3pystatus.log',
)

status.register(
    'scores',
    log_level=logging.DEBUG,
    backends=[
        mlb.MLB(
            teams=['CWS', 'SF'],
            log_level=logging.DEBUG,
        ),
        nhl.NHL(
            teams=['CHI'],
            log_level=logging.DEBUG,
        ),
        nba.NBA(
            teams=['CHI'],
            log_level=logging.DEBUG,
        ),
    ],
)

status.run()

Note

The log_level must be set separately in both the module and the backend instances (as shown above), otherwise the backends will still use the default log level.

Settings

backends (default: []) – List of backend instances
favorite_icon (default: ★) – Value for the {away_favorite} and {home_favorite} formatter when the displayed game is being played by a followed team
color (default: empty) – Color to be used for non-colorized text (defaults to the i3bar color)
color_no_games (default: empty) – Color to use when no games are scheduled for the currently-displayed backend (defaults to the i3bar color)
colorize_teams (default: False) – Dislay team city, name, and abbreviation in the team’s color (as defined in the backend‘s team_colors attribute)
scroll_arrow (default: ⬍) – Value used for the {scroll} formatter to indicate that more than one game is being tracked for the currently-displayed backend
refresh_icon (default: ⟳) – Text to display (in addition to any text currently shown by the module) when refreshing scores. NOTE: Depending on how quickly the update is performed, the icon may not be displayed.
on_leftclick (default: ['check_scores', 'click event']) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: ['cycle_backend', 1]) – Callback called on right click (see Callbacks)
on_upscroll (default: ['scroll_game', 1]) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: ['scroll_game', -1]) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: ['launch_web']) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: ['reset_backend']) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.scratchpad.Scratchpad[source]¶

Display the amount of windows and indicate urgency hints on scratchpad (async).

fork from scratchpad_async of py3status by cornerman

Requires the PyPI package i3ipc.

Available formaters

{number} — amount of windows on scratchpad

@author jok @license BSD

Settings

format (default: {number} ⌫) – format string.
always_show (default: True) – whether the indicator should be shown if there are no scratchpad windows
color_urgent (default: #900000) – color of urgent
color (default: #FFFFFF) – text color
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.sge.SGETracker[source]¶

Used to display status of Batch computing jobs on a cluster running Sun Grid Engine. The data is collected via ssh, so a valid ssh address must be specified.

Requires lxml.

Settings

ssh (required) – The SSH connection address. Can be user@host or user:password@host or user@host -p PORT etc.
color (default: #ffffff)
format (default: SGE qw: {queued} / r: {running} / Eqw: {error})
interval (default: 60) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.shell.Shell[source]¶

Shows output of shell command

Available formatters

{output} — just the striped command output without newlines

Settings

command (required) – command to be executed
color (default: #FFFFFF) – standard color
error_color (default: #FF0000) – color to use when non zero exit code is returned
format (default: {output})
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.solaar.Solaar[source]¶

Shows status and load percentage of bluetooth-device

Available formatters

{output} — percentage of battery and status

Settings

nameOfDevice (required) – name of the bluetooth-device
color (default: #FFFFFF) – standard color
error_color (default: #FF0000) – color to use when non zero exit code is returned
interval (default: 30) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.spotify.Spotify[source]¶

Gets Spotify info using playerctl

Available formatters

{status} — current status icon (paused/playing)
{length} — total song duration (mm:ss format)
{artist} — artist
{title} — title
{album} — album

Settings

format (default: {status} {length} {artist} - {title}) – formatp string
format_not_running (default: Not running) – Text to show if cmus is not running
color (default: #ffffff) – The color of the text
color_not_running (default: #ffffff) – The color of the text, when cmus is not running
status (default: {'playing': '▶', 'paused': '▷'}) – Dictionary mapping status to output
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: playpause) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: next_song) – Callback called on right click (see Callbacks)
on_upscroll (default: next_song) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: previous_song) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

get_info(player)[source]¶: gets spotify track info from playerctl

next_song()[source]¶: skips to the next song

playpause()[source]¶: Pauses and plays spotify

previous_song()[source]¶: Plays the previous song

run()[source]¶: Main statement, executes all code every interval

class i3pystatus.syncthing.Syncthing[source]¶

Check Syncthing’s online status and start/stop Syncthing via click events.

Requires requests.

Settings

format_up (default: ST up) – Text to show when Syncthing is running
format_down (default: ST down) – Text to show when Syncthing is not running
color_up (default: #00ff00) – Color when Syncthing is running
color_down (default: #ff0000) – Color when Syncthing is not running
configfile (default: ~/.config/syncthing/config.xml) – Path to Syncthing config
url (default: auto) – Syncthing GUI URL; “auto” reads from local config
apikey (default: auto) – Syncthing APIKEY; “auto” reads from local config
verify_ssl (default: True) – Verify SSL certificate
interval (default: 10) – interval in seconds between module updates
on_leftclick (default: st_open) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: st_toggle_systemd) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

st_open()[source]¶: Callback: Open Syncthing web UI

st_restart()[source]¶: Callback: Restart Syncthing

st_restart_systemd()[source]¶: Callback: systemctl –user restart syncthing.service

st_start_systemd()[source]¶: Callback: systemctl –user start syncthing.service

st_stop()[source]¶: Callback: Stop Syncthing

st_stop_systemd()[source]¶: Callback: systemctl –user stop syncthing.service

st_toggle_systemd()[source]¶: Callback: start Syncthing service if offline, or stop it when online

class i3pystatus.taskwarrior.Taskwarrior[source]¶

Check Taskwarrior for pending tasks Requires json

Formaters:

{ready} — contains number of tasks returned by ready_filter
{urgent} — contains number of tasks returned by urgent_filter
{next} — contains the description of next task

Settings

format (default: Task: {next}) – format string
ready_filter (default: +READY) – Filters to get ready tasks example: +READY
urgent_filter (default: +TODAY) – Filters to get urgent tasks example: +TODAY
enable_mark_done (default: False) – Enable right click mark task as done
color_urgent (default: #FF0000) – #FF0000
color_ready (default: #78EAF2) – #78EAF2
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: mark_task_as_done) – Callback called on right click (see Callbacks)
on_upscroll (default: get_prev_task) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: get_next_task) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.temp.Temperature[source]¶

Shows CPU temperature of Intel processors

AMD is currently not supported as they can only report a relative temperature, which is pretty useless

Settings

format (default: {temp} °C) – format string used for output. {temp} is the temperature in degrees celsius
display_if (default: True) – snippet that gets evaluated. if true, displays the module output
color (default: #FFFFFF)
file (default: /sys/class/thermal/thermal_zone0/temp)
alert_temp (default: 90)
alert_color (default: #FF0000)
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.text.Text[source]¶

Display static, colored text.

Settings

text (required)
color (default: empty) – HTML color code #RRGGBB
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.timer.Timer[source]¶

Timer module to remind yourself that there probably is something else you should be doing right now.

Main features include:

Set custom time interval with click events.
Different output formats triggered when remaining time is less than x seconds.
Execute custom python function or external command when timer overflows (or reaches zero depending on how you look at it).

Available formatters

Time formatters are available to show the remaining time. These include %h, %m, %s, %H, %M, %S. See TimeWrapper for detailed description.

The format_custom setting allows you to display different formats when certain amount of seconds is remaining. This setting accepts list of tuples which contain time in seconds, format string and color string each. See the default settings for an example:

(0, "+%M:%S", "#ffffff") - Use this format after overflow. White text with red background set by the urgent flag.
(60, "-%M:%S", "#ffa500") - Change color to orange in last minute.
(3600, "-%M:%S", "#00ff00") - Hide hour digits when remaining time is less than one hour.

Only first matching rule is applied (if any).

Callbacks

Module contains three mouse event callback methods:

start() - Default: Left click starts (or adds) 5 minute countdown.
increase() - Default: Upscroll/downscroll increase/decrease time by 1 minute.
reset() - Default: Right click resets timer.

Two new event settings were added:

on_overflow - Executed when remaining time reaches zero.
on_reset - Executed when timer is reset but only if overflow occured.

These settings accept either a python callable object or a string with shell command. Python callbacks should be non-blocking and without any arguments.

Here is an example that plays a short sound file in ‘loop’ every 60 seconds until timer is reset. (play is part of SoX - the Swiss Army knife of audio manipulation)

on_overflow = "play -q /path/to/sound.mp3 pad 0 60 repeat -"
on_reset = "pkill -SIGTERM -f 'play -q /path/to/sound.mp3 pad 0 60 repeat -'"

Settings

format (default: -%h:%M:%S) – Default format that is showed if no format_custom rules are matched.
format_stopped (default: T) – Format showed when timer is inactive.
color (default: #00ff00)
color_stopped (default: #ffffff)
format_custom (default: [(0, '+%M:%S', '#ffffff'), (60, '-%M:%S', '#ffa500'), (3600, '-%M:%S', '#00ff00')])
overflow_urgent (default: True) – Set urgent flag on overflow.
on_overflow (default: empty)
on_reset (default: empty)
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: ['start', 300]) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: reset) – Callback called on right click (see Callbacks)
on_upscroll (default: ['increase', 60]) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: ['increase', -60]) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

increase(seconds)[source]¶

Change remainig time value.

Parameters:	seconds (int) – Seconds to add. Negative value substracts from remaining time.

reset()[source]¶: Stop timer and execute on_reset if overflow occured.

start(seconds=300)[source]¶

Starts timer. If timer is already running it will increase remaining time instead.

Parameters:	seconds (int) – Initial time.

class i3pystatus.uname.Uname[source]¶

uname(1) like module.

Available formatters

{sysname} — operating system name
{nodename} — name of machine on network (implementation-defined)
{release} — operating system release
{version} — operating system version
{machine} — hardware identifier

Settings

format (default: {sysname} {release}) – format string used for output
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.updates.Updates[source]¶

Generic update checker. To use select appropriate backend(s) for your system. For list of all available backends see Update Backends.

Left clicking on the module will refresh the count of upgradeable packages. This may be used to dismiss the notification after updating your system.

Right clicking shows a desktop notification with a summary count and a list of available updates.

Available formatters

{count} — Sum of all available updates from all backends.
For each backend registered there is one formatter named after the backend, multiple identical backends do not accumulate, but overwrite each other.
For example, {Cower} (note capital C) is the number of updates reported by the cower backend, assuming it has been registered.

Usage example

from i3pystatus import Status
from i3pystatus.updates import pacman, cower

status = Status()

status.register("updates",
                format = "Updates: {count}",
                format_no_updates = "No updates",
                backends = [pacman.Pacman(), cower.Cower()])

status.run()

Settings

backends (required) – Required list of backends used to check for updates.
format (default: Updates: {count}) – Format used when updates are available. May contain formatters.
format_no_updates (default: empty) – String that is shown if no updates are available. If not set the module will be hidden if no updates are available.
format_working (default: empty) – Format used while update queries are run. By default the same as format.
format_summary (default: empty) – Format for the summary line of notifications. By default the same as format.
notification_icon (default: software-update-available) – Icon shown when reporting the list of updates. Default is software-update-available, and can be None for no icon.
color (default: #00DD00)
color_no_updates (default: empty)
color_working (default: empty)
interval (default: 3600) – Default interval is set to one hour.
on_leftclick (default: run) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: report) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.uptime.Uptime[source]¶

Outputs Uptime

Available formatters

{days} - uptime in days
{hours} - rest of uptime in hours
{mins} - rest of uptime in minutes
{secs} - rest of uptime in seconds
{uptime} - deprecated: equals ‘{hours}:{mins}‘

Settings

format (default: up {hours}:{mins}) – Format string
color (default: #ffffff) – String color
alert (default: False) – If you want the string to change color
seconds_alert (default: 2592000) – How many seconds necessary to start the alert
color_alert (default: #ff0000) – Alert color
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.vk.Vk[source]¶

Display amount of unread messages in VK social network. Creating your own VK API app is highly recommended for your own privacy, though there is a default one provided. Reference vk.com/dev for instructions on creating VK API app. If access_token is not specified, the module will try to open a request page in browser. You will need to manually copy obtained acess token to your config file. Requires the PyPI package vk.

Settings

app_id (default: 5160484) – Id of your VK API app
access_token (default: empty) – Your access token. You must have messages and offline access permissions
token_error (default: Vk: token error) – Message to be shown if there’s some problem with your token
color (default: #ffffff) – General color of the output
color_bad (default: #ff0000) – Color of the output in case of access token error
color_unread (default: #ffffff) – Color of the output if there are unread messages
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.weather.Weather[source]¶

This is a generic weather-checker which must use a configured weather backend. For list of all available backends see Weather Backends.

Left clicking on the module will launch the forecast page for the location being checked.

Available formatters

{city} — Location of weather observation
{condition} — Current weather condition (Rain, Snow, Overcast, etc.)
{icon} — Icon representing the current weather condition
{observation_time} — Time of weather observation (supports strftime format flags)
{current_temp} — Current temperature, excluding unit
{low_temp} — Forecasted low temperature, excluding unit
{high_temp} — Forecasted high temperature, excluding unit (may be empty in the late afternoon)
{temp_unit} — Either °C or °F, depending on whether metric or
{feelslike} — “Feels Like” temperature, excluding unit
{dewpoint} — Dewpoint temperature, excluding unit imperial units are being used
{wind_speed} — Wind speed, excluding unit
{wind_unit} — Either kph or mph, depending on whether metric or imperial units are being used
{wind_direction} — Wind direction
{wind_gust} — Speed of wind gusts in mph/kph, excluding unit
{pressure} — Barometric pressure, excluding unit
{pressure_unit} — mb or in, depending on whether metric or imperial units are being used
{pressure_trend} — + if rising, - if falling, or an empty string if the pressure is steady (neither rising nor falling)
{visibility} — Visibility distance, excluding unit
{visibility_unit} — Either km or mi, depending on whether metric or imperial units are being used
{humidity} — Current humidity, excluding percentage symbol
{uv_index} — UV Index

This module supports the formatp extended string format syntax. This allows for values to be hidden when they evaluate as False. This comes in handy for the weathercom backend, which at a certain point in the afternoon will have a blank {high_temp} value. Using the following snippet in your format string will only display the high temperature information if it is not blank:

{current_temp}{temp_unit}[ Hi: {high_temp}[{temp_unit}]] Lo: {low_temp}{temp_unit}

Brackets are evaluated from the outside-in, so the fact that the only formatter in the outer block ({high_temp}) is empty would keep the inner block from being evaluated at all, and entire block would not be displayed.

See the following links for usage examples for the available weather backends:

Weather.com
Weather Underground

Settings

colorize (default: False) – Vary the color depending on the current conditions.
color_icons (default: {'Partly Cloudy': ('☁', '#f8f8ff'), 'Rainy': ('⛈', '#cbd2c0'), 'Fog': ('', '#949494'), 'Thunderstorm': ('⚡', '#cbd2c0'), 'Snow': ('☃', '#ffffff'), 'Sunny': ('☀', '#ffff00'), 'default': ('', None), 'Cloudy': ('☁', '#f8f8ff'), 'Fair': ('☼', '#ffcc00')}) – Dictionary mapping weather conditions to tuples containing a UTF-8 code for the icon, and the color to be used.
color (default: empty) – Display color (or fallback color if colorize is True). If not specified, falls back to default i3bar color.
backend (required) – Weather backend instance
interval (default: 1800)
format (default: {current_temp}{temp_unit})
on_leftclick (default: open_forecast_url) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

get_color_data(condition)[source]¶: Disambiguate similarly-named weather conditions, and return the icon and color that match.

class i3pystatus.weekcal.WeekCal[source]¶

Displays the days of the current week as they would be represented on a calendar sheet, with the current day highlighted. By default, the current day of week is displayed in the front, and the month and year are displayed in the back.

Example: Sat 16 17 18 19 20[21]22 May 2016

Settings

startofweek (default: 0) – First day of the week (0 = Monday, 6 = Sunday), defaults to 0.
prefixformat (default: %a) – Prefix in strftime-format
suffixformat (default: %b %Y) – Suffix in strftime-format
todayhighlight (default: ('[', ']')) – Characters to highlight today’s date
interval (default: 30) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.whosonlocation.WOL[source]¶

Change your whosonlocation.com status.

Requires the PyPi module beautifulsoup4

Settings

keyring_backend (default: empty) – alternative keyring backend for retrieving credentials
email (default: empty)
password (default: empty)
interval (default: 5) – interval in seconds between module updates
on_leftclick (default: change_status) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.window_title.WindowTitle[source]¶

Display the current window title with async update. Uses asynchronous update via i3 IPC events. Provides instant title update only when it required.

fork from window_tile_async of py3status by Anon1234 https://github.com/Anon1234

Requires the PyPI package i3ipc.

Available formaters

{title} — title of current focused window
{class_name} - name of application class

@author jok @license BSD

Settings

format (default: {title}) – format string.
always_show (default: False) – do not hide the title when it can be already visible
empty_title (default: empty) – string that will be shown instead of the title when the title is hidden
max_width (default: 79) – maximum width of title
color (default: #FFFFFF) – text color
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.xkblayout.Xkblayout[source]¶

Displays and changes current keyboard layout.

change_layout callback finds the current layout in the layouts setting and enables the layout following it. If the current layout is not in the layouts setting the first layout is enabled.

layouts can be stated with or without variants, e.g.: status.register(“xkblayout”, layouts=[“de neo”, “de”])

Settings

format (default: ⌨ {name}) – Format string
layouts (default: []) – List of layouts
uppercase (default: True) – Flag for uppercase output
interval (default: 1) – interval in seconds between module updates
on_leftclick (default: change_layout) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.zabbix.Zabbix[source]¶

Zabbix alerts watcher

Requires: pyzabbix

Available formatters

{default} - Full output count alerts like total:a5/a4/a3/a2/a1/a0
{total} - Total count of alerts
{aX_count} - Count alerts of X severity
{colorX} - Predicted color for X severity. It can be used with Pango markup hint for different colours at each severity with

Settings

zabbix_server (required) – Zabbix Server URL
zabbix_user (required) – Zabbix API User
zabbix_password (required) – Zabbix users password
interval (default: 60) – Update interval
format (default: {default})
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

Mail Backends¶

The generic mail module can be configured to use multiple mail backends. Here is an example configuration for the MaildirMail backend:

from i3pystatus.mail import maildir
status.register("mail",
                backends=[maildir.MaildirMail(
                        directory="/home/name/Mail/inbox")
                ],
                format="P {unread}",
                log_level=20,
                hide_if_null=False, )

imap
maildir
mbox
notmuchmail
thunderbird

class i3pystatus.mail.imap.IMAP[source]¶

Checks for mail on a IMAP server

Settings

host (required)
port (default: 993)
username (required)
password (required)
keyring_backend (default: empty) – alternative keyring backend for retrieving credentials
ssl (default: True)
mailbox (default: INBOX)
account (default: Default account) – Account name
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

imap_class¶: alias of IMAP4

class i3pystatus.mail.maildir.MaildirMail[source]¶

Checks for local mail in Maildir

Settings

directory (default: empty)
account (default: Default account) – Account name
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.mail.mbox.MboxMail[source]¶

Checks for local mail in mbox

Settings

account (default: Default account) – Account name
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.mail.notmuchmail.Notmuch[source]¶

This class uses the notmuch python bindings to check for the number of messages in the notmuch database with the tags “inbox” and “unread”

Settings

db_path (default: empty) – Path to the directory of your notmuch database
query (default: tag:unread and tag:inbox) – Same query notmuch would accept, by default ‘tag:unread and tag:inbox‘
account (default: Default account) – Account name
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.mail.thunderbird.Thunderbird[source]¶

This class listens for dbus signals emitted by the dbus-sender extension for thunderbird.

Requires python-dbus

Settings

account (default: Default account) – Account name
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.scores.epl.EPL[source]¶

Backend to retrieve scores from the English Premier League. For usage examples, see here.

Promotion / Relegation

Due to promotion/relegation, the team_colors configuration will eventuall become out of date. When this happens, it will be necessary to manually set the colors for the newly-promoted teams until the source for this module is updated. An example of setting colors for newly promoted teams can be seen below:

from i3pystatus import Status
from i3pystatus.scores import epl

status = Status()

status.register(
    'scores',
    hints={'markup': 'pango'},
    colorize_teams=True,
    backends=[
        epl.EPL(
            teams=['LIV'],
            team_colors={
                'ABC': '#1D78CA',
                'DEF': '#8AFEC3',
                'GHI': '#33FA6D',
            },
        ),
    ],
)

status.run()

Available formatters

{home_name} — Name of home team (e.g. Tottenham Hotspur)
{home_name_short} — Shortened team name (e.g. Spurs)
{home_abbrev} — 2 or 3-letter abbreviation for home team’s city (e.g.

TOT)
{home_score} — Home team’s current score
{home_wins} — Home team’s number of wins
{home_losses} — Home team’s number of losses
{home_draws} — Home team’s number of draws
{home_points} — Home team’s number of standings points
{home_favorite} — Displays the value for the scores module’s favorite attribute, if the home team is one of the teams being followed. Otherwise, this formatter will be blank.
{away_name} — Name of away team (e.g. Manchester United)
{away_name_short} — Name of away team’s city (e.g. Man Utd)
{away_abbrev} — 2 or 3-letter abbreviation for away team’s name (e.g.

MUN)
{away_score} — Away team’s current score
{away_wins} — Away team’s number of wins
{away_losses} — Away team’s number of losses
{away_draws} — Away team’s number of draws
{away_points} — Away team’s number of standings points
{away_favorite} — Displays the value for the scores module’s favorite attribute, if the away team is one of the teams being followed. Otherwise, this formatter will be blank.
{minute} — Current minute of game when in progress
{start_time} — Start time of game in system’s localtime (supports strftime formatting, e.g. {start_time:%I:%M %p})

Team abbreviations

ARS — Arsenal
AVL — Aston Villa
BOU — Bournemouth
CHE — Chelsea
CRY — Crystal Palace
EVE — Everton
LEI — Leicester City
LIV — Liverpool
MCI — Manchester City
MUN — Manchester United
NEW — Newcastle United
NOR — Norwich City
SOU — Southampton
STK — Stoke City
SUN — Sunderland Association
SWA — Swansea City
TOT — Tottenham Hotspur
WAT — Watford
WBA — West Bromwich Albion
WHU — West Ham United

Settings

favorite_teams (default: []) – List of abbreviations of favorite teams. Games for these teams will appear first in the scroll list. A detailed description of how games are ordered can be found here.
all_games (default: True) – If set to True, all games will be present in the scroll list. If set to False, then only games from favorite_teams will be present in the scroll list.
display_order (default: ['in_progress', 'final', 'pregame']) – When all_games is set to True, this option will dictate the order in which games from teams not in favorite_teams are displayed
format_no_games (default: EPL: No games) – Format used when no tracked games are scheduled for the current day (does not support formatter placeholders)
format_pregame (default: [{scroll} ]EPL: [{away_favorite} ]{away_abbrev} ({away_points}, {away_wins}-{away_losses}-{away_draws}) at [{home_favorite} ]{home_abbrev} ({home_points}, {home_wins}-{home_losses}-{home_draws}) {start_time:%H:%M %Z}) – Format used when the game has not yet started
format_in_progress (default: [{scroll} ]EPL: [{away_favorite} ]{away_abbrev} {away_score}[ ({away_power_play})], [{home_favorite} ]{home_abbrev} {home_score}[ ({home_power_play})] ({minute})) – Format used when the game is in progress
format_final (default: [{scroll} ]EPL: [{away_favorite} ]{away_abbrev} {away_score} ({away_points}, {away_wins}-{away_losses}-{away_draws}) at [{home_favorite} ]{home_abbrev} {home_score} ({home_points}, {home_wins}-{home_losses}-{home_draws}) (Final)) – Format used when the game is complete
team_colors (default: {'EVE': '#004F9E', 'SUN': '#BC0007', 'ARS': '#ED1B22', 'MUN': '#DD1921', 'MCI': '#74B2E0', 'TOT': '#DADADA', 'CHE': '#195FAF', 'BOU': '#CB0B0F', 'STK': '#D81732', 'WHU': '#9DE4FA', 'NOR': '#00A651', 'LEI': '#304FB6', 'SOU': '#DB1C26', 'NEW': '#06B3EB', 'LIV': '#D72129', 'SWA': '#B28250', 'WBA': '#B43C51', 'AVL': '#94BEE5', 'CRY': '#195FAF', 'WAT': '#E4D500'}) – Dictionary mapping team abbreviations to hex color codes. If overridden, the passed values will be merged with the defaults, so it is not necessary to define all teams if specifying this value.
date (default: empty) – Date for which to display game scores, in YYYY-MM-DD format. If unspecified, the date will be determined by the return value of an API call to the context_url. Due to API limitations, the date can presently only be overridden to another date in the current week. This option exists primarily for troubleshooting purposes.
live_url (default: http://live.premierleague.com/#/gameweek/%s/matchday/%s/match/%s) – URL string to launch EPL Live Match Centre. This value should not need to be changed.
scoreboard_url (default: http://live.premierleague.com/) – Link to the EPL scoreboard page. Like live_url, this value should not need to be changed.
api_url (default: http://live.premierleague.com/syndicationdata/competitionId=%s/seasonId=%s/gameWeekId=%s/scores.json) – Alternate URL string from which to retrieve score data. Like live_url, this value should not need to be changed.
stats_url (default: http://live.premierleague.com/syndicationdata/competitionId=%s/seasonId=%s/matchDayId=%s/league-table.json) – Alternate URL string from which to retrieve team statistics. Like live_url, this value should not need to be changed.
match_details_url (default: http://live.premierleague.com/syndicationdata/competitionId=%s/seasonId=%s/matchDayId=%s/matchId=%s/match-details.json) – Alternate URL string from which to retrieve match details. Like live_url, this value should not need to be changed.
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.scores.mlb.MLB[source]¶

Backend to retrieve MLB scores. For usage examples, see here.

Available formatters

{home_name} — Name of home team
{home_city} — Name of home team’s city
{home_abbrev} — 2 or 3-letter abbreviation for home team’s city
{home_score} — Home team’s current score
{home_wins} — Home team’s number of wins
{home_losses} — Home team’s number of losses
{home_favorite} — Displays the value for the scores module’s favorite attribute, if the home team is one of the teams being followed. Otherwise, this formatter will be blank.
{away_name} — Name of away team
{away_city} — Name of away team’s city
{away_abbrev} — 2 or 3-letter abbreviation for away team’s city
{away_score} — Away team’s current score
{away_wins} — Away team’s number of wins
{away_losses} — Away team’s number of losses
{away_favorite} — Displays the value for the scores module’s favorite attribute, if the away team is one of the teams being followed. Otherwise, this formatter will be blank.
{top_bottom} — Displays the value of either inning_top or inning_bottom based on whether the game is in the top or bottom of an inning.
{inning} — Current inning
{outs} — Number of outs in current inning
{venue} — Name of ballpark where game is being played
{start_time} — Start time of game in system’s localtime (supports strftime formatting, e.g. {start_time:%I:%M %p})
{delay} — Reason for delay, if game is currently delayed. Otherwise, this formatter will be blank.
{postponed} — Reason for postponement, if game has been postponed. Otherwise, this formatter will be blank.
{extra_innings} — When a game lasts longer than 9 innings, this formatter will show that number of innings. Otherwise, it will blank.

Team abbreviations

ARI — Arizona Diamondbacks
ATL — Atlanta Braves
BAL — Baltimore Orioles
BOS — Boston Red Sox
CHC — Chicago Cubs
CIN — Cincinnati Reds
CLE — Cleveland Indians
COL — Colorado Rockies
CWS — Chicago White Sox
DET — Detroit Tigers
HOU — Houston Astros
KC — Kansas City Royals
LAA — Los Angeles Angels of Anaheim
LAD — Los Angeles Dodgers
MIA — Miami Marlins
MIL — Milwaukee Brewers
MIN — Minnesota Twins
NYY — New York Yankees
NYM — New York Mets
OAK — Oakland Athletics
PHI — Philadelphia Phillies
PIT — Pittsburgh Pirates
SD — San Diego Padres
SEA — Seattle Mariners
SF — San Francisco Giants
STL — St. Louis Cardinals
TB — Tampa Bay Rays
TEX — Texas Rangers
TOR — Toronto Blue Jays
WSH — Washington Nationals

Settings

favorite_teams (default: []) – List of abbreviations of favorite teams. Games for these teams will appear first in the scroll list. A detailed description of how games are ordered can be found here.
all_games (default: True) – If set to True, all games will be present in the scroll list. If set to False, then only games from favorite_teams will be present in the scroll list.
display_order (default: ['in_progress', 'suspended', 'final', 'postponed', 'pregame']) – When all_games is set to True, this option will dictate the order in which games from teams not in favorite_teams are displayed
format_no_games (default: MLB: No games) – Format used when no tracked games are scheduled for the current day (does not support formatter placeholders)
format_pregame (default: [{scroll} ]MLB: [{away_favorite} ]{away_abbrev} ({away_wins}-{away_losses}) at [{home_favorite} ]{home_abbrev} ({home_wins}-{home_losses}) {start_time:%H:%M %Z}[ ({delay} Delay)]) – Format used when the game has not yet started
format_in_progress (default: [{scroll} ]MLB: [{away_favorite} ]{away_abbrev} {away_score}, [{home_favorite} ]{home_abbrev} {home_score} ({top_bottom} {inning}, {outs} Out)[ ({delay} Delay)]) – Format used when the game is in progress
format_final (default: [{scroll} ]MLB: [{away_favorite} ]{away_abbrev} {away_score} ({away_wins}-{away_losses}) at [{home_favorite} ]{home_abbrev} {home_score} ({home_wins}-{home_losses}) (Final[/{extra_innings}])) – Format used when the game is complete
format_postponed (default: [{scroll} ]MLB: [{away_favorite} ]{away_abbrev} ({away_wins}-{away_losses}) at [{home_favorite} ]{home_abbrev} ({home_wins}-{home_losses}) (PPD: {postponed})) – Format used when the game has been postponed
format_suspended (default: [{scroll} ]MLB: [{away_favorite} ]{away_abbrev} {away_score} ({away_wins}-{away_losses}) at [{home_favorite} ]{home_abbrev} {home_score} ({home_wins}-{home_losses}) (Suspended: {suspended})) – Format used when the game has been suspended
inning_top (default: Top) – Value for the {top_bottom} formatter when game is in the top half of an inning
inning_bottom (default: Bot) – Value for the {top_bottom} formatter when game is in the bottom half of an inning
team_colors (default: {'SD': '#285F9A', 'DET': '#FF6600', 'COL': '#5E5EB6', 'CLE': '#E31937', 'PHI': '#E81828', 'MIL': '#0747CC', 'STL': '#B53B30', 'CWS': '#DADADA', 'TOR': '#0046DD', 'BAL': '#DF4601', 'WSH': '#C70003', 'NYY': '#0747CC', 'MIA': '#F14634', 'BOS': '#BD3039', 'NYM': '#FF5910', 'CIN': '#C6011F', 'TEX': '#C0111F', 'OAK': '#006659', 'ARI': '#A71930', 'LAD': '#005A9C', 'ATL': '#CE1141', 'SEA': '#2E8B90', 'PIT': '#FFCC01', 'MIN': '#D31145', 'KC': '#0046DD', 'LAA': '#BA0021', 'CHC': '#004EC1', 'TB': '#8FBCE6', 'HOU': '#EB6E1F', 'SF': '#FD5A1E'}) – Dictionary mapping team abbreviations to hex color codes. If overridden, the passed values will be merged with the defaults, so it is not necessary to define all teams if specifying this value.
date (default: empty) – Date for which to display game scores, in YYYY-MM-DD format. If unspecified, the current day’s games will be displayed starting at 10am Eastern time, with last evening’s scores being shown before then. This option exists primarily for troubleshooting purposes.
live_url (default: http://mlb.mlb.com/mlb/gameday/index.jsp?gid=%s) – Alternate URL string to launch MLB Gameday. This value should not need to be changed
scoreboard_url (default: http://m.mlb.com/scoreboard) – Link to the MLB.com scoreboard page. Like live_url, this value should not need to be changed.
api_url (default: http://gd2.mlb.com/components/game/mlb/year_%04d/month_%02d/day_%02d/miniscoreboard.json) – Alternate URL string from which to retrieve score data. Like live_url* this value should not need to be changed.
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.scores.nba.NBA[source]¶

Backend to retrieve NBA scores. For usage examples, see here.

Available formatters

{home_name} — Name of home team
{home_city} — Name of home team’s city
{home_abbrev} — 3-letter abbreviation for home team’s city
{home_score} — Home team’s current score
{home_wins} — Home team’s number of wins
{home_losses} — Home team’s number of losses
{home_seed} — During the playoffs, shows the home team’s playoff seed. When not in the playoffs, this formatter will be blank.
{home_favorite} — Displays the value for the scores module’s favorite attribute, if the home team is one of the teams being followed. Otherwise, this formatter will be blank.
{away_name} — Name of away team
{away_city} — Name of away team’s city
{away_abbrev} — 2 or 3-letter abbreviation for away team’s city
{away_score} — Away team’s current score
{away_wins} — Away team’s number of wins
{away_losses} — Away team’s number of losses
{away_seed} — During the playoffs, shows the away team’s playoff seed. When not in the playoffs, this formatter will be blank.
{away_favorite} — Displays the value for the scores module’s favorite attribute, if the away team is one of the teams being followed. Otherwise, this formatter will be blank.
{time_remaining} — Time remaining in the current quarter/OT period
{quarter} — Number of the current quarter
{venue} — Name of arena where game is being played
{start_time} — Start time of game in system’s localtime (supports strftime formatting, e.g. {start_time:%I:%M %p})
{overtime} — If the game ended in overtime, this formatter will show OT. If the game ended in regulation, or has not yet completed, this formatter will be blank.

Team abbreviations

ATL — Atlanta Hawks
BKN — Brooklyn Nets
BOS — Boston Celtics
CHA — Charlotte Hornets
CHI — Chicago Bulls
CLE — Cleveland Cavaliers
DAL — Dallas Mavericks
DEN — Denver Nuggets
DET — Detroit Pistons
GSW — Golden State Warriors
HOU — Houston Rockets
IND — Indiana Pacers
MIA — Miami Heat
MEM — Memphis Grizzlies
MIL — Milwaukee Bucks
LAC — Los Angeles Clippers
LAL — Los Angeles Lakers
MIN — Minnesota Timberwolves
NOP — New Orleans Pelicans
NYK — New York Knicks
OKC — Oklahoma City Thunder
ORL — Orlando Magic
PHI — Philadelphia 76ers
PHX — Phoenix Suns
POR — Portland Trailblazers
SAC — Sacramento Kings
SAS — San Antonio Spurs
TOR — Toronto Raptors
UTA — Utah Jazz
WAS — Washington Wizards

Settings

favorite_teams (default: []) – List of abbreviations of favorite teams. Games for these teams will appear first in the scroll list. A detailed description of how games are ordered can be found here.
all_games (default: True) – If set to True, all games will be present in the scroll list. If set to False, then only games from favorite_teams will be present in the scroll list.
display_order (default: ['in_progress', 'final', 'pregame']) – When all_games is set to True, this option will dictate the order in which games from teams not in favorite_teams are displayed
format_no_games (default: NBA: No games) – Format used when no tracked games are scheduled for the current day (does not support formatter placeholders)
format_pregame (default: [{scroll} ]NBA: [{away_favorite} ][{away_seed} ]{away_abbrev} ({away_wins}-{away_losses}) at [{home_favorite} ][{home_seed} ]{home_abbrev} ({home_wins}-{home_losses}) {start_time:%H:%M %Z}) – Format used when the game has not yet started
format_in_progress (default: [{scroll} ]NBA: [{away_favorite} ]{away_abbrev} {away_score}[ ({away_power_play})], [{home_favorite} ]{home_abbrev} {home_score}[ ({home_power_play})] ({time_remaining} {quarter})) – Format used when the game is in progress
format_final (default: [{scroll} ]NBA: [{away_favorite} ]{away_abbrev} {away_score} ({away_wins}-{away_losses}) at [{home_favorite} ]{home_abbrev} {home_score} ({home_wins}-{home_losses}) (Final[/{overtime}])) – Format used when the game is complete
team_colors (default: {'MEM': '#628BBC', 'DET': '#207EC0', 'CHI': '#CD1041', 'DAL': '#006BB7', 'BKN': '#DADADA', 'PHI': '#006BB7', 'MIL': '#4C7B4B', 'GSW': '#DEB934', 'SAS': '#DADADA', 'UTA': '#4B7059', 'TOR': '#CD112C', 'ORL': '#1980CB', 'MIA': '#A72249', 'BOS': '#178D58', 'CHA': '#00798D', 'NYK': '#F68428', 'CLE': '#FDBA31', 'PHX': '#E76120', 'LAC': '#ED174C', 'ATL': '#E2383F', 'DEN': '#5593C3', 'NOP': '#A78F59', 'OKC': '#F05033', 'SAC': '#7A58A1', 'MIN': '#35749F', 'POR': '#B03037', 'LAL': '#FDB827', 'HOU': '#CD1042', 'WAS': '#E51735', 'IND': '#FFBB33'}) – Dictionary mapping team abbreviations to hex color codes. If overridden, the passed values will be merged with the defaults, so it is not necessary to define all teams if specifying this value.
date (default: empty) – Date for which to display game scores, in YYYY-MM-DD format. If unspecified, the current day’s games will be displayed starting at 10am Eastern time, with last evening’s scores being shown before then. This option exists primarily for troubleshooting purposes.
live_url (default: http://www.nba.com/gametracker/#/%s/lp) – URL string to launch NBA Game Tracker. This value should not need to be changed.
scoreboard_url (default: http://www.nba.com/scores) – Link to the NBA.com scoreboard page. Like live_url, this value should not need to be changed.
api_url (default: http://data.nba.com/data/10s/json/cms/noseason/scoreboard/%04d%02d%02d/games.json) – Alternate URL string from which to retrieve score data. Like, live_url, this value should not need to be changed.
standings_url (default: http://data.nba.com/data/json/cms/%s/league/standings.json) – Alternate URL string from which to retrieve team standings. Like live_url, this value should not need to be changed.
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.scores.nhl.NHL[source]¶

Backend to retrieve NHL scores. For usage examples, see here.

Available formatters

{home_name} — Name of home team
{home_city} — Name of home team’s city
{home_abbrev} — 3-letter abbreviation for home team’s city
{home_score} — Home team’s current score
{home_wins} — Home team’s number of wins
{home_losses} — Home team’s number of losses
{home_otl} — Home team’s number of overtime losses
{home_favorite} — Displays the value for the scores module’s favorite attribute, if the home team is one of the teams being followed. Otherwise, this formatter will be blank.
{home_empty_net} — Shows the value from the empty_net parameter when the home team’s net is empty.
{away_name} — Name of away team
{away_city} — Name of away team’s city
{away_abbrev} — 2 or 3-letter abbreviation for away team’s city
{away_score} — Away team’s current score
{away_wins} — Away team’s number of wins
{away_losses} — Away team’s number of losses
{away_otl} — Away team’s number of overtime losses
{away_favorite} — Displays the value for the scores module’s favorite attribute, if the away team is one of the teams being followed. Otherwise, this formatter will be blank.
{away_empty_net} — Shows the value from the empty_net parameter when the away team’s net is empty.
{period} — Current period
{venue} — Name of arena where game is being played
{start_time} — Start time of game in system’s localtime (supports strftime formatting, e.g. {start_time:%I:%M %p})
{overtime} — If the game ended in overtime or a shootout, this formatter will show OT kor SO. If the game ended in regulation, or has not yet completed, this formatter will be blank.

Playoffs

In the playoffs, losses are not important (as the losses will be equal to the other team’s wins). Therefore, it is a good idea during the playoffs to manually set format strings to exclude information on team losses. For example:

from i3pystatus import Status
from i3pystatus.scores import nhl

status = Status()
status.register(
    'scores',
    hints={'markup': 'pango'},
    colorize_teams=True,
    favorite_icon='<span size="small" color="#F5FF00">★</span>',
    backends=[
        nhl.NHL(
            favorite_teams=['CHI'],
            format_pregame = '[{scroll} ]NHL: [{away_favorite} ]{away_abbrev} ({away_wins}) at [{home_favorite} ]{home_abbrev} ({home_wins}) {start_time:%H:%M %Z}',
            format_final = '[{scroll} ]NHL: [{away_favorite} ]{away_abbrev} {away_score} ({away_wins}) at [{home_favorite} ]{home_abbrev} {home_score} ({home_wins}) (Final[/{overtime}])',
        ),
    ],
)

Team abbreviations

ANA — Anaheim Ducks
ARI — Arizona Coyotes
BOS — Boston Bruins
BUF — Buffalo Sabres
CAR — Carolina Hurricanes
CBJ — Columbus Blue Jackets
CGY — Calgary Flames
CHI — Chicago Blackhawks
COL — Colorado Avalanche
DAL — Dallas Stars
DET — Detroit Red Wings
EDM — Edmonton Oilers
FLA — Florida Panthers
LAK — Los Angeles Kings
MIN — Minnesota Wild
MTL — Montreal Canadiens
NJD — New Jersey Devils
NSH — Nashville Predators
NYI — New York Islanders
NYR — New York Rangers
OTT — Ottawa Senators
PHI — Philadelphia Flyers
PIT — Pittsburgh Penguins
SJS — San Jose Sharks
STL — St. Louis Blues
TBL — Tampa Bay Lightning
TOR — Toronto Maple Leafs
VAN — Vancouver Canucks
WPG — Winnipeg Jets
WSH — Washington Capitals

Settings

favorite_teams (default: []) – List of abbreviations of favorite teams. Games for these teams will appear first in the scroll list. A detailed description of how games are ordered can be found here.
all_games (default: True) – If set to True, all games will be present in the scroll list. If set to False, then only games from favorite_teams will be present in the scroll list.
display_order (default: ['in_progress', 'final', 'pregame']) – When all_games is set to True, this option will dictate the order in which games from teams not in favorite_teams are displayed
format_no_games (default: NHL: No games) – Format used when no tracked games are scheduled for the current day (does not support formatter placeholders)
format_pregame (default: [{scroll} ]NHL: [{away_favorite} ]{away_abbrev} ({away_wins}-{away_losses}-{away_otl}) at [{home_favorite} ]{home_abbrev} ({home_wins}-{home_losses}-{home_otl}) {start_time:%H:%M %Z}) – Format used when the game has not yet started
format_in_progress (default: [{scroll} ]NHL: [{away_favorite} ]{away_abbrev} {away_score}[ ({away_power_play})][ ({away_empty_net})], [{home_favorite} ]{home_abbrev} {home_score}[ ({home_power_play})][ ({home_empty_net})] ({time_remaining} {period})) – Format used when the game is in progress
format_final (default: [{scroll} ]NHL: [{away_favorite} ]{away_abbrev} {away_score} ({away_wins}-{away_losses}-{away_otl}) at [{home_favorite} ]{home_abbrev} {home_score} ({home_wins}-{home_losses}-{home_otl}) (Final[/{overtime}])) – Format used when the game is complete
empty_net (default: EN) – Value for the {away_empty_net} or {home_empty_net} formatter when the net is empty. When the net is not empty, these formatters will be empty strings.
team_colors (default: {'DET': '#E51937', 'BUF': '#1568C5', 'CBJ': '#1568C5', 'FLA': '#E51837', 'NYI': '#F8630D', 'STL': '#1764AD', 'MTL': '#C8011D', 'WPG': '#1568C5', 'CHI': '#CD0E24', 'TOR': '#296AD5', 'OTT': '#C50B2F', 'WSH': '#E51937', 'COL': '#9F415B', 'VAN': '#0454FA', 'DAL': '#058158', 'BOS': '#F6BD27', 'PIT': '#D9CBAE', 'LAK': '#DADADA', 'TBL': '#296AD5', 'NYR': '#1576CA', 'CGY': '#D23429', 'ANA': '#B4A277', 'PHI': '#FF690B', 'ARI': '#AC313A', 'CAR': '#FA272E', 'NJD': '#CC0000', 'MIN': '#176B49', 'EDM': '#2F6093', 'SJS': '#007888', 'NSH': '#FDB71A'}) – Dictionary mapping team abbreviations to hex color codes. If overridden, the passed values will be merged with the defaults, so it is not necessary to define all teams if specifying this value.
date (default: empty) – Date for which to display game scores, in YYYY-MM-DD format. If unspecified, the current day’s games will be displayed starting at 10am Eastern time, with last evening’s scores being shown before then. This option exists primarily for troubleshooting purposes.
live_url (default: https://www.nhl.com/gamecenter/%s) – URL string to launch NHL GameCenter. This value should not need to be changed.
scoreboard_url (default: https://www.nhl.com/scores) – Link to the NHL.com scoreboard page. Like live_url, this value should not need to be changed.
api_url (default: https://statsapi.web.nhl.com/api/v1/schedule?startDate=%04d-%02d-%02d&endDate=%04d-%02d-%02d&expand=schedule.teams,schedule.linescore,schedule.broadcasts.all&site=en_nhl&teamId=) – Alternate URL string from which to retrieve score data. Like live_url, this value should not need to be changed.
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

Update Backends¶

aptget
cower
dnf
pacman
yaourt

class i3pystatus.updates.aptget.AptGet[source]¶

Gets update count for Debian based distributions.

This mimics the Arch Linux checkupdates script but with apt-get and written in python.

Settings

log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.updates.cower.Cower[source]¶

Checks for updates in Arch User Repositories using the cower AUR helper.

Depends on cower AUR agent - https://github.com/falconindy/cower

Settings

log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.updates.dnf.Dnf[source]¶

Gets updates for RPM-based distributions with dnf check-update.

The notification body consists of the status line followed by the package name and version for each update.

https://dnf.readthedocs.org/en/latest/command_ref.html#check-update-command

Settings

log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.updates.pacman.Pacman[source]¶

Checks for updates in Arch Linux repositories using the checkupdates script which is part of the pacman package.

Settings

log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

class i3pystatus.updates.yaourt.Yaourt[source]¶

This module counts the available updates using yaourt. By default it will only count aur packages. Thus it can be used with the pacman backend like this:

from i3pystatus.updates import pacman, yaourt
status.register("updates", backends = [pacman.Pacman(), yaourt.Yaourt()])

If you want to count both pacman and aur packages with this module you can set the variable count_only_aur = False like this:

from i3pystatus.updates import yaourt
status.register("updates", backends = [yaourt.Yaourt(False)])

Settings

log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

Weather Backends¶

weathercom
wunderground

class i3pystatus.weather.weathercom.Weathercom[source]¶

This module gets the weather from weather.com. The location_code parameter should be set to the location code from weather.com. To obtain this code, search for the location on weather.com, and the location code will be everything after the last slash (e.g. 94107:4:US).

Usage example

from i3pystatus import Status
from i3pystatus.weather import weathercom

status = Status()

status.register(
    'weather',
    format='{condition} {current_temp}{temp_unit}{icon}[ Hi: {high_temp}] Lo: {low_temp}',
    colorize=True,
    backend=weathercom.Weathercom(
        location_code='94107:4:US',
        units='imperial',
    ),
)

status.run()

See here for a list of formatters which can be used.

Settings

location_code (required) – Location code from www.weather.com
units (default: metric) – ‘metric’ or ‘imperial’
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

weather_data()[source]¶: Fetches the current weather from wxdata.weather.com service.

class i3pystatus.weather.wunderground.Wunderground[source]¶

This module retrieves weather data using the Weather Underground API.

Note

A Weather Underground API key is required to use this module, you can sign up for a developer API key free at https://www.wunderground.com/weather/api/

A developer API key is allowed 500 queries per day, and no more than 10 in a given minute. Therefore, it is recommended to be conservative when setting the update interval.

Valid values for location_code include:

State/City_Name - CA/San_Francisco
Country/City - France/Paris
Geolocation by IP - autoip
Zip or Postal Code - 60616
ICAO Airport Code - icao:LAX
Latitude/Longitude - 41.8301943,-87.6342619
Personal Weather Station (PWS) - pws:KILCHICA30

When not using a pws or icao station ID, the location will be queried, and the closest station will be used. For a list of PWS station IDs, visit the following URL:

http://www.wunderground.com/weatherstation/ListStations.asp

Usage example

from i3pystatus import Status
from i3pystatus.weather import wunderground

status = Status()

status.register(
    'weather',
    format='{condition} {current_temp}{temp_unit}{icon}[ Hi: {high_temp}] Lo: {low_temp}',
    colorize=True,
    backend=wunderground.Wunderground(
        api_key='dbafe887d56ba4ad',
        location_code='pws:MAT645',
        units='imperial',
    ),
)

status.run()

See here for a list of formatters which can be used.

Settings

api_key (required) – Weather Underground API key
location_code (required) – Location code from wunderground.com
units (default: metric) – ‘metric’ or ‘imperial’
use_pws (default: True) – Set to False to use only airport stations
forecast (default: False) – Set to True to check forecast (generates one additional API request per weather update). If set to False, then the low_temp and high_temp formatters will be set to empty strings.
interval (default: 300) – interval in seconds between module updates
on_leftclick (default: empty) – Callback called on left click (see Callbacks)
on_middleclick (default: empty) – Callback called on middle click (see Callbacks)
on_rightclick (default: empty) – Callback called on right click (see Callbacks)
on_upscroll (default: empty) – Callback called on scrolling up (see Callbacks)
on_downscroll (default: empty) – Callback called on scrolling down (see Callbacks)
on_doubleleftclick (default: empty) – Callback called on double left click (see Callbacks)
on_doublemiddleclick (default: empty) – Callback called on double middle click (see Callbacks)
on_doublerightclick (default: empty) – Callback called on double right click (see Callbacks)
on_doubleupscroll (default: empty) – Callback called on double scroll up (see Callbacks)
on_doubledownscroll (default: empty) – Callback called on double scroll down (see Callbacks)
on_otherclick (default: empty) – Callback called on other click (see Callbacks)
on_doubleotherclick (default: empty) – Callback called on double other click (see Callbacks)
multi_click_timeout (default: 0.25) – Time (in seconds) before a single click is executed.
hints (default: {'markup': 'none'}) – Additional output blocks for module output (see Hints)
log_level (default: 30) – Set to true to log error to .i3pystatus-<pid> file.

api_request(url)[source]¶: Execute an HTTP POST to the specified URL and return the content

geolookup()[source]¶: Use the location_code to perform a geolookup and find the closest station. If the location is a pws or icao station ID, no lookup will be peformed.

get_forecast()[source]¶: If configured to do so, make an API request to retrieve the forecast data for the configured/queried weather station, and return the low and high temperatures. Otherwise, return two empty strings.

weather_data()[source]¶: Query the configured/queried station and return the weather data