Awesome

Caterpillar - 🐛

[!WARNING] This project is still in beta/testing phase. Expect bugs, naming changes and errors while using this library. C API Reference is WIP, C extensions are supported since v2.1.0.

Caterpillar is a Python 3.12+ library to pack and unpack structurized binary data. It enhances the capabilities of Python Struct by enabling direct class declaration. More information about the different configuration options will be added in the future. Documentation is here >.

Caterpillar is able to:

• Pack and unpack data just from processing Python class definitions (including support for bitfields, c++-like templates and c-like unions!),
• apply a wide range of data types (with endianess and architecture configuration),
• dynamically adapt structs based on their inheritance layout,
• reduce the used memory space using __slots__,
• allowing you to place conditional statements into class definitions,
• insert proper types into the class definition to support documentation and
• it helps you to create cleaner and more compact code.
• You can even extend Caterpillar and write your parsing logic in C or C++!!

What does it look like?

from caterpillar._Py import *

@struct(order=LittleEndian)
class Format:
    magic: b"ITS MAGIC"       # Supports string and byte constants directly
    a: uint8                  # Primitive data types
    b: int32
    length: uint8             # String fields with computed lengths
    name: String(this.length) #  -> you can also use Prefixed(uint8)
    names: CString[uint8::]   # Sequences with prefixed, computed lengths

# Instantiation (keyword-only arguments, magic is auto-inferred):
obj = Format(a=1, b=2, length=3, name="foo", names=["a", "b"])
# Packing the object:
blob = pack(obj) # objects of struct classes can be packed right away
# results in: b'ITS MAGIC\x01\x02\x00\x00\x00\x03foo\x02a\x00b\x00'
# Unpacking the binary data:
obj2 = unpack(blob, Format)

This library offers extensive functionality beyond basic struct handling. For further details on its powerful features, explore the official documentation, examples, and test cases.

Installation

[!NOTE] As of Caterpillar v2.1.2 it is possible to install the library without the need of compiling the C extension.

Simply use pip to install the package with all tools, all extra packages and the C extension:

pip install "caterpillar[all]@git+https://github.com/MatrixEditor/caterpillar.git"

If you want to use the native C extension you can specify the following environment variables:

• CP_ENABLE_NATIVE - Enables installation of the native C extension
• CP_ENABLE_TOOLS - Enables installation of extra tools (proposed)

For instance, the following command will install the caterpillar package with a native interface and with extra tools:

CP_ENABLE_NATIVE=1 \
CP_ENABLE_TOOLS=1 \
pip install git+https://github.com/MatrixEditor/caterpillar

Starting Point

Please visit the Documentation, it contains a complete tutorial on how to use this library.

Other Approaches

A list of similar approaches to parsing structured binary data with Python can be taken from below:

• construct
• kaitai_struct
• hachoir
• mrcrowbar

The documentation also provides a Comparison to these approaches.

License

Distributed under the GNU General Public License (V3). See License for more information.