Using pycrate core objects

How to use pycrate core objects:

• the Charpy object: a bit string handler and consumer
• the pack_val function: a bit string concatener
• Atom objects: Element representing a basic value
• the Envelope object: sequence of Elements
• the Array object: repeated list of an immutable Element
• the Sequence object: repeated list of a mutable Element

Charpy

The Charpy class enables to deal with bit strings in Python ; more specifically, it exposes a simple API to consume a given bytes buffer into signed or unsigned, big or little endian, integral values, or shorter bytes buffers, providing a length in bits.

The class is defined in the pycrate_core/charpy.py file.

>>> from pycrate_core.charpy import Charpy
>>> help(Charpy) # a doc string is provided
[...]
>>> c = Charpy(b'this is a buffer')
>>> c
charpy(b'this is a buffer')
>>> c.bin()
'01110100011010000110100101110011001000000110100101110011001000000110000100100000011000100111010101100110011001100110010101110010'
>>> c.hex()
'74686973206973206120627566666572'
>>> c._cur # current position of the cursor in the Charpy instance
0
>>> c.len_bit() # current length in bits of the remaining buffer
128
>>> c.get_int(12) # returns the value of a 12 bits integer
1862
>>> c
charpy(b"\x86\x972\x06\x972\x06\x12\x06'VffW ")
>>> c.get_int_le(12) # returns the value of a little endian 12 bits integer
-122
>>> c.get_uint(27) # returns the value of a 27 bits unsigned integer
79269940
>>> c.len_bit() # current length in bits of the remaining buffer (128-12-12-27)
81
>>> c._cur # 12 + 12 + 27
47
>>> c.get_bytes(38) # returns the buffer corresponding to the next 38 bits (zeroing last bits of the last byte)
'\xb9\x900\x900'
>>> c.get_bitlist(6) # returns the list of next 0 or 1
[0, 1, 0, 0, 1, 1]
>>> c.get_bytelist(22) # returns the list of next 22 bits unsigned byte value (zeroing last bits of the last byte)
[171, 51, 48]
>>> c.len_bit()
15
>>> c._cur
113
>>> c.get_uint(32) # this raises as there is only 15 remaining bits available from the original buffer

Traceback (most recent call last):
  File "<pyshell#20>", line 1, in <module>
    c.get_uint(32)
  File "C:\Python27\lib\site-packages\pycrate-0.1.0-py2.7.egg\pycrate_core\charpy.py", line 797, in get_uint
    .format(bitlen, self._len_bit-self._cur)))
CharpyErr: bitlen overflow: 32, max 15
>>> c.rewind(17) # if no args are passed, i.e. c.rewind(), this sets the cursor to 0, reinitializing the original buffer
>>> c._cur
96
>>> c.len_bit()
32
>>> c.get_uint(32)
1717986674

pack_val

The pack_val function allows to pack a list of composite values: signed or unsigned, big or little endian, integral values, or bytes buffers, specifying their length in bits. The function then returns the resulting bytes buffer after concatenating all those composite values. It is the revert part of the Charpy class.

The function is defined in pycrate_core/utils_py2.py and pycrate_core/utils_py3.py, and is made available in an uniform way by importing the utils.py module.

>>> from pycrate_core.utils import pack_val
>>> help(pack_val) # a doc string is provided
[...]

Element parent class

TODO

Atom basic classes

TODO

Envelope class

TODO

Array class

TODO

Sequence class

TODO