                    Python bzip2 interface 0.02b alpha
                   ====================================

25 April 1999  Copyright Laurence Tratt 1999



 Introduction
==============

After a request on comp.lang.python for a module such as this (I hope :)),
here's a quick Python interface to Julian Seward's bzlib2 compression
system.

This isn't complete, and it isn't fully tested, but I'm releasing it to see
whether there is sufficient interest for me - or someone else - to develop
a more fully featured version. When/if such a version appears, I will
announce it on comp.lang.python and/or comp.lang.python.announce.

To find out more about bzip2, have a look at the bzip2 homepage:

  http://www.muraroa.demon.co.uk/



 Licence
=========

The licence for this interface is included in the 'Licence' file. By using
this software, you are bound to the enclosed licence.



 Contacting
============

I can be contacted via e-mail at:

  tratt@dcs.kcl.ac.uk



 Requirements
==============

I developed this interface with the latest version of bzip2: 0.9.0c
available from http://www.muraroa.demon.co.uk/. You may or may not have
success with previous versions (which come as standard on some modern Linux
systems); if you have troubles, upgrade to the latest version. If it works
with old versions of bzip2, please let me know!



 Installing
============

I developed this module under Linux using a stock Python 1.5.2 install; the
instructions should be the same for any modern Unix platform.

You will need a recent version of the bzip2 library which must be installed as
per the instructions in the README file that come with that library. To
summarise:

  * you need to decompress the tar file, and cd into it
  * execute 'make'
  * copy libbz2.a and bzlib.h to /usr/lib and /usr/include respectively
      [nb I reccomend copying the files to /usr/local/lib and /usr/local/include
            respectively to avoid confusing any package management systems you
            may use]

When you've done that, you then follow the standard instructions for the
"Universal Unix Makefile for Python extensions". To summarise:

  * make -f Makefile.pre.in boot
  * make
  * If you want the bzlib module available to all Python users
      type 'make install'


 Testing
=========

There are two simple test scripts, 'pybzip2' & 'pybunzip2'. They are
invoked thus:

  pyb[un]zip2 <in file> <out file>

The bzip2 files they take in and give out should be entirely compatible
with the standard bzip2 program: feel free to try this out!



 The module
============

The 'bzlib' module has two commands: 'compress' & 'decompress':

   compress(<string>, <compression level>) --> <string>
   decompress(<string>, [<small>]) --> <string>

<compression level> must be an integer between 0 and 9 inclusive; <small>
is an optional boolean argument which forces the bzip2 library to use less
memory when decompressing.

They can both throw the error 'bzlib.error'.



 To do
=======

Testing. I haven't tried out any of the error conditions yet :)

A buffering input/output system to cope with low memory (compared to the
size of the file being compressed) limits (such as in zlib).