crcmod – CRC calculation — crcmod v1.7 documentation

### Navigation

- index
- modules |
- next |
- previous |
- crcmod v1.7 documentation »

# `crcmod` – CRC calculation

This module provides a function factory `mkCrcFun()` and a class `Crc` for calculating CRCs of byte strings using common CRC algorithms.

Note

This documentation normally shows Python 2.x usage. Python 3.x usage is very similar, with the main difference that input strings must be explicitly defined as `bytes` type, or an object that supports the buffer protocol. E.g.:

    >>> crc_value = crc_function(b'123456789')

    >>> crc_value = crc_function(bytearray((49, 50, 51, 52, 53, 54, 55, 56, 57)))

## `mkCrcFun()` – CRC function factory

The function factory provides a simple interface for CRC calculation.

`crcmod.` `mkCrcFun`(poly[, initCrc, rev, xorOut])

  Function factory that returns a new function for calculating CRCs using a specified CRC algorithm.

  Parameters: | poly – The generator polynomial to use in calculating the CRC. The value is specified as a Python integer or long integer. The bits in this integer are the coefficients of the polynomial. The only polynomials allowed are those that generate 8, 16, 24, 32, or 64 bit CRCs. initCrc – Initial value used to start the CRC calculation. This initial value should be the initial shift register value, reversed if it uses a reversed algorithm, and then XORed with the final XOR value. That is equivalent to the CRC result the algorithm should return for a zero-length string. Defaults to all bits set because that starting value will take leading zero bytes into account. Starting with zero will ignore all leading zero bytes. rev – A flag that selects a bit reversed algorithm when `True`. Defaults to `True` because the bit reversed algorithms are more efficient. xorOut – Final value to XOR with the calculated CRC value. Used by some CRC algorithms. Defaults to zero.
  Returns: | CRC calculation function
  Return type: | function

  The function that is returned is as follows:

  `.``crc_function`(data[, crc=initCrc])

  Parameters: | data (byte string) – Data for which to calculate the CRC. crc – Initial CRC value.
  Returns: | Calculated CRC value.
  Return type: | integer

### Examples

CRC-32 Example:

    >>> import crcmod

    >>> crc32_func = crcmod.mkCrcFun(0x104c11db7, initCrc=0, xorOut=0xFFFFFFFF)
    >>> hex(crc32_func('123456789'))
    '0xcbf43926L'

The CRC-32 uses a “reversed” algorithm, used for many common CRC algorithms. Less common is the non-reversed algorithm, as used by the 16-bit XMODEM CRC:

    >>> xmodem_crc_func = crcmod.mkCrcFun(0x11021, rev=False, initCrc=0x0000, xorOut=0x0000)
    >>> hex(xmodem_crc_func('123456789'))
    '0x31c3'

The CRC function can be called multiple times. On subsequent calls, pass the CRC value previously calculated as a second parameter:

    >>> crc_value = crc32_func('1234')
    >>> crc_value = crc32_func('56789', crc_value)
    >>> hex(crc_value)
    '0xcbf43926L'

Python 3.x example: Unicode strings are not accepted as input. Byte strings are acceptable. You may calculate a CRC for an object that implements the buffer protocol:

    >>> import crcmod
    >>> crc32_func = crcmod.mkCrcFun(0x104c11db7, initCrc=0, xorOut=0xFFFFFFFF)
    >>> hex(crc32_func('123456789'))
    ...
    TypeError: Unicode-objects must be encoded before calculating a CRC
    >>> hex(crc32_func(b'123456789'))
    '0xcbf43926'
    >>> hex(crc32_func(bytearray((49, 50, 51, 52, 53, 54, 55, 56, 57))))
    '0xcbf43926'

## Class `Crc`

The class provides an interface similar to the Python `hashlib`, `md5` and `sha` modules.

class `crcmod.` `Crc`(poly[, initCrc, rev, xorOut])

  Returns a new `Crc` object for calculating CRCs using a specified CRC algorithm.

  The parameters are the same as those for the factory function `mkCrcFun()`.

  Parameters: | poly – The generator polynomial to use in calculating the CRC. The value is specified as a Python integer or long integer. The bits in this integer are the coefficients of the polynomial. The only polynomials allowed are those that generate 8, 16, 24, 32, or 64 bit CRCs. initCrc – Initial value used to start the CRC calculation. This initial value should be the initial shift register value, reversed if it uses a reversed algorithm, and then XORed with the final XOR value. That is equivalent to the CRC result the algorithm should return for a zero-length string. Defaults to all bits set because that starting value will take leading zero bytes into account. Starting with zero will ignore all leading zero bytes. rev – A flag that selects a bit reversed algorithm when `True`. Defaults to `True` because the bit reversed algorithms are more efficient. xorOut – Final value to XOR with the calculated CRC value. Used by some CRC algorithms. Defaults to zero.

  `Crc` objects contain the following constant values:

  `digest_size`
    The size of the resulting digest in bytes. This depends on the width of the CRC polynomial. E.g. for a 32-bit CRC, `digest_size` will be `4`.
  `crcValue`
    The calculated CRC value, as an integer, for the data that has been input using `update()`. This value is updated after each call to `update()`.

  `Crc` objects support the following methods:

  `new`([arg])
    Create a new instance of the `Crc` class initialized to the same values as the original instance. The CRC value is set to the initial value. If a string is provided in the optional `arg` parameter, it is passed to the `update()` method.
  `copy`()
    Create a new instance of the `Crc` class initialized to the same values as the original instance. The CRC value is copied from the current value. This allows multiple CRC calculations using a common initial string.
  `update`(data)

    Parameter: | data (byte string) – Data for which to calculate the CRC

    Update the calculated CRC value for the specified input data.

  `digest`()
    Return the current CRC value as a string of bytes. The length of this string is specified in the `digest_size` attribute.
  `hexdigest`()
    Return the current CRC value as a string of hex digits. The length of this string is twice the `digest_size` attribute.
  `generateCode`(functionName, out[, dataType, crcType])

    Generate a C/C++ function.

    Parameters: | functionName – String specifying the name of the function. out – An open file-like object with a write method. This specifies where the generated code is written. dataType – An optional parameter specifying the data type of the input data to the function. Defaults to `UINT8`. crcType – An optional parameter specifying the data type of the CRC value. Defaults to one of `UINT8`, `UINT16`, `UINT32`, or `UINT64` depending on the size of the CRC value.

### Examples

CRC-32 Example:

    >>> import crcmod

    >>> crc32 = crcmod.Crc(0x104c11db7, initCrc=0, xorOut=0xFFFFFFFF)
    >>> crc32.update('123456789')
    >>> hex(crc32.crcValue)
    '0xcbf43926L'
    >>> crc32.hexdigest()
    'CBF43926'

The `Crc.update()` method can be called multiple times, and the CRC value is updated with each call:

    >>> crc32new = crc32.new()
    >>> crc32new.update('1234')
    >>> crc32new.hexdigest()
    '9BE3E0A3'
    >>> crc32new.update('56789')
    >>> crc32new.hexdigest()
    'CBF43926'

### Navigation

- index
- modules |
- next |
- previous |
- crcmod v1.7 documentation »