==================
 summer.py Manual
==================
-----------------
A checksum script
-----------------

:author: Marc 'BlackJack' Rintsch
:contact: marc@rintsch.de
:date: $Date: 2005-02-27 12:46:17 +0100 (Sun, 27 Feb 2005) $
:version: 0.0.1
:revision: $Rev: 642 $
:copyright: This document has been placed in the public domain.

.. meta::
   :description: Manual for the summer.py script.
   :keywords: checksum, md5, sha1, Python

.. contents::
.. sectnum::


Name
====

summer.py -- calculates checksums of files.


Synopsis
========
::

  summer.py [path ...]

..  summer.py [-h|--help|--version]
    summer.py [options] [path ...]

If ``-`` or no path is given at the command line the input is read
from `stdin`.


Description
===========

The program calculates checksums of the given file(s).  It uses the
*md5* and the *sha1* algorithms and produces output compatible with
the commands ``md5sum`` and ``sha1sum``.  Those tools can be used to
test the files against the checksums later.

The reason to use ``summer.py`` instead of the two programs mentioned
above is that this program calculates both checksums in one pass,
i.e. the data is just read once.  This makes a noticable difference in
execution time, especially on large files like movies, CD or DVD
images.


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

The script requires Python_ version 2.3 or higher.


.. Commandline Options
   ===================


Examples
========

Calculate the *md5* and *sha1* checksum of an ISO image and store them
into a file::

  ./summer.py image.iso > checksums.txt


Output Format
=============

The output format is the same as the one of the standard ``md5sum``
and ``sha1sum`` programs.  It is a text file with one line per
checksum with the checksum as hexdigest, followed by a single space,
followed by another space if the file was opened as text file or a
``*`` if it was opened in binary mode, followed by the filename.

Example of checksums for a file that was opened in text mode::

  c83e90b70123138ec8de3528eb1aa5ba  image.iso
  bc7c898b034bec1de8cf8fc76185e2432ac360eb  image.iso


History
=======


0.0.1a : 2005-02-27
  Initial alpha release.


ToDo
====

- Add hash algorithms of the `Python Cryptography Toolkit`_ if
  available.
- Option to test checksums instead of just generating them.


Bugs
====

None known yet.  If you find some please send me a mail.


Copyright
=========

Copyright © 2005 Marc 'BlackJack' Rintsch <marc@rintsch.de>

This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.


.. _Python Cryptography Toolkit: http://http://www.amk.ca/python/code/crypto.html
.. _Python: http://www.python.org/


.. bj@s8n:~/data> time { md5sum image.iso; sha1sum image.iso; }
   c83e90b70123138ec8de3528eb1aa5ba  image.iso
   bc7c898b034bec1de8cf8fc76185e2432ac360eb  image.iso

   real    1m8.287s
   user    0m21.922s
   sys     0m7.961s
   bj@s8n:~/data> time summer.py image.iso
   c83e90b70123138ec8de3528eb1aa5ba  image.iso
   bc7c898b034bec1de8cf8fc76185e2432ac360eb  image.iso

   real    0m39.154s
   user    0m25.914s
   sys     0m4.090s
