Configuration

The configuration file is a normal Python script. The status bar is controlled by a central Status object, which individual modules like a clock or a battery monitor are added to with the register method.

A typical configuration file could look like this (note the additional dependencies from network and pulseaudio in this example):

from i3pystatus import Status

status = Status()

# Displays clock like this:
# Tue 30 Jul 11:59:46 PM KW31
#                          ^-- calendar week
status.register("clock",
    format="%a %-d %b %X KW%V",)

# Shows the average load of the last minute and the last 5 minutes
# (the default value for format is used)
status.register("load")

# Shows your CPU temperature, if you have a Intel CPU
status.register("temp",
    format="{temp:.0f}°C",)

# The battery monitor has many formatting options, see README for details

# This would look like this, when discharging (or charging)
# ↓14.22W 56.15% [77.81%] 2h:41m
# And like this if full:
# =14.22W 100.0% [91.21%]
#
# This would also display a desktop notification (via D-Bus) if the percentage
# goes below 5 percent while discharging. The block will also color RED.
# If you don't have a desktop notification demon yet, take a look at dunst:
#   http://www.knopwob.org/dunst/
status.register("battery",
    format="{status}/{consumption:.2f}W {percentage:.2f}% [{percentage_design:.2f}%] {remaining:%E%hh:%Mm}",
    alert=True,
    alert_percentage=5,
    status={
        "DIS": "↓",
        "CHR": "↑",
        "FULL": "=",
    },)

# This would look like this:
# Discharging 6h:51m
status.register("battery",
    format="{status} {remaining:%E%hh:%Mm}",
    alert=True,
    alert_percentage=5,
    status={
        "DIS":  "Discharging",
        "CHR":  "Charging",
        "FULL": "Bat full",
    },)

# Displays whether a DHCP client is running
status.register("runwatch",
    name="DHCP",
    path="/var/run/dhclient*.pid",)

# Shows the address and up/down state of eth0. If it is up the address is shown in
# green (the default value of color_up) and the CIDR-address is shown
# (i.e. 10.10.10.42/24).
# If it's down just the interface name (eth0) will be displayed in red
# (defaults of format_down and color_down)
#
# Note: the network module requires PyPI package netifaces
status.register("network",
    interface="eth0",
    format_up="{v4cidr}",)

# Note: requires both netifaces and basiciw (for essid and quality)
status.register("network",
    interface="wlan0",
    format_up="{essid} {quality:03.0f}%",)

# Shows disk usage of /
# Format:
# 42/128G [86G]
status.register("disk",
    path="/",
    format="{used}/{total}G [{avail}G]",)

# Shows pulseaudio default sink volume
#
# Note: requires libpulseaudio from PyPI
status.register("pulseaudio",
    format="♪{volume}",)

# Shows mpd status
# Format:
# Cloud connected▶Reroute to Remain
status.register("mpd",
    format="{title}{status}{album}",
    status={
        "pause": "▷",
        "play": "▶",
        "stop": "◾",
    },)

status.run()

Also change your i3wm config to the following:

# i3bar
bar {
    status_command    python ~/.path/to/your/config/file.py
    position          top
    workspace_buttons yes
}

Note

Don’t name your config file i3pystatus.py, as it would make i3pystatus un-importable and lead to errors.

Another way to launch your configuration file is to use i3pystatus script from installation:

i3pystatus -c ~/.path/to/your/config/file.py

If no arguments were provided, i3pystatus script works as an example of Clock module.

Formatting

All modules let you specifiy the exact output formatting using a format string, which gives you a great deal of flexibility.

If a module gives you a float, it probably has a ton of uninteresting decimal places. Use {somefloat:.0f} to get the integer value, {somefloat:0.2f} gives you two decimal places after the decimal dot

formatp

Some modules use an extended format string syntax (the mpd and weather modules, for example). Given the format string below the output adapts itself to the available data.

[{artist}/{album}/]{title}{status}

Only if both the artist and album is known they’re displayed. If only one or none of them is known the entire group between the brackets is excluded.

“is known” is here defined as “value evaluating to True in Python”, i.e. an empty string or 0 (or 0.0) counts as “not known”.

Inside a group always all format specifiers must evaluate to true (logical and).

You can nest groups. The inner group will only become part of the output if both the outer group and the inner group are eligible for output.

TimeWrapper

Some modules that output times use TimeWrapper to format these. TimeWrapper is a mere extension of the standard formatting method.

The time format that should be used is specified using the format specifier, i.e. with some_time being 3951 seconds a format string like {some_time:%h:%m:%s} would produce 1:5:51.

  • %h, %m and %s are the hours, minutes and seconds without leading zeros (i.e. 0 to 59 for minutes and seconds)
  • %H, %M and %S are padded with a leading zero to two digits, i.e. 00 to 59
  • %l and %L produce hours non-padded and padded but only if hours is not zero. If the hours are zero it produces an empty string.
  • %% produces a literal %
  • %E (only valid on beginning of the string) if the time is null, don’t format anything but rather produce an empty string. If the time is non-null it is removed from the string.
  • When the module in question also uses formatp, 0 seconds counts as “not known”.
  • The formatted time is stripped, i.e. spaces on both ends of the result are removed.

Logging

Errors do happen and to ease debugging i3pystatus includes a logging facility. By default i3pystatus will log exceptions raised by modules to files in your home directory named .i3pystatus-<pid-of-thread>. Some modules might log additional information.

Setting a specific logfile

When instantiating your Status object, the path to a log file can be specified (it accepts environment variables). If this is done, then log messages will be sent to that file and not to an .i3pystatus-<pid-of-thread> file in your home directory. This is useful in that it helps keep your home directory from becoming cluttered with files containing errors.

from i3pystatus import Status

status = Status(logfile='$HOME/var/i3pystatus.log')

Changing log format

New in version 3.35.

The logformat option can be useed to change the format of the log files, using LogRecord attributes.

from i3pystatus import Status

status = Status(
    logfile='/home/username/var/i3pystatus.log',
    logformat='%(asctime)s %(levelname)s:',
)

Log level

Every module has a log_level option which sets the minimum severity required for an event to be logged.

The numeric values of logging levels are given in the following table.

Level Numeric value
CRITICAL 50
ERROR 40
WARNING 30
INFO 20
DEBUG 10
NOTSET 0

Exceptions raised by modules are of severity ERROR by default. The default log_level in i3pystatus (some modules might redefine the default, see the reference of the module in question) is 30 (WARNING).

Callbacks

Callbacks are used for click-events (merged into i3bar since i3 4.6, mouse wheel events are merged since 4.8), that is, you click (or scroll) on the output of a module in your i3bar and something happens. What happens is defined by these settings for each module individually:

  • on_leftclick
  • on_rightclick
  • on_upscroll
  • on_downscroll

The global default action for all settings is None (do nothing), but many modules define other defaults, which are documented in the module reference.

The values you can assign to these four settings can be divided to following three categories:

Member callbacks

These callbacks are part of the module itself and usually do some simple module related tasks (like changing volume when scrolling, etc.). All available callbacks are (most likely not) documented in their respective module documentation.

For example the module ALSA has callbacks named switch_mute, increase_volume and decrease volume. They are already assigned by default but you can change them to your liking when registering the module.

status.register("alsa",
    on_leftclick = ["switch_mute"],
    # or as a strings without the list
    on_upscroll = "decrease_volume",
    on_downscroll = "increase_volume",
    # this will refresh any module by clicking on it
    on_rightclick = "run",
    )

Some callbacks also have additional parameters. Both increase_volume and decrease_volume have an optional parameter delta which determines the amount of percent to add/subtract from the current volume.

status.register("alsa",
    # all additional items in the list are sent to the callback as arguments
    on_upscroll = ["decrease_volume", 2],
    on_downscroll = ["increase_volume", 2],
    )

Python callbacks

These refer to to any callable Python object (most likely a function). To external Python callbacks that are not part of the module the self parameter is not passed by default. This allows to use many library functions with no additional wrapper.

If self is needed to access the calling module, the get_module() decorator can be used on the callback:

from i3pystatus import get_module

# Note that the 'self' parameter is required and gives access to all
# variables of the module.
@get_module
def change_text(self):
    self.output["full_text"] = "Clicked"

status.register("text",
    text = "Initial text",
    on_leftclick = [change_text],
    # or
    on_rightclick = change_text,
    )

You can also create callbacks with parameters.

from i3pystatus import get_module

@get_module
def change_text(self, text="Hello world!", color="#ffffff"):
    self.output["full_text"] = text
    self.output["color"] = color

status.register("text",
    text = "Initial text",
    color = "#00ff00",
    on_leftclick = [change_text, "Clicked LMB", "#ff0000"],
    on_rightclick = [change_text, "Clicked RMB"],
    on_upscroll = change_text,
    )

External program callbacks

You can also use callbacks to execute external programs. Any string that does not match any member callback is treated as an external command. If you want to do anything more complex than executing a program with a few arguments, consider creating an python callback or execute a script instead.

status.register("text",
    text = "Launcher?",
    # open terminal window running htop
    on_leftclick = "i3-sensible-terminal -e htop",
    # open i3pystatus github page in firefox
    on_rightclick = "firefox --new-window https://github.com/enkore/i3pystatus",
    )

Most modules provide all the formatter data to program callbacks. The snippet below demonstrates how this could be used, in this case XMessage will display a dialog box showing verbose information about the network interface:

status.register("network",
    interface="eth0",
    on_leftclick="ip addr show dev {interface} | xmessage -file -"
    )

Hints

Hints are additional parameters used to customize output of a module. They give you access to all attributes supported by i3bar protocol.

Hints are available as the hints setting in all modules and its value should be a dictionary or None. An attribute defined in hints will be applied only if the module output does not contain attribute with the same name already.

Some possible uses for these attributes are:

  • min_width and align can be used to set minimal width of output and align the text if its width is shorter than minimal_width.
  • separator and separator_block_width can be used to remove the vertical bar that is separating modules.
  • markup can be set to “none” or “pango”. Pango markup provides additional formatting options for drawing rainbows and other fancy stuff.

Note

Pango markup requires that i3bar is configured to use Pango, too. It can’t work with X core fonts.

Here is an example with the network module. Pango markup is used to keep the ESSID green at all times while the recieved/sent part is changing color depending on the amount of traffic.

status.register("network",
    interface = "wlp2s0",
    hints = {"markup": "pango"},
    format_up = "<span color=\"#00FF00\">{essid}</span> {bytes_recv:6.1f}KiB {bytes_sent:5.1f}KiB",
    format_down = "",
    dynamic_color = True,
    start_color = "#00FF00",
    end_color = "#FF0000",
    color_down = "#FF0000",
    upper_limit = 800.0,
    )

Or you can use pango to customize the color of status setting in now_playing and mpd modules.

...
hints = {"markup": "pango"},
status = {
    "play": "▶",
    "pause": "<span color=\"orange\">▶</span>",
    "stop": "<span color=\"red\">◾</span>",
},
...

Or make two modules look like one.

status.register("text",
    text = "shmentarianism is a pretty long word.")
status.register("text",
    hints = {"separator": False, "separator_block_width": 0},
    text = "Antidisestabli",
    color="#FF0000")

Refreshing the bar

The whole bar can be refreshed by sending SIGUSR1 signal to i3pystatus process. This feature is not available in chained mode (Status was created with standalone=False parameter and gets it’s input from i3status or a similar program).

To find the PID of the i3pystatus process look for the status_command you use in your i3 config file. If your bar section of i3 config looks like this

bar {
    status_command python ~/.config/i3/pystatus.py
}

then you can refresh the bar by using the following command:

pkill -SIGUSR1 -f "python /home/user/.config/i3/pystatus.py"

Note that the path must be expanded if using ‘~’.

Internet Connectivity

Module methods that @require(internet) won’t be run unless a test TCP connection is successful. By default, this is made to Google’s DNS server, but you can customize the host and port. See internet.

If you are behind a gateway that redirects web traffic to an authorization page and blocks other traffic, the DNS check will return a false positive. This is often encountered in open WiFi networks. In these cases it is helpful to try a service that is not traditionally required for web browsing:

from i3pystatus import Status

status = Status(check_internet=("whois.arin.net", 43))
from i3pystatus import Status

status = Status(check_internet=("github.com", 22))

Credentials

For modules which require credentials, i3pystatus supports credential management using the keyring module from PyPI.

Important

Many distributions have keyring pre-packaged, available as python-keyring. Unless you have KWallet or SecretService available, you will also most likely need to install keyrings.alt, which contains additional keyring backends for use by the keyring module.

Both i3pystatus and i3pystatus-setting-util will abort with a RuntimeError if keyring isinstalled but a usable keyring backend is not present, so it is a good idea to install both if you plan to use a module which supports credential handling.

To store credentials in a keyring, use the i3pystatus-setting-util script installed along i3pystatus.

Note

i3pystatus-setting-util will store credentials using the default keyring backend. The method for determining which backend is the default can be found below. If, for some reason, it is necessary to use a keyring other than the default, then you will need to override the default in your keyringrc.cfg for i3pystatus-setting-util to successfully use it.

Once you have successfully set up credentials, you can add the module to your config file without specifying the credentials in the registration, e.g.:

# Use the default keyring to retrieve credentials
status.register('github')

i3pystatus will locate and set the credentials during the module loading process. Currently supported credentials are password, email and username.

Note

To determine which backend is the default on your system, run the following:

python -c 'import keyring; print(keyring.get_keyring())'

If this command returns a keyring.backends.fail.Keyring object, none of the keyrings supported out-of-the box by the keyring module are available, and you will need to install the keyrings.alt Python module. keyrings.alt provides an encrypted keyring which will be seen as the default if both keyrings.alt and keyring are installed, and none of the keyrings supported by keyring are present:

$ python -c 'import keyring; print(keyring.get_keyring())'
<EncryptedKeyring at /home/username/.local/share/python_keyring/crypted_pass.cfg>

If the keyring backend you used to store credentials using i3pystatus-setting-util is not the default, then you can change which keyring backend i3pystatus will use in one of two ways:

  1. Override the default in your keyringrc.cfg

  2. Import and instantiate a keyring backend class, and pass it as the keyring_backend parameter when registering the module:

    # Requires the keyrings.alt package
    from keyrings.alt.file import PlaintextKeyring
    status.register('github', keyring_backend=PlaintextKeyring())