Skip to main content

BinaryFileParser

BinaryFileParser allows the user to create a binary file format specification in the form of a struct and then use it to read/write files.

Installation

On Linux:

$ python3 -m venv venv
$ source venv/bin/activate
$ pip install binary-file-parser

On Windows:

> py -m venv venv
> venv/Scripts/activate
> pip install binary-file-parser

Getting Started

This is a very basic script to give you an idea of how to use this library. Check out the API Reference (coming soon™) for documentation containing more details on how to use this library.

from binary_file_parser import BaseStruct, Retriever
from binary_file_parser.types import int32, uint64, str32, FixedLenStr


class Spam(BaseStruct):
    file_version: str = Retriever(FixedLenStr[4], default = "1.00")
    creator_name: str = Retriever(str32, default = "bfp")
    saved_timestamp: int = Retriever(uint64, default = 0)
    eggs: int = Retriever(int32, default = 0)


# read a binary file that has the above format
file = Spam._from_file("path/to/file")

# modify the creator name
file.creator_name = "Alian713"
file.eggs = 20

# write the modified data to a new file
file._to_file("path/to/write/to")

A Slightly More Complex Example

The main magic of this library is that:

  1. You can use your own structs within another struct
  2. Event hooks help you keep any interdependencies in the file structure synchronised:
from __future__ import annotations

from binary_file_parser import BaseStruct, Retriever
from binary_file_parser.types import FixedLenArray, uint32, uint8


class Pixel(BaseStruct):
    red: int = Retriever(uint8, default = 0)
    green: int = Retriever(uint8, default = 0)
    blue: int = Retriever(uint8, default = 0)
    alpha: int = Retriever(uint8, default = 0)

    def __init__(
        self,
        red: int,
        green: int,
        blue: int,
        alpha: int = 0,
    ):
        super().__init__(initialise_defaults = False)
        self.red = red
        self.green = green
        self.blue = blue
        self.alpha = alpha


class Img(BaseStruct):
    @staticmethod
    def _set_width(retriever: Retriever, obj: Img):
        # here Img.pixels.dtype refers to FixedLenArray
        Img.pixels.dtype.length = obj._width

    @staticmethod
    def _set_height(retriever: Retriever, obj: Img):
        # The repeat value defines how many times a single retriever should read data
        Retriever.set_repeat(Img.pixels, obj, obj._height)

    @staticmethod
    def _update_dims(retriever: Retriever, obj: Img):
        # this ensures that when the file is written back, the height and width being written back to file are
        # up to date
        obj._height = obj.height
        Img.pixels.dtype.length = obj._width = obj.width

    _width: int = Retriever(uint32, default = 100, on_read = [_set_width], on_write = [_update_dims])
    _height: int = Retriever(uint32, default = 200, on_set = [_set_height])
    pixels: list[list[Pixel]] = Retriever(
        FixedLenArray[Pixel, 100], default_factory = lambda _: [Pixel(0, 0, 0) for _ in range(100)], repeat = 200
    )

    @property
    def width(self) -> int:
        return len(self.pixels[0])

    @property
    def height(self) -> int:
        return len(self.pixels)


# Make a new image from all defaults
a = Img()
# Note: Mutable defaults will be shallow copied, use default_factory when such is not intended

About the Author

If you have any questions, suggestions or feedback regarding the library, feel free to send me a message on discord!

Author Discord
Alian713 Alian713#0069

Metadata

Release files for binary-file-parser 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for binary-file-parser 0.2.2
File Size Uploaded Provenance Actions
binary_file_parser-0.2.2.tar.gz 55.9 kB Without provenance Details for binary_file_parser-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for binary-file-parser 0.2.2
File Interpreter ABI Platform Actions
binary_file_parser-0.2.2-py3-none-any.whl Python 3 none any Details for binary_file_parser-0.2.2-py3-none-any.whl

Total release size: 107.7 kB

Release files / binary_file_parser-0.2.2.tar.gz

Download URL binary_file_parser-0.2.2.tar.gz
Size 55.9 kB
Tags Source
SHA-256 checksum
How to use checksums
260de5d3e33381763c31d95ccaf2d0ceceec12915de694d1c9dbab66d9b9dd45
BLAKE2b-256 checksum
How to use checksums
1df066ac7e56081bac8cbfbcdc8eaae73d76a5316321f268400251e5cd10e650
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.10.11

Release files / binary_file_parser-0.2.2-py3-none-any.whl

Download URL binary_file_parser-0.2.2-py3-none-any.whl
Size 51.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fb0512c72ce48e193757b9b746e96db482d59028ce9c9d89d5710cc00fc30cff
BLAKE2b-256 checksum
How to use checksums
dd72a7779e72cf2914868736a822007fb655cb2fbc542470ed0fabf5e80b54a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.10.11

Security for binary-file-parser 0.2.2

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.

Release history Release notifications | RSS feed

This release

0.2.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page