Skip to main content

Library for read/write access of binary data via structures

Project description

The binstruct library allows you to access binary data using a predefined structure. The binary data can be provided in any form that allows an indexed access to single bytes. This could for example be an mmaped file. The data structure itself is defined in way similar to Django database table definitions by declaring a new class with its fields.

Current build status Test coverage PyPI version Supported Python versions Egg Status Wheel Status License

Simple Example

First you have to define the structure which you want to use to access your binary data. This is done by specifying all desired fields with their types and their position inside a new class. As an example let’s take the first of the ELF header which in C would look like this

#define EI_NIDENT 16

typedef struct {
    unsigned char e_ident[EI_NIDENT];
    uint16_t      e_type;
    uint16_t      e_machine;
    uint32_t      e_version;
    // rest of the fields omitted for simplicity
} ElfN_Ehdr;

Using binstruct you now declare the following Python class

from binstruct import *

class ElfN_Ehdr(StructTemplate):
    e_ident = RawField(0, 16)
    e_type = UInt16Field(16)
    e_machine = UInt16Field(18)
    e_version = UInt32Field(20)

Note that you have to specify the offset of the fields even though it would be possible to derive that from the size of the previous fields. I opted for this solution because it makes the implementation easier and because it allows for easier skipping of irrelevant or reserved fields.

Now we can create an instance of this class by providing the constructor an indexable data structure and an offset. The indexable data structure is any Python object representing binary data to which you want to have “structured access”. The offset allows you to place the structure at any place inside the indexable data structure.

For this example lets just use a simple list for the binary data

binary_data = 24 * [0]
header = ElfN_Ehdr(binary_data, 0)

Now you can simply read and write any of the fields

header.e_type = 0x0
header.e_ident[0] = 0x7f
header.e_ident[1] = ord('E')
header.e_ident[2] = ord('L')
header.e_ident[3] = ord('F')

print(header.e_type)
print(header.e_ident[1])

The current implementation provides signed and unsigned fields for 8-bit, 16-bit and 32-bit integers, strings, raw data fields and even nested structures. For some ideas of how to use them, also checkout the unit tests.

Contributing

The library is fully standalone and only requires py.test to run the unit tests. To contribute any changes simply clone the project on GitHub: https://github.com/Jokymon/binstruct, push your changes to your own GitHub project and send a pull request. For any changes please make sure you have good unit tests.

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

binstruct-1.0.1.zip (23.2 kB view details)

Uploaded Source

Built Distributions

binstruct-1.0.1.win-py2.7.exe (205.5 kB view details)

Uploaded Source

binstruct-1.0.1.win-amd64-py3.4.exe (231.6 kB view details)

Uploaded Source

binstruct-1.0.1.win-amd64-py2.7.exe (233.2 kB view details)

Uploaded Source

binstruct-1.0.1.win32-py3.4.exe (200.4 kB view details)

Uploaded Source

binstruct-1.0.1.win32-py2.7.exe (205.5 kB view details)

Uploaded Source

binstruct-1.0.1-py3.4.egg (8.0 kB view details)

Uploaded Source

binstruct-1.0.1-py2.7.egg (7.8 kB view details)

Uploaded Source

File details

Details for the file binstruct-1.0.1.zip.

File metadata

  • Download URL: binstruct-1.0.1.zip
  • Upload date:
  • Size: 23.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for binstruct-1.0.1.zip
Algorithm Hash digest
SHA256 6238b637c18e5889a1977d0c9c72b14cc3ca56b4ab7f0e9d4c40cad5bfbdd056
MD5 066a5f55c2f406050aead269ce064355
BLAKE2b-256 d3666c6b14ae151e370879276336a8cf853be193209df51b87660705e4ec98d5

See more details on using hashes here.

File details

Details for the file binstruct-1.0.1.win-py2.7.exe.

File metadata

File hashes

Hashes for binstruct-1.0.1.win-py2.7.exe
Algorithm Hash digest
SHA256 59949c31ede3127d03436ebc753288c01c2568fc29f0704845f5609bee0870ba
MD5 63bc5fc709c5a6b548dbad1329d79291
BLAKE2b-256 6dbb4b75a7836806509bdbf0da89e051aca389a5d8199bf7d87819cd509707ba

See more details on using hashes here.

File details

Details for the file binstruct-1.0.1.win-amd64-py3.4.exe.

File metadata

File hashes

Hashes for binstruct-1.0.1.win-amd64-py3.4.exe
Algorithm Hash digest
SHA256 a9513b09f4deeaf4bb514c1ff367ff83a91eb68482cafc53e0018f45667269a4
MD5 d461c7c65c69d46296c5aa5791e06ed8
BLAKE2b-256 1514c75ee4789bcaf72e11bc12e3e06522ea0ee276b04581b18c7e5d84f08c36

See more details on using hashes here.

File details

Details for the file binstruct-1.0.1.win-amd64-py2.7.exe.

File metadata

File hashes

Hashes for binstruct-1.0.1.win-amd64-py2.7.exe
Algorithm Hash digest
SHA256 6d803f6c6761d14ff89209d4569ba52400f5dc3be7c1507543d728caa68d6fe7
MD5 4221e9188bfbcb79fd80d7bd59682d68
BLAKE2b-256 ddcab7ddc567b2116d7dc2aaae496fbda94947350571986f742b09ae622d219e

See more details on using hashes here.

File details

Details for the file binstruct-1.0.1.win32-py3.4.exe.

File metadata

File hashes

Hashes for binstruct-1.0.1.win32-py3.4.exe
Algorithm Hash digest
SHA256 8e13d2567d51001813438ae1a86f3ff6965edac37b0ed1f65c113d346a86a98c
MD5 da9fbfab0970dfdfb950e4ac77c000f1
BLAKE2b-256 d056b65819d40d9da0e3ad6e175bb8cbf007297feb768e5871813bcb3a6f7822

See more details on using hashes here.

File details

Details for the file binstruct-1.0.1.win32-py2.7.exe.

File metadata

File hashes

Hashes for binstruct-1.0.1.win32-py2.7.exe
Algorithm Hash digest
SHA256 0a703cfd9d5b45781b26a8db2b58f8bff04a2353d75101db9f2281522427d429
MD5 f1f16dadd33c20fd44e681b85dd6d531
BLAKE2b-256 d7b0ebfcfb1d95a9035161d0878b58867d77ca280f7b77981a0c3f19638d242c

See more details on using hashes here.

File details

Details for the file binstruct-1.0.1-py3.4.egg.

File metadata

File hashes

Hashes for binstruct-1.0.1-py3.4.egg
Algorithm Hash digest
SHA256 1447bed53098724911ff26445495e0b12bdde1587899304fb115e8c4b833acf7
MD5 9f26b240934fc19920ffb1ce4b62b89a
BLAKE2b-256 d6c62eda60721a0622ad4952639d304441b0683acfd968c114f50b1f9d6641cf

See more details on using hashes here.

File details

Details for the file binstruct-1.0.1-py2.7.egg.

File metadata

File hashes

Hashes for binstruct-1.0.1-py2.7.egg
Algorithm Hash digest
SHA256 0835032fc8f0531ffa51e19c5adea35256b318ca103cb0ce659fe32a6973bbe8
MD5 71a04fd98507e2057988895604ac8f65
BLAKE2b-256 2311b7ba8aad5130ecc07a5ba79cc40615045e44a0cfe246e783b99a81e574ff

See more details on using hashes here.

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