binobj
A cross-platform Python 3 library for reading and writing structured binary data in an object-oriented (ish) style.
Why use binobj?
You may have used Python’s built-in struct library to load and dump binary data. It’s unwieldy for larger or more complex data structures, and the format strings are easy to get wrong. binobj is different in that it takes a class-based approach to declaring binary structures.
Take a look at this example using struct:
data = (b'BM', 1024, 0, 12, 40, 32, 32, 1, 1, 0, 0, 72, 72, 2, 2)
header_bytes = struct.pack('<2sIIIIiiHHIIiiII', *data)
loaded = struct.unpack('<2sIIIIiiHHIIiiII', header_bytes)
n_pixels = loaded[5] * loaded[6]
The same example rewritten using binobj:
class BMP(binobj.Struct):
class Meta:
argument_defaults = {
"endian": "little"
}
magic: Bytes = b"BM"
file_size: UInt32
_reserved: binobj.Bytes(const=b"\0\0\0\0", discard=True)
pixels_offset: UInt32
# Legacy DIB header
header_size: UInt32 = 40
image_width: Int32
image_height: Int32
n_color_planes: UInt16
n_bits_per_pixel: UInt16
compression_method: UInt32 = 0
bitmap_size: UInt32
v_resolution: Int32
h_resolution: Int32
n_palette_colors: UInt32
n_important_colors: UInt32
bmp = BMP(file_size=1024, pixels_offset=12, image_width=32, image_height=32, ...)
header_bytes = bytes(bmp)
loaded = BMP.from_bytes(header_bytes)
n_pixels = loaded.image_width * loaded.image_height
binobj also has other advantages in that it supports strings in any encoding Python supports, toggling endianness on a per-field basis (necessary for ISO 9660 images), a variety of integer encodings, computed fields, validation, and more.
System Requirements
This package will not work on a mixed-endian system. Those are pretty rare nowadays so chances are you won’t have a problem.
This has been tested on CPython 3.9-3.13, PyPy 3.9-3.10.
Installation
You can install this with pip like so:
pip3 install binobj
Be sure to use pip3 and not pip, because pip defaults to Python 2.
If you get a “Permission Denied” error, try:
pip3 install --user binobj
Side note: Don’t use sudo (even sudo -EH) to force a package to install, as that’s a security risk. See this answer on Stack Overflow to find out why.
Testing and Development
This package uses Tox to run tests on multiple versions of Python.
Setup
To set up your development environment, you’ll need to install a few things.
For Python version management, I use pyenv-virtualenv. Follow the installation instructions there.
You’ll also need make. Depending on your platform you can install it in one of several ways:
macOS: brew install make
Debian systems (e.g. Ubuntu): sudo apt-get install make
Windows: Use Cygwin and install it during setup.
Once you have those installed, in the root directory of this repo run:
make setup
Running the Tests
To run the unit tests for all supported versions of Python, run make test. The environments will automatically be rebuilt if needed.
Issues and Feature Requests
To report an issue, request a feature, or propose a change, please file a report on the project’s GitHub page here.
License
I’m releasing this under the terms of the 3-Clause BSD License. For the full legal text, see LICENSE.txt in the repository.
Metadata
Release files for binobj 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| binobj-0.12.0.tar.gz | 46.9 kB | Without provenance | Details for binobj-0.12.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| binobj-0.12.0-py3-none-any.whl | Python 3 | none | any | Details for binobj-0.12.0-py3-none-any.whl |
Total release size: 100.5 kB
Release files / binobj-0.12.0.tar.gz
| Download URL | binobj-0.12.0.tar.gz |
|---|---|
| Size | 46.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
597bc3c781eebd3c21683e1eed8da6ee0e8ce0dbbc8ad3b454d969295a3329c2
|
|
BLAKE2b-256 checksum How to use checksums |
d0e38a69857c4a36ece8dde80d59c3058014fae9521c6ed33dc2ac6602375105
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.3 CPython/3.12.3 Linux/6.6.47-gentoo-dist
|
Release files / binobj-0.12.0-py3-none-any.whl
| Download URL | binobj-0.12.0-py3-none-any.whl |
|---|---|
| Size | 53.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
724fcc60969c269f23b03ac4a3269128d82e4c9794a902319f280b1872c00c4c
|
|
BLAKE2b-256 checksum How to use checksums |
def1556689c2e28ccedf97e6d6afcad6e27155b73b69d14b8b38ca8813405293
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.3 CPython/3.12.3 Linux/6.6.47-gentoo-dist
|
Security for binobj 0.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.