| Name | binobj JSON |
| Version |
0.11.4
JSON |
| download |
| home_page | |
| Summary | A Python library for reading and writing structured binary data. |
| upload_time | 2024-03-13 14:39:58 |
| maintainer | |
| docs_url | None |
| author | Diego Argueta |
| requires_python | >=3.7,<4.0 |
| license | BSD-3 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
binobj
======
|build-status| |python-versions| |installs-month| |installs-ever|
.. |build-status| image:: https://github.com/dargueta/binobj/actions/workflows/ci.yml/badge.svg
:alt: Build status
.. |python-versions| image:: https://img.shields.io/badge/python-3.7,%203.8,%203.9,%203.10,%203.11,%203.12-blue.svg
:alt: Python versions
.. |installs-month| image:: https://pepy.tech/badge/binobj/month
:alt: Installs per month
:target: https://pepy.tech/project/binobj
.. |installs-ever| image:: https://pepy.tech/badge/binobj
:alt: Total installs
:target: https://pepy.tech/project/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``:
.. code-block:: python
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``:
.. code-block:: python
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.7-3.11, PyPy 3.7-3.9.
.. _mixed-endian: https://en.wikipedia.org/wiki/Endianness#Mixed
Installation
------------
You can install this with ``pip`` like so:
.. code-block:: sh
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:
.. code-block:: sh
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 <https://stackoverflow.com/a/42021993>`_
on Stack Overflow to find out why.
Testing and Development
-----------------------
This package uses `Tox <https://tox.readthedocs.io/en/latest/>`_ 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 <https://github.com/pyenv/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 <https://www.cygwin.com/>`_ and install it during setup.
Once you have those installed, in the root directory of this repo run:
.. code-block:: sh
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 <https://github.com/dargueta/binobj/issues>`_.
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.
.. _3-Clause BSD License: https://tldrlegal.com/license/bsd-3-clause-license-(revised)
Raw data
{
"_id": null,
"home_page": "",
"name": "binobj",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Diego Argueta",
"author_email": "620513-dargueta@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/10/44/6343f7bb61072e7bf5a6dca60a643b4f770a03ccde86cf0b81262067bd90/binobj-0.11.4.tar.gz",
"platform": null,
"description": "binobj\n======\n\n|build-status| |python-versions| |installs-month| |installs-ever|\n\n.. |build-status| image:: https://github.com/dargueta/binobj/actions/workflows/ci.yml/badge.svg\n :alt: Build status\n\n.. |python-versions| image:: https://img.shields.io/badge/python-3.7,%203.8,%203.9,%203.10,%203.11,%203.12-blue.svg\n :alt: Python versions\n\n.. |installs-month| image:: https://pepy.tech/badge/binobj/month\n :alt: Installs per month\n :target: https://pepy.tech/project/binobj\n\n.. |installs-ever| image:: https://pepy.tech/badge/binobj\n :alt: Total installs\n :target: https://pepy.tech/project/binobj\n\nA cross-platform Python 3 library for reading and writing structured binary data\nin an object-oriented (ish) style.\n\nWhy use ``binobj``?\n-------------------\n\nYou may have used Python's built-in ``struct`` library to load and dump binary\ndata. It's unwieldy for larger or more complex data structures, and the format\nstrings are easy to get wrong. ``binobj`` is different in that it takes a class-based\napproach to declaring binary structures.\n\nTake a look at this example using ``struct``:\n\n.. code-block:: python\n\n data = (b'BM', 1024, 0, 12, 40, 32, 32, 1, 1, 0, 0, 72, 72, 2, 2)\n header_bytes = struct.pack('<2sIIIIiiHHIIiiII', *data)\n loaded = struct.unpack('<2sIIIIiiHHIIiiII', header_bytes)\n n_pixels = loaded[5] * loaded[6]\n\n\nThe same example rewritten using ``binobj``:\n\n.. code-block:: python\n\n class BMP(binobj.Struct):\n class Meta:\n argument_defaults = {\n \"endian\": \"little\"\n }\n\n magic: Bytes = b\"BM\"\n file_size: UInt32\n _reserved: binobj.Bytes(const=b\"\\0\\0\\0\\0\", discard=True)\n pixels_offset: UInt32()\n\n # Legacy DIB header\n header_size: UInt32 = 40\n image_width: Int32\n image_height: Int32\n n_color_planes: UInt16\n n_bits_per_pixel: UInt16\n compression_method: UInt32 = 0\n bitmap_size: UInt32\n v_resolution: Int32\n h_resolution: Int32\n n_palette_colors: UInt32\n n_important_colors: UInt32\n\n bmp = BMP(file_size=1024, pixels_offset=12, image_width=32, image_height=32, ...)\n header_bytes = bytes(bmp)\n loaded = BMP.from_bytes(header_bytes)\n n_pixels = loaded.image_width * loaded.image_height\n\n\n``binobj`` also has other advantages in that it supports strings in any encoding\nPython supports, toggling endianness on a per-field basis (necessary for ISO 9660\nimages), a variety of integer encodings, computed fields, validation, and more.\n\nSystem Requirements\n-------------------\n\n- This package will *not* work on a `mixed-endian`_ system. Those are pretty rare\n nowadays so chances are you won't have a problem.\n- This has been tested on CPython 3.7-3.11, PyPy 3.7-3.9.\n\n.. _mixed-endian: https://en.wikipedia.org/wiki/Endianness#Mixed\n\nInstallation\n------------\n\nYou can install this with ``pip`` like so:\n\n.. code-block:: sh\n\n pip3 install binobj\n\n- Be sure to use ``pip3`` and not ``pip``, because ``pip`` defaults to Python 2.\n- If you get a \"Permission Denied\" error, try:\n\n.. code-block:: sh\n\n pip3 install --user binobj\n\nSide note: Don't use ``sudo`` (even ``sudo -EH``) to force a package to install,\nas that's a security risk. See `this answer <https://stackoverflow.com/a/42021993>`_\non Stack Overflow to find out why.\n\nTesting and Development\n-----------------------\n\nThis package uses `Tox <https://tox.readthedocs.io/en/latest/>`_ to run tests on\nmultiple versions of Python.\n\nSetup\n~~~~~\n\nTo set up your development environment, you'll need to install a few things.\n\n* For Python version management, I use `pyenv-virtualenv <https://github.com/pyenv/pyenv-virtualenv>`_.\n Follow the installation instructions there.\n* You'll also need ``make``. Depending on your platform you can install it in\n one of several ways:\n\n * macOS: ``brew install make``\n * Debian systems (e.g. Ubuntu): ``sudo apt-get install make``\n * Windows: Use `Cygwin <https://www.cygwin.com/>`_ and install it during setup.\n\nOnce you have those installed, in the root directory of this repo run:\n\n.. code-block:: sh\n\n make setup\n\nRunning the Tests\n~~~~~~~~~~~~~~~~~\n\nTo run the unit tests for all supported versions of Python, run ``make test``.\nThe environments will automatically be rebuilt if needed.\n\nIssues and Feature Requests\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo report an issue, request a feature, or propose a change, please file a\nreport on the project's GitHub page `here <https://github.com/dargueta/binobj/issues>`_.\n\nLicense\n-------\n\nI'm releasing this under the terms of the `3-Clause BSD License`_. For the full\nlegal text, see ``LICENSE.txt`` in the repository.\n\n.. _3-Clause BSD License: https://tldrlegal.com/license/bsd-3-clause-license-(revised)\n",
"bugtrack_url": null,
"license": "BSD-3",
"summary": "A Python library for reading and writing structured binary data.",
"version": "0.11.4",
"project_urls": {
"Bug Tracker": "https://github.com/dargueta/binobj/issues",
"Documentation": "https://dargueta.github.io/binobj",
"Homepage": "https://dargueta.github.io/binobj",
"Repository": "https://github.com/dargueta/binobj"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "35e7b9314968a0597e9eb8ea8f86e58ddd4627135963201e91443ca270ec20b2",
"md5": "c6f22469c290c651a253091c2b55abdd",
"sha256": "942fa4334c499363d96cf143bffa0eb5eed7b0c35d6ef893c46a52c614da29c6"
},
"downloads": -1,
"filename": "binobj-0.11.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6f22469c290c651a253091c2b55abdd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 51245,
"upload_time": "2024-03-13T14:39:56",
"upload_time_iso_8601": "2024-03-13T14:39:56.814536Z",
"url": "https://files.pythonhosted.org/packages/35/e7/b9314968a0597e9eb8ea8f86e58ddd4627135963201e91443ca270ec20b2/binobj-0.11.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "10446343f7bb61072e7bf5a6dca60a643b4f770a03ccde86cf0b81262067bd90",
"md5": "cefbff5e8ed16e331d20ecb0e56adfc9",
"sha256": "d851c561df9ab05be7820ec1fbe774d0616db5c6ba603e2b42711d0cc3500d7f"
},
"downloads": -1,
"filename": "binobj-0.11.4.tar.gz",
"has_sig": false,
"md5_digest": "cefbff5e8ed16e331d20ecb0e56adfc9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 45967,
"upload_time": "2024-03-13T14:39:58",
"upload_time_iso_8601": "2024-03-13T14:39:58.507294Z",
"url": "https://files.pythonhosted.org/packages/10/44/6343f7bb61072e7bf5a6dca60a643b4f770a03ccde86cf0b81262067bd90/binobj-0.11.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-13 14:39:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dargueta",
"github_project": "binobj",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "binobj"
}
