PyBiff is an email notification utility for the system tray, periodically checking email accounts for new messages. The current status is indicated by the icon in the tray, and a custom command can be executed when new mail arrives. Another custom action can be performed by clicking the icon.

PyBiff is implemented in Python 3 using PyQt6. It supports POP3 and IMAP4 protocols with or without SSL. Besides showing an icon it provides status details in a tooltip, a control menu, and a convenient configuration dialog.

PyBiff has been inspired by KBiff and provides the original icons from that package as default icon set. It is licensed under GPLv2.

The project is hosted at pybiff.sourceforge.net.

Installation

So far PyBiff has been tested only on Linux running the LXQt desktop environment.

Read the warnings below first before configuring and using it.

The installation provides an executable file biff.py, which contains everything necessary to run PyBiff, except the external dependencies listed below. Additionally a desktop and an icon file are installed for convenience and proper desktop environment integration.

The installation prefix defaults to /usr/local. The executable is installed as <prefix>/bin/biff.py, and the other files in the appropriate subdirectories according to the Freedesktop.org specification. For proper function you should make sure that you choose a prefix which matches one of the common application locations on your system (usally /usr, /usr/local, or ~/.local), and <prefix>/bin is in your PATH environment variable.

To clean up all remains after uninstalling PyBiff, delete the configuration file ~/.config/pybiffrc, and the directory ~/.local/share/PyBiff/ if it exists.

Dependencies

You need to have installed reasonably recent versions of

• Python 3
• PyQt6

If you want to develop or install the project from source you additionally need

• make utility
• zip utility
• Qt 6 development tools (qmake6, lrelease, rcc)
• PyQt6 development tools (pyuic6, pylupdate6)
• pyflakes code checker

For creating a distribution archive you also need

• markdown_py from the Python Markdown package
• LibreOffice

Installing from distribution archive

The archive containing a PyBiff distribution is named PyBiff-<version>.tar.bz2, e. g. PyBiff-1.0.0.tar.bz2. It contains a subdirectory with the files to install, this Readme, and a Makefile with the installation recipes.

1. Unpack the archive in a directory you have write permissions to, e. g. your home directory, and change into the resulting distribution directory:

   $ tar -xf PyBiff-<version>.tar.bz2
   $ cd PyBiff-<version>
   

2. Continue with one of the installation alternatives.

3. After you installed PyBiff into the prefix location, the distribution directory is obsolete, and you can delete it.

Installing from source

Build and installation recipes are provided by a Makefile located in the project's root directory, the same as this Readme.

To just build the executable without installation, simply use

$ make

and check the output for error messages. If the build was successful the executable file can be found in the subdirectory bin/.

You can now continue with one of the installation alternatives.

Installation alternatives

Using the Makefile

To install into the default location, you will probably need superuser privileges:

$ sudo make install

Example for changing the prefix to a path in your home directory, no superuser privileges needed:

$ make prefix=~/.local install

For deinstallation the same additional parts need to be provided to the call as for installation. Example:

$ sudo make uninstall

This will not remove an existing configuration file.

Custom installation

biff.py can be copied or moved to any directory you are able to start programs from; executing it from the original location should do for a first try. It will always use the current user's configuration independent of it's location.

You can place the executable file in any directory that's convenient for you, and also the desktop and icon files in appropriate places where your desktop environment can find them. You may have to edit pybiff.desktop to use absolute paths to the files to make it work.

Usage

If you want PyBiff to be started automatically with your desktop environment, you will need to copy the desktop file into the appropriate autostart folder. Make sure it is started after the system tray is available. Refer to the tools or documentation of your desktop environment how to do this.

Start

On first start, and while you haven't saved a configuration yet, the configuration dialog will be shown additionally to the icon in the tray.

While you haven't added at least one email account, the tray icon will always show the stopped icon

If necessary biff.py can be executed directly from a shell. Additionally to the usual default options there's a switch to open the configuration dialog immediately.

$ biff.py --help
Usage: /usr/local/bin/biff.py [options]
Email notification utility for the system tray.

Options:
  -c, --config   Opens just the configuration dialog.
  -v, --version  Displays version information.
  -h, --help     Displays help on commandline options.
  --help-all     Displays help, including generic Qt options.

Tray icons and tooltips

You can always hover over the tray icon with your mouse pointer to see additional details to the current PyBiff status in a tooltip message.

Left mouse click on the tray icon will execute the "Read mail" command, right mouse click will open the menu.

• No connection

  

  PyBiff was unable to check for new email. The tooltip will provide error details if available. You might need to execute "Check mail" from the menu manually in order to try the next check.

• No mail

  

  PyBiff is active, and no emails have been found at the last check. The tooltip will show the timestamp of the latest check for each configured account.

• New mail

  

  Unseen emails have been found with the latest check. The tooltip will show the number of messages for each configured account, and the timestamp of the last detected change.

• Old mail

  

  Only mails already seen have been found. The tooltip will show the number of messages for each configured account, and the timestamp of the last detected change.

• Stopped

  

  Either no email account has been configured yet, or checks have been stopped manually via the menu.

Menu

Right click on the tray icon to show the PyBiff menu.

• Check for mail

  Check all accounts for new email immediately.

• Read mail

  Execute the command for reading new email. Same as left-clicking on the tray icon.

• Stop

  Stop checking for new email until starting it again. The tray icon will change to stopped and this menu entry to "Start". This status is retained over restarts of the application by a flag file.

• Configuration...

  The configuration dialog is shown.

• About...

  Application information is shown in a separate window.

• Quit

  Exit PyBiff.

Configuration

In the general configuration you can select your own tray icons to be used to show the current PyBiff status. Shell commands to be executed when a new mail has been found in your email account (e. g. play a sound), or when you want to read your email (e. g. start your email client), can be provided and tested.

If you click "Save" and mandatory data is missing (e. g. in an account configuration), a message dialog will open, and saving will be refused.

If you click "Cancel", all unsaved changes will be discarded and the configuration dialog closed.

You need to add at least one account; after clicking the button at the bottom you can select the type.

For each new account you need to provide a name, the host (server) to connect to for checking for new email, and your user credentials. Read the warnings below to learn how your password is stored. You can adapt the check interval from the default 10 minutes. Clicking the button "Remove account" will discard this account configuration.

The configuration is stored in ~/.config/pybiffrc.

Warnings

• Currently your account passwords are stored in the configuration file using symmetric encryption without a master password. Though security measures have been taken to my best knowledge (heavy salting, restrictive permissions for the config file), anyone able to understand the code and figure out the salt could decrypt it if able to read the file.

• You can switch off SSL for POP3 and IMAP4, but this is clearly not recommended (and often not supported anymore by providers anyhow).

FAQ

• Why GPLv2?

  Because I wanted to include the original KBiff icon set. They've once been contributed to a GPLv2 project, and re-licensing wasn't possible after all that time, so PyBiff had to be v2, too.

  With friendly support by Kurt Granroth, the creator of KBiff.

• I can't read the body of the executable. Is it compiled or encrypted?

  No. It's multiple script files zipped into an executable Python package. The default icons and translations are included using the Qt Resource System, and the UI files are generated from their Qt Designer sources. To see the content you can remove the header lines and unzip the remaining archive.