1 2============ 3Introduction 4============ 5 6The software in this package is a Python module for generating objects that 7compute the Cyclic Redundancy Check (CRC). It includes a (optional) C 8extension for fast calculation, as well as a pure Python implementation. 9 10There is no attempt in this package to explain how the CRC works. There are a 11number of resources on the web that give a good explanation of the algorithms. 12Just do a Google search for "crc calculation" and browse till you find what you 13need. Another resource can be found in chapter 20 of the book "Numerical 14Recipes in C" by Press et. al. 15 16This package allows the use of any 8, 16, 24, 32, or 64 bit CRC. You can 17generate a Python function for the selected polynomial or an instance of the 18:class:`crcmod.Crc` class which provides the same interface as the 19:mod:`hashlib`, :mod:`md5` and :mod:`sha` modules from the Python standard 20library. A :class:`crcmod.Crc` class instance can also generate C/C++ source 21code that can be used in another application. 22 23---------- 24Guidelines 25---------- 26 27Documentation is available here as well as from the doc strings. 28 29It is up to you to decide what polynomials to use in your application. Some 30common CRC algorithms are predefined in :mod:`crcmod.predefined`. If someone 31has not specified the polynomials to use, you will need to do some research to 32find one suitable for your application. Examples are available in the unit 33test script :file:`test.py`. 34 35If you need to generate code for another language, I suggest you subclass the 36:class:`crcmod.Crc` class and replace the method 37:meth:`crcmod.Crc.generateCode`. Use :meth:`crcmod.Crc.generateCode` as a 38model for the new version. 39 40------------ 41Dependencies 42------------ 43 44Python Version 45^^^^^^^^^^^^^^ 46 47The package has separate code to support the 2.x and 3.x Python series. 48 49For the 2.x versions of Python, these versions have been tested: 50 51* 2.4 52* 2.5 53* 2.6 54* 2.7 55 56It may still work on earlier versions of Python 2.x, but these have not been 57recently tested. 58 59For the 3.x versions of Python, these versions have been tested: 60 61* 3.1 62 63Building C extension 64^^^^^^^^^^^^^^^^^^^^ 65 66To build the C extension, the appropriate compiler tools for your platform must 67be installed. Refer to the Python documentation for building C extensions for 68details. 69 70------------ 71Installation 72------------ 73 74The :mod:`crcmod` package is installed using :mod:`distutils`. 75Run the following command:: 76 77 python setup.py install 78 79If the extension module builds, it will be installed. Otherwise, the 80installation will include the pure Python version. This will run significantly 81slower than the extension module but will allow the package to be used. 82 83For Windows users who want to use the mingw32 compiler, run this command:: 84 85 python setup.py build --compiler=mingw32 install 86 87For Python 3.x, the install process is the same but you need to use the 3.x 88interpreter. 89 90------------ 91Unit Testing 92------------ 93 94The :mod:`crcmod` package has a module :mod:`crcmod.test`, which contains 95unit tests for both :mod:`crcmod` and :mod:`crcmod.predefined`. 96 97When you first install :mod:`crcmod`, you should run the unit tests to make 98sure everything is installed properly. The test script performs a number of 99tests including a comparison to the direct method which uses a class 100implementing polynomials over the integers mod 2. 101 102To run the unit tests on Python >=2.5:: 103 104 python -m crcmod.test 105 106Alternatively, in the :file:`test` directory run:: 107 108 python test_crcmod.py 109 110--------------- 111Code Generation 112--------------- 113 114The :mod:`crcmod` package is capable of generating C functions that can be 115compiled with a C or C++ compiler. In the :file:`test` directory, there is an 116:file:`examples.py` script that demonstrates how to use the code generator. 117The result of this is written out to the file :file:`examples.c`. The 118generated code was checked to make sure it compiles with the GCC compiler. 119 120------- 121License 122------- 123 124The :mod:`crcmod` package is released under the MIT license. See the 125:file:`LICENSE` file for details. 126 127---------- 128References 129---------- 130 131.. seealso:: 132 133 :func:`binascii.crc32` function from the :mod:`binascii` module 134 CRC-32 implementation 135 136 :func:`zlib.crc32` function from the :mod:`zlib` module 137 CRC-32 implementation 138 139 Module :mod:`hashlib` 140 Secure hash and message digest algorithms. 141 142 Module :mod:`md5` 143 RSA's MD5 message digest algorithm. 144 145 Module :mod:`sha` 146 NIST's secure hash algorithm, SHA. 147 148 Module :mod:`hmac` 149 Keyed-hashing for message authentication. 150