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.)

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).

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.

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.

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.

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).