[catapult] - Copy Telemetry's gsutilz over to third_party.

third_party/gsutil/third_party/crcmod/docs/source/intro.rst

+
+============
+Introduction
+============
+
+The software in this package is a Python module for generating objects that
+compute the Cyclic Redundancy Check (CRC).  It includes a (optional) C
+extension for fast calculation, as well as a pure Python implementation.
+
+There is no attempt in this package to explain how the CRC works.  There are a
+number of resources on the web that give a good explanation of the algorithms.
+Just do a Google search for "crc calculation" and browse till you find what you
+need.  Another resource can be found in chapter 20 of the book "Numerical
+Recipes in C" by Press et. al.
+
+This package allows the use of any 8, 16, 24, 32, or 64 bit CRC.  You can
+generate a Python function for the selected polynomial or an instance of the
+:class:`crcmod.Crc` class which provides the same interface as the
+:mod:`hashlib`, :mod:`md5` and :mod:`sha` modules from the Python standard
+library.  A :class:`crcmod.Crc` class instance can also generate C/C++ source
+code that can be used in another application.
+
+----------
+Guidelines
+----------
+
+Documentation is available here as well as from the doc strings.
+
+It is up to you to decide what polynomials to use in your application.  Some
+common CRC algorithms are predefined in :mod:`crcmod.predefined`.  If someone
+has not specified the polynomials to use, you will need to do some research to
+find one suitable for your application.  Examples are available in the unit
+test script :file:`test.py`.
+
+If you need to generate code for another language, I suggest you subclass the
+:class:`crcmod.Crc` class and replace the method
+:meth:`crcmod.Crc.generateCode`.  Use :meth:`crcmod.Crc.generateCode` as a
+model for the new version.
+
+------------
+Dependencies
+------------
+
+Python Version
+^^^^^^^^^^^^^^
+
+The package has separate code to support the 2.x and 3.x Python series.
+
+For the 2.x versions of Python, these versions have been tested:
+
+* 2.4
+* 2.5
+* 2.6
+* 2.7
+
+It may still work on earlier versions of Python 2.x, but these have not been
+recently tested.
+
+For the 3.x versions of Python, these versions have been tested:
+
+* 3.1
+
+Building C extension
+^^^^^^^^^^^^^^^^^^^^
+
+To build the C extension, the appropriate compiler tools for your platform must
+be installed. Refer to the Python documentation for building C extensions for
+details.
+
+------------
+Installation
+------------
+
+The :mod:`crcmod` package is installed using :mod:`distutils`.
+Run the following command::
+
+   python setup.py install
+
+If the extension module builds, it will be installed.  Otherwise, the
+installation will include the pure Python version.  This will run significantly
+slower than the extension module but will allow the package to be used.
+
+For Windows users who want to use the mingw32 compiler, run this command::
+
+    python setup.py build --compiler=mingw32 install
+
+For Python 3.x, the install process is the same but you need to use the 3.x
+interpreter.
+
+------------
+Unit Testing
+------------
+
+The :mod:`crcmod` package has a module :mod:`crcmod.test`, which contains
+unit tests for both :mod:`crcmod` and :mod:`crcmod.predefined`.
+
+When you first install :mod:`crcmod`, you should run the unit tests to make
+sure everything is installed properly.  The test script performs a number of
+tests including a comparison to the direct method which uses a class
+implementing polynomials over the integers mod 2.
+
+To run the unit tests on Python >=2.5::
+
+    python -m crcmod.test
+
+Alternatively, in the :file:`test` directory run::
+
+    python test_crcmod.py
+
+---------------
+Code Generation
+---------------
+
+The :mod:`crcmod` package is capable of generating C functions that can be
+compiled with a C or C++ compiler.  In the :file:`test` directory, there is an
+:file:`examples.py` script that demonstrates how to use the code generator.
+The result of this is written out to the file :file:`examples.c`.  The
+generated code was checked to make sure it compiles with the GCC compiler.
+
+-------
+License
+-------
+
+The :mod:`crcmod` package is released under the MIT license.  See the
+:file:`LICENSE` file for details.
+
+----------
+References
+----------
+
+.. seealso::
+
+   :func:`binascii.crc32` function from the :mod:`binascii` module
+      CRC-32 implementation
+   
+   :func:`zlib.crc32` function from the :mod:`zlib` module
+      CRC-32 implementation
+
+   Module :mod:`hashlib`
+      Secure hash and message digest algorithms.
+
+   Module :mod:`md5`
+      RSA's MD5 message digest algorithm.
+
+   Module :mod:`sha`
+      NIST's secure hash algorithm, SHA.
+
+   Module :mod:`hmac`
+      Keyed-hashing for message authentication.