Chunks

A file usually contains many types of chunks. In most occasions, chunks are not arranged in a fixed order. So we need to use matches() to read a few bytes first to detect if the following data match the specific chunk type.

class chunks.Chunk(fp, parser)

Chunk in the file. A chunk usually contains a signature indicating its type, and a group of data fields.

Parameters:

• fp – File object to read from.
• parser – The parser it belongs to. It’s optional and you can leave it None.

To define your chunk class, you should follow these steps:

1. Define its fields. Fields are populated in this order. See Fields for more information.

2. Define a matches() or safe_matches() class method to judge if the following bytes match this type of chunk.

   • Override matches() to handle fp state by yourself.
   • Override safe_matches() to get fp state auto saved.

Example:

import os
import struct

from chunker.chunks import Chunk

class DataChunk(Chunk):
    Fields = (
        UnsignedLongField('sig'),   # 0x01020304
        UnsignedLongField('type'),
        UnsignedLongField('data_length'),
        StringField('data', length_field_name='data_length'),
    )

    @classmethod
    def safe_matches(fp):
        buf = fp.read(4)
        type = struct.unpack('>H', buf)[0]

        return type == 0x01020304

if DataChunk.matches(fp):
    c = DataChunk(fp, None)
    print(c.data) # Access field value by its name

classmethod matches(fp)

Read next a few bytes to judge if the following data match this type of chunk.

It calls safe_matches() and restores fp state by default.

You can override this to avoid saving fp state.

Parameters:fp – File object to read from. Returns:If the following bytes match this chunk type.

populate()

Populate chunk fields. After that, you can access each field data directly by field name.

classmethod safe_matches(fp)

The difference between safe_matches() and matches() is that if you override this, you can get your fp state auto saved.

You only need to override one of them:

• Override matches() to handle fp state by yourself.
• Override safe_matches() to get fp state auto saved.

Parameters:fp – File object to read from. Returns:If the following bytes match this chunk type.