Py3status Documentation Release 3.6

py3status Documentation Release 3.6

ultrabug

Aug 22, 2017

Contents:

1 Introduction 1 1.1 About...... 1 1.2 Philosophy...... 1 1.3 Installation...... 2 1.4 Support...... 2 1.5 Usage...... 2

2 Modules 5 2.1 air_quality...... 5 2.2 apt_updates...... 6 2.3 arch_updates...... 7 2.4 aws_bill...... 7 2.5 backlight...... 8 2.6 battery_level...... 9 2.7 bitcoin_price...... 10 2.8 bluetooth...... 11 2.9 check_tcp...... 11 2.10 clementine...... 12 2.11 clock...... 12 2.12 cmus...... 14 2.13 coin_balance...... 16 2.14 coin_market...... 17 2.15 deadbeef...... 19 2.16 diskdata...... 19 2.17 do_not_disturb...... 21 2.18 dpms...... 21 2.19 dropboxd_status...... 22 2.20 exchange_rate...... 23 2.21 external_script...... 23 2.22 fedora_updates...... 24 2.23 ﬁle_status...... 24 2.24 frame...... 25 2.25 getjson...... 26 2.26 github...... 27 2.27 glpi...... 28 2.28 gpmdp...... 29

i 2.29 graphite...... 29 2.30 group...... 30 2.31 hamster...... 32 2.32 i3block...... 32 2.33 icinga2...... 34 2.34 imap...... 34 2.35 insync...... 35 2.36 kdeconnector...... 35 2.37 keyboard_layout...... 37 2.38 keyboard_locks...... 37 2.39 moc...... 38 2.40 mpd_status...... 39 2.41 mpris...... 40 2.42 net_iplist...... 42 2.43 net_rate...... 43 2.44 netdata...... 44 2.45 ns_checker...... 45 2.46 nvidia_temp...... 45 2.47 online_status...... 46 2.48 pingdom...... 47 2.49 player_control...... 47 2.50 pomodoro...... 48 2.51 process_status...... 49 2.52 rainbow...... 49 2.53 rate_counter...... 50 2.54 rss_aggregator...... 51 2.55 rt...... 52 2.56 scratchpad_async...... 53 2.57 scratchpad_counter...... 53 2.58 screenshot...... 54 2.59 selinux...... 54 2.60 spaceapi...... 55 2.61 spotify...... 56 2.62 static_string...... 57 2.63 sysdata...... 57 2.64 systemd...... 58 2.65 taskwarrior...... 59 2.66 timer...... 59 2.67 tor_rate...... 60 2.68 twitch_streaming...... 61 2.69 uname...... 61 2.70 uptime...... 62 2.71 vnstat...... 63 2.72 volume_status...... 63 2.73 vpn_status...... 65 2.74 weather_yahoo...... 65 2.75 whatismyip...... 67 2.76 whoami...... 67 2.77 wiﬁ...... 68 2.78 window_title...... 69 2.79 window_title_async...... 69 2.80 wwan_status...... 70 2.81 xrandr...... 71 2.82 xrandr_rotate...... 72 ii 2.83 xscreensaver...... 73 2.84 xsel...... 73 2.85 yandexdisk_status...... 74

3 Using modules 77 3.1 Loading a py3status module and ordering modules output...... 77 3.2 Configuring a py3status module...... 78 3.3 py3status configuration section...... 78 3.4 Configuration obfuscation...... 78 3.5 Configuring colors...... 79 3.6 Configuring thresholds...... 80 3.7 Urgent...... 80 3.8 Grouping Modules...... 81 3.9 Custom click events...... 83 3.10 Special on_click commands...... 84 3.11 Module data and on_click commands...... 84

4 py3-cmd 85 4.1 Commands available...... 85 4.2 Calling commands from i3...... 86

5 Writing custom py3status modules 87 5.1 Example 1: The basics - Hello World!...... 87 5.2 Example 2: Configuration parameters...... 88 5.3 Example 3: Click events...... 89 5.4 Example 4: Status string placeholders...... 90 5.5 Example 5: Using color constants...... 91 5.6 Module methods...... 92 5.7 Py3 module helper...... 93 5.8 Composites...... 93 5.9 Module documentation...... 94 5.10 Deprecation of configuration parameters...... 95 5.11 Updating of configuration parameters...... 98 5.12 Module testing...... 98

6 py3 module helper 101 6.1 Constants...... 101 6.2 Exceptions...... 101 6.3 Methods...... 102

7 Developing and Contributing 109 7.1 What you will need...... 109 7.2 Setting up a development environment...... 109 7.3 Python versions...... 110 7.4 Pytest...... 110 7.5 Travis CI...... 110 7.6 Coding in containers...... 111 7.7 Building documentation...... 111 7.8 Contributions...... 111

iii iv CHAPTER 1

Introduction

Using py3status, you can take control of your i3bar easily by: • using one of the available Modules shipped with py3status • grouping multiple modules and automatically or manually cycle their display • writing your own modules and have their output displayed on your bar • handling click events on your i3bar and play with them in no time • seeing your clock tick every second whatever your i3status interval No extra conﬁguration ﬁle needed, just install & enjoy!

About

You will love py3status if you’re using i3wm and are frustrated by the i3status limitations on your i3bar such as: • you cannot hack into it easily • you want more than the built-in modules and their limited conﬁguration • you cannot pipe the result of one of more scripts or commands in your bar easily

Philosophy

• no added configuration file, use the standard i3status.conf • rely on i3status’ strengths and its existing configuration as much as possible • be extensible, it must be easy for users to add their own stuff/output by writing a simple python class which will be loaded and executed dynamically • easily allow interactivity with the i3bar

1 py3status Documentation, Release 3.6

• add some built-in enhancement/transformation of basic i3status modules output • support python 2.7 and python 3.x

Installation

Distro Helpful Command Useful Note $ pacaur -S py3status Stable updates. Ofﬁcial releases. Arch Linux $ pacaur -S py3status-git Hot updates. Directly from master branch. Debian & Ubuntu $ pypi-install py3status Usually in python-stdeb package. Fedora $ dnf install py3status Gentoo Linux $ emerge -a py3status Pypi $ pip install py3status Installation Note: This list is incomplete. Please help us ﬁll in the gaps.

Support

Get help, share ideas or feedbacks, join community, report bugs, or others, see:

Github

Issues/ Pull requests

Live IRC Chat

Visit #py3status at freenode.net

Usage

In your i3 conﬁg ﬁle, simply switch from i3status to py3status in your status_command: status_command py3status

Usually you have your own i3status conﬁguration, just point to it: status_command py3status -c ~/.i3/i3status.conf

Available modules

You can get a list with short descriptions of all available modules by using the CLI:

$ py3status modules list

To get more details about all available modules and their conﬁguration, use:

2 Chapter 1. Introduction py3status Documentation, Release 3.6

$ py3status modules details

All modules shipped with py3status are present as the Python source ﬁles in the py3status/modules directory.

Options

You can see the help of py3status by issuing py3status --help:

-h, --help show this help message and exit -b, --dbus-notify use notify-send to send user notifications rather than i3-nagbar, requires a notification daemon eg dunst -c I3STATUS_CONF, --config I3STATUS_CONF path to i3status config file -d, --debug be verbose in syslog -i INCLUDE_PATHS, --include INCLUDE_PATHS include user-written modules from those directories (default ~/.i3/py3status) -l LOG_FILE, --log-file LOG_FILE path to py3status log file -n INTERVAL, --interval INTERVAL update interval in seconds(default1 sec) -s, --standalone standalone mode, do not use i3status -t CACHE_TIMEOUT, --timeout CACHE_TIMEOUT default injection cache timeout in seconds(default 60 sec) -v, --version show py3status version and exit

Control

Just like i3status, you can force an update of your i3bar by sending a SIGUSR1 signal to py3status. Note that this will also send a SIGUSR1 signal to i3status. killall -USR1 py3status

Note: Since version 3.6 py3status can be controlled via the py3-cmd which is recommended.

1.5. Usage 3 py3status Documentation, Release 3.6

4 Chapter 1. Introduction CHAPTER 2

Modules

py3status comes with a large selection of modules ready to use. For information on conﬁgurating see Using modules air_quality

Display air quality polluting in a given location. An air quality index (AQI) is a number used by government agencies to communicate to the public how polluted the air currently is or how polluted it is forecast to become. As the AQI increases, an increasingly large percentage of the population is likely to experience increasingly severe adverse health effects. Different countries have their own air quality indices, corresponding to different national air quality standards. Conﬁguration parameters: • auth_token Required. Personal token. http://aqicn.org (default ‘demo’) • cache_timeout refresh interval for this module. A message from the site: The default quota is max 1000 (one thousand) requests per minute (~16RPS) and with burst up to 60 requests. Read more: http: //aqicn.org/api/ (default 3600)

5 py3status Documentation, Release 3.6

• format display format for this module (default ‘{location}: {aqi} {category}’) • location location or uid to query. To search for nearby stations in Kraków, use curl http://api. waqi.info/search/?token=YOUR_TOKEN&keyword=kraków We recommend you to use uid instead of name in location, eg “@8691” (default ‘Shanghai’) Format placeholders: • {aqi} air quality index • {category} health risk category • {location} location or uid Note: Stations may use {pm25}, {pm10}, {o3}, {so2}, or other parameters. See http://api.waqi.info/feed/@UID/ ?token=TOKEN (Replace UID and TOKEN) Category options: • category_ display name eg category_very_unhealthy = ‘Level 5: Wear a mask’ Color options: • color_ display color eg color_hazardous = ‘#7E0023’ Example: air_quality { auth_token = 'demo' location = 'Shanghai' format = 'Shanghai: {aqi} {category}' }

**author** beetleman, lasers

**license** BSD apt_updates

Display number of pending updates for Debian based Distros. Thanks to Iain Tatch for the script that this is based on. This will display a count of how many ‘apt’ updates are waiting to be installed. Conﬁguration parameters: • cache_timeout How often we refresh this module in seconds (default 600) • format Display format to use (default ‘UPD[?not_zero : {apt}]’) Format placeholders: • {apt} Number of pending apt updates Requires: • apt Needed to display pending ‘apt’ updates

6 Chapter 2. Modules py3status Documentation, Release 3.6 author Joshua Pratt license BSD arch_updates

Display number of pending updates for Arch Linux. This will display a count of how many ‘pacman’ updates are waiting to be installed and optionally a count of how many ‘aur’ updates are also waiting. Conﬁguration parameters: • cache_timeout How often we refresh this module in seconds (default 600) • format Display format to use (default ‘UPD: {pacman}’ or ‘UPD: {pacman}/{aur}’) • hide_if_zero Don’t show on bar if True (default False) • include_aur Set to True to use ‘cower’ to check for AUR updates (default False) Format placeholders: • {aur} Number of pending aur updates • {pacman} Number of pending pacman updates • {total} Total updates pending Requires: • cower Needed to display pending ‘aur’ updates author Iain Tatch license BSD aws_bill

Display bill for Amazon Web Services. WARNING: This module generate some costs on the AWS bill. Take care about the cache_timeout to limit these fees! Conﬁguration parameters: • aws_access_key_id Your AWS access key (default ‘’) • aws_account_id The root ID of the AWS account Can be found here‘‘ https://console.aws.amazon. com/billing/home#/account (default ‘’) • aws_secret_access_key Your AWS secret key (default ‘’)

2.3. arch_updates 7 py3status Documentation, Release 3.6

• billing_file Csv ﬁle location (default ‘/tmp/.aws_billing.csv’) • cache_timeout How often we refresh this module in seconds (default 3600) • format string that formats the output. See placeholders below. (default ‘{bill_amount}$’) • s3_bucket_name The bucket where billing ﬁles are sent by AWS. Follow this article to activate this feature: http://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/detailed-billing-reports.html (default ‘’) Format placeholders: • {bill_amount} AWS bill amount Color options: • color_good Balance available • color_bad An error has occured Requires: • boto author nawadanp backlight

Adjust screen backlight brightness. Conﬁguration parameters: • brightness_delta Change the brightness by this step. (default 8) • brightness_initial Set brightness to this value on start. (default None) • brightness_minimal Don’t go below this brightness to avoid black screen (default 1) • button_down Button to click to decrease brightness. Setting to 0 disables. (default 5) • button_up Button to click to increase brightness. Setting to 0 disables. (default 4) • cache_timeout How often we refresh this module in seconds (default 10) • device Device name or full path to use, eg, acpi_video0 or /sys/class/backlight/acpi_video0, otherwise automatic (default None) • format Display brightness, see placeholders below (default ‘: {level}%’) Format status string parameters: • {level} brightness Requires: • xbacklight need for changing brightness, not detection author Tjaart van der Walt (github:tjaartvdwalt) license BSD

8 Chapter 2. Modules py3status Documentation, Release 3.6

battery_level

Display battery information. Configuration parameters: • battery_id id of the battery to be displayed set to ‘all’ for combined display of all batteries (default 0) • blocks a string, where each character represents battery level especially useful when using icon fonts (e.g. FontAwesome) (default “_”) • cache_timeout a timeout to refresh the battery state (default 30) • charging_character a character to represent charging battery especially useful when using icon fonts (e.g. FontAwesome) (default “”) • format string that formats the output. See placeholders below. (default “{icon}”) • format_notify_charging format of the notification received when you click on the module while your computer is plugged in (default ‘Charging ({percent}%)’) • format_notify_discharging format of the notification received when you click on the module while your computer is not plugged in (default “{time_remaining}”) • hide_seconds hide seconds in remaining time (default False) • hide_when_full hide any information when battery is fully charged (when the battery level is greater than or equal to ‘threshold_full’) (default False) • measurement_mode either ‘acpi’ or ‘sys’, or None to autodetect. ‘sys’ should be more robust and does not have any extra requirements, however the time measurement may not work in some cases (default None) • notification show current battery state as notification on click (default False) • notify_low_level display notification when battery is running low (when the battery level is less than ‘threshold_degraded’) (default False) • sys_battery_path set the path to your battery(ies), without including its number (default “/sys/class/power_supply/”) • threshold_bad a percentage below which the battery level should be considered bad (default 10) • threshold_degraded a percentage below which the battery level should be considered degraded (default 30) • threshold_full a percentage at or above which the battery level should should be considered full (default 100) Format placeholders: • {ascii_bar} - a string of ascii characters representing the battery level, an alternative visualization to ‘{icon}’ option • {icon} - a character representing the battery level, as defined by the ‘blocks’ and ‘charging_character’ parameters • {percent} - the remaining battery percentage (previously ‘{}’)

2.6. battery_level 9 py3status Documentation, Release 3.6

• {time_remaining} - the remaining time until the battery is empty Color options: • color_bad Battery level is below threshold_bad • color_charging Battery is charging (default “#FCE94F”) • color_degraded Battery level is below threshold_degraded • color_good Battery level is above thresholds Requires: • the acpi the acpi command line utility (only if measurement_mode='acpi') author shadowprince, AdamBSteele, maximbaz, 4iar, m45t3r license Eclipse Public License

bitcoin_price

Display bitcoin using bitcoincharts.com. Conﬁguration parameters: • cache_timeout refresh interval for this module. A message from the site: Don’t query more often than once every 15 minutes (default 900) • color_index Index of the market responsible for coloration, -1 means no coloration, except when only one market is selected (default -1) • field Field that is displayed per market, see http://bitcoincharts.com/about/markets-api/ (default ‘close’) • format display format for this module (default ‘{format_bitcoin}’) • format_bitcoin display format for bitcoin (default ‘{market}: {price}{symbol}’) • format_separator show separator only if more than one (default ‘, ‘) • hide_on_error show error message (default False) • markets list of supported markets http://bitcoincharts.com/markets/list/ (default ‘btceUSD, btcdeEUR’) • symbols if possible, convert currency abbreviations to symbols e.g. USD -> $, EUR -> C and so on (default True) Format placeholders: • {format_bitcoin} format for bitcoin format_bitcoin placeholders: • {market} market names • {price} current prices • {symbol} currency symbols Color options: • color_bad Price has dropped or not available • color_good Price has increased

10 Chapter 2. Modules py3status Documentation, Release 3.6

author Andre Doser

bluetooth

Display bluetooth status. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 10) • format display format for this module (default ‘BT[: {format_device}]’) • format_device display format for bluetooth devices (default ‘{name}’) • format_separator show separator only if more than one (default ‘|’) Format placeholders: • {format_device} format for bluetooth devices format_device placeholders: • {mac} bluetooth device address • {name} bluetooth device name Color options: • color_bad No connection • color_good Active connection author jmdana license GPLv3

check_tcp

Display status of a TCP port on a given host. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 10) • format display format for this module (default ‘{host}:{port} {state}’) • host name of host to check for (default ‘localhost’) • icon_off show this when unavailable (default ‘DOWN’) • icon_on show this when available (default ‘UP’)

2.8. bluetooth 11 py3status Documentation, Release 3.6

• port number of port to check for (default 22) Format placeholders: • {state} port state Color options: • color_down Closed, default to color_bad • color_up Open, default to color_good author obb, Moritz Lüdecke clementine

Display song currently playing in Clementine. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 5) • format display format for this module (default ‘ {current}’) Format placeholders: • {current} currently playing Requires: • clementine a modern music player and library organizer • qdbus a communication-interface for qt-based applications (may be part of qt5-tools) author Francois LASSERRE license GNU GPL http://www.gnu.org/licenses/gpl.html clock

Display date and time. This module allows one or more datetimes to be displayed. All datetimes share the same format_time but can set their own timezones. Timezones are deﬁned in the format using the TZ name in squiggly brackets eg {GMT}, {Portugal}, {Europe/Paris}, {America/Argentina/Buenos_Aires}. ISO-3166 two letter country codes eg {de} can also be used but if more than one timezone exists for the country eg {us} the ﬁrst one will be selected. {Local} can be used for the local settings of your computer. Note: Timezones are case sensitive

12 Chapter 2. Modules py3status Documentation, Release 3.6

A full list of timezones can be found at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones Configuration parameters: • block_hours length of time period for all blocks in hours (default 12) • blocks a string, where each character represents time period from the start of a time period. (default ‘’) • button_change_format button that switches format used setting to None disables (default 1) • button_change_time_format button that switches format_time used. Setting to None disables (default 2) • button_reset button that switches display to the first timezone. Setting to None disables (default 3) • cycle If more than one display then how many seconds between changing the display (default 0) • format defines the timezones displayed. This can be a single string or a list. If a list is supplied then the formats can be cycled through using cycle or by button click. (default ‘{Local}’) • format_time format to use for the time, strftime directives such as %H can be used this can be either a string or to allow multiple formats as a list. The one used can be changed by button click. (default [’[{name_unclear} ]%c’, ‘[{name_unclear} ]%x %X’, ‘[{name_unclear} ]%a %H:%M’, ‘[{name_unclear} ]{icon}’]) • round_to_nearest_block defines how a block icon is chosen. Examples: when set to True, ‘13:14’ is ‘’, ‘13:16’ is ‘’ and ‘13:31’ is ‘’; when set to False, ‘13:14’ is ‘’, ‘13:16’ is ‘’ and ‘13:31’ is ‘’. (default True) Format placeholders: • {icon} a character representing the time from blocks • {name} friendly timezone name eg Buenos Aires • {name_unclear} friendly timezone name eg Buenos Aires but is empty if only one timezone is provided • {timezone} full timezone name eg America/Argentina/Buenos_Aires • {timezone_unclear} full timezone name eg America/Argentina/Buenos_Aires but is empty if only one timezone is provided Requires: • pytz python library • tzlocal python library i3status.conf example:

# cycling through London, Warsaw, Tokyo clock { cycle = 30 format = ["{Europe/London}", "{Europe/Warsaw}", "{Asia/Tokyo}"] format_time = "{name} %H:%M" }

# Show the time and date in New York clock { format = "Big Apple {America/New_York}" format_time = "%Y-%m-%d %H:%M:%S" }

2.11. clock 13 py3status Documentation, Release 3.6

# wall clocks clock { format = "{Asia/Calcutta} {Africa/Nairobi} {Asia/Bangkok}" format_time = "{name} {icon}" } author tobes license BSD cmus

Display currently playing song in cmus. cmus (C* Music Player) is a small, fast and powerful console audio player which supports most major audio formats. Various features include gapless playback, ReplayGain support, MP3 and Ogg streaming, live filtering, instant startup, customizable key-bindings, and vi-style default key-bindings. Configuration parameters: • button_next mouse button to skip next track (default None) • button_pause mouse button to pause/play the playback (default 1) • button_previous mouse button to skip previous track (default None) • button_stop mouse button to stop the playback (default 3) • cache_timeout refresh interval for this module (default 5) • format display format for this module (default ‘[?if=is_started [?if=is_playing > ][?if=is_paused || ] [?if=is_stopped .. ][[{artist}][?soft - ][{title}] |?show cmus: waiting for user input]]’) • sleep_timeout sleep interval for this module. when cmus is not running, this interval will be used. this allows some flexible timing where one might want to refresh constantly with some placeholders... or to refresh only once every minute rather than every few seconds. (default 20) Control placeholders: • {is_paused} a boolean based on cmus status • {is_playing} a boolean based on cmus status • {is_started} a boolean based on cmus status • {is_stopped} a boolean based on cmus status • {continue} a boolean based on data status • {play_library} a boolean based on data status

14 Chapter 2. Modules py3status Documentation, Release 3.6

• {play_sorted} a boolean based on data status • {repeat} a boolean based on data status • {repeat_current} a boolean based on data status • {replaygain} a boolean based on data status • {replaygain_limit} a boolean based on data status • {shuffle} a boolean based on data status • {softvol} a boolean based on data status • {stream} a boolean based on data status Format placeholders: • {aaa_mode} shufﬂe mode, eg artist, album, all • {albumartist} album artist, eg (new output here) • {album} album name, eg (new output here) • {artist} artist name, eg (new output here) • {bitrate} audio bitrate, eg 229 • {comment} comment, eg URL • {date} year number, eg 2015 • {duration} length time in seconds, eg 171 • {durationtime} length time in [HH:]MM:SS, eg 02:51 • {file} ﬁle location, eg /home/user/Music... • {position} elapsed time in seconds, eg 17 • {positiontime} elapsed time in [HH:]MM:SS, eg 00:17 • {replaygain_preamp} replay gain preamp, eg 0.000000 • {status} playback status, eg playing, paused, stopped • {title} track title, eg (new output here) • {tracknumber} track number, eg 0 • {vol_left} left volume number, eg 90 • {vol_right} right volume number, eg 90 Placeholders are retrieved directly from cmus-remote --query command. The list was harvested only once and should not represent a full list. Color options: • color_paused Paused, defaults to color_degraded • color_playing Playing, defaults to color_good • color_stopped Stopped, defaults to color_bad Requires: • cmus a small feature-rich ncurses-based music player author lasers

2.12. cmus 15 py3status Documentation, Release 3.6 coin_balance

Display balances of diverse crypto-currencies. This module grabs your current balance of different crypto-currents from a wallet server. The server must conform to the bitcoin RPC specification. Currently Bitcoin, Dogecoin, and Litecoin are supported. Configuration parameters: • cache_timeout An integer specifying the cache life-time of the output in seconds (default 30) • coin_password A string containing the password for the server for ‘coin’. The ‘coin’ part must be replaced by a supported coin identifier (see below for a list of identifiers). If no value is supplied, the value of ‘password’ (see below) will be used. If ‘password’ too is not set, the value will be retrieved from the standard ‘coin’ daemon configuration file. (default None) • coin_username A string containing the username for the server for ‘coin’. The ‘coin’ part must be replaced by a supported coin identifier (see below for a list of identifiers). If no value is supplied, the value of ‘username’ (see below) will be used. If ‘username’ too is not set, the value will be retrieved from the standard ‘coin’ daemon configuration file. (default None) • credentials (default None) • format A string describing the output format for the module. The {} placeholder (see below) will be used to determine how to fetch the coin balance. Multiple placeholders are allowed, but all balances will be fetched from the same host. (default ‘LTC: {litecoin}’) • host The coin-server hostname. Note that all coins will use the same host for their querries. (default ‘localhost’) • password A string containing the password for all coin-servers. If neither this setting, nor a specific coin_password (see above) is specified, the password for each coin will be read from the respective standard daemon configuration file. (default None) • protocol A string to select the server communication protocol. (default ‘http’) • username A string containing the username for all coin-servers. If neither this setting, nor a specific coin_username (see above) is specified, the username for each coin will be read from the respective standard daemon configuration file. (default None) Format placeholders: • {} Your balance for the coin where is one of: • bitcoin • dogecoin • litecoin Requires: • requests python module from pypi https://pypi.python.org/pypi/requests At least version 2.4.2 is required. Example:

# Get your Bitcoin balance using automatic credential detection coin_balance { cache_timeout = 45

16 Chapter 2. Modules py3status Documentation, Release 3.6

format = "My BTC: {bitcoin}" host = "localhost" protocol = "http" }

# Get your Bitcoin, Dogecoin and Litecoin balances using specific credentials # for Bitcoin and automatic detection for Dogecoin and Litecoin coin_balance { # ... format = "{bitcoin} BTC {dogecoin} XDG {litecoin} LTC" bitcoin_username = "lcdata" bitcoin_password = "omikron-theta" # ... }

# Get your Dogecoin and Litecoin balances using 'global' credentials coin_balance { # ... format = "XDG: {dogecoin} LTC: {litecoin}" username = "crusher_b" password = "WezRulez" # ... }

# Get you Dogecoin, Litecoin, and Bitcoin balances by using 'global' # credentials for Bitcoin and Dogecoin but specific credentials for # Litecoin. coin_balance { # ... format = "XDG: {dogecoin} LTC: {litecoin} BTC: {bitcoin}" username = "zcochrane" password = "sunny_islands" litecoin_username = 'locutus' litecoin_password = 'NCC-1791-D' # ... } author Felix Morgner license 3-clause-BSD coin_market

Display cryptocurrency data. The site we retrieve cryptocurrency data from offer various types of data such as name, symbol, price, volume, percentage change, total supply, et cetera for a wide range of cryptocurrencies and the prices can be obtained in a different currency along with USD currency, For more information, visit https://coinmarketcap.com Conﬁguration parameters:

2.14. coin_market 17 py3status Documentation, Release 3.6

• cache_timeout refresh interval for this module. A message from the site: Please limit requests to no more than 10 per minute. (default 600) • format display format for this module (default ‘{format_coin}’) • format_coin display format for coins (default ‘{name} ${price_usd:.2f} [?color=24h {per- cent_change_24h}%]’) • format_separator show separator only if more than one (default ‘ ‘) • markets number of top-ranked markets or list of user-inputted markets (default [’btc’]) • request_timeout time to wait for a response, in seconds (default 5) • thresholds for percentage changes (default [(-100, ‘bad’), (0, ‘good’)]) Format placeholder: • {format_coin} format for cryptocurrency coins format_coin placeholders: • {24h_volume_usd} eg 1435150000.0 • {available_supply} eg 16404825.0 • {id} eg bitcoin • {last_updated} eg 1498135152 • {market_cap_usd} eg 44119956596.0 • {name} eg Bitcoin • {percent_change_1h} eg -0.17 • {percent_change_24h} eg -1.93 • {percent_change_7d} eg +14.73 • {price_btc} eg 1.0 • {price_usd} eg 2689.45 • {rank} eg 1 • {symbol} eg BTC • {total_supply} eg 16404825.0 Placeholders are retrieved directly from the URL. The list was harvested only once and should not represent a full list. To print coins in different currency, replace or replicate the placeholders below with a valid option (eg ‘{price_gbp}’) to create additional placeholders: {price_xxx} eg (new output here) {24h_volume_xxx} eg (new output here) {market_cap_xxx} eg (new output here) Valid options are: AUD, BRL, CAD, CHF, CNY, EUR, GBP, HKD, IDR, INR, JPY, KRW, MXN, RUB, otherwise USD... and be written in lowercase. Color thresholds: 1h: print color based on the value of percent_change_1h 24h: print color based on the value of percent_change_24h 7d: print color based on the value of percent_change_7d Example:

18 Chapter 2. Modules py3status Documentation, Release 3.6

# view coins in GBP and optionally USD coin_market { format_coin = '{name} £{price_gbp:.2f} ${price_usd:.2f} {percent_change_24h}' } author lasers, x86kernel deadbeef

Display song currently playing in deadbeef. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 1) • format display format for this module (default ‘[{artist} - ][{title}]’) Format placeholders: • {album} name of the album • {artist} name of the artist • {length} length time in [HH:]MM:SS • {playback_time} elapsed time in [HH:]MM:SS • {title} title of the track • {tracknumber} track number in two digits • {year} year in four digits For more placeholders, see title formatting 2.0 in ‘deadbeef –help’ or http://github.com/ Alexey-Yakovenko/deadbeef/wiki/Title-formatting-2.0 Not all of Foobar2000 remapped metadata ﬁelds will work with deadbeef and a quick reminder about using {placeholders} here instead of %placeholder%. Color options: • color_paused Paused, defaults to color_degraded • color_playing Playing, defaults to color_good • color_stopped Stopped, defaults to color_bad Requires: • deadbeef a GTK+ audio player for GNU/Linux author mrt-prodz, tobes, lasers diskdata

2.15. deadbeef 19 py3status Documentation, Release 3.6

Display disk information. Conﬁguration parameters: • cache_timeout refresh interval for this module. (default 10) • disk show stats for disk or partition, i.e. sda1. None for all disks. (default None) • format display format for this module. (default “{disk}: {used_percent}% ({total})”) • format_rate display format for rates value (default “[?min_length=11 {value:.1f} {unit}]”) • format_space display format for disk space values (default “[?min_length=5 {value:.1f}]”) • sector_size size of the disk’s sectors. (default 512) • si_units use SI units (default False) • thresholds thresholds to use for color changes (default {‘free’: [(0, ‘bad’), (10, ‘degraded’), (100, ‘good’)], ‘total’: [(0, “good”), (1024, ‘degraded’), (1024 * 1024, ‘bad’)]}) • unit unit to use. If the unit contains a multiplier preﬁx, only this exact unit will ever be used (default “B/s”) Format placeholders: • {disk} the selected disk • {free} free space on disk in GB • {used} used space on disk in GB • {used_percent} used space on disk in % • {read} reading rate • {total} total IO rate • {write} writing rate format_rate placeholders: • {unit} name of the unit • {value} numeric value of the rate format_space placeholders: • {value} numeric value of the free/used space on the device Color thresholds: • {free} Change color based on the value of free • {used} Change color based on the value of used_percent • {read} Change color based on the value of read • {total} Change color based on the value of total • {write} Change color based on the value of write author guiniol license BSD

20 Chapter 2. Modules py3status Documentation, Release 3.6 do_not_disturb

Turn on and off dbus notifications. A left mouse click will toggle the state of this module. Configuration parameters: • format Display format for the “Do Not Disturb” module. (default ‘{state}’) • notification_manager The process name of your notification manager. (default ‘dunst’) • refresh_interval Refresh interval to use for killing notification manager process. (default 0.25) • state_off Message when the “Do Not Disturb” mode is disabled. (default ‘OFF’) • state_on Message when the “Do Not Disturb” mode is enabled. (default ‘ON’) Color options: • color_bad “Do Not Disturb” mode is enabled. • color_good “Do Not Disturb” mode is disabled. dpms

Turn on and off DPMS and screen saver blanking. This module allows activation and deactivation of DPMS (Display Power Management Signaling) by clicking on ‘DPMS’ in the status bar. Conﬁguration parameters: • button_off mouse button to turn off screen (default None) • button_toggle mouse button to toggle DPMS (default 1) • cache_timeout refresh interval for this module (default 15) • format display format for this module (default ‘{icon}’) • icon_off show when DPMS is disabled (default ‘DPMS’) • icon_on show when DPMS is enabled (default ‘DPMS’) Format placeholders: • {icon} DPMS icon Color options: • color_on Enabled, defaults to color_good

2.17. do_not_disturb 21 py3status Documentation, Release 3.6

• color_off Disabled, defaults to color_bad author Andre Doser dropboxd_status

Display status of Dropbox daemon. Configuration parameters: • cache_timeout refresh interval for this module (default 10) • format display format for this module (default “Dropbox: {status}”) • status_busy text for placeholder {status} when Dropbox is busy (default None) • status_off text for placeholder {status} when Dropbox isn’t running (default “isn’t running”) • status_on text for placeholder {status} when Dropbox is up to date (default “Up to date”) Value for status_off if not set: • Dropbox isn’t running! Value for status_on if not set: • Up to date Values for status_busy if not set: • Connecting... • Starting... • Downloading file list... • Syncing “filename” Format placeholders: • {status} Dropbox status Color options: • color_bad Not running • color_degraded Busy • color_good Up to date Requires: • dropbox-cli command line interface for dropbox author Tjaart van der Walt (github:tjaartvdwalt) license BSD

22 Chapter 2. Modules py3status Documentation, Release 3.6 exchange_rate

Display foreign exchange rates. The exchange rate data comes from Yahoo Finance. For a list of three letter currency codes please see https://en.wikipedia.org/wiki/ISO_4217 NOTE: Not all listed currencies may be available Conﬁguration parameters: • base Base currency used for exchange rates (default ‘EUR’) • cache_timeout How often we refresh this module in seconds (default 600) • format Format of the output. This is also where requested currencies are conﬁgured. Add the currency code surrounded by curly braces and it will be replaced by the current exchange rate. (default ‘${USD} £{GBP} ¥{JPY}’) author tobes license BSD external_script

Display output of a given script. Display output of any executable script set by script_path. Only the first two lines of output will be used. The first line is used as the displayed text. If the output has two or more lines, the second line is set as the text color (and should hence be a valid hex color code such as #FF0000 for red). The script should not have any parameters, but it could work. Configuration parameters: • cache_timeout how often we refresh this module in seconds (default 15) • format see placeholders below (default ‘{output}’) • script_path script you want to show output of (compulsory) (default None) • strip_output shall we strip leading and trailing spaces from output (default False) Format placeholders: • {output} output of script given by “script_path” i3status.conf example: external_script { format = "my name is {output}" script_path = "/usr/bin/whoami" }

2.20. exchange_rate 23 py3status Documentation, Release 3.6

author frimdo [email protected]

fedora_updates

Display number of pending updates for Fedora Linux. This will display a count of how many dnf updates are waiting to be installed. Additionally check if any update security notices. Conﬁguration parameters: • cache_timeout How often we refresh this module in seconds (default 600) • check_security Check for security updates (default True) • format Display format to use (default ‘DNF: {updates}’) Format placeholders: • {updates} number of pending dnf updates Color options: • color_bad Security notice • color_degraded Upgrade available • color_good No upgrades needed author tobes license BSD

ﬁle_status

Display if a file or directory exists. Configuration parameters: • cache_timeout how often to run the check (default 10) • format format of the output. (default ‘{icon}’) • icon_available icon to display when available (default ‘’) • icon_unavailable icon to display when unavailable (default ‘’) • path the path to a file or dir to check if it exists (default None) Color options: • color_bad Error or file/directory does not exist • color_good File or directory exists

24 Chapter 2. Modules py3status Documentation, Release 3.6

Format placeholders: • {icon} icon for the current availability author obb, Moritz Lüdecke

frame

Group modules and treat them as a single one. This can be useful for example when adding modules to a group and you wish two modules to be shown at the same time. By adding the {button} placeholder in the format you can enable a toggle button to hide or show the content. Conﬁguration parameters: • button_toggle Button used to toggle if one in format. Setting to None disables (default 1) • format Display format to use (default ‘{output}’) • format_button_closed Format for the button when frame open (default ‘+’) • format_button_open Format for the button when frame closed (default ‘-‘) • format_separator Specify separator between contents. If this is None then the default i3bar separator will be used (default None) • open If button then the frame can be set to be open or close (default True) Format of status string parameters: • {button} If used a button will be used that can be clicked to hide/show the contents of the frame. • {output} The output of the modules in the frame Example conﬁg:

# A frame showing times in different cities. # We also have a button to hide/show the content

frame time { format = '{output}{button}' format_separator = ' ' # have space instead of usual i3bar separator

tztime la { format = "LA %H:%M" timezone = "America/Los_Angeles" }

tztime ny { format = "NY %H:%M" timezone = "America/New_York" }

tztime du {

2.24. frame 25 py3status Documentation, Release 3.6

format = "DU %H:%M" timezone = "Asia/Dubai" } }

# Define a group which shows volume and battery info # or the current time. # The frame, volume_status and battery_level modules are named # to prevent them clashing with any other defined modules of the same type. group { frame { volume_status {} battery_level {} }

time {} } author tobes getjson

Display JSON data fetched from a URL. This module gets the given url conﬁguration parameter and assumes the response is a JSON object. The keys of the JSON object are used as the format placeholders. The format placeholders are replaced by the value. Objects that are nested can be accessed by using the delimiter conﬁguration parameter in between. Examples:

# Straightforward key replacement url = 'http://ip-api.com/json' format = '{lat}, {lon}'

# Access child objects url = 'http://api.icndb.com/jokes/random' format = '{value-joke}'

# Access title from 0th element of articles list url = 'https://newsapi.org/v1/articles?source=bbc-news&sortBy=top&apiKey={KEY}' format = '{articles-0-title}'

# Access if top-level object is a list url = 'https://jsonplaceholder.typicode.com/posts/1/comments' format = '{0-name}'

Conﬁguration parameters: • cache_timeout refresh interval for this module (default 30) • delimiter the delimiter between parent and child objects (default ‘-‘) • format display format for this module (default None) • timeout time to wait for a response, in seconds (default 5)

26 Chapter 2. Modules py3status Documentation, Release 3.6

• url specify URL to fetch JSON from (default None) Format placeholders: Placeholders will be replaced by the JSON keys. Placeholders for objects with sub-objects are ﬂattened using ‘delimiter’ in between (eg. {‘parent’: {‘child’: ‘value’}} will use placeholder {parent-child}). Placeholders for list elements have ‘delimiter’ followed by the index (eg. {‘parent’: [’this’, ‘that’]) will use placeholders {parent-0} for ‘this’ and {parent-1} for ‘that’. author vicyap

github

Display Github notifications and issue/pull requests for a repo. To check notifications a Github username and personal access token are required. You can create a personal access token at https://github.com/settings/tokens The only scope needed is notifications, which provides readonly access to notifications. The Github API is rate limited so setting cache_timeout too small may cause issues see https://developer.github. com/v3/#rate-limiting for details Configuration parameters: • auth_token Github personal access token, needed to check notifications see above. (default None) • button_action Button that when clicked opens the Github notification page if notifications, else the project page for the repository if there is one (otherwise the github home page). Setting to None disables. (default 3) • button_refresh Button that when clicked refreshes module. Setting to None disables. (default 2) • cache_timeout How often we refresh this module in seconds (default 60) • format Format of output (default ‘{repo} {issues}/{pull_requests}{notifications}’ if username and auth_token provided else ‘{repo} {issues}/{pull_requests}’) • format_notifications Format of {notification} status placeholder. (default ‘ N{notifications_count}’) • notifications Type of notifications can be all for all notifications or repo to only get notifications for the repo specified. If repo is not provided then all notifications will be checked. (default ‘all’) • repo Github repo to check (default ‘ultrabug/py3status’) • username Github username, needed to check notifications. (default None) Format placeholders: • {issues} Number of open issues. • {notifications} Notifications. If no notifications this will be empty. • {notifications_count} Number of notifications. This is also the __Only__ placeholder available to format_notifications. • {pull_requests} Number of open pull requests

2.26. github 27 py3status Documentation, Release 3.6

• {repo} short name of the repository being checked. eg py3status • {repo_full} full name of the repository being checked. eg ultrabug/py3status Examples:

# set github access credentials github { auth_token = '40_char_hex_access_token' username = 'my_username' }

# just check for any notifications github { auth_token = '40_char_hex_access_token' username = 'my_username' format = 'Github {notifications_count}' } author tobes glpi

Display number of open tickets from GLPI. It features thresholds to colorize the output and forces a low timeout to limit the impact of a server connectivity problem on your i3bar freshness. Conﬁguration parameters: • cache_timeout how often we refresh this module in seconds (default 300) • critical set bad color above this threshold (default 20) • db database to use (default ‘’) • format format of the module output (default ‘{tickets_open} tickets’) • host database host to connect to (default ‘’) • password login password (default ‘’) • timeout timeout for database connection (default 5) • user login user (default ‘’) • warning set degraded color above this threshold (default 15) Format placeholders: • {tickets_open} The number of open tickets Color options: • color_bad Open ticket above critical threshold • color_degraded Open ticket above warning threshold Requires: MySQL-python: http://pypi.python.org/pypi/MySQL-python

28 Chapter 2. Modules py3status Documentation, Release 3.6 gpmdp

Display song currently playing in Google Play Music Desktop Player. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 5) • format specify the items and ordering of the data in the status bar. These area 1:1 match to gpmdp- remote’s options (default ‘ {info}’) Format placeholders: • {info} Print info about now playing song • {title} Print current song title • {artist} Print current song artist • {album} Print current song album • {album_art} Print current song album art URL • {time_current} Print current song time in milliseconds • {time_total} Print total song time in milliseconds • {status} Print whether GPMDP is paused or playing • {current} Print now playing song in “artist - song” format Requires: • gpmdp http://www.googleplaymusicdesktopplayer.com/ • gpmdp-remote https://github.com/iandrewt/gpmdp-remote author Aaron Fields https://twitter.com/spirotot license BSD graphite

Display Graphite metrics. Conﬁguration parameters: • cache_timeout how often we refresh this module in seconds. (default 120) • datapoint_selection when multiple data points are returned, use “max” or “min” to determine which one to display. (default “max”) • format you MUST use placeholders here to display data, see below. (default ‘’) • graphite_url URL to your graphite server. (default ‘’) • http_timeout HTTP query timeout to graphite. (default 10) • proxy You can conﬁgure the proxy with HTTP or HTTPS. (default: None) examples: proxy = ‘https://myproxy.example.com:1234/‘ proxy = ‘http://user:[email protected]/‘ proxy =

2.28. gpmdp 29 py3status Documentation, Release 3.6

‘socks5://user:passwd@host:port’ (proxy_socks is available after an ‘pip install requests[socks]’) (default None) • targets semicolon separated list of targets to query graphite for. (default ‘’) • threshold_bad numerical threshold, if set will send a notification and colorize the output. (default None) • threshold_degraded numerical threshold, if set will send a notification and colorize the output. (default None) • timespan time range to query graphite for. (default “-2minutes”) • value_comparator choose between “max” and “min” to compare thresholds to the data point value. (default “max”) • value_format pretty format long numbers with “K”, “M” etc. (default True) • value_round round values so they’re not displayed as floats. (default True) Dynamic format placeholders: The “format” parameter placeholders are dynamically based on the data points names returned by the “targets” query to graphite. For example if your target is "carbon.agents.localhost-a.memUsage", you’d get a JSON result like this:

{ "target": "carbon.agents.localhost-a.memUsage", "datapoints": [[19693568.0, 1463663040]] }

So the placeholder you could use on your “format” conﬁg is: format = "{carbon.agents. localhost-a.memUsage}" TIP: use aliases !

targets = "alias(carbon.agents.localhost-a.memUsage, 'local_memuse')" format = "local carbon mem usage: {local_memuse} bytes"

Color options: • color_bad threshold_bad has been exceeded • color_degraded threshold_degraded has been exceeded author ultrabug group

Group modules and switch between them.

30 Chapter 2. Modules py3status Documentation, Release 3.6

In i3status.conf groups can be configured. The active one of these groups is shown in the i3bar. The active group can be changed by a user click. If the click is not used by the group module then it will be passed down to the displayed module. Modules can be i3status core modules or py3status modules. The active group can be cycled through automatically. The group can handle clicks by reacting to any that are made on it or its content or it can use a button and only respond to clicks on that. The way it does this is selected via the click_mode option. Configuration parameters: • align Text alignment when fixed_width is set can be ‘left’, ‘center’ or ‘right’ (default ‘center’) • button_next Button that when clicked will switch to display next module. Setting to 0 will disable this action. (default 5) • button_prev Button that when clicked will switch to display previous module. Setting to 0 will disable this action. (default 4) • button_toggle Button that when clicked toggles the group content being displayed between open and closed. This action is ignored if {button} is not in the format. Setting to 0 will disable this action (default 1) • click_mode This defines how clicks are handled by the group. If set to all then the group will respond to all click events. This may cause issues with contained modules that use the same clicks that the group captures. If set to button then only clicks that are directly on the {button} are acted on. The group will need {button} in its format. (default ‘all’) • cycle Time in seconds till changing to next module to display. Setting to 0 will disable cycling. (default 0) • fixed_width Reduce the size changes when switching to new group (default False) • format Format for module output. (default “{output}” if click_mode is ‘all’, “{output} {button}” if click_mode ‘button’) • format_button_closed Format for the button when group open (default ‘+’) • format_button_open Format for the button when group closed (default ‘-‘) • format_closed Format for module output when closed. (default “{button}”) • open Is the group open and displaying its content. Has no effect if {button} not in format (default True) Format placeholders: • {button} The button to open/close or change the displayed group • {output} Output of current active module Example:

# Create a disks group that will show space on '/' and '/home' # Change between disk modules every 30 seconds ... order += "group disks" ... group disks { cycle = 30 format = "Disks: {output} {button}" click_mode = "button"

2.30. group 31 py3status Documentation, Release 3.6

disk "/" { format = "/ %avail" }

disk "/home" { format = "/home %avail" } } author tobes hamster

Display time tracking activities from Hamster. Conﬁguration parameters: • cache_timeout how often we refresh this module in seconds (default 10) • format see placeholders below (default ‘{current}’) Format placeholders: • {current} current activity Requires: • hamster author Aaron Fields (spirotot [at] gmail.com) license BSD i3block

Support i3blocks blocklets in py3status. [i3blocks](https://github.com/vivien/i3blocks) is a project to allow simple scripts to provide output to the i3bar. This module allows these blocklets to run under py3status. The configuration of the blocklets is similar to how they are configured in i3blocks. Note: i3blocks and i3blocklets are subject to their respective licenses. Note: This support is experimental and done for convenience to users so they can benefit from both worlds, issues or PRs regarding i3blocks related blocklets should not be raised. Some blocklets may return pango markup eg

32 Chapter 2. Modules py3status Documentation, Release 3.6

# i3blocks config

[time] command=date '+%D %T' interval=5

[wifi] instance=wls1 label='wifi:' command=~/i3blocks/wifi.sh interval=5

# py3status config order += 'i3block time' i3block time { command = "date '+%D %T'" interval = 5 } order += 'i3block wifi' i3block wifi { instance = wls1 label = 'wifi:' command = '~/i3blocks/wifi.sh' interval = 5 }

Note: format configuration parameter is used as is standard in py3status, not as in i3blocks configuration. Currently blocklets must provide responses in the standard i3blocks manner of one line per value (not as json). Configuration parameters: • cache_timeout How often the blocklet should be called (in seconds). This is similar to cache_timeout used by standard modules. However it can also take the following values; once the blocklet will be called once, repeat the blocklet will be called constantly, or persist where the command will be expected to keep providing new data. If this is not set or is None then the blocklet will not be called unless clicked on. Note: To simplify i3block compatability this configuration parameter can also be provided as interval. (default None) • command Path to blocklet or command (default None) • format What to display on the bar (default ‘{output}’) • instance Will be provided to the blocklet as $BLOCK_INSTANCE (default ‘’) • label Will be prepended to the blocklets output (default ‘’) • name Name of the blocklet - passed as $BLOCK_NAME (default ‘’) Format placeholders: • {output} The output of the blocklet author tobes

2.32. i3block 33 py3status Documentation, Release 3.6 icinga2

Display service status for Icinga2. Conﬁguration parameters: • base_url the base url to the icinga-web2 services list (default ‘’) • ca (default True) • cache_timeout how often the data should be updated (default 60) • disable_acknowledge enable or disable counting of acknowledged service problems (default False) • format deﬁne a format string like “CRITICAL: %d” (default ‘{status_name}: {count}’) • password password to authenticate against the icinga-web2 interface (default ‘’) • status set the status you want to obtain (0=OK,1=WARNING,2=CRITICAL,3=UNKNOWN) (default 0) • url_parameters (default ‘?service_state={service_state}&format=json’) • user username to authenticate against the icinga-web2 interface (default ‘’) author Ben Oswald license BSD License source https://github.com/nazco/i3status-modules imap

Display number of unread messages from IMAP account. Conﬁguration parameters: • allow_urgent display urgency on unread messages (default False) • cache_timeout refresh interval for this module (default 60) • criterion status of emails to check for (default ‘UNSEEN’) • format display format for this module (default ‘Mail: {unseen}’) • hide_if_zero hide this module when no new mail (default False) • mailbox name of the mailbox to check (default ‘INBOX’) • password login password (default None) • port number to use (default ‘993’) • security login authentication method: ‘ssl’ or ‘starttls’ (startssl needs python 3.2 or later) (default ‘ssl’) • server server to connect (default None) • user login user (default None) Format placeholders: • {unseen} number of unread emails

34 Chapter 2. Modules py3status Documentation, Release 3.6

Color options: • color_new_mail use color when new mail arrives, default to color_good author obb insync

Display Insync status Thanks to Iain Tatch for the script that this is based on. Configuration parameters: • cache_timeout refresh interval for this module (default 10) • format display format for this module (default ‘{status} {queued}’) • status_offline show when Insync is offline (default ‘OFFLINE’) • status_paused show when Insync is paused (default ‘PAUSED’) • status_share show when Insync is sharing (default ‘SHARE’) • status_syncing show when Insync is syncing (default ‘SYNCING’) Format placeholders: • {status} Insync status • {queued} Number of files queued Color options: • color_bad Offline • color_degraded Default • color_good Synced Requires: • insync an unofficial Google Drive client with support for various desktops author Joshua Pratt license BSD kdeconnector

2.35. insync 35 py3status Documentation, Release 3.6

Display information about your smartphone with KDEConnector. Configuration parameters: • cache_timeout how often we refresh this module in seconds (default 30) • device the device name, you need this if you have more than one device connected to your PC (default None) • device_id alternatively to the device name you can set your device id here (default None) • format see placeholders below (default ‘{name}{notif_status} {bat_status} {charge}%’) • format_disconnected text if device is disconnected (default ‘device disconnected’) • low_threshold percentage value when text is twitch to color_bad (default 20) • status_bat text when battery is discharged (default ‘’) • status_chr text when device is charged (default ‘’) • status_full text when battery is full (default ‘’) • status_no_notif text when you have no notifications (default ‘’) • status_notif text when notifications are available (default ‘ ’) Format placeholders: • {bat_status} battery state • {charge} the battery charge • {name} name of the device • {notif_size} number of notifications • {notif_status} shows if a notification is available or not Color options: • color_bad Device unknown, unavailable or battery below low_threshold and not charging • color_degraded Connected and battery not charging • color_good Connected and battery charging i3status.conf example: kdeconnector { device_id = "aa0844d33ac6ca03" format = "{name} {battery} {state}" low_battery = "10" }

36 Chapter 2. Modules py3status Documentation, Release 3.6

Requires: pydbus kdeconnect author Moritz Lüdecke keyboard_layout

Display keyboard layout. Configuration parameters: • cache_timeout refresh interval for this module (default 10) • colors deprecated. see color options below (default None) • format display format for this module (default ‘{layout}’) Format placeholders: • {layout} keyboard layout Color options: • color_ colorize the layout. eg color_fr = ‘#729FCF’ Requires: • xkblayout-state or • setxkbmap and xset (works for the first two predefined layouts.) author shadowprince, tuxitop license Eclipse Public License keyboard_locks

Monitor CapsLock, NumLock, and ScrLock keys Conﬁguration parameters: • cache_timeout refresh interval for this module (default 1)

2.37. keyboard_layout 37 py3status Documentation, Release 3.6

• format display format for this module (default ‘{caps} {num} {scr}’) • icon_caps_off show when Capitals Lock is off (default ‘CAPS’) • icon_caps_on show when Capitals Lock is on (default ‘CAPS’) • icon_num_off show when Numeric Lock is off (default ‘NUM’) • icon_num_on show when Numeric Lock is on (default ‘NUM’) • icon_scr_off show when Scroll Lock is off (default ‘SCR’) • icon_scr_on show when Scroll Lock is on (default ‘SCR’) Color options: • color_good Lock on • color_bad Lock off author lasers moc

Display currently playing song in moc. MOC (music on console) is a console audio player for Linux/Unix designed to be powerful and easy to use. It consists of two parts, a server (moc) and a player/interface (mocp). It supports OGG, WAV, MP3 and other formats. Conﬁguration parameters: • button_next mouse button to skip next track (default None) • button_pause mouse button to pause/play the playback (default 1) • button_previous mouse button to skip previous track (default None) • button_stop mouse button to stop the playback (default 3) • cache_timeout refresh interval for this module (default 5) • format display format for this module (default ‘?if=is_started [?if=is_stopped [] moc| [?if=is_paused ||][?if=is_playing >] {title}]’) • sleep_timeout sleep interval for this module. when moc is not running, this interval will be used. this allows some ﬂexible timing where one might want to refresh constantly with some placeholders... or to refresh only once every minute rather than every few seconds. (default 20) Control placeholders: • {is_paused} a boolean based on moc status • {is_playing} a boolean based on moc status • {is_started} a boolean based on moc status • {is_stopped} a boolean based on moc status

38 Chapter 2. Modules py3status Documentation, Release 3.6

Format placeholders: • {album} album name, eg (new output here) • {artist} artist name, eg (new output here) • {avgbitrate} audio average bitrate, eg 230kbps • {bitrate} audio bitrate, eg 230kbps • {currentsec} elapsed time in seconds, eg 32 • {currenttime} elapsed time in [HH:]MM:SS, eg 00:32 • {file} ﬁle location, eg /home/user/Music... • {rate} audio rate, eg 44kHz • {songtitle} song title, eg (new output here) • {state} playback state, eg PLAY, PAUSE, STOP • {timeleft} time left in [HH:]MM:SS, eg 71:30 • {title} track title, eg (new output here) • {totalsec} total time in seconds, eg 4322 • {totaltime} total time in seconds, eg 72:02 Placeholders are retrieved directly from mocp --info command. The list was harvested only once and should not represent a full list. Color options: • color_paused Paused, defaults to color_degraded • color_playing Playing, defaults to color_good • color_stopped Stopped, defaults to color_bad Requires: • moc a console audio player with simple ncurses interface author lasers mpd_status

Display song currently playing in mpd. Conﬁguration parameters: • cache_timeout how often we refresh this module in seconds (default 2) • format template string (see below) (default ‘{state} [[[{artist}] - {title}]|[{ﬁle}]]’) • hide_when_paused hide the status if state is paused (default False)

2.40. mpd_status 39 py3status Documentation, Release 3.6

• hide_when_stopped hide the status if state is stopped (default True) • host mpd host (default ‘localhost’) • max_width maximum status length (default 120) • password mpd password (default None) • port mpd port (default ‘6600’) • state_pause label to display for “paused” state (default ‘[pause]’) • state_play label to display for “playing” state (default ‘[play]’) • state_stop label to display for “stopped” state (default ‘[stop]’) Color options: • color_pause Paused, default color_degraded • color_play Playing, default color_good • color_stop Stopped, default color_bad Format placeholders: • {state} state (paused, playing. stopped) can be defined via state_.. configuration parameters Refer to the mpc(1) manual page for the list of available placeholders to be used in the format. Placeholders should use braces {} rather than percent %% eg {artist}. Every placeholder can also be prefixed with next_ to retrieve the data for the song following the one currently playing. Requires: • python-mpd2 (NOT python2-mpd2)

# pip install python-mpd2

Note: previously formats using %ﬁeld% where allowed for this module, but standard placeholders should be used. Examples of format

# Show state and (artist -) title, if no title fallback to file: {state} [[[{artist} - ]{title}]|[{file}]]

# Show state, [duration], title (or file) and next song title (or file): {state} \[{time}\] [{title}|{file}] → [{next_title}|{next_file}] author shadowprince, zopieux license Eclipse Public License mpris

Display song/video and control MPRIS compatible players. There are two ways to control the media player. Either by clicking with a mouse button in the text information or by using buttons. For former you have to define the button parameters in the i3status config. Configuration parameters:

40 Chapter 2. Modules py3status Documentation, Release 3.6

• button_next mouse button to play the next entry (default 4) • button_previous mouse button to play the previous entry (default 5) • button_stop mouse button to stop the player (default None) • button_toggle mouse button to toggle between play and pause mode (default 1) • format see placeholders below (default ‘{previous}{toggle}{next} {state} [{artist} - ][{title}]’) • format_none deﬁne output if no player is running (default ‘no player running’) • icon_next text for the next button in the button control panel (default ‘»’) • icon_pause text for the pause button in the button control panel (default ‘’) • icon_play text for the play button in the button control panel (default ‘’) • icon_previous text for the previous button in the button control panel (default ‘«’) • icon_stop text for the stop button in the button control panel (default ‘’) • player_priority priority of the players. Keep in mind that the state has a higher priority than player_priority. So when player_priority is “[mpd, bomi]” and mpd is paused and bomi is playing than bomi wins. (default []) • state_pause text for placeholder {state} when song is paused (default ‘’) • state_play text for placeholder {state} when song is playing (default ‘’) • state_stop text for placeholder {state} when song is stopped (default ‘’) Format of status string placeholders: • {album} album name • {artist} artiste name (ﬁrst one) • {length} time duration of the song • {player} show name of the player • {state} playback status of the player • {time} played time of the song • {title} name of the song Format of button placeholders: • {next} play the next title • {pause} pause the player • {play} play the player • {previous} play the previous title • {stop} stop the player • {toggle} toggle between play and pause Color options: • color_control_inactive button is not clickable • color_control_active button is clickable • color_paused song is paused, defaults to color_degraded • color_playing song is playing, defaults to color_good

2.41. mpris 41 py3status Documentation, Release 3.6

• color_stopped song is stopped, defaults to color_bad Requires: • pydbus python library module i3status.conf example:

mpris { format = "{previous}{play}{next} {player}: {state} [[{artist} - {title}]|[{title}

˓→]]" format_none = "no player" player_priority = "[mpd, cantata, vlc, bomi, *]" }

only show information from mpd and vlc, but mpd has a higher priority:

mpris { player_priority = "[mpd, vlc]" }

show information of all players, but mpd and vlc have the highest priority:

mpris { player_priority = "[mpd, vlc, *]" }

vlc has the lowest priority:

mpris { player_priority = "[*, vlc]" }

Tested players: bomi Cantata mpDris2 (mpris extension for mpd) vlc author Moritz Lüdecke, tobes, valdur55

net_iplist

Display list of network interfaces and IP addresses. This module supports both IPv4 and IPv6. There is the possibility to blacklist interfaces and IPs, as well as to show interfaces with no IP address. It will show an alternate text if no IP are available. Conﬁguration parameters: • cache_timeout refresh interval for this module in seconds. (default 30) • format format of the output. (default ‘Network: {format_iface}’) • format_iface format string for the list of IPs of each interface. (default ‘{iface}:[ {ip4}][ {ip6}]’) • format_no_ip string to show if there are no IPs to display. (default ‘no connection’) • iface_blacklist list of interfaces to ignore. Accepts shell-style wildcards. (default [’lo’]) • iface_sep string to write between interfaces. (default ‘ ‘)

42 Chapter 2. Modules py3status Documentation, Release 3.6

• ip_blacklist list of IPs to ignore. Accepts shell-style wildcards. (default []) • ip_sep string to write between IP addresses. (default ‘,’) • remove_empty do not show interfaces with no IP. (default True) Format placeholders: • {format_iface} the format_iface string. Format placeholders for format_iface: • {iface} name of the interface. • {ip4} list of IPv4 of the interface. • {ip6} list of IPv6 of the interface. Color options: • color_bad no IPs to show • color_good IPs to show Example: net_iplist { iface_blacklist = [] ip_blacklist = ['127.*', '::1'] }

Requires: • ip utility found in iproute2 package author guiniol net_rate

Display network transfer rate. Conﬁguration parameters: • all_interfaces ignore self.interfaces, but not self.interfaces_blacklist (default True) • cache_timeout how often we refresh this module in seconds (default 2) • devfile location of dev ﬁle under /proc (default ‘/proc/net/dev’) • format format of the module output (default ‘{interface}: {total}’) • format_no_connection when there is no data transmitted from the start of the plugin (default ‘’) • format_value format to use for values (default “[?min_length=11 {value:.1f} {unit}]”) • hide_if_zero hide indicator if rate == 0 (default False) • interfaces comma separated list of interfaces to track (default []) • interfaces_blacklist comma separated list of interfaces to ignore (default ‘lo’) • si_units use SI units (default False)

2.43. net_rate 43 py3status Documentation, Release 3.6

• sum_values sum values of each interface instead of taking the top one (default False) • thresholds thresholds to use for colors (default [(0, ‘bad’), (1024, ‘degraded’), (1024 * 1024, ‘good’)]) • unit unit to use. If the unit contains a multiplier preﬁx, only this exact unit will ever be used (default “B/s”) Format placeholders: • {down} download rate • {interface} name of interface • {total} total rate • {up} upload rate format_value placeholders: • {unit} current unit • {value} numeric value Color thresholds: • {down} Change color based on the value of down • {total} Change color based on the value of total • {up} Change color based on the value of up author shadowprince license Eclipse Public License netdata

Display network speed and bandwidth usage. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 2) • format display format for this module (default ‘{nic} [?color=down LAN(Kb): {down}↓ {up}↑] [?color=total T(Mb): {download}↓ {upload}↑ {total}]’) • nic network interface to use (default None) • thresholds color thresholds to use (default {‘down’: [(0, ‘bad’), (30, ‘degraded’), (60, ‘good’)], ‘total’: [(0, ‘good’), (400, ‘degraded’), (700, ‘bad’)]}) Format placeholders: • {nic} network interface • {down} number of download speed • {up} number of upload speed • {download} number of download usage • {upload} number of upload usage • {total} number of total usage

44 Chapter 2. Modules py3status Documentation, Release 3.6

Color thresholds: • {down} color threshold of download speed • {total} color threshold of total usage author Shahin Azad

ns_checker

Display DNS resolution success on a configured domain. This module launch a simple query on each nameservers for the specified domain. Nameservers are dynamically retrieved. The FQDN is the only one mandatory parameter. It’s also possible to add additional nameservers by appending them in nameservers list. The default resolver can be overwritten with my_resolver.nameservers parameter. Configuration parameters: • cache_timeout how often we refresh this module in seconds (default 300) • domain domain name to check (default ‘’) • format output format string (default ‘{total_count} NS {status}’) • lifetime resolver lifetime (default 0.3) • nameservers comma separated list of reference DNS nameservers (default ‘’) • resolvers comma separated list of DNS resolvers to use (default ‘’) Format placeholders: • {nok_count} The number of failed name servers • {ok_count} The number of working name servers • {status} The overall status of the name servers (OK or NOK) • {total_count} The total number of name servers Color options: • color_bad One or more lookups have failed • color_good All lookups have succeeded Requires: • dnspython python module author nawadanp

nvidia_temp

Display NVIDIA GPU temperature. Conﬁguration parameters:

2.45. ns_checker 45 py3status Documentation, Release 3.6

• cache_timeout refresh interval for this module (default 10) • format display format for this module (default ‘GPU: {format_temp}’) • format_temp display format for temperatures (default ‘{temp}°C’) • temp_separator temperature separator (if more than one) (default ‘|’) Format placeholders: • {format_temp} format for temperatures format_temp placeholders: • {temp} temperatures Color options: • color_bad Unavailable • color_good Available Requires: • nvidia-smi NVIDIA System Management Interface program author jmdana license BSD

online_status

Determine if you have an Internet Connection. Configuration parameters: • cache_timeout refresh interval for this module (default 10) • format display format for this module (default ‘{icon}’) • icon_off show when connection is offline (default ‘’) • icon_on show when connection is online (default ‘’) • timeout time to wait for a response, in seconds (default 2) • url specify URL to connect when checking for a connection (default ‘http://www.google.com’) Format placeholders: • {icon} connection status Color options: • color_off Connection offline, defaults to color_bad • color_on Connection online, defaults to color_good author obb

46 Chapter 2. Modules py3status Documentation, Release 3.6 pingdom

Display response times of the configured Pingdom checks. We also verify the status of the checks and colorize if needed. Pingdom API doc : https://www.pingdom.com/features/ api/documentation/ Configuration parameters: • app_key create an APP KEY on pingdom first (default ‘’) • cache_timeout how often to refresh the check from pingdom (default 600) • checks comma separated pindgom check names to display (default ‘’) • format display format for this module (default ‘{pingdom}’) • login pingdom login (default ‘’) • max_latency maximal latency before coloring the output (default 500) • password pingdom password (default ‘’) • request_timeout pindgom API request timeout (default 15) Format placeholders: • {pingdom} pingdom response times Color options: • color_bad Site is down • color_degraded Latency exceeded max_latency Requires: • requests python module from pypi https://pypi.python.org/pypi/requests player_control

Control Audacious or VLC media player. Provides an icon to control simple functions of audio/video players: • start (left click) • stop (left click) • pause (middle click) Conﬁguration parameters: • cache_timeout how often to update in seconds (default 10) • debug enable verbose logging (bool) (default False)

2.48. pingdom 47 py3status Documentation, Release 3.6

• format format of the output (default “{icon}”) • pause_icon (default ‘’) • play_icon (default ‘’) • stop_icon (default ‘’) • supported_players supported players (str) (comma separated list) (default ‘audacious,vlc’) • volume_tick percentage volume change on mouse wheel (int) (positive number or None to disable it) (default 1) Format placeholders: • {icon} an icon to control music/video players author Federico Ceratto , rixx license BSD pomodoro

Use Pomodoro technique to get things done easily. Button 1 starts/pauses countdown. Button 2 switch Pomodoro/Break. Button 3 resets timer. Configuration parameters: • display_bar display time in bars when True, otherwise in seconds (default False) • format define custom display format. See placeholders below (default ‘{ss}’) • format_separator separator between minutes:seconds (default ‘:’) • max_breaks maximum number of breaks (default 4) • num_progress_bars number of progress bars (default 5) • sound_break_end break end sound (file path) (requires pyglet or pygame) (default None) • sound_pomodoro_end pomodoro end sound (file path) (requires pyglet or pygame) (default None) • sound_pomodoro_start pomodoro start sound (file path) (requires pyglet or pygame) (default None) • timer_break normal break time (seconds) (default 300) • timer_long_break long break time (seconds) (default 900) • timer_pomodoro pomodoro time (seconds) (default 1500) Format placeholders: • {bar} display time in bars • {ss} display time in total seconds (1500) • {mm} display time in total minutes (25) • {mmss} display time in (hh-)mm-ss (25:00)

48 Chapter 2. Modules py3status Documentation, Release 3.6

Color options: • color_bad Pomodoro not running • color_degraded Pomodoro break • color_good Pomodoro active i3status.conf example: pomodoro { format = "{mmss} {bar}" } author Fandekasp (Adrien Lemaire), rixx, FedericoCeratto, schober-ch process_status

Display if a process is running. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 10) • format default format for this module (default ‘{icon}’) • full if True, match against full command line (default False) • icon_off show when process not running (default ‘’) • icon_on show when process running (default ‘’) • process process name to check for (default None) Format placeholders: • {icon} process icon • {process} process name Color options: • color_bad Not running • color_good Running author obb, Moritz Lüdecke rainbow

Add color cycling fun to your i3bar. This is the most pointless yet most exciting module you can imagine.

2.51. process_status 49 py3status Documentation, Release 3.6

It allows color cycling of modules. Imagine the joy of having the current time change through the colors of the rainbow. If you were completely insane you could also use it to implement the i3bar equivalent of the tag and cause yourself endless headaches and the desire to vomit. The color for the contained module(s) is changed and cycles through your chosen gradient by default this is the colors of the rainbow. This module will increase the amount of updates that py3status needs to do so should be used sparingly. Conﬁguration parameters: • cycle_time How often we change this color in seconds (default 1) • force If True then the color will always be set. If false the color will only be changed if it has not been set by a module. (default False) • format display format for this module (default ‘{output}’) • gradient The colors we will cycle through, This is a list of hex values (default [ ‘#FF0000’, ‘#FFFF00’, ‘#00FF00’, ‘#00FFFF’, ‘#0000FF’, ‘#FF00FF’, ‘#FF0000’, ]) • multi_color If True then each module the rainbow contains will be colored differently (default True) • steps Number of steps between each color in the gradient (default 10) Example conﬁg:

order += "rainbow time"

# show time colorfully rainbow time { time {} }

Example blinking conﬁg:

order += "rainbow blink_time"

# blinking text black/white rainbow blink_time{ gradient = [ '#FFFFFF', '#000000', ] steps = 1

time {} }

author tobes

rate_counter

Display time spent and calculate the price of your service. Conﬁguration parameters: • cache_timeout how often to update in seconds (default 5)

50 Chapter 2. Modules py3status Documentation, Release 3.6

• config_file ﬁle path to store the time already spent and restore it the next session (default ‘~/.i3/py3status/counter-conﬁg.save’) • format output format string (default ‘Time: {days} day {hours}:{mins:02d} Cost: {total}’) • format_money output format string (default ‘{price}$’) • hour_price your price per hour (default 30) • tax tax value (1.02 = 2%) (default 1.02) Format placeholders: • {days} The number of whole days in running timer • {hours} The remaining number of whole hours in running timer • {mins} The remaining number of whole minutes in running timer • {secs} The remaining number of seconds in running timer • {subtotal} The subtotal cost (time * rate) • {tax} The tax cost, based on the subtotal cost • {total} The total cost (subtotal + tax) • {total_hours} The total number of whole hours in running timer • {total_mins} The total number of whole minutes in running timer Money placeholders: • {price} numeric value of money Color options: • color_running Running, default color_good • color_stopped Stopped, default color_bad author Amaury Brisou rss_aggregator

Display unread feeds in your favorite RSS aggregator. For now, supported aggregators are: • OwnCloud/NextCloud with News application • Tiny Tiny RSS 1.6 or newer You can also decide to check only for speciﬁc feeds or folders of feeds. To use this feature, you have to ﬁrst get the IDs of those feeds or folders. You can get those IDs by clicking on the desired feed or folder and watching the URL. For OwnCloud/NextCloud: https://yourcloudinstance.com/index.php/apps/news/#/items/feeds/FEED_ID https://yourcloudinstance.com/index.php/apps/news/#/items/folders/FOLDER_ID

2.54. rss_aggregator 51 py3status Documentation, Release 3.6

For Tiny Tiny RSS:

https://yourttrssinstance.com/index.php#f=FEED_ID&c=0 https://yourttrssinstance.com/index.php#f=FOLDER_ID&c=1

If both feeds list and folders list are left empty, all unread feed items will be counted. You may use both feeds list and folders list, but given feeds shouldn’t be included in given folders, else unread count number behavior is unpredictable. Same warning when aggregator allows subfolders: the folders list shouldn’t include a folder and one of its subfolder. Conﬁguration parameters: • aggregator feed aggregator used. Supported values are owncloud and ttrss. Other aggregators might be supported in future releases. Contributions are welcome. (default ‘owncloud’) • cache_timeout how often to run this check (default 60) • feed_ids list of IDs of feeds to watch, see note below (default []) • folder_ids list of IDs of folders ro watch (default []) • format format to display (default ‘Feed: {unseen}’) • password login password (default None) • server aggregator server to connect to (default ‘https://yourcloudinstance.com’) • user login user (default None) Format placeholders: • {unseen} sum of numbers of unread feed elements Color options: • color_new_items text color when there is new items (default color_good) • color_error text color when there is an error (default color_bad) Requires: • requests python module from pypi https://pypi.python.org/pypi/requests author raspbeguy rt

Display number of ongoing tickets from RT queues. Conﬁguration parameters: • cache_timeout how often we refresh this module in seconds (default 300) • db database to use (default ‘’) • format see placeholders below (default ‘general: {General}’) • host database host to connect to (default ‘’) • password login password (default ‘’)

52 Chapter 2. Modules py3status Documentation, Release 3.6

• threshold_critical set bad color above this threshold (default 20) • threshold_warning set degraded color above this threshold (default 10) • timeout timeout for database connection (default 5) • user login user (default ‘’) Format placeholders: • {YOUR_QUEUE_NAME} number of ongoing RT tickets (open+new+stalled) Color options: • color_bad Exceeded threshold_critical • color_degraded Exceeded threshold_warning Requires: PyMySQL: https://pypi.python.org/pypi/PyMySQL or MySQL-python: http://pypi.python.org/pypi/ MySQL-python It features thresholds to colorize the output and forces a low timeout to limit the impact of a server connectivity problem on your i3bar freshness. author ultrabug scratchpad_async

Display number of windows and urgency hints asynchronously. Conﬁguration parameters: • always_show always display the format (default False) • format display format for this module (default “{counter} ”) Format placeholders: • {counter} number of scratchpad windows Requires: • i3ipc (https://github.com/acrisci/i3ipc-python) author cornerman license BSD scratchpad_counter

Display number of windows in scratchpad. Conﬁguration parameters: • cache_timeout How often we refresh this module in seconds (default 5) • format Format of indicator (default ‘{counter} ’)

2.56. scratchpad_async 53 py3status Documentation, Release 3.6

• hide_when_none Hide indicator when there is no windows (default False) Format placeholders: • {counter} number of scratchpad windows author shadowprince license Eclipse Public License screenshot

Take screenshots and upload them to a given server. Display a ‘SHOT’ button in your i3bar allowing you to take a screenshot and directly send (if wanted) the file to your online server. When the screenshot has been taken, ‘SHOT’ is replaced by the file_name. By default, this modules uses the ‘gnome-screenshot’ program to take the screenshot, but this can be configured with the screenshot_command configuration parameter. Configuration parameters: • cache_timeout how often to update in seconds (default 5) • file_length generated file_name length (default 4) • push True/False if you want to push your screenshot to your server (default True) • save_path Directory where to store your screenshots. (default ‘~/Pictures/’) • screenshot_command the command used to generate the screenshot (default ‘gnome-screenshot -f’) • upload_path the remote path where to push the screenshot (default ‘/files’) • upload_server your server address (default ‘puzzledge.org’) • upload_user your ssh user (default ‘erol’) Color options: • color_good Displayed color author Amaury Brisou selinux

Display SELinux state. This module displays the state of SELinux on your machine: Enforcing (good), Permissive (degraded), or Dis- abled (bad).

54 Chapter 2. Modules py3status Documentation, Release 3.6

Conﬁguration parameters: • cache_timeout refresh interval for this module (default 10) • format display format for this module (default ‘SELinux: {state}’) • state_disabled show when no SELinux policy is loaded. (default ‘disabled’) • state_enforcing show when SELinux security policy is enforced. (default ‘enforcing’) • state_permissive show when SELinux prints warnings instead of enforcing. (default ‘permissive’) Format placeholders: • {state} SELinux state Color options: • color_bad Enforcing • color_degraded Permissive • color_good Disabled Requires: • libselinux-python SELinux python bindings for libselinux author bstinsonmhk license BSD

spaceapi

Display status of a given hackerspace. Conﬁguration parameters: • button_url mouse button to open URL sent in space’s API (default 3) • cache_timeout refresh interval for this module (default 60) • format display format for this module (default ‘{state}[ {lastchanged}]’) • format_lastchanged display format for time (default ‘since %H:%M’) • state_closed show when hackerspace is closed (default ‘closed’) • state_open show when hackerspace is open (default ‘open’) • url specify JSON URL of a hackerspace to retrieve from (default ‘http://status.chaospott.de/status.json’) Format placeholders: • {state} Hackerspace state • {lastchanged} Time format_lastchanged conversion: ‘%’ Strftime characters to be translated Color options:

2.60. spaceapi 55 py3status Documentation, Release 3.6

• color_closed Space closed, defaults to color_bad • color_open Space open, defaults to color_good author timmszigat license WTFPL spotify

Display song currently playing in Spotify. Configuration parameters: • cache_timeout how often to update the bar (default 5) • format see placeholders below (default ‘{artist} : {title}’) • format_down define output if spotify is not running (default ‘Spotify not running’) • format_stopped define output if spotify is not playing (default ‘Spotify stopped’) • sanitize_titles whether to remove meta data from album/track title (default True) • sanitize_words which meta data to remove (default [’bonus’, ‘demo’, ‘edit’, ‘explicit’, ‘extended’, ‘feat’, ‘mono’, ‘remaster’, ‘stereo’, ‘version’]) Format placeholders: • {album} album name • {artist} artiste name (first one) • {time} time duration of the song • {title} name of the song Color options: • color_offline Spotify is not running, defaults to color_bad • color_paused Song is stopped or paused, defaults to color_degraded • color_playing Song is playing, defaults to color_good i3status.conf example: spotify { format = "{title} by {artist} -> {time}" format_down = "no Spotify" }

Requires: spotify (>=1.0.27.71.g0a26e3b2) author Pierre Guilbert, Jimmy Garpehäll, sondrele, Andrwe

56 Chapter 2. Modules py3status Documentation, Release 3.6 static_string

Display static text. Conﬁguration parameters: • format display format for this module (default ‘Hello, world!’) author frimdo [email protected] sysdata

Display system RAM, SWAP and CPU utilization. Configuration parameters: • cache_timeout how often we refresh this module in seconds (default 10) • format output format string (default ‘[?color=cpu CPU: {cpu_usage}%], ‘ ‘[?color=mem Mem: {mem_used}/{mem_total} GB ({mem_used_percent}%)]’) • mem_unit the unit of memory to use in report, case insensitive. [’dynamic’, ‘KiB’, ‘MiB’, ‘GiB’] (default ‘GiB’) • swap_unit the unit of swap to use in report, case insensitive. [’dynamic’, ‘KiB’, ‘MiB’, ‘GiB’] (default ‘GiB’) • temp_unit unit used for measuring the temperature (‘C’, ‘F’ or ‘K’) (default ‘°C’) • thresholds thresholds to use for color changes (default [(0, “good”), (40, “degraded”), (75, “bad”)]) • zone thermal zone to use. If None try to guess CPU temperature (default None) Format placeholders: • {cpu_temp} cpu temperature • {cpu_usage} cpu usage percentage • {load1} load average over the last minute • {load5} load average over the five minutes • {load15} load average over the fifteen minutes • {mem_total} total memory • {mem_unit} unit for memory • {mem_used} used memory • {mem_used_percent} used memory percentage • {swap_total} total swap • {swap_unit} unit for swap • {swap_used} used swap

2.62. static_string 57 py3status Documentation, Release 3.6

• {swap_used_percent} used swap percentage • {temp_unit} temperature unit Color thresholds: • cpu change color based on the value of cpu_usage • max_cpu_mem change the color based on the max value of cpu_usage and mem_used_percent • load change color based on the value of load1 • mem change color based on the value of mem_used_percent • swap change color based on the value of swap_used_percent • temp change color based on the value of cpu_temp NOTE: If using the {cpu_temp} option, the sensors command should be available, provided by the lm-sensors or lm_sensors package. author Shahin Azad , shrimpza, guiniol systemd

Check systemd unit status. Check the status of a systemd unit. Conﬁguration parameters: • cache_timeout How often we refresh this module in seconds (default 5) • format Format for module output (default “{unit}: {status}”) • unit Name of the unit (default “dbus.service”) Format of status string placeholders: • {unit} name of the unit • {status} ‘active’, ‘inactive’ or ‘not-found’ Color options: • color_good Unit active • color_bad Unit inactive • color_degraded Unit not found Example:

# Check status of vpn service # Start with left click # Stop with right click systemd vpn { unit = 'vpn.service' on_click 1 = "exec sudo systemctl start vpn" on_click 3 = "exec sudo systemctl stop vpn" format = '{unit} is {status}' }

Requires:

58 Chapter 2. Modules py3status Documentation, Release 3.6

• pydbus python lib for dbus author Adrian Lopez license BSD

taskwarrior

Display tasks currently running in taskwarrior. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 5) • format display format for this module (default ‘{task}’) Format placeholders: • {task} active tasks Requires task: https://taskwarrior.org/download/ author James Smith http://jazmit.github.io/ license BSD

timer

A simple countdown timer. This is a very basic countdown timer. You can change the timer length as well as pausing, restarting and resetting it. Currently this is more of a demo of a composite. Each part of the timer can be changed independently hours, minutes, seconds using mouse buttons 4 and 5 (scroll wheel). Button 1 starts/pauses the countdown. Button 2 resets timer. Conﬁguration parameters: • format display format for this module (default ‘Timer {timer}’) • sound play sound ﬁle path when the timer ends (default None) • time number of seconds to start countdown with (default 60) Format placeholders: • {timer} display hours:minutes:seconds author tobes

2.65. taskwarrior 59 py3status Documentation, Release 3.6 tor_rate

Display the current transfer rates of a tor instance Conﬁguration parameters: • cache_timeout An integer specifying the cache life-time of the modules output in seconds (default 2) • control_address The address on which the Tor daemon listens for control connections (default “127.0.0.1”) • control_password The password to use for the Tor control connection (default None) • control_port The port on which the Tor daemon listens for control connections (default 9051) • format A string describing the output format for the module (default “↑ {up} ↓ {down}”) • format_value A string describing how to format the transfer rates (default “[?min_length=12 {rate:.1f} {unit}]”) • rate_unit The unit to use for the transfer rates (default “B/s”) • si_units A boolean value selecting whether or not to use SI units (default False) Format placeholders: • {down} The incoming transfer rate • {up} The outgoing transfer rate format_value placeholders: • {rate} The current transfer-rate’s value • {unit} The current transfer-rate’s unit Requires: • stem python module from pypi https://pypi.python.org/pypi/stem Example: tor_rate { cache_timeout = 10 format = "IN: {down} | OUT: {up}" control_port = 1337 control_password = "TertiaryAdjunctOfUnimatrix01" si_units = True } order += "tor_rate" author Felix Morgner license 3-clause-BSD

60 Chapter 2. Modules py3status Documentation, Release 3.6 twitch_streaming

Display status on a given Twitch streamer. Checks if a streamer is online using the Twitch Kraken API to see if a channel is currently streaming or not. Configuration parameters: • cache_timeout how often we refresh this module in seconds (default 10) • format Display format when online (default “{stream_name} is live!”) • format_invalid Display format when streamer does not exist (default “{stream_name} does not exist!”) • format_offline Display format when offline (default “{stream_name} is offline.”) • stream_name name of streamer(twitch.tv/) (default None) Format placeholders: • {stream_name} name of the streamer Color options: • color_bad Stream offline or error • color_good Stream is live author Alex Caswell [email protected] license BSD uname

Display system information from uname. Conﬁguration parameters: • format see placeholders below (default ‘{system} {release} {machine}’) Format placeholders: • {system} system/OS name, e.g. ‘Linux’, ‘Windows’, or ‘Java’ • {node} computer’s network name (may not be fully qualiﬁed!) • {release} system’s release, e.g. ‘2.2.0’ or ‘NT’ • {version} system’s release version, e.g. ‘#3 on degas’ • {machine} machine type, e.g. ‘x86_64’ • {processor} the (real) processor name, e.g. ‘amdk6’ author ultrabug (inspired by ndalliard)

2.68. twitch_streaming 61 py3status Documentation, Release 3.6 uptime

Display system uptime. Conﬁguration parameters: • format display format for this module (default ‘up {days} days {hours} hours {minutes} minutes’) Format placeholders: • {decades} decades • {years} years • {weeks} weeks • {days} days • {hours} hours • {minutes} minutes • {seconds} seconds Note: If you don’t use one of the placeholders, the value will be carried over to the next unit. For example, given an uptime of 1h 30min: If you use {minutes} as your only placeholder, then its value will be 90. If you use {hours} and {minutes}, then its values will be 1 and 30, respectively. Examples:

# show uptime without zeroes uptime { format = 'up [\?if=weeks {weeks} weeks ][\?if=days {days} days ] [\?if=hours {hours} hours ][\?if=minutes {minutes} minutes ]' }

# show uptime in multiple formats using group module group uptime { format = "up {output}" uptime { format = '[\?if=weeks {weeks} weeks ][\?if=days {days} days ] [\?if=hours {hours} hours ][\?if=minutes {minutes} minutes]' } uptime { format = '[\?if=weeks {weeks}w ][\?if=days {days}d ] [\?if=hours {hours}h ][\?if=minutes {minutes}m]' } uptime { format = '[\?if=days {days}, ][\?if=hours {hours}:] [\?if=minutes {minutes:02d}]' } } author Alexis “Horgix” Chotard , tobes, lasers license BSD

62 Chapter 2. Modules py3status Documentation, Release 3.6 vnstat

Display vnstat statistics. Configuration parameters: • cache_timeout refresh interval for this module (default 180) • coloring see coloring rules below (default {}) • format display format for this module (default ‘{total}’) • initial_multi set to 1 to disable first bytes (default 1024) • left_align (default 0) • multiplier_top if value is greater, divide it with unit_multi and get next unit from units (default 1024) • precision (default 1) • statistics_type d for daily, m for monthly (default ‘d’) • unit_multi value to divide if rate is greater than multiplier_top (default 1024) Coloring rules: If value is more than dict key, the string will change color based on the specified values in the coloring section. Example: coloring = { 800: "#dddd00", # over 800: yellow 900: "#dd0000", # over 900: red }

Format placeholders: • {down} download • {total} total • {up} upload Requires: • vnstat a console-based network trafﬁc monitor author shadowprince license Eclipse Public License volume_status

Volume control.

2.71. vnstat 63 py3status Documentation, Release 3.6

Expands on the standard i3status volume module by adding color and percentage threshold settings. Volume up/down and Toggle mute via mouse clicks can be easily added see example. Conﬁguration parameters: • button_down Button to click to decrease volume. Setting to 0 disables. (default 0) • button_mute Button to click to toggle mute. Setting to 0 disables. (default 0) • button_up Button to click to increase volume. Setting to 0 disables. (default 0) • cache_timeout how often we refresh this module in seconds. (default 10) • channel channel to track. Default value is backend dependent. (default None) • command Choose between “amixer”, “pamixer” or “pactl”. If None, try to guess based on available commands. (default None) • device Device to use. Defaults value is backend dependent (default None) • format Format of the output. (default ‘[?if=is_input |♪]: {percentage}%’) • format_muted Format of the output when the volume is muted. (default ‘[?if=is_input |♪]: muted’) • is_input Is this an input device or an output device? (default False) • max_volume Allow the volume to be increased past 100% if available. pactl supports this (default 120) • thresholds Threshold for percent volume. (default [(0, ‘bad’), (20, ‘degraded’), (50, ‘good’)]) • volume_delta Percentage amount that the volume is increased or decreased by when volume buttons pressed. (default 5) Format placeholders: • {percentage} Percentage volume Color options: • color_muted Volume is muted, if not supplied color_bad is used if set to None then the threshold color will be used. Example:

# Add mouse clicks to change volume # Set thresholds to rainbow colors volume_status { button_up = 4 button_down = 5 button_mute = 2

thresholds = [ (0, "#FF0000"), (10, "#E2571E"), (20, "#FF7F00"), (30, "#FFFF00"), (40, "#00FF00"), (50, "#96BF33"), (60, "#0000FF"), (70, "#4B0082"), (80, "#8B00FF"), (90, "#FFFFFF") ] }

64 Chapter 2. Modules py3status Documentation, Release 3.6

Requires: • alsa-utils alsa backend (tested with alsa-utils 1.0.29-1) • pamixer pulseaudio backend NOTE: If you are changing volume state by external scripts etc and want to refresh the module quicker than the i3status interval, send a USR1 signal to py3status in the keybinding. Example: killall -s USR1 py3status author license BSD vpn_status

Drop-in replacement for i3status run_watch VPN module. Expands on the i3status module by displaying the name of the connected vpn using pydbus. Asynchronously updates on dbus signals unless check_pid is True. Conﬁguration parameters: • cache_timeout How often to refresh in seconds when check_pid is True. (default 10) • check_pid If True, act just like the default i3status module. (default False) • format Format of the output. (default ‘VPN: {name}|VPN: no’) • pidfile Same as i3status.conf pidﬁle, checked when check_pid is True. (default ‘/sys/class/net/vpn0/dev_id’) Format placeholders: • {name} The name and/or status of the VPN. Color options: • color_bad VPN connected • color_good VPN down Requires: • pydbus Which further requires PyGi. Check your distribution’s repositories. author Nathan Smith weather_yahoo

Display Yahoo! Weather forecast. Based on Yahoo! Weather. forecast, thanks guys ! http://developer.yahoo.com/weather/

2.73. vpn_status 65 py3status Documentation, Release 3.6

Find your woeid using: http://woeid.rosselliot.co.nz/ Conﬁguration parameters: • cache_timeout how often to check for new forecasts (default 7200) • forecast_days how many forecast days you want shown (default 3) • forecast_include_today show today’s forecast. Note that {today} in format shows the current conditions, while this variable shows today’s forecast. (default False) • forecast_text_separator separator between forecast entries. (default ‘ ‘) • format uses 2 placeholders forecast_text_separator (default ‘{today} {forecasts}’) • format_forecast format of a forecast item (default ‘{icon}’) • format_today format for today {today} in format example: format = “Now: {icon}{temp}°{units} {text}” output: Now: -4°C Light Rain/Windy (default ‘{icon}’) • icon_cloud cloud icon, (default ‘’) • icon_default unknown weather icon, (default ‘?’) • icon_rain rain icon, (default ‘’) • icon_snow snow icon, (default ‘’) • icon_sun sun icon, (default ‘’) • request_timeout check timeout (default 10) • units Celsius (C) or Fahrenheit (F) (default ‘c’) • woeid Yahoo woeid (extended location) (default None) Format placeholders: • {today} text generated by format_today • {forecasts} text generated by format_forecast, separated by Forcast placeholders: • {icon} Icon representing weather • {low} low temperature • {high} high temperature • {units} units ‘C’ or ‘F’ • {text} text description of forecats The WOEID in this example is for Paris, France => 615702 weather_yahoo { woeid = 615702 format_today = "Now: {icon}{temp}°{units} {text}" forecast_days = 5 } author ultrabug, rail

66 Chapter 2. Modules py3status Documentation, Release 3.6 whatismyip

Display public IP address and online status. Configuration parameters: • button_refresh mouse button to refresh this module (default 2) • button_toggle mouse button to toggle between states (default 1) • cache_timeout how often we refresh this module in seconds (default 30) • expected define expected values for format placeholders, and use color_degraded to show the output of this module if any of them does not match the actual value. This should be a dict eg {‘country’: ‘France’} (default None) • format available placeholders are {ip} and {country}, as well as any other key in JSON fetched from url_geo (default ‘{ip}’) • hide_when_offline hide the module output when offline (default False) • icon_off what to display when offline (default ‘’) • icon_on what to display when online (default ‘’) • mode default mode to display is ‘ip’ or ‘status’ (click to toggle) (default ‘ip’) • negative_cache_timeout how often to check again when offline (default 2) • timeout how long before deciding we’re offline (default 5) • url_geo IP to check for geo location (must output json) (default ‘https://freegeoip.net/json/’) Format placeholders: • {icon} display the icon • {country} display the country • {ip} display current ip address any other key in JSON fetched from url_geo Color options: • color_bad Offline • color_degraded Output is unexpected (IP/country mismatch, etc.) • color_good Online author ultrabug whoami

2.75. whatismyip 67 py3status Documentation, Release 3.6

Display logged-in username. Conﬁguration parameters: • format display format for whoami (default ‘{username}’) Format placeholders: • {username} display current username Inspired by i3 FAQ: https://faq.i3wm.org/question/1618/add-user-name-to-status-bar.1.html author ultrabug

wiﬁ

Display WiFi bit rate, quality, signal and SSID using iw. Conﬁguration parameters: • bitrate_bad Bad bit rate in Mbit/s (default 26) • bitrate_degraded Degraded bit rate in Mbit/s (default 53) • blocks a string, where each character represents quality level (default “_”) • cache_timeout Update interval in seconds (default 10) • device Wireless device name (default “wlan0”) • down_color Output color when disconnected, possible values: “good”, “degraded”, “bad” (default “bad”) • format Display format for this module (default ‘W: {bitrate} {signal_percent} {ssid}|W: down’) • round_bitrate If true, bit rate is rounded to the nearest whole number (default True) • signal_bad Bad signal strength in percent (default 29) • signal_degraded Degraded signal strength in percent (default 49) • use_sudo Use sudo to run iw, make sure iw requires some root rights without a password by adding a sudoers entry, eg... ‘ ALL=(ALL) NOPASSWD:/usr/bin/iw dev,/usr/bin/iw dev [a-z]* link’ (default False) Format placeholders: • {bitrate} Display bit rate • {device} Display device name • {icon} Character representing the quality based on bitrate, as deﬁned by the ‘blocks’ • {ip} Display IP address • {signal_dbm} Display signal in dBm • {signal_percent} Display signal in percent • {ssid} Display SSID Color options: • color_bad Signal strength signal_bad or lower

68 Chapter 2. Modules py3status Documentation, Release 3.6

• color_degraded Signal strength signal_degraded or lower • color_good Signal strength above signal_degraded Requires: • iw cli conﬁguration utility for wireless devices • ip only for {ip}. may be part of iproute2: ip routing utilities __Note: Some distributions eg Debian require iw to be run with privileges. In this case you will need to use the use_sudo conﬁguration parameter.__ author Markus Weimar license BSD window_title

Display window title. Prints the name of focused window at frequent intervals. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 0.5) • format display format for this module (default ‘{title}’) • max_width If width of title is greater, shrink it and add ‘...’ (default 120) author shadowprince license Eclipse Public License window_title_async

Display window title asynchronously. Uses asynchronous update via i3 IPC events. Provides instant title update only when it required. Conﬁguration parameters: • always_show do not hide the title when it can be already visible (e.g. in tabbed layout). (default False) • empty_title string that will be shown instead of the title when the title is hidden. (default “”) • format format of the title, (default “{title}”) • max_width maximum width of block (in symbols). If the title is longer than max_width, the title will be truncated to max_width - 1 ﬁrst symbols with ellipsis appended. (default 120) Requires: • i3ipc (https://github.com/acrisci/i3ipc-python)

2.78. window_title 69 py3status Documentation, Release 3.6 author Anon1234 https://github.com/Anon1234 license BSD wwan_status

Display network and IP address for newer Huwei modems. It is tested for Huawei E3276 (usb-id 12d1:1506) aka Telekom Speed Stick LTE III but may work on other devices, too. Conﬁguration parameters: • baudrate There should be no need to conﬁgure this, but feel free to experiment. (default 115200) • cache_timeout How often we refresh this module in seconds. (default 5) • consider_3G_degraded If set to True, only 4G-networks will be considered ‘good’; 3G connections are shown as ‘degraded’, which is yellow by default. Mostly useful if you want to keep track of where there is a 4G connection. (default False) • format_down What to display when the modem is not plugged in (default ‘WWAN: down’) • format_error What to display when modem can’t be accessed. (default ‘WWAN: {error}’) • format_no_service What to display when the modem does not have a network connection. This allows to omit the (then meaningless) network generation. (default ‘WWAN: {status} {ip}’) • format_up What to display upon regular connection (default ‘WWAN: {status} ({netgen}) {ip}’) • interface The default interface to obtain the IP address from. For wvdial this is most likely ppp0. For netctl it can be different. (default ‘ppp0’) • modem The device to send commands to. (default ‘/dev/ttyUSB1’) • modem_timeout The timespan between querying the modem and collecting the response. (default 0.4) Color options: • color_bad Error or no connection • color_degraded Low generation connection eg 2G • color_good Good connection Requires: • netifaces • pyserial author Timo Kohorst [email protected] PGP: B383 6AE6 6B46 5C45 E594 96AB 89D2 209D DBF3 2BB5

70 Chapter 2. Modules py3status Documentation, Release 3.6 xrandr

Control screen layout. This modules allows you to handle your screens outputs directly from your bar! • Detect and propose every possible screen combinations • Switch between combinations using click events and mouse scroll • Activate the screen or screen combination on a single click • It will detect any newly connected or removed screen automatically For convenience, this module also proposes some added features: • Dynamic parameters for POSITION and WORKSPACES assignment (see below) • Automatic fallback to a given screen or screen combination when no more screen is available (handy for laptops) • Automatically apply this screen combination on start: no need for xorg! • Automatically move workspaces to screens when they are available • Define your own subset of output combinations to use Configuration parameters: • cache_timeout how often to (re)detect the outputs (default 10) • fallback when the current output layout is not available anymore, fallback to this layout if available. This is very handy if you have a laptop and switched to an external screen for presentation and want to automatically fallback to your laptop screen when you disconnect the external screen. (default True) • fixed_width show output as fixed width (default True) • force_on_start switch to the given combination mode if available when the module starts (saves you from having to configure xorg) (default None) • format display format for xrandr (default ‘{output}’) • hide_if_single_combination hide if only one combination is available (default False) • icon_clone icon used to display a ‘clone’ combination (default ‘=’) • icon_extend icon used to display a ‘extend’ combination (default ‘+’) • output_combinations string used to define your own subset of output combinations to use, instead of generating every possible combination automatically. Provide the values in the format that this module uses, splitting the combinations using ‘|’ character. The combinations will be rotated in the exact order as you listed them. When an output layout is not available any more, the configurations are automatically filtered out. Example: Assuming the default values for icon_clone and icon_extend are used, and assuming you have two screens ‘eDP1’ and ‘DP1’, the following setup will reduce the number of output

2.81. xrandr 71 py3status Documentation, Release 3.6

combinations from four (every possible one) down to two: output_combinations = “eDP1|eDP1+DP1” (default None) Dynamic conﬁguration parameters: • _pos: apply the given position to the OUTPUT Example: DP1_pos = “-2560x0” Example: DP1_pos = “above eDP1” Example: DP1_pos = “below eDP1” Example: DP1_pos = “left-of LVDS1” Example: DP1_pos = “right-of eDP1” • _workspaces: comma separated list of workspaces to move to the given OUTPUT when it is activated Example: DP1_workspaces = “1,2,3” • _rotate: rotate the output as told Example: DP1_rotate = “left” Color options: • color_bad Displayed layout unavailable • color_degraded Using a fallback layout • color_good Displayed layout active Example conﬁg: xrandr { force_on_start = "eDP1+DP1" DP1_pos = "left-of eDP1" VGA_workspaces = "7" } author ultrabug xrandr_rotate

Control screen rotation. Configuration parameters: • cache_timeout how often to refresh this module. (default 10) • format a string that formats the output, can include placeholders. (default ‘{icon}’) • hide_if_disconnected a boolean flag to hide icon when screen is disconnected. It has no effect unless screen option is also configured. (default False) • horizontal_icon a character to represent horizontal rotation. (default ‘H’) • horizontal_rotation a horizontal rotation for xrandr to use. Available options: ‘normal’ or ‘in- verted’. (default ‘normal’) • screen display output name to rotate, as detected by xrandr. If not provided, all enabled screens will be rotated. (default None) • vertical_icon a character to represent vertical rotation. (default ‘V’) • vertical_rotation a vertical rotation for xrandr to use. Available options: ‘left’ or ‘right’. (default ‘left’)

72 Chapter 2. Modules py3status Documentation, Release 3.6

Format placeholders: • {icon} a rotation icon, speciﬁed by horizontal_icon or vertical_icon. • {screen} a screen name, speciﬁed by screen option or detected automatically if only one screen is connected, otherwise ‘ALL’. Color options: • color_degraded Screen is disconnected • color_good Displayed rotation is active author Maxim Baz (https://github.com/maximbaz) license BSD xscreensaver

Control Xscreensaver. This script is useful for people who let Xscreensaver manage DPMS settings. Xscreensaver has its own DPMS vari- ables separate from xset. DPMS can be safely turned off in xset as long as Xscreensaver is running. Settings can be managed using “xscreensaver-demo”. Conﬁguration parameters: • button_activate mouse button to activate Xscreensaver (default 3) • button_toggle mouse button to toggle Xscreensaver (default 1) • cache_timeout refresh interval for this module (default 15) • format display format for this module (default ‘{icon}’) • icon_off show when Xscreensaver is not running (default ‘XSCR’) • icon_on show when Xscreensaver is running (default ‘XSCR’) Format placeholders: • {icon} Xscreensaver icon Color options: • color_on Enabled, defaults to color_good • color_off Disabled, defaults to color_bad author neutronst4r , lasers xsel

2.83. xscreensaver 73 py3status Documentation, Release 3.6

Display X selection. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 0.5) • command the clipboard command to run (default ‘xsel -o’) • format display format for this module (default ‘{selection}’) • max_size strip the selection to this value (default 15) • symmetric show beginning and end of the selection string with respect to conﬁgured max_size. (default True) Format placeholders: • {selection} output from clipboard command Requires: • xsel a command-line program to retrieve/set the X selection author Sublim3 [email protected] license BSD yandexdisk_status

Display Yandex.Disk status. Conﬁguration parameters: • cache_timeout refresh interval for this module (default 10) • format display format for this module (default ‘Yandex.Disk: {status}’) • status_busy show when Yandex.Disk is busy (default None) • status_off show when Yandex.Disk isn’t running (default ‘Not started’) • status_on show when Yandex.Disk is idling (default ‘Idle’) Format placeholders: • {status} Yandex.Disk status Color options: • color_bad Not started • color_degraded Idle • color_good Busy

74 Chapter 2. Modules py3status Documentation, Release 3.6

Requires: • yandex-disk command line interface for Yandex.Disk author Vladimir Potapev (github:vpotapev) license BSD

2.85. yandexdisk_status 75 py3status Documentation, Release 3.6

76 Chapter 2. Modules CHAPTER 3

Using modules

py3status comes with a large range of Modules. Modules in py3status are configured using your usual i3status. conf. py3status tries to find the config in the following locations: • ~/.i3/i3status.conf • ~/.i3status.conf • /etc/i3status.conf • XDG_CONFIG_HOME/.config/i3status/config • ~/.config/i3status/config • XDG_CONFIG_DIRS/i3status/config • /etc/xdg/i3status/config You can also specify the config location using py3status -c in your i3 configuration file.

Loading a py3status module and ordering modules output

To load a py3status module you just have to list it like any other i3status module using the order += parameter. Ordering your py3status modules in your i3bar is just the same as i3status modules, just list the order parameter where you want your module to be displayed. For example you could insert and load the imap module like this:

Listing 3.1: Example order += "disk /home" order += "disk /" order += "imap" order += "time"

77 py3status Documentation, Release 3.6

Conﬁguring a py3status module

Your py3status modules are conﬁgured the exact same way as i3status modules, directly from your i3status.conf, like this :

Listing 3.2: Example # configure the py3status imap module # and run thunderbird when I left click on it imap { cache_timeout = 60 imap_server = 'imap.myprovider.com' mailbox = 'INBOX' password = 'coconut' port = '993' user = 'mylogin' on_click 1= "exec thunderbird" } py3status conﬁguration section

This special section holds py3status specific configuration. Settings here will affect all py3status modules. Many settings e.g. colors can still be overridden by also defining in the individual module. Global options: • nagbar_font. It will be used as an argument to i3-nagbar -f, thus setting its font.

Listing 3.3: Example py3status { nagbar_font = 'pango:Ubuntu Mono 12' }

Conﬁguration obfuscation

Note: New in version 3.1

Py3status allows you to hide individual configuration parameters so that they do not leak into log files, user notifications or to the i3bar. Additionally they allow you to obfuscate configuration parameters using base64 encoding. To do this you need to add an obfuscation option to the configuration parameter. Obfuscation options are added by adding :hide or :base64 to the name of the parameters.

Note: Obfuscation is only available for string parameters.

78 Chapter 3. Using modules py3status Documentation, Release 3.6

Listing 3.4: Example # normal_parameter will be shown in log files etc as 'some value' # obfuscated_parameter will be shown in log files etc as '***' module { normal_parameter = 'some value' obfuscated_parameter:hide = 'some value' }

In the previous example conﬁguration the users password is in plain text. Users may want to make it less easy to read. Py3status allows strings to be base64 encoded. To use an encoded string add :base64 to the name of the parameter.

Listing 3.5: Example # Example of obfuscated configuration imap { imap_server = 'imap.myprovider.com' password:base64 = 'Y29jb251dA==' user = 'mylogin' }

Note: Base64 encoding is very simple and should not be considered secure in any way.

Conﬁguring colors

Since version 3.1 py3status allows greater color configuration. Colors can be set in the general section of your i3status.conf or in an individual modules configuration. If a color is not in a modules configuration then the values from the general section will be used. If a module does not specify colors but it is in a container, then the colors of the container will be used if they are set, before using ones defined in the general section.

Listing 3.6: Example general { # These will be used if not supplied by a module color = '#FFFFFF' color_good = '#00FF00' color_bad = '#FF0000' color_degraded = '#FFFF00' } time { color = 'FF00FF' format = "%H:%M" } battery_level { color_good = '#00AA00' color_bad = '#AA0000' color_degraded = '#AAAA00'

3.5. Conﬁguring colors 79 py3status Documentation, Release 3.6

color_charging = '#FFFF00' }

Conﬁguring thresholds

Some modules allow you to define thresholds in a module. These are used to determine which color to use when displaying the module. Thresholds are defined in the config as a list of tuples. With each tuple containing a value and a color. The color can either be a named color eg good referring to color_good or a hex value.

Listing 3.7: Example volume_status { thresholds =[ (0, "#FF0000"), (20, "degraded"), (50, "bad"), ] }

If the value checked against the threshold is equal to or more than a threshold then that color supplied will be used. In the above example the logic would be if 0 >= value < 20 use #FF0000 else if 20 >= value < 50 use color_degraded else if 50 >= value use color_good

Some modules may allow more than one threshold to be deﬁned. If all the thresholds are the same they can be deﬁned as above but if you wish to specify them separately you can by giving a dict of lists.

Listing 3.8: Example my_module { thresholds ={ 'threshold_1':[ (0, "#FF0000"), (20, "degraded"), (50, "bad"), ], 'threshold_2':[ (0, "good"), (30, "bad"), ], } }

Urgent

Some modules use i3bar’s urgent feature to indicate that something important has occurred. The allow_urgent conﬁguration parameter can be used to allow/prevent a module from setting itself as urgent.

80 Chapter 3. Using modules py3status Documentation, Release 3.6

Listing 3.9: Example # prevent modules showing as urgent, except github py3status { allow_urgent = false } github { allow_urgent = true }

Grouping Modules

The group module allows you to group several modules together. Only one of the modules are displayed at a time. The displayed module can either be cycled through automatically or by user action (the default, on mouse scroll). This module is very powerful and allows you to save a lot of space on your bar.

Listing 3.10: Example order += "group tz"

# cycle through different timezone hours every 10s group tz { cycle = 10 format = "{output}"

tztime la { format = "LA %H:%M" timezone = "America/Los_Angeles" }

tztime ny { format = "NY %H:%M" timezone = "America/New_York" }

tztime du { format = "DU %H:%M" timezone = "Asia/Dubai" } }

The frame module also allows you to group several modules together, however in a frame all the modules are shown. This allows you to have more than one module shown in a group.

Listing 3.11: Example order += "group frames"

# group showing disk space or times using button to change what is shown. group frames { click_mode = "button"

frame time { tztime la {

3.8. Grouping Modules 81 py3status Documentation, Release 3.6

format = "LA %H:%M" timezone = "America/Los_Angeles" }

tztime ny { format = "NY %H:%M" timezone = "America/New_York" }

tztime du { format = "DU %H:%M" timezone = "Asia/Dubai" } }

frame disks { disk "/"{ format = "/ %avail" }

disk "/home"{ format = "/home %avail" } } }

Frames can also have a toggle button to hide/show the content

Listing 3.12: Example # A frame showing times in different cities. # We also have a button to hide/show the content frame time { format = '{output}{button}' format_separator ='' # have space instead of usual i3bar separator

tztime la { format = "LA %H:%M" timezone = "America/Los_Angeles" }

tztime ny { format = "NY %H:%M" timezone = "America/New_York" }

tztime du { format = "DU %H:%M" timezone = "Asia/Dubai" } }

82 Chapter 3. Using modules py3status Documentation, Release 3.6

Custom click events py3status allows you to easily add click events to modules in your i3bar. These modules can be both i3status or py3status modules. This is done in your i3status.config using the on_click parameter. Just add a new configuration parameter named on_click [button number] to your module config and py3status will then execute the given i3 command (using i3-msg). This means you can run simple tasks like executing a program or execute any other i3 specific command. As an added feature and in order to get your i3bar more responsive, every on_click command will also trigger a module refresh. This works for both py3status modules and i3status modules as described in the refresh command below.

Listing 3.13: Example # reload the i3 config when I left click on the i3status time module # and restart i3 when I middle click on it time { on_click 1= "reload" on_click 2= "restart" }

# control the volume with your mouse (need >i3-4.8) # launch alsamixer when I left click # kill it when I right click # toggle mute/unmute when I middle click # increase the volume when I scroll the mouse wheel up # decrease the volume when I scroll the mouse wheel down volume master { format =" ♪: %volume" device = "default" mixer = "Master" mixer_idx =0 on_click 1= "exec i3-sensible-terminal -e alsamixer" on_click 2= "exec amixer set Master toggle" on_click 3= "exec killall alsamixer" on_click 4= "exec amixer set Master 1+" on_click 5= "exec amixer set Master 1-" }

# run wicd-gtk GUI when I left click on the i3status ethernet module # and kill it when I right click on it ethernet eth0 { # if you use %speed, i3status requires root privileges format_up = "E: %ip" format_down ="" on_click 1= "exec wicd-gtk" on_click 3= "exec killall wicd-gtk" }

# run thunar when I left click on the / disk info module disk "/"{ format = "/ %free" on_click 1= "exec thunar /" }

# this is a py3status module configuration # open an URL on opera when I left click on the weather_yahoo module

3.9. Custom click events 83 py3status Documentation, Release 3.6

weather_yahoo paris { cache_timeout = 1800 woeid = 615702 forecast_days =2 on_click 1= "exec opera http://www.meteo.fr" request_timeout = 10 }

Special on_click commands

There are two commands you can pass to the on_click parameter that have a special meaning to py3status : • refresh : This will refresh (expire the cache) of the clicked module. This also works for i3status modules (it will send a SIGUSR1 to i3status for you). • refresh_all : This will refresh all the modules from your i3bar (i3status included). This has the same effect has sending a SIGUSR1 to py3status.

Module data and on_click commands

Since version 3.3 it is possible to use the output text of a module in the on_click command. To do this $OUTPUT can be used in command and it will be substituted by the modules text output when the command is run.

Listing 3.14: Example # copy module output to the clipboard using xclip my_module { on_click 1= 'exec echo $OUTPUT | xclip -i' }

If the output of a module is a composite then the output of the part clicked on can be accessed using $OUTPUT_PART.

84 Chapter 3. Using modules CHAPTER 4

py3-cmd

py3status can be controlled remotely via the py3-cmd cli utility. This utility allows you to run a number of commands.

Commands available refresh

Cause named module(s) to have their output refreshed. To refresh all modules use the all keyword.

# refresh any wifi modules py3-cmd refresh wifi

# refresh wifi module instance eth0 py3-cmd refresh "wifi eth0"

# refresh any wifi or whatismyip modules py3-cmd refresh wifi whatismyip

# refresh all py3status modules py3-cmd refresh all click

Send a click event to a module as though it had been clicked on. You can specify the button to simulate.

# send a click event to the whatismyip module (button 1) py3-cmd click whatismyip

# send a click event to the backlight module with button 5 py3-cmd click5 backlight

85 py3status Documentation, Release 3.6

You can also specify the button using one of the named shortcuts leftclick, rightclick, middleclick, scrollup, scrolldown.

# send a click event to the whatismyip module (button 1) py3-cmd leftclick whatismyip

# send a click event to the backlight module with button 5 py3-cmd scrolldown backlight

Calling commands from i3 py3-cmd can be used in your i3 conﬁguration ﬁle. To send a click event to the whatismyip module when Mod+x is pressed bindsym $mod+x exec py3-cmd click whatismyip

This example shows how volume control keys can be bound to change the volume and then cause the volume_status module to be updated. bindsym XF86AudioRaiseVolume exec "amixer -q sset Master 5%+ unmute; py3-cmd refresh

˓→volume_status" bindsym XF86AudioLowerVolume exec "amixer -q sset Master 5%- unmute; py3-cmd refresh

˓→volume_status" bindsym XF86AudioMute exec "amixer -q sset Master toggle; py3-cmd refresh

˓→volume_status"

Note: py3-cmd was added in py3status version 3.6 if you are using a source installation from a prior version, then you may have to run setup.py again so that it is correctly installed see Setting up a development environment.

86 Chapter 4. py3-cmd CHAPTER 5

Writing custom py3status modules

Note: This guide covers the new style of py3status modules. These are only available in version 3.0 and above.

Writing custom modules for py3status is easy. This guide will teach you how. Let’s start by looking at a simple example.

Example 1: The basics - Hello World!

Here we start with the most basic module that just outputs a static string to the status bar.

#-*- coding: utf-8 -*- """ Example module that says 'Hello World!'

This demonstrates how to produce a simple custom module. """ class Py3status:

def hello_world(self): return { 'full_text':'Hello World!', 'cached_until': self.py3.CACHE_FOREVER }

Running the example

Save the ﬁle as hello_world.py in a directory that py3status will check for modules. By default it will look in $HOME/.i3/py3status/ or you can specify additional directories using --include when you run py3status.

87 py3status Documentation, Release 3.6

You need to tell py3status about your new module, so in your i3status.conf add:

order += "hello_world"

Then restart i3 by pressing Mod + Shift + R. Your new module should now show up in the status bar.

How does it work?

The Py3status class tells py3status that this is a module. The module gets loaded. py3status then calls any public methods that the class contains to get a response. In our example there is a single method hello_world(). Read more here: [module methods](#module_methods).

The response

The response that a method returns must be a python dict. It should contain at least two key / values. full_text

This is the text that will be displayed in the status bar. cached_until

This tells py3status how long it should consider your response valid before it should re-run the method to get a fresh response. In our example our response will not need to be updated so we can use the special self.py3. CACHE_FOREVER constant. This tells py3status to consider our response always valid. cached_until should be generated via the self.py3.time_in() method. self.py3

This is a special object that gets injected into py3status modules. It helps provide functionality for the module, such as the CACHE_FOREVER constant. Read more about the py3 module helper.

Example 2: Conﬁguration parameters

Allow users to supply conﬁguration to a module.

#-*- coding: utf-8 -*- """ Example module that says 'Hello World!' that can be customised.

This demonstrates how to use configuration parameters.

Configuration parameters: format: Display format (default 'Hello World!') """

class Py3status:

88 Chapter 5. Writing custom py3status modules py3status Documentation, Release 3.6

format='Hello World!'

def hello_world(self): return { 'full_text': self.format, 'cached_until': self.py3.CACHE_FOREVER }

This module still outputs ‘Hello World’ as before but now you can customise the output using your i3status. config for example to show the text in French. hello_world { format = 'Bonjour tout le monde!' }

In your module self.format will have been set to the value supplied in the conﬁg.

Example 3: Click events

Catch click events and perform an action.

#-*- coding: utf-8 -*- """ Example module that handles events

This demonstrates how to use events. """ class Py3status:

def __init__(self): self.full_text='Click me'

def click_info(self): return { 'full_text': self.full_text, 'cached_until': self.py3.CACHE_FOREVER }

def on_click(self, event): """ event will be a dict like {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'} """ button= event['button'] # update our output (self.full_text) format_string='You pressed button {button}' data={'button': button} self.full_text= self.py3.safe_format(format_string, data) # Our modules update methods will get called automatically.

The on_click method of a module is special and will get called when the module is clicked on. The event parameter will be a dict that gives information about the event.

5.3. Example 3: Click events 89 py3status Documentation, Release 3.6

A typical event dict will look like this: {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'} You should only receive events for the module clicked on, so generally we only care about the button. The __init__() method is called when our class is instantiated.

Note: __init__ is called before any conﬁg parameters have been set.

We use the safe_format() method of py3 for formatting. Read more about the py3 module helper.

Example 4: Status string placeholders

Status string placeholders allow us to add information to formats.

#-*- coding: utf-8 -*- """ Example module that demonstrates status string placeholders

Configuration parameters: format: Initial format to use (default 'Click me') format_clicked: Display format to use when we are clicked (default 'You pressed button {button}')

Format placeholders: {button} The button that was pressed """ class Py3status: format='Click me' format_clicked='You pressed button {button}'

def __init__(self): self.button= None

def click_info(self): if self.button: data={'button': self.button} full_text= self.py3.safe_format(self.format_clicked, data) else: full_text= self.format

return { 'full_text': full_text, 'cached_until': self.py3.CACHE_FOREVER }

def on_click(self, event): """ event will be a dict like {'y': 13, 'x': 1737, 'button': 1, 'name': 'example', 'instance': 'first'} """ self.button= event['button'] # Our modules update methods will get called automatically.

90 Chapter 5. Writing custom py3status modules py3status Documentation, Release 3.6

This works just like the previous example but we can now be customised. The following example assumes that our module has been saved as click_info.py. click_info { format = "Cliquez ici" format_clicked = "Vous avez appuyé sur le bouton {button}" }

Example 5: Using color constants self.py3 in our module has color constants that we can access, these allow the user to set colors easily in their conﬁg.

Note: py3 colors constants require py3status 3.1 or higher

#-*- coding: utf-8 -*- """ Example module that uses colors.

We generate a random number between and color it depending on its value. Clicking on the module will update it an a new number will be chosen.

Configuration parameters: format: Initial format to use (default 'Number {number}')

Format placeholders: {number} Our random number

Color options: color_high: number is 5 or higher color_low: number is less than 5 """ from random import randint class Py3status: format='Number {number}'

def random(self): number= randint(0,9) full_text= self.py3.safe_format(self.format, {'number': number})

if number<5: color= self.py3.COLOR_LOW else: color= self.py3.COLOR_HIGH

return { 'full_text': full_text, 'color': color,

5.5. Example 5: Using color constants 91 py3status Documentation, Release 3.6

'cache_until': self.py3.CACHE_FOREVER }

def on_click(self, event): # by defining on_click pressing any mouse button will refresh the # module. pass

The colors can be set in the config in the module or its container or in the general section. The following example assumes that our module has been saved as number.py. Although the constants are capitalized they are defined in the config in lower case. number { color_high = '#FF0000' color_low = '#00FF00' }

Module methods

Py3status will call a method in a module to provide output to the i3bar. Methods that have names starting with an underscore will not be used in this way. Any methods deﬁned as static methods will also not be used.

Outputs

Output methods should provide a response dict. Example response:

{ 'full_text':"This text will be displayed", 'cached_until': 1470922537, # Time in seconds since the epoch }

The response can include the folowing keys cached_until The time (in seconds since the epoch) that the output will be classed as no longer valid and the output function will be called again. Since version 3.1, if no cached_until value is provided the the output will be cached for cache_timeout seconds by default this is 60 and can be set using the -t or --timeout option when running py3status. To never expire the self.py3.CACHE_FOREVER constant should be used. cached_until should be generated via the self.py3.time_in() method. color The color that the module output will be displayed in. composite Used to output more than one item to i3bar from a single output method. If this is provided then full_text should not be. full_text

92 Chapter 5. Writing custom py3status modules py3status Documentation, Release 3.6

This is the text output that will be sent to i3bar. index The index of the output. Allows composite output to identify which component of their output had an event triggered. separator If False no separator will be shown after the output block (requires i3bar 4.12). urgent If True the output will be shown as urgent in i3bar.

Special methods

Some special method are also defined. kill() Called just before a module is destroyed. on_click(event) Called when an event is recieved by a module. post_config_hook() Called once an instance of a module has been created and the configuration parameters have been set. This is useful for any work a module must do before its output methods are run for the first time. post_config_hook() introduced in version 3.1

Py3 module helper

Py3 is a special helper object that gets injected into py3status modules, providing extra functionality. A module can access it via the self.py3 instance attribute of its py3status class. For details see py3 module helper.

Composites

Whilst most modules return a simple response eg:

{ 'full_text':, 'cached_until':, }

Sometimes it is useful to provide a more complex, composite response. A composite is made up of more than one simple response which allows for example a response that has multiple colors. Different parts of the response can also be differentiated between when a click event occures and so allow clicking on different parts of the response to have different outcomes. The different parts of the composite will not have separators between them in the output so they will appear as a single module to the user. The format of a composite is as follows:

5.7. Py3 module helper 93 py3status Documentation, Release 3.6

{ 'cached_until':, 'composite':[ { 'full_text':, }, { 'full_text':, 'index': }, ] }

The index key in the response is used to identify the individual block and when the the modules on_click() method is called the event will include this. Supplied index values should be strings. If no index is given then it will have an integer value indicating its position in the composite.

Module documentation

All contributed modules should have correct documentation. This documentation is in a specific format and is used to generate user documentation. The docsting of a module is used. The format is as follows: • Single line description of the module followed by a single blank line. • Longer description of the module providing more detail. • Configuration parameters. This section describes the user setable parameters for the module. All parameters should be listed (in alphabetical order). default values should be given in parentheses eg (default 7). • Format placeholders. These are used for substituting values in format strings. All placeholders should be listed (in alphabetical order) and describe the output that they provide. • Color options. These are the color options that can be provided for this module. All color options should be listed (in alphabetical order) that the module uses. • Requires. A list of all the additional requirements for the module to work. These may be command line utilities, python librarys etc. • Example. Example configerations for the module can be given. • Author and license. Finally information on the modules author and a license can be provided. Here is an example of a docstring.

""" Single line summary

Longer description of the module. This should help users understand the modules purpose.

Configuration parameters: parameter: Explanation of this parameter (default ) parameter_other: This parameter has a longer explanation that continues onto a second line so it is indented. (default )

Format placeholders:

94 Chapter 5. Writing custom py3status modules py3status Documentation, Release 3.6

{info} Description of the placeholder

Color options: color_meaning: what this signifies, defaults to color_good color_meaning2: what this signifies

Requires: program: Information about the program python_lib: Information on the library

Example:

``` module { parameter = "Example" parameter_other = 7 } ```

@author @license """

Deprecation of conﬁguration parameters

Sometimes it is necessary to deprecate configuration parameters. Modules are able to specify information about deprecation so that it can be done automatically. Deprecation information is specified in the Meta class of a py3status module using the deprecated attribute. The following types of deprecation are supported. The deprecation types will be performed in the order here. rename The parameter has been renamed. We will update the configuration to use the new name. class Py3status:

class Meta:

deprecated={ 'rename':[ { 'param':'format_available', # parameter name to be renamed 'new':'icon_available', # the parameter that will get the value 'msg':'obsolete parameter use `icon_available`', # message }, ], } format_ﬁx_unnamed_param Some formats used {} as a placeholder this needs to be updated to a named placeholder eg {value}. class Py3status:

class Meta:

5.10. Deprecation of conﬁguration parameters 95 py3status Documentation, Release 3.6

deprecated={ 'format_fix_unnamed_param':[ { 'param':'format', # parameter to be changed 'placeholder':'percent', # the place holder to use 'msg':'{} should not be used in format use `{percent}`', #

˓→message }, ], } rename_placeholder We can use this to rename placeholders in format strings class Py3status:

class Meta:

deprecated={ 'rename_placeholder':[ { 'placeholder':'cpu', # old placeholder name 'new':'cpu_usage', # new placeholder name 'format_strings':['format'], # config settings to update }, ], } update_placeholder_format This allows us to update the format of a placeholder in format strings. The key value pairs {placeholder: format} can be supplied as a dict in placeholder_formats or the dict can be provided by function the function will be called with the current conﬁg and must return a dict. If both are supplied then placeholder_formats will be updated using the dict supplied by the function. class Py3status:

class Meta:

deprecated={ 'update_placeholder_format':[ { 'function': update_placeholder_format, # function returning dict 'placeholder_formats':{ # dict of placeholder:format 'cpu_usage':':.2f', }, 'format_strings':['format'], # config settings to update } ], } substitute_by_value This allows one conﬁguration parameter to set the value of another. class Py3status:

class Meta:

96 Chapter 5. Writing custom py3status modules py3status Documentation, Release 3.6

deprecated={ 'substitute_by_value':[ { 'param':'mode', # parameter to be checked for substitution 'value':'ascii_bar', # value that will trigger the substitution 'substitute':{ 'param':'format', # parameter to be updated 'value':'{ascii_bar}', # the value that will be set }, 'msg':'obsolete parameter use `format ="{ascii_bar}"`',

˓→#message }, ], } function For more complex substitutions a function can be deﬁned that will be called with the conﬁg as a parameter. This function must return a dict of key value pairs of parameters to update class Py3status:

class Meta:

# Create a function to be called def deprecate_function(config): # This function must return a dict return {'thresholds':[ (0,'bad'), (config.get('threshold_bad', 20),'degraded'), (config.get('threshold_degraded', 50),'good'), ], }

deprecated={ 'function':[ { 'function': deprecate_function, # function to be called }, ], } remove The parameters will be removed. class Py3status:

class Meta:

deprecated={ 'remove':[ { 'param':'threshold_bad', # name of parameter to remove 'msg':'obsolete set using thresholds parameter', #message }, ], }

5.10. Deprecation of conﬁguration parameters 97 py3status Documentation, Release 3.6

Updating of conﬁguration parameters

Sometimes it is necessary to update configuration parameters. Modules are able to specify information about updates so that it can be done automatically. Config updating information is specified in the Meta class of a py3status module using the update_config attribute. The following types of updates are supported. update_placeholder_format This allows us to update the format of a placeholder in format strings. The key value pairs {placeholder: format} can be supplied as a dict in placeholder_formats or the dict can be provided by function the function will be called with the current config and must return a dict. If both are supplied then placeholder_formats will be updated using the dict supplied by the function. This is similar to the deprecation method but is to allow default formatting of placeholders to be set. In a module like sysdata we have placeholders eg {cpu_usage} this ends up having a value something like 20. 542317173377157 which is strange as the value to use but gives the user the ability to have as much precision as they want. A module writer may decide that they want this displayed as 20.54 so {cpu_usage:.2f} would do this. Having a default format containing that just looks long/silly and the user setting a custom format just wants to do format = 'CPU: {cpu_usage}%' and get expected results ie not the full precision. If they don’t like the default formatting of the number they could still do format = ‘CPU: {cpu_usage:d}%’ etc. So using this allows sensible defaults formatting and allows simple placeholders for user configurations.

class Py3status:

class Meta:

update_config={ 'update_placeholder_format':[ { 'placeholder_formats':{ # dict of placeholder:format 'cpu_usage':':.2f', }, 'format_strings':['format'], # config settings to update } ], }

Module testing

Each module should be able to run independantly for testing purposes. This is simply done by adding the following code to the bottom of your module.

if __name__ =="__main__": """ Run module in test mode. """ from py3status.module_test import module_test module_test(Py3status)

If a speciﬁc conﬁg should should be provided for the module test, this can be done as follows.

98 Chapter 5. Writing custom py3status modules py3status Documentation, Release 3.6

if __name__ =="__main__": """ Run module in test mode. """ config={ 'always_show': True, } from py3status.module_test import module_test module_test(Py3status, config=config)

Such modules can then be tested independently by running python path/to/module

5.12. Module testing 99 py3status Documentation, Release 3.6

100 Chapter 5. Writing custom py3status modules CHAPTER 6

py3 module helper

Py3 is a special helper object that gets injected into py3status modules, providing extra functionality. A module can access it via the self.py3 instance attribute of its py3status class.

Constants

CACHE_FOREVER Special constant that when returned for cache_until will cause the module to not update unless externally triggered. LOG_ERROR Show as Error LOG_INFO Show as Informational LOG_WARNING Show as Warning

Exceptions exception CommandError An error occurred running the given command. This exception provides some additional attributes error_code: The error code returned from the call output: Any output returned by the call error: Any error output returned by the call

101 py3status Documentation, Release 3.6

exception Py3Exception Base Py3 exception class. All custom Py3 exceptions derive from this class. exception RequestException A Py3.request() base exception. This will catch any of the more speciﬁc exceptions. exception RequestInvalidJSON The request has not returned valid JSON exception RequestTimeout A timeout has occurred during a request made via Py3.request(). exception RequestURLError A URL related error has occurred during a request made via Py3.request().

Methods

build_composite(format_string, param_dict=None, composites=None, attr_getter=None)

Note: deprecated in 3.3 use safe_format().

Build a composite output using a format string. Takes a format_string and treats it the same way as safe_format() but also takes a composites dict where each key/value is the name of the placeholder and either an output eg {'full_text': 'something'} or a list of outputs. check_commands(cmd_list) Checks to see if commands in list are available using which. returns the ﬁrst available command. If a string is passed then that command will be checked for. command_output(command, shell=False) Run a command and return its output as unicode. The command can either be supplied as a sequence or string. An Exception is raised if an error occurs command_run(command) Runs a command and returns the exit code. The command can either be supplied as a sequence or string. An Exception is raised if an error occurs composite_create(item) Create and return a Composite. The item may be a string, dict, list of dicts or a Composite. composite_join(separator, items) Join a list of items with a separator. This is used in joining strings, responses and Composites. A Composite object will be returned. composite_update(item, update_dict, soft=False)

102 Chapter 6. py3 module helper py3status Documentation, Release 3.6

Takes a Composite (item) if item is a type that can be converted into a Composite then this is done automatically. Updates all entries it the Composite with values from update_dict. Updates can be soft in which case existing values are not overwritten. A Composite object will be returned. error(msg, timeout=None) Raise an error for the module. param msg message to be displayed explaining the error param timeout how long before we should retry. For permanent errors py3.CACHE_FOREVER should be returned. If not supplied then the modules cache_timeout will be used. flatten_dict(d, delimiter=’-‘, intermediates=False, parent_key=None) Flatten a dictionary. Values that are dictionaries are ﬂattened using delimiter in between (eg. parent-child) Values that are lists are ﬂattened using delimiter followed by the index (eg. parent-0) example:

{ 'fish_facts':{ 'sharks':'Most will drown if they stop moving', 'skates':'More than 200 species', }, 'fruits':['apple','peach','watermelon'], 'number': 52 }

# becomes

{ 'fish_facts-sharks':'Most will drown if they stop moving', 'fish_facts-skates':'More than 200 species', 'fruits-0':'apple', 'fruits-1':'peach', 'fruits-2':'watermelon', 'number': 52 }

# if intermediates is True then we also get unflattened elements # as well as the flattened ones.

{ 'fish_facts':{ 'sharks':'Most will drown if they stop moving', 'skates':'More than 200 species', }, 'fish_facts-sharks':'Most will drown if they stop moving', 'fish_facts-skates':'More than 200 species', 'fruits':['apple','peach','watermelon'], 'fruits-0':'apple', 'fruits-1':'peach', 'fruits-2':'watermelon', 'number': 52 }

6.3. Methods 103 py3status Documentation, Release 3.6

format_contains(format_string, name) Determines if format_string contains placeholder name name is tested against placeholders using fnmatch so the following patterns can be used:

* matches everything ? matches any single character [seq] matches any character in seq [!seq] matches any character not in seq

This is useful because a simple test like '{placeholder}' in format_string will fail if the format string contains placeholder formatting eg '{placeholder:.2f}' format_units(value, unit=’B’, optimal=5, auto=True, si=False) Takes a value and formats it for user output, we can choose the unit to use eg B, MiB, kbits/second. This is mainly for use with bytes/bits it converts the value into a human readable form. It has various additional options but they are really only for special cases. The function returns a tuple containing the new value (this is a number so that the user can still format it if required) and a unit that is the units that we have been converted to. By supplying unit to the function we can force those units to be used eg unit=KiB would force the output to be in Kibibytes. By default we use non-si units but if the unit is si eg kB then we will switch to si units. Units can also be things like Mbit/sec. If the auto parameter is False then we use the unit provided. This only makes sense when the unit is singular eg ‘Bytes’ and we want the result in bytes and not say converted to MBytes. optimal is used to control the size of the output value. We try to provide an output value of that number of characters (including decimal point), it may also be less due to rounding. If a ﬁxed unit is used the output may be more than this number of characters. get_output(module_name) Return the output of the named module. This will be a list. get_placeholder_formats_list(format_string) Parses the format_string and returns a list of tuples [(placeholder, format), ...]. eg '{placeholder:.2f}' will give [('placeholder', ':.2f')] get_placeholders_list(format_string, match=None) Returns a list of placeholders in format_string. If match is provided then it is used to ﬁlter the result using fnmatch so the following patterns can be used:

* matches everything ? matches any single character [seq] matches any character in seq [!seq] matches any character not in seq

This is useful because we just get simple placeholder without any formatting that may be applied to them eg '{placeholder:.2f}' will give ['{placeholder}'] i3s_config() returns the i3s_conﬁg dict. is_color(color)

104 Chapter 6. py3 module helper py3status Documentation, Release 3.6

Tests to see if a color is defined. Because colors can be set to None in the config and we want this to be respected in an expression like. color = self.py3.COLOR_MUTED or self.py3.COLOR_BAD The color is treated as True but sometimes we want to know if the color has a value set in which case the color should count as False. This function is a helper for this second case. is_composite(item) Check if item is a Composite and return True if it is. is_my_event(event) Checks if an event triggered belongs to the module recieving it. This is mainly for containers who will also recieve events from any children they have. Returns True if the event name and instance match that of the module checking. is_python_2() True if the version of python being used is 2.x Can be helpful for fixing python 2 compatability issues log(message, level=LOG_INFO) Log the message. The level must be one of LOG_ERROR, LOG_INFO or LOG_WARNING notify_user(msg, level=LOG_INFO, rate_limit=5) Send a notification to the user. level must be ‘info’, ‘error’ or ‘warning’. rate_limit is the time period in seconds during which this message should not be repeated. play_sound(sound_file) Plays sound_file if possible. prevent_refresh() Calling this function during the on_click() method of a module will request that the module is not refreshed after the event. By default the module is updated after the on_click event has been processed. register_function(function_name, function) Register a function for the module. The following functions can be registered content_function() Called to discover what modules a container is displaying. This is used to determine when updates need passing on to the container and also when modules can be put to sleep. the function must return a set of module names that are being displayed.

Note: This function should only be used by containers.

urgent_function(module_names) This function will be called when one of the contents of a container has changed from a non-urgent to an urgent state. It is used by the group module to switch to displaying the urgent module. module_names is a list of modules that have become urgent

Note: This function should only be used by containers.

6.3. Methods 105 py3status Documentation, Release 3.6

request(url, params=None, data=None, headers=None, timeout=None, auth=None) Make a request to a url and retrieve the results. param url url to request eg http://example.com param params extra query string parameters as a dict param data POST data as a dict. If this is not supplied the GET method will be used param headers http headers to be added to the request as a dict param timeout timeout for the request in seconds param auth authentication info as tuple (username, password) returns HttpResponse safe_format(format_string, param_dict=None, force_composite=False, attr_getter=None) Parser for advanced formatting. Unknown placeholders will be shown in the output eg {foo}. Square brackets [] can be used. The content of them will be removed from the output if there is no valid placeholder contained within. They can also be nested. A pipe (vertical bar) | can be used to divide sections the ﬁrst valid section only will be shown in the output. A backslash \ can be used to escape a character eg \[ will show [ in the output. \? is special and is used to provide extra commands to the format string, example \?color=#FF00FF. Multiple commands can be given using an ampersand & as a separator, example \?color=#FF00FF&show. {} will be converted, or removed if it is None or empty. Formating can also be applied to the placeholder eg {number:03.2f}. example format_string: "[[{artist} - ]{title}]|{file}" This will show artist - title if artist is present, title if title but no artist, and file if ﬁle is present but not artist or title. param_dict is a dictionary of palceholders that will be substituted. If a placeholder is not in the dictionary then if the py3status module has an attribute with the same name then it will be used.

Note: Added in version 3.3

Composites can be included in the param_dict. The result returned from this function can either be a string in the case of simple parsing or a Composite if more complex. If force_composite parameter is True a composite will always be returned. attr_getter is a function that will when called with an attribute name as a parameter will return a value. stop_sound() Stops any currently playing sounds for this module. threshold_get_color(value, name=None) Obtain color for a value using thresholds.

106 Chapter 6. py3 module helper py3status Documentation, Release 3.6

The value will be checked against any defined thresholds. These should have been set in the i3status configuration. If more than one threshold is needed for a module then the name can also be supplied. If the user has not supplied a named threshold but has defined a general one that will be used. If the gradients config parameter is True then rather than sharp thresholds we will use a gradient between the color values. time_in(seconds=None, sync_to=None, offset=0) Returns the time a given number of seconds into the future. Helpful for creating the cached_until value for the module output.

Note: from version 3.1 modules no longer need to explicitly set a cached_until in their response unless they wish to directly control it. seconds speciﬁes the number of seconds that should occure before the update is required. sync_to causes the update to be syncronised to a time period. 1 would cause the update on the second, 60 to the nearest minute. By defalt we syncronise to the nearest second. 0 will disable this feature. offset is used to alter the base time used. A timer that started at a certain time could set that as the offset and any syncronisation would then be relative to that time. trigger_event(module_name, event) Trigger an event on a named module. update(module_name=None) Update a module. If module_name is supplied the module of that name is updated. Otherwise the module calling is updated.

6.3. Methods 107 py3status Documentation, Release 3.6

108 Chapter 6. py3 module helper CHAPTER 7

Developing and Contributing

Contributions to py3status including documentation, the core code, or for new or existing modules are welcome.

What you will need

• python3/python2 • i3status – http://i3wm.org/i3status/ – https://github.com/i3/i3status • pytest pytest-ﬂake8 – https://pypi.python.org/pypi/pytest – https://pypi.python.org/pypi/pytest-ﬂake8

Setting up a development environment

First clone the git repository

# using https git clone https://github.com/ultrabug/py3status.git

# using ssh (needs github account) git clone [email protected]:ultrabug/py3status.git

Run setup.py to install

# cd to the directory containing setup.py cd py3status

109 py3status Documentation, Release 3.6

# install you may need to use sudo to have required permissions python setup.py develop

you can now run py3status and any changes to the code you make will active.

Note: py3status will only be installed for the version of python that you used to run setup.py. To run against a different version of python You should repeat the above step eg python2.7 setup.py develop. If you wish to have multiple versions available. First run setup.py develop using the required python versions. Next copy the executable eg sudo cp /usr/bin/py3status /usr/bin/py3status2 Then edit the hash- bang to point to your chosen python version.

Python versions

py3status code, including modules, should run under both python 2 and python 3.

Pytest

Py3status uses pytest and the pytest-ﬂake8 plugin for testing. All submissions to the project must pass testing. To install these via pip use

pip install pytest pip install pytest-flake8

The tests can be run by using py.test --flake8 in the py3status root directory. Tests are kept in the tests directory.

Travis CI

When you create your Pull Request, some checks from Travis CI will automatically run; you can see previous builds if you want to. If something fails in the CI: • Take a look the build log • If you don’t get what is failing or why it is failing, feel free to tell it as a comment in your PR: people here are helpful and open-minded :) • Once the problem is identified and fixed, rebase your commit with the fix and push it on your fork to trigger the CI again For reference, you can take a look at this PR; you won’t see the old failed CI runs, but you’ll get an idea of the PR flow.

110 Chapter 7. Developing and Contributing py3status Documentation, Release 3.6

Coding in containers

Warning, by default (at least on Archlinux), i3status has cap_net_admin capabilities, which will make it fail with operation not permitted when running inside a Docker container.

$ getcap`which i3status` /usr/sbin/i3status= cap_net_admin+ep

To allow it to run without these capabilites (hence disabling some of the functionnalities), remove it with: setcap -r`which i3status`

Building documentation

Py3status documentation is build using sphinx. The requirements needed to build the documentation are in doc/ doc-requirements.txt make sure you have them installed. To build the documentation.

# cd to the doc directory cd doc

# build documentation make html

The created documentation will be found in _build/html

Contributions

To make a contribution please create a pull request.

7.6. Coding in containers 111 py3status Documentation, Release 3.6

112 Chapter 7. Developing and Contributing Index

B N build_composite() (built-in function), 102 notify_user() (built-in function), 105 C P CACHE_FOREVER, 101 play_sound() (built-in function), 105 check_commands() (built-in function), 102 prevent_refresh() (built-in function), 105 command_output() (built-in function), 102 Py3Exception, 101 command_run() (built-in function), 102 CommandError, 101 R composite_create() (built-in function), 102 register_function() (built-in function), 105 composite_join() (built-in function), 102 request() (built-in function), 105 composite_update() (built-in function), 102 RequestException, 102 content_function() (built-in function), 105 RequestInvalidJSON, 102 RequestTimeout, 102 E RequestURLError, 102 error() (built-in function), 103 S F safe_format() (built-in function), 106 ﬂatten_dict() (built-in function), 103 stop_sound() (built-in function), 106 format_contains() (built-in function), 103 format_units() (built-in function), 104 T threshold_get_color() (built-in function), 106 G time_in() (built-in function), 107 get_output() (built-in function), 104 trigger_event() (built-in function), 107 get_placeholder_formats_list() (built-in function), 104 get_placeholders_list() (built-in function), 104 U I update() (built-in function), 107 urgent_function() (built-in function), 105 i3s_conﬁg() (built-in function), 104 is_color() (built-in function), 104 is_composite() (built-in function), 105 is_my_event() (built-in function), 105 is_python_2() (built-in function), 105 L log() (built-in function), 105 LOG_ERROR, 101 LOG_INFO, 101 LOG_WARNING, 101

113