
$Id: README,v 1.2 2004/02/18 23:05:05 cvs Exp $

Description:
-----------
This a fairly simple module, it provide only raw yEnc encoding/decoding with
builitin crc32 calculation.
Header parsing, checkings and yenc formatting are left to you (see examples 
directory for possible implementations). The interface was originally intended 
to be similar to the uu module from Python standard library.
Version 0.2 changed a bit the previous (0.1)  behaviour, but it should be
more usable and flexible (now you can encode/decode from and to standard
input and output and use filenames instead of file objects as arguments
for encode() and decode() ). See CHANGES file for details.
Version 0.3 doesn't introduce anything new, just a bugfix a some internals
changes.


Requirements:
------------
A C developement environment, Python>=2.1 and python developement libs (look for 
python-dev or something like that if you're using .rpm or .deb packages, if you 
installed from sources you already have everything you need).
The module is known to work with Python2.1 and 2.2, maybe it will work also
with 1.5.2 (as long as you have distutils I think).


Installation:
------------
To install:
tar xzfv yenc-0.3.tar.gz
cd yenc-0.3
python setup.py build
su
python setup.py install

To uninstall:
Simply remove _yenc.so, yenc.py and yenc.pyc from your PYTHONPATH.
On my Debian GNU/Linux 3.0:
/usr/local/lib/python2.2/site-packages/{_yenc.so,yenc.py,yenc.pyc} 


Usage:
-----
As usual:

import yenc

in your modules. The 'yenc' module defines 2 functions (encode() and decode())
and an error class, yenc.Error(Exception). 


encode(in_file, out_file, bytes=0):

Accepts both filenames or file objects as arguments, if "in_file" is a file
type object it must be opened for reading ("r","rw"...), if "out_file"  is a
file type object it must be opened for writing ("w","rw"..), when files are 
specified as filenames the files are (if possible) automatically opened in the
correct mode.
The "bytes" argument is an optional numeric value, if set to 0 or omitted it
causes the input file to be read and encoded until EOF, otherwise it specifies
the maximum number of bytes to read and encode.
When reading from stdin "bytes" argument can't be 0 (or omitted).

If arguments don't match such criteria an exception is raised. encode() reads 
data from "in_file" and writes the encoded data on "out_file", it returns a 
tuple containing the number of encoded bytes and a crc32 sum of the original 
data.
Specifing "-" as "in_file" or "out_file" arguments causes the input/output to
be read/written on standard input/output.


decode(in_file, out_file, size=0, crc_in=""):

Same as encode (of course it does the inverse job). Exceptions are raised when
output can't be written or calculated crc doesn't match the optional crc_in 
argument (useful for writing decoding tools).

CRC32 sums are always represented as lowercase strings, whithout any
preceeding simbol ( like '0x').


Performances:
------------
Fast enough.


Author:
------
Alessandro Duca <dual@golug.cc.uniud.it>


Thanks:
------
Michael Muller <mmuller@endunden.com> for code reviewing and fixing.


Greets, Sandro.

