# DzenStatus

DzenStatus is a configurable python script meant to drive a statusbar program like dzen, for use with window-managers like xmonad or ratpoison. It is still in early development, so your mileage may vary. (Do email me with bugs or, preferrably, patches if you find breakage.)

Additional documentation will be added to the wiki as it is produced.

## ChangeLog

Version 0.1.4
• Fix packaging. Should now actually be installable with easy_install or pip.
Version 0.1.3
• Make simple changes to run on python3 and python2.6 or higher.
• Added a simple mpd plugin, requires python-mpd to work. (No dependency has been added, you can safely ignore the plugin entirely without any ill effects, but python-mpd is required to use the plugin.)
Version 0.1.2
• Fix hardcoded battery and AC adaptor names in the battery plugin.
Version 0.1.1
• Fixed an issue with trying to be too smart with encodings.
Version 0.1.0
• Initial release.

## Installing

Installing DzenStatus should be a simple matter of using pip (or easy_install if you must):

pip install DzenStatus


If you don't want, or can't, install using easy_install then, assuming you have setuptools installed (which is required for DzenStatus to run, or at least pkg_resources), you can download the egg-file, mark it executable (or eggsecutable, as it were), and run it directly. This is not recommended. Source distributions are also provided. (python setup.py install)

Note

Setuptools is required for DzenStatus to work, in particular, it uses the pkg_resources entry point tools to discover and load plugins. There are no other requirements (other than a python installation). This requirement is fulfilled by the Setuptools fork, Distribute.

After installing with easy_install you should have two new commands in your path, dzenstatus and dzenstatus_pipe. The dzenstatus command runs the configured statusbar program (from the configuration file), typically dzen and directly pipes it's output to the standard in of that process.

dzenstatus_pipe is available for those who would rather pipe the output of dzenstatus to its destination manually (helpful if you want to integrate DzenStatus into an existing statusbar script).

## Configuration

DzenStatus is configured by a single configuration file located in ~/.dzenstatus/config.ini. The configuration file uses the standard python ConfigParser format. An example configuration file is available in the distribution.

Full documentation for each plugin is provided in the source code as docstrings.

## Running DzenStatus

Once you have a configuration you like, you can add it to your .xinitrc or .xsession file in several different ways:

dzenstatus&


This is the simplest way, just invoking DzenStatus, letting it take care of all the statubar startup and not using a plugin that reads from standard input. If you have a window manager that writes useful information to standard output you may wish to capture it like so (assuming you have a suitable DzenStatus plugin configured to read standard input):

/path/to/my/wm | dzenstatus


If you wish to have DzenStatus write it's output directly to standard output, instead of spawning the statusbar program itself, you would use something like:

/path/to/my/wm | dzenstatus_pipe | /path/to/my/statusbar_sink


It is also possible to use a FIFO (named pipe) to allow you to restart DzenStatus without restarting the window manager yet keeping the ability to read the output.

mkfifo .status_fifo
cat .status_fifo | dzenstatus&
/path/to/my/wm > .status_fifo


mkfifo .status_fifo
dzenstatus&
/path/to/my/wm > .status_fifo


## Writing DzenStatus Plugins

DzenStatus uses pkg_resources to load plugins, so writing a plugin doesn't require you to patch or modify the base DzenStatus installation at all.

### Plugin Structure

A plugin will be found by DzenStatus if it declares an entry point for dzenstatus.plugins.v1 (where the v1 is the version number of the plugin interface). The entry point must be a callable that takes a dictionary mapping strings to strings of configuration data, and returning a tuple of three elements:

• The configured name of the instance of the plugin (passed in as config['name']).
• The update predicate of the plugin instance. This must be a callable taking two arguments, the current seconds since the epoch, and the last time (in seconds since the epoch) an update was checked for.
• The update function this is a callable that takes no arguments and returns a string that will be included for this instance of the plugin in the output. It should not contain newlines.

### Example

As an example, let's reimplement the static plugin that is already included with DzensStatus.

First, since DzenStatus uses entry points, we need a setup.py file:

#!/usr/bin/env python

from setuptools import setup

setup(
name = "ExampleDzenStatusPlugin",

version = "0.0 example",
packages = find_packages(),

entry_points = {
'dzenstatus.plugins.v1' : [
'example_static = example_dzenstatus:example_plugin_static',
],
},

description = "A minimal example plugin for DzenStatus",
)


The key thing to note is how to declare the entry point for the plugin. All the other parts are standard setuptools that you should already be familiar with.

Now the implementation of our plugin:

# example_dzenstatus.py
'''
An example DzenStatus plugin.
'''
from dzenstatus import UPDATE_ONCE

def example_plugin_static(config):
'''
A simple plugin that returns static text.

text is the only required config parameter.
'''
return (config['name'], UPDATE_ONCE(), lambda: config['text'])


Now, you can install the plugin using easy_install or by running the setup.py file.

\$ python setup.py develop


Now, you can place a section into your DzenStatus config file that looks like:

[example_static_inst]
plugin=example_static
text=I'm an example!


If you run DzenStatus you will now see that the plugin is loaded and the text is output.

The simplest way to distribute your plugin is via an egg that is placed in the plugins directory configured by the config file. This requires no additional installation and makes the installation as easy as copying a file.

See the code of DzenStatus for more examples (especially for how to deal with file descriptors and polling for available input).