1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
Overview
========
What is bpack?
--------------
.. include:: ../README.rst
:start-after: .. description
:end-before: .. local-definitions
.. |struct| replace:: :mod:`struct`
Features
--------
* declarative description of binary data structures
* specification of data structures up to *bit* level
* automatic *codec* generation from data descriptors
* decoding (from binary data to Python objects)
* encoding (from Python objects to binary data)
* backend:
- :mod:`bpack.st` backend based on the :mod:`struct` module of
standard Python_ library
- :mod:`bpack.bs` backend based on bitstruct_
- :mod:`bpack.np` backend based on numpy_
- :mod:`bpack.ba` backend based on bitarray_
(only included for benchmarking purposes)
* support for signed/unsigned integer types
* support for :class:`enum.Enum` types
* support for sequence types, i.e. fields with multiple (homogeneous) items
* both bit and byte order can be specified by the user
* automatic size determination for some data types
* record nesting (the field in a record descriptor can be another record)
* possibility to specify data types using the special type annotation class
:class:`bpack.typing.T` that accepts annotations and string specifiers
compatible with the numpy_ "Array Interface" and ``dtype``
* comprehensive test suite
Limitations
-----------
* only fixed size binary records are supported by design, the size of the
record shall be known at the moment of the record descriptor definition.
It should be easy for the user to leverage tools provided by the *bpack*
Python package to support more complex decoding scenarios.
* currently it is assumed that all fields in a binary record share the
same bit/byte order. The management of different byte order in the same
binary record is, in principle, possible but not planned at the moment.
* sequence types can only contain basic numeric types; nested sequences,
sequences of enums or sequences of records are not allowed at the moment.
* record nesting is only possible for records having the same base-units,
bits or bytes, and compatible decoder types eventually.
* currently the :mod:`bpack.np` has a limited (incomplete) support to record
nesting and encoding capabilities.
Possible additional features still not implemented
--------------------------------------------------
* user defined converters
* support for complex and datetime data types
* conversion to CSV, HDF5 and :func:`numpy.dtype`
.. _Python: https://www.python.org
.. _bitstruct: https://github.com/eerimoq/bitstruct
.. _numpy: https://numpy.org
.. _bitarray: https://github.com/ilanschnell/bitarray
|
