Metadata-Version: 2.1
Name: KonFoo
Version: 2.0
Summary: A declarative byte stream mapping engine.
Home-page: http://github.com/JoeVirtual/KonFoo
Author: Jochen Gerhaeusser
Author-email: jochen_privat@gmx.de
License: BSD
Download-URL: http://github.com/JoeVirtual/KonFoo/zipball/master#egg=konfoo-dev
Keywords: binary data deserialize serialize parse decode encode unpack pack
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.6


.. |Doc Status| image:: https://readthedocs.org/projects/konfoo/badge/?version=latest
    :target: http://konfoo.readthedocs.io/en/latest/?badge=latest
.. |Build Status| image:: https://travis-ci.org/JoeVirtual/KonFoo.svg?branch=master
    :target: https://travis-ci.org/JoeVirtual/KonFoo
.. |PyPI| image:: https://img.shields.io/pypi/v/KonFoo.svg
    :target: https://pypi.org/project/KonFoo
.. |License| image:: https://img.shields.io/pypi/l/KonFoo.svg
    :target: https://pypi.org/project/KonFoo
.. |Python| image:: https://img.shields.io/pypi/pyversions/KonFoo.svg
    :target: https://pypi.org/project/KonFoo
.. |Status| image:: https://img.shields.io/pypi/status/KonFoo.svg
    :target: https://pypi.org/project/KonFoo
.. |Binder| image:: https://mybinder.org/badge.svg
    :target: https://mybinder.org/v2/gh/JoeVirtual/KonFoo/master?filepath=notebooks

KonF'00'
========

|Doc Status| |Build Status| |PyPI| |License| |Python| |Status| |Binder|

KonFoo is a Python Package for creating byte stream mappers in a declarative
way with as little code as necessary to help fighting the confusion with the
foo of the all too well-known memory dumps or hexadecimal views of binary
data.

It comes with sensible defaults out of the box.

It aims to make the process of reading, de-serializing, viewing, serializing
and writing binary data from and back to a data provider as easy as possible.

KonFoo in points:

- declarative way to describe the mapping of binary data to Python types
- declarative classes to read, deserialize, serialize and write binary data
  from and back to a data source
- easy adjustable byte stream provider bridge to any kind of data source
- nesting of classes
- adaptable classes on the fly while reading/de-serializing binary data
- easy syntax for accessing nested fields
- view the mapped binary data as a JSON string
- list the mapped binary data as a flatten list or dictionary
- write the mapped binary data to a ``.json`` file
- write the mapped binary data to a ``.csv`` file
- save the mapped binary data to an ``.ini`` file
- load the mapped binary data from an ``.ini`` file
- easy creatable nested metadata dictionaries of the members of a byte stream mapper
- metadata converter to the ``flare.json`` format to visualise the mapper with
  `d3.js <https://d3js.org>`_.


Example
-------

A short example how to define a byte stream mapper.

>>> from konfoo import *

>>> class Identifier(Structure):
...     def __init__(self):
...         super().__init__()
...         self.version = Byte(align_to=4)
...         self.id = Unsigned(8, align_to=4)
...         self.length = Decimal(8, align_to=4)
...         self.module = Char(align_to=4)
...         self.index_fields()
>>> class HeaderV1(Structure)
...     def __init__(self):
...         super().__init__()
...         self.type = Identifier()
>>> class HeaderV2(HeaderV1)
...     def __init__(self):
...         super().__init__()
...         self.size = Decimal(16)
>>> header = HeaderV2()
>>> header.to_list()
[('Structure.type.version', '0x0'),
 ('Structure.type.id', '0x0'),
 ('Structure.type.length', 0),
 ('Structure.type.module', ' '),
 ('Structure.size', 0)]
>>> header.type.to_csv()
[{'id': 'Identifier.version', 'value': '0x0'},
 {'id': 'Identifier.id', 'value': '0x0'},
 {'id': 'Identifier.length', 'value': 0},
 {'id': 'Identifier.module', 'value': ' '}]
>>> header.to_json()
'{"type": {"version": "0x0", "id": "0x0", "length": 0, "module": "\u0000"},
  "size": 0}'
>>> header.deserialize(bytes.fromhex('0102094610'))
>>> header.to_json()
'{"type": {"version": "0x1", "id": "0x2", "length": 9, "module": "F"},
  "size": 16}'
>>> bytes(header).hex()
'0102094610'

>>> header = Structure(
...     type=Structure(version=Byte(4),
...                    id=Unsigned(8, 4),
...                    length=Decimal(8, 4),
...                    module=Char(4)),
...     size=Decimal(16))
>>> header.to_list()
[('Structure.type.version', '0x0'),
 ('Structure.type.id', '0x0'),
 ('Structure.type.length', 0),
 ('Structure.type.module', ' '),
 ('Structure.size', 0)]
>>> header.type.to_csv()
[{'id': 'Structure.version', 'value': '0x0'},
 {'id': 'Structure.id', 'value': '0x0'},
 {'id': 'Structure.length', 'value': 0},
 {'id': 'Structure.module', 'value': ' '}]
>>> header.to_json()
'{"type": {"version": "0x0", "id": "0x0", "length": 0, "module": "\u0000"},
  "size": 0}'
>>> header.deserialize(bytes.fromhex('0102094610'))
>>> header.to_json()
'{"type": {"version": "0x1", "id": "0x2", "length": 9, "module": "F"},
  "size": 16}'
>>> bytes(header).hex()
'0102094610'


Installing
----------

.. code-block:: bash

    > pip install konfoo

Links
-----

* `Code <http://github.com/JoeVirtual/KonFoo/>`_
* `Documentation <http://konfoo.readthedocs.io>`_
* `Development version
  <http://github.com/JoeVirtual/KonFoo/zipball/master#egg=konfoo-dev>`_