unpyc -- A Python byte-code decompiler
                          1.0
                          2009-02-15

Introduction
------------

'unpyc' converts Python byte-code back into equivalent Python
source. It accepts byte-code from any Python version starting with 1.5
up to 2.3.

The generated source is very readable: docstrings, lists, tuples and
hashes get pretty-printed.

'unpyc' may also verify the equivalence of the generated source by
by compiling it and comparing both byte-codes.

'unpyc' is based on John Aycock's generic small languages compiler
'spark' (http://www.csr.uvic.ca/~aycock/python/) and his prior work on
'unpyc'.

Additional note (3 July 2004, Ben Burton):

    The original website from which this software was obtained is no longer
    available.  It has now become a commercial decompilation service, with
    no software available for download.

    Any developers seeking to make alterations or enhancements to this code
    should therefore consider these debian packages an appropriate starting
    point.

Features
--------

  * decompiles Python byte-code into equivalent Python source

  * decompiles byte-code from Python versions 1.5 up to 2.3

  * pretty-prints docstrings, hashes, lists and tuples
  
  * supports an option for verifing the generated Python source is
    equivalent to the byte-code. This is done by compiling the
    generated source and comparing both byte-codes.

  * decompiles and successfully verifies 100% of the Python 1.5, 2.0,
    2.1 and 2.2 library

  * decompiles and successfully verifies 100% of the Python 1.5
    library, including lib-stdwin, lib-tk, gnome and gtk.

  * reads directly from .pyc/.pyo files, bulk-decompile whole
    directories

  * output may be written to file, a directory or to stdout

  * option for including byte-code disassembly into generated source

  * If translation fails, the part causing the problem is output. This
    helps improofing 'decompile'. If this happens to you, please
    contact the author.

  For a list of changes please refer to the 'CHANGES' file.


Requirements
------------

'decompile' requires Python 2.2 or later.


Installation
------------

You may either create a RPM and install this, or install directly from
the source distribution.

Creating RPMS:

  python setup.py bdist_rpm

  If you need to force the python interpreter to eg. pyton2:
     python2 setup.py bdist_rpm --python=python2


Installation from the source distribution:

     python setup.py install

   To install to a user's home-dir:
     python setup.py install --home=<dir>

   To install to another prefix (eg. /usr/local)
     python setup.py install --prefix=/usr/local

  If you need to force the python interpreter to eg. pyton2:
     python2 setup.py install

  For more information on 'Installing Python Modules' please refer to
     http://www.python.org/doc/current/inst/inst.html


Usage
-----

unpyc -h		prints short usage
unpyc --help	prints long usage


Known Bugs/Restrictions
-----------------------

* EXTENDED_ARG token is untested (this is a new token for Python 2.0
  which is used only if many items exist within a code object).

* Verifying decompiled source with optizimzed byte code (.pyo) when
  running without optimizations (option '-O' not given) fails in most
  cases. Same is true for vis-a-versa. This is due to the fact that
  Python generated different bytecode depending on option '-O'.


* Python 2.2 generated different byte-code than prior version for the
  same source. This is due the intruduction of iterators. Currently
  'unpyc' fails verifying this source if the byte-code was
  generated by an older version of Python.