search

Schnouki / bccc

buddycloud console client
9 stars 4 forks source link

readme

bccc

Welcome to bccc, the buddycloud console client.

Screenshot

They say it's worth a thousand words, so here it is.

Screenshot

There's even a screencast on YouTube.

Installation

bccc is written in Python 3, and is known to work with Python 3.1 and 3.2. It probably won't work with previous versions of Python 3, and it definitely won't work with Python 2.

bccc uses the following libraries:

You can install them using pip3 (python-pip package in Arch Linux) or easy_install3 (python3-setuptools package in Debian/Ubuntu):

# Global installation (in /usr or /usr/local):
sudo pip3 install urwid sleekxmpp python-dateutil dnspython3 pyasn1{,-modules}
# or
sudo easy_install3 urwid sleekxmpp python-dateutil dnspython3 pyasn1{,-modules}

# User installation (in $HOME):
pip3 install --user urwid sleekxmpp python-dateutil dnspython3 pyasn1{,-modules}
# or
sudo easy_install3 --user urwid sleekxmpp python-dateutil dnspython3 pyasn1{,-modules}

(If you're using Debian/Ubuntu, you will need to install python3-dev and gcc first.)

If you use Arch Linux, you're awesome! And if you have installed yaourt (or any other AUR helper), you can install all of these with the following command:

yaourt -S python-{urwid,sleekxmpp-git,dateutil,dnspython,pyasn1,pyasn1-modules}

After doing all of this, you can install bccc from its Git repository:

git clone git://github.com/Schnouki/bccc.git
cd bccc
python3 setup.py build

# Global installation (in /usr or /usr/local):
sudo python3 setup.py install
# User installation (in $HOME):
python3 setup.py install --user

If you want to hack on bccc, you should install it with develop. It will be installed globally, but will still use the files in your Git checkout, making it easier to test your changes:

# Global "develop" installation (in /usr or /usr/local):
sudo python3 setup.py develop
# User "develop" installation (in $HOME):
python3 setup.py develop --user

If you installed bccc with --user, you must add $HOME/.local/bin to your $PATH.

You should now be able to run bccc by just typing bccc in a terminal emulator. If it complain about a missing configuration file, congratulations, your installation probably works :)

Uninstall

If you don't like bccc, you can uninstall it with pip3:

pip3 uninstall bccc

There may be some leftover files after that if you did a --user or develop install: $HOME/.local/bin/bccc and /usr/bin/bccc. You will have to remove them by hand.

At the moment easy_install does not seem to be capable of uninstalling modules. So if pip3 is not available on your platform (and can't be installed with easy_install3 pip), you will have to uninstall bccc by hand. On my computer I can do it with these commands (as root):

rm /usr/lib/python3.2/site-packages/bccc*
rm /usr/bin/bccc
nano /usr/lib/python3.2/site-packages/easy-install.pth
# remove bccc lines in easy-install.pth

You will probably have to adapt them on your system, for example by using /usr/local instead of /usr.

Troubleshooting

When using easy_install3 or some old versions of setuptools or distribute, bccc won't run but will fail with the following message:

Traceback (most recent call last):
  File "/usr/local/bin/bccc", line 7, in <module>
    execfile(__file__)
NameError: name 'execfile' is not defined

This is due to these versions of setuptools/distribute not being correctly updated for Python 3, where the execfile function is no longer available.

To fix it, edit your /usr/local/bin/bccc file and replace the execfile(__file__) line with the following one:

exec(compile(open(__file__).read(), __file__, 'exec'))

Configuration

Before being able to use bccc, you will need to write a configuration file. The easiest way to do so is actually to run bccc: if no configuration file is found, it will ask for your credentials and create a configuration file using the default one.

If you want to write the configuration file by hand, a good sample is available in the Git repository, in bccc/bccc.conf.sample. You should copy it to ~/.config/bccc/bccc.conf, make sure it is only readable by you (chmod 600 ~/.config/bccc/bccc.conf), and edit it to adjust your login and password.

This configuration file also contains the name of the theme used to render the UI. Two sample themes are bundled with bccc: "dark" for terminals with a dark background, and "light" for terminals with a light backgrounds. You can of course write your own theme; feel free to share it here if you write a nice one!

Basic usage

Posts and replies in the active channel are grouped by thread: first the post, then its replies in chronological order. Most recently updated threads are listed first.

When new content is posted to the active channel, the corresponding thread will be moved to the top, and the view will scroll so that you can see it. If it can't scroll enough without hiding the currently focused item, a message will be displayed in the status bar instead.

When new content is posted to an inactive channel, the channel will be moved to the top of the sidebar and the number of unread items will be displayed next to the channel name.

TODO

Patches welcome! :)

Hacking

bccc is free software, available under the terms of the Apache License, version 2.0. You are encouraged to redistribute and modify it as you need. If you wish to contribute to it (by reporting bugs, writing doc or submitting patches), the easiest way is to use the GitHub page.

Contact

If you need help setting up, using or hacking bccc, feel free to contact me: