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