binobj


Namebinobj JSON
Version 0.3.1 PyPI version JSON
download
home_pagehttps://www.github.com/dargueta/binobj
SummaryA Python library for reading and writing structured binary data.
upload_time2018-03-29 05:50:43
maintainer
docs_urlNone
authorDiego Argueta
requires_python>=3.3
licenseBSD 3-Clause License
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            binobj
======

|build-status| |python-versions|

.. |build-status| image:: https://travis-ci.org/dargueta/binobj.svg?branch=master
   :alt: Build status
   :target: https://travis-ci.org/dargueta/binobj

.. |python-versions| image:: https://img.shields.io/badge/python-3.3,%203.4,%203.5,%203.6-blue.svg
   :alt: Python versions

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 seen other libraries like `Construct <https://github.com/construct/construct>`_
that accomplish the same job. ``binobj`` is different in that it's heavily inspired
by `Marshmallow <http://marshmallow.readthedocs.io/en/latest/>`_ and takes a
more class-based approach to declaring binary structures.

Take a look at this example taken from the README of ``construct`` library:

.. code-block:: python

    format = Struct(
        "signature" / Const(b"BMP"),
        "width" / Int8ub,
        "height" / Int8ub,
        "pixels" / Array(this.width * this.height, Byte),
    )

    format.build(dict(width=3,height=2,pixels=[7,8,9,11,12,13]))


The same example rewritten using ``binobj``:

.. code-block:: python

    class BMPFile(Struct):
        signature = Bytes(const=b'BMP')
        width = UInt8()
        height = UInt8()
        pixels = Array(UInt8(), count=width * height)

    bmp_file = BMPFile(width=3, height=2, pixels=[7,8,9,11,12,13])
    bytes(bmp_file)


``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.

Note: Size expressions are currently not implemented but they're in the works.

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 Python 3.3, 3.4, 3.5, 3.6, and PyPy3.5.

Sorry, I have no intention of supporting Python 2. Feel free to fork this and do
a backport if you like! I'd be interested to see it and might even contribute.

Installation
------------

Once I get this up on PyPI, you can install it 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 `Three-Clause BSD License <https://tldrlegal.com/license/bsd-3-clause-license-(revised)>`_.
For the full legal text, see `LICENSE.txt <./LICENSE.txt>`_.



            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": ">=3.3", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "", 
    "upload_time": "2018-03-29 05:50:43", 
    "author": "Diego Argueta", 
    "home_page": "https://www.github.com/dargueta/binobj", 
    "download_url": "https://pypi.python.org/packages/82/07/f0d013b883dbca4285b851c817dcde0db12012c15bc1576ab83ac553e75f/binobj-0.3.1.tar.gz", 
    "platform": "", 
    "version": "0.3.1", 
    "cheesecake_documentation_id": null, 
    "description": "binobj\n======\n\n|build-status| |python-versions|\n\n.. |build-status| image:: https://travis-ci.org/dargueta/binobj.svg?branch=master\n   :alt: Build status\n   :target: https://travis-ci.org/dargueta/binobj\n\n.. |python-versions| image:: https://img.shields.io/badge/python-3.3,%203.4,%203.5,%203.6-blue.svg\n   :alt: Python versions\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 seen other libraries like `Construct <https://github.com/construct/construct>`_\nthat accomplish the same job. ``binobj`` is different in that it's heavily inspired\nby `Marshmallow <http://marshmallow.readthedocs.io/en/latest/>`_ and takes a\nmore class-based approach to declaring binary structures.\n\nTake a look at this example taken from the README of ``construct`` library:\n\n.. code-block:: python\n\n    format = Struct(\n        \"signature\" / Const(b\"BMP\"),\n        \"width\" / Int8ub,\n        \"height\" / Int8ub,\n        \"pixels\" / Array(this.width * this.height, Byte),\n    )\n\n    format.build(dict(width=3,height=2,pixels=[7,8,9,11,12,13]))\n\n\nThe same example rewritten using ``binobj``:\n\n.. code-block:: python\n\n    class BMPFile(Struct):\n        signature = Bytes(const=b'BMP')\n        width = UInt8()\n        height = UInt8()\n        pixels = Array(UInt8(), count=width * height)\n\n    bmp_file = BMPFile(width=3, height=2, pixels=[7,8,9,11,12,13])\n    bytes(bmp_file)\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\nNote: Size expressions are currently not implemented but they're in the works.\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 Python 3.3, 3.4, 3.5, 3.6, and PyPy3.5.\n\nSorry, I have no intention of supporting Python 2. Feel free to fork this and do\na backport if you like! I'd be interested to see it and might even contribute.\n\nInstallation\n------------\n\nOnce I get this up on PyPI, you can install it 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 `Three-Clause BSD License <https://tldrlegal.com/license/bsd-3-clause-license-(revised)>`_.\nFor the full legal text, see `LICENSE.txt <./LICENSE.txt>`_.\n\n\n", 
    "lcname": "binobj", 
    "bugtrack_url": null, 
    "github": false, 
    "name": "binobj", 
    "license": "BSD 3-Clause License", 
    "summary": "A Python library for reading and writing structured binary data.", 
    "split_keywords": [], 
    "author_email": "dargueta@users.noreply.github.com", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2018-03-29T05:50:42", 
            "comment_text": "", 
            "python_version": "py3", 
            "url": "https://pypi.python.org/packages/fb/cb/e49ef32463f17987212935234233b9415e6fe711e9be0a350baeae3d8c69/binobj-0.3.1-py3-none-any.whl", 
            "md5_digest": "c92a90b34313f26f3707564506fb3e32", 
            "downloads": 0, 
            "filename": "binobj-0.3.1-py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "fb/cb/e49ef32463f17987212935234233b9415e6fe711e9be0a350baeae3d8c69/binobj-0.3.1-py3-none-any.whl", 
            "digests": {
                "sha256": "64acb4ba60646fbdeb5ef8f2bcf91cf60b1739630a6e4650deac3f90232b64b4", 
                "md5": "c92a90b34313f26f3707564506fb3e32"
            }, 
            "sha256_digest": "64acb4ba60646fbdeb5ef8f2bcf91cf60b1739630a6e4650deac3f90232b64b4", 
            "size": 24748
        }, 
        {
            "has_sig": false, 
            "upload_time": "2018-03-29T05:50:43", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/82/07/f0d013b883dbca4285b851c817dcde0db12012c15bc1576ab83ac553e75f/binobj-0.3.1.tar.gz", 
            "md5_digest": "048bf1cbc78d752f6ca43dd7065d36f9", 
            "downloads": 0, 
            "filename": "binobj-0.3.1.tar.gz", 
            "packagetype": "sdist", 
            "path": "82/07/f0d013b883dbca4285b851c817dcde0db12012c15bc1576ab83ac553e75f/binobj-0.3.1.tar.gz", 
            "digests": {
                "sha256": "a198f69c93a432807f253f3f988ec24585b85bafceaa44b3902eb3ba6a2b88ca", 
                "md5": "048bf1cbc78d752f6ca43dd7065d36f9"
            }, 
            "sha256_digest": "a198f69c93a432807f253f3f988ec24585b85bafceaa44b3902eb3ba6a2b88ca", 
            "size": 19614
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}