Skip to main content

A versatile and extensible binary data parsing/serializing library for Python 3

Project description

Supyr Struct

PyPI version GitHub version

Supyr Struct is an extensible and powerful binary data parsing, editing, and serializing library for Python 3.

Supyr's parsing and serializing is declarative, meaning that rather than write code to handle parsing and serializing data, you instead create a description of the structure using various FieldTypes. These descriptions are used by BlockDef objects to build Blocks, which represent/contain the parsed data. A BlockDef is simply a constructor object that scans its description for errors on initialization and uses it for creating Blocks.

Supyr provides a large collection of FieldTypes, ranging from atomic data types(floats and ints of various sizes) to hierarchical structures(structs, containers, and arrays) and logical structures and wrappers(switches and unions).

For a detailed overview of the more abstract concepts and features of Supyr, read the text files in the 'docs' folder.


Check out the changelog here.


This project is licensed under the MIT License, check out the details and author info here.


You'll need Python 3.5 or higher.

In your terminal execute:

python3 -m pip install supyr_struct

or, you can clone/download this repo and run the

git clone
cd supyr_struct
python3 -m pip install .


Heres a small example of defining a structure using a BlockDef and FieldTypes and using it to create a Block.

>>> from supyr_struct import *
>>> asdf = BlockDef('some_block',
... UInt32('some_int'),
... BytesRaw('some_bytes', SIZE=16),
... ENDIAN='>')
>>> test_block =
>>> test_block.some_int = 1337
>>> test_block['some_bytes'] = b'here\'s a cstring\x00'
>>> print('test_block:', test_block)
test_block: [ Container, entries:2, some_block
    [ UInt32, size:4, some_int, 1337 ]
    [ BytesRaw, size:16, some_bytes, <RAWDATA> ]
>>> test_block.serialize()
BytearrayBuffer(b"\x00\x00\x059here\'s a cstring\x00")

Supyr allows forcing endianness to be either big, little, or back to normal on a library scale and/or on individual FieldTypes.

>>> field_types.FieldType.force_little()
>>> test_block.serialize()
BytearrayBuffer(b"9\x05\x00\x00here\'s a cstring\x00")
>>> field_types.FieldType.force_normal()
>>> test_block.serialize()
BytearrayBuffer(b"\x00\x00\x059here\'s a cstring\x00")
>>> field_types.FieldType.force_big()
>>> test_block.serialize()
BytearrayBuffer(b"\x00\x00\x059here\'s a cstring\x00")
>>> field_types.FieldType.force_little()
>>> test_block.serialize()
BytearrayBuffer(b"9\x05\x00\x00here\'s a cstring\x00")

Take a look at the examples module for some ready-to-run example programs that utilize Supyr in different ways.

Who do I talk to?

If you're having any issues with the library you can report them on our GitHub Issues page.

If the issue requires some more direct attention we'll drop a contact link.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

supyr_struct-1.5.4.tar.gz (197.5 kB view hashes)

Uploaded Source

Built Distribution

supyr_struct-1.5.4-py3-none-any.whl (236.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page