Belle II Software  release-05-01-25
scripts.bitstring Namespace Reference

Classes

class  BitArray
 
class  Bits
 
class  BitStream
 
class  ByteAlignError
 
class  ByteStore
 
class  ConstBitStream
 
class  ConstByteStore
 
class  CreationError
 
class  Error
 
class  InterpretError
 
class  MmapByteArray
 
class  ReadError
 

Functions

def offsetcopy (s, newoffset)
 
def equal (a, b)
 
def tidy_input_string (s)
 
def structparser (token)
 
def tokenparser (fmt, keys=None, token_cache={})
 
def expand_brackets (s)
 
def pack (fmt, *values, **kwargs)
 

Variables

string __licence__
 
string __version__ = "3.1.5"
 
string __author__ = "Scott Griffiths"
 
 byteorder = sys.byteorder
 
bool bytealigned = False
 
int MAX_CHARS = 250
 
int CACHE_SIZE = 1000
 
 BYTE_REVERSAL_DICT = dict()
 
 xrange = range
 
 basestring = str
 
int LEADING_OCT_CHARS = len(oct(1)) - 1
 
tuple INIT_NAMES
 
 TOKEN_RE
 
 DEFAULT_UINT = re.compile(r'(?P<len>[^=]+)?(=(?P<value>.*))?$', re.IGNORECASE)
 
 MULTIPLICATIVE_RE = re.compile(r'(?P<factor>.*)\*(?P<token>.+)')
 
 LITERAL_RE = re.compile(r'(?P<name>0(x|o|b))(?P<value>.+)', re.IGNORECASE)
 
 STRUCT_PACK_RE = re.compile(r'(?P<endian><|>|@)?(?P<fmt>(?:\d*[bBhHlLqQfd])+)$')
 
 STRUCT_SPLIT_RE = re.compile(r'\d*[bBhHlLqQfd]')
 
dictionary REPLACEMENTS_BE
 
dictionary REPLACEMENTS_LE
 
dictionary PACK_CODE_SIZE
 
dictionary _tokenname_to_initialiser
 
 BRACKET_RE = re.compile(r'(?P<factor>\d+)\*\(')
 
list OCT_TO_BITS = ['{0:03b}'.format(i) for i in xrange(8)]
 
 BIT_COUNT = dict(zip(xrange(256), [bin(i).count('1') for i in xrange(256)]))
 
dictionary name_to_read
 
dictionary init_with_length_and_offset
 
dictionary init_with_length_only
 
dictionary init_without_length_or_offset
 
 ConstBitArray = Bits
 
 BitString = BitStream
 
list __all__
 

Detailed Description

This package defines classes that simplify bit-wise creation, manipulation and
interpretation of data.

Classes:

Bits -- An immutable container for binary data.
BitArray -- A mutable container for binary data.
ConstBitStream -- An immutable container with streaming methods.
BitStream -- A mutable container with streaming methods.

                  Bits (base class)
                 /    \
 + mutating methods /      \ + streaming methods
               /        \
          BitArray   ConstBitStream
               \        /
                \      /
                 \    /
                BitStream

Functions:

pack -- Create a BitStream from a format string.

Exceptions:

Error -- Module exception base class.
CreationError -- Error during creation.
InterpretError -- Inappropriate interpretation of binary data.
ByteAlignError -- Whole byte position or length needed.
ReadError -- Reading or peeking past the end of a bitstring.

https://github.com/scott-griffiths/bitstring

Function Documentation

◆ equal()

def scripts.bitstring.equal (   a,
  b 
)
Return True if ByteStores a == b.

Not part of public interface.

Definition at line 291 of file bitstring.py.

291 def equal(a, b):
292  """Return True if ByteStores a == b.
293 
294  Not part of public interface.
295  """
296  # We want to return False for inequality as soon as possible, which
297  # means we get lots of special cases.
298  # First the easy one - compare lengths:
299  a_bitlength = a.bitlength
300  b_bitlength = b.bitlength
301  if a_bitlength != b_bitlength:
302  return False
303  if not a_bitlength:
304  assert b_bitlength == 0
305  return True
306  # Make 'a' the one with the smaller offset
307  if (a.offset % 8) > (b.offset % 8):
308  a, b = b, a
309  # and create some aliases
310  a_bitoff = a.offset % 8
311  b_bitoff = b.offset % 8
312  a_byteoffset = a.byteoffset
313  b_byteoffset = b.byteoffset
314  a_bytelength = a.bytelength
315  b_bytelength = b.bytelength
316  da = a._rawarray
317  db = b._rawarray
318 
319  # If they are pointing to the same data, they must be equal
320  if da is db and a.offset == b.offset:
321  return True
322 
323  if a_bitoff == b_bitoff:
324  bits_spare_in_last_byte = 8 - (a_bitoff + a_bitlength) % 8
325  if bits_spare_in_last_byte == 8:
326  bits_spare_in_last_byte = 0
327  # Special case for a, b contained in a single byte
328  if a_bytelength == 1:
329  a_val = ((da[a_byteoffset] << a_bitoff) & 0xff) >> (8 - a_bitlength)
330  b_val = ((db[b_byteoffset] << b_bitoff) & 0xff) >> (8 - b_bitlength)
331  return a_val == b_val
332  # Otherwise check first byte
333  if da[a_byteoffset] & (0xff >> a_bitoff) != db[b_byteoffset] & (0xff >> b_bitoff):
334  return False
335  # then everything up to the last
336  b_a_offset = b_byteoffset - a_byteoffset
337  for x in range(1 + a_byteoffset, a_byteoffset + a_bytelength - 1):
338  if da[x] != db[b_a_offset + x]:
339  return False
340  # and finally the last byte
341  return (da[a_byteoffset + a_bytelength - 1] >> bits_spare_in_last_byte ==
342  db[b_byteoffset + b_bytelength - 1] >> bits_spare_in_last_byte)
343 
344  assert a_bitoff != b_bitoff
345  # This is how much we need to shift a to the right to compare with b:
346  shift = b_bitoff - a_bitoff
347  # Special case for b only one byte long
348  if b_bytelength == 1:
349  assert a_bytelength == 1
350  a_val = ((da[a_byteoffset] << a_bitoff) & 0xff) >> (8 - a_bitlength)
351  b_val = ((db[b_byteoffset] << b_bitoff) & 0xff) >> (8 - b_bitlength)
352  return a_val == b_val
353  # Special case for a only one byte long
354  if a_bytelength == 1:
355  assert b_bytelength == 2
356  a_val = ((da[a_byteoffset] << a_bitoff) & 0xff) >> (8 - a_bitlength)
357  b_val = ((db[b_byteoffset] << 8) + db[b_byteoffset + 1]) << b_bitoff
358  b_val &= 0xffff
359  b_val >>= 16 - b_bitlength
360  return a_val == b_val
361 
362  # Compare first byte of b with bits from first byte of a
363  if (da[a_byteoffset] & (0xff >> a_bitoff)) >> shift != db[b_byteoffset] & (0xff >> b_bitoff):
364  return False
365  # Now compare every full byte of b with bits from 2 bytes of a
366  for x in range(1, b_bytelength - 1):
367  # Construct byte from 2 bytes in a to compare to byte in b
368  b_val = db[b_byteoffset + x]
369  a_val = ((da[a_byteoffset + x - 1] << 8) + da[a_byteoffset + x]) >> shift
370  a_val &= 0xff
371  if a_val != b_val:
372  return False
373 
374  # Now check bits in final byte of b
375  final_b_bits = (b.offset + b_bitlength) % 8
376  if not final_b_bits:
377  final_b_bits = 8
378  b_val = db[b_byteoffset + b_bytelength - 1] >> (8 - final_b_bits)
379  final_a_bits = (a.offset + a_bitlength) % 8
380  if not final_a_bits:
381  final_a_bits = 8
382  if b.bytelength > a_bytelength:
383  assert b_bytelength == a_bytelength + 1
384  a_val = da[a_byteoffset + a_bytelength - 1] >> (8 - final_a_bits)
385  a_val &= 0xff >> (8 - final_b_bits)
386  return a_val == b_val
387  assert a_bytelength == b_bytelength
388  a_val = da[a_byteoffset + a_bytelength - 2] << 8
389  a_val += da[a_byteoffset + a_bytelength - 1]
390  a_val >>= (8 - final_a_bits)
391  a_val &= 0xff >> (8 - final_b_bits)
392  return a_val == b_val
393 
394 

◆ expand_brackets()

def scripts.bitstring.expand_brackets (   s)
Remove whitespace and expand all brackets.

Definition at line 645 of file bitstring.py.

◆ offsetcopy()

def scripts.bitstring.offsetcopy (   s,
  newoffset 
)
Return a copy of a ByteStore with the newoffset.

Not part of public interface.

Definition at line 249 of file bitstring.py.

◆ pack()

def scripts.bitstring.pack (   fmt,
values,
**  kwargs 
)
Pack the values according to the format string and return a new BitStream.

fmt -- A single string or a list of strings with comma separated tokens
       describing how to create the BitStream.
values -- Zero or more values to pack according to the format.
kwargs -- A dictionary or keyword-value pairs - the keywords used in the
          format string will be replaced with their given value.

Token examples: 'int:12'    : 12 bits as a signed integer
                'uint:8'    : 8 bits as an unsigned integer
                'float:64'  : 8 bytes as a big-endian float
                'intbe:16'  : 2 bytes as a big-endian signed integer
                'uintbe:16' : 2 bytes as a big-endian unsigned integer
                'intle:32'  : 4 bytes as a little-endian signed integer
                'uintle:32' : 4 bytes as a little-endian unsigned integer
                'floatle:64': 8 bytes as a little-endian float
                'intne:24'  : 3 bytes as a native-endian signed integer
                'uintne:24' : 3 bytes as a native-endian unsigned integer
                'floatne:32': 4 bytes as a native-endian float
                'hex:80'    : 80 bits as a hex string
                'oct:9'     : 9 bits as an octal string
                'bin:1'     : single bit binary string
                'ue' / 'uie': next bits as unsigned exp-Golomb code
                'se' / 'sie': next bits as signed exp-Golomb code
                'bits:5'    : 5 bits as a bitstring object
                'bytes:10'  : 10 bytes as a bytes object
                'bool'      : 1 bit as a bool
                'pad:3'     : 3 zero bits as padding

>>> s = pack('uint:12, bits', 100, '0xffe')
>>> t = pack(['bits', 'bin:3'], s, '111')
>>> u = pack('uint:8=a, uint:8=b, uint:55=a', a=6, b=44)

Definition at line 4164 of file bitstring.py.

◆ structparser()

def scripts.bitstring.structparser (   token)
Parse struct-like format string token into sub-token list.

Definition at line 510 of file bitstring.py.

◆ tidy_input_string()

def scripts.bitstring.tidy_input_string (   s)
Return string made lowercase and with all whitespace removed.

Definition at line 462 of file bitstring.py.

◆ tokenparser()

def scripts.bitstring.tokenparser (   fmt,
  keys = None,
  token_cache = {} 
)
Divide the format string into tokens and parse them.

Return stretchy token and list of [initialiser, length, value]
initialiser is one of: hex, oct, bin, uint, int, se, ue, 0x, 0o, 0b etc.
length is None if not known, as is value.

If the token is in the keyword dictionary (keys) then it counts as a
special case and isn't messed with.

tokens must be of the form: [factor*][initialiser][:][length][=value]

Definition at line 539 of file bitstring.py.

Variable Documentation

◆ __all__

list __all__
private
Initial value:
1 = ['ConstBitArray', 'ConstBitStream', 'BitStream', 'BitArray',
2  'Bits', 'BitString', 'pack', 'Error', 'ReadError',
3  'InterpretError', 'ByteAlignError', 'CreationError', 'bytealigned']

Definition at line 4243 of file bitstring.py.

◆ __licence__

string __licence__
private
Initial value:
1 = """
2 The MIT License
3 
4 Copyright (c) 2006-2016 Scott Griffiths (dr.scottgriffiths@gmail.com)
5 
6 Permission is hereby granted, free of charge, to any person obtaining a copy
7 of this software and associated documentation files (the "Software"), to deal
8 in the Software without restriction, including without limitation the rights
9 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 copies of the Software, and to permit persons to whom the Software is
11 furnished to do so, subject to the following conditions:
12 
13 The above copyright notice and this permission notice shall be included in
14 all copies or substantial portions of the Software.
15 
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 THE SOFTWARE.
23 """

Definition at line 38 of file bitstring.py.

◆ _tokenname_to_initialiser

dictionary _tokenname_to_initialiser
private
Initial value:
1 = {'hex': 'hex', '0x': 'hex', '0X': 'hex', 'oct': 'oct',
2  '0o': 'oct', '0O': 'oct', 'bin': 'bin', '0b': 'bin',
3  '0B': 'bin', 'bits': 'auto', 'bytes': 'bytes', 'pad': 'pad'}

Definition at line 505 of file bitstring.py.

◆ INIT_NAMES

tuple INIT_NAMES
Initial value:
1 = ('uint', 'int', 'ue', 'se', 'sie', 'uie', 'hex', 'oct', 'bin', 'bits',
2  'uintbe', 'intbe', 'uintle', 'intle', 'uintne', 'intne',
3  'float', 'floatbe', 'floatle', 'floatne', 'bytes', 'bool', 'pad')

Definition at line 468 of file bitstring.py.

◆ init_with_length_and_offset

dictionary init_with_length_and_offset
Initial value:
1 = {'bytes': Bits._setbytes_safe,
2  'filename': Bits._setfile,
3  }

Definition at line 2914 of file bitstring.py.

◆ init_with_length_only

dictionary init_with_length_only
Initial value:
1 = {'uint': Bits._setuint,
2  'int': Bits._setint,
3  'float': Bits._setfloat,
4  'uintbe': Bits._setuintbe,
5  'intbe': Bits._setintbe,
6  'floatbe': Bits._setfloat,
7  'uintle': Bits._setuintle,
8  'intle': Bits._setintle,
9  'floatle': Bits._setfloatle,
10  'uintne': Bits._setuintne,
11  'intne': Bits._setintne,
12  'floatne': Bits._setfloatne,
13  }

Definition at line 2918 of file bitstring.py.

◆ init_without_length_or_offset

dictionary init_without_length_or_offset
Initial value:
1 = {'bin': Bits._setbin_safe,
2  'hex': Bits._sethex,
3  'oct': Bits._setoct,
4  'ue': Bits._setue,
5  'se': Bits._setse,
6  'uie': Bits._setuie,
7  'sie': Bits._setsie,
8  'bool': Bits._setbool,
9  }

Definition at line 2932 of file bitstring.py.

◆ name_to_read

dictionary name_to_read
Initial value:
1 = {'uint': Bits._readuint,
2  'uintle': Bits._readuintle,
3  'uintbe': Bits._readuintbe,
4  'uintne': Bits._readuintne,
5  'int': Bits._readint,
6  'intle': Bits._readintle,
7  'intbe': Bits._readintbe,
8  'intne': Bits._readintne,
9  'float': Bits._readfloat,
10  'floatbe': Bits._readfloat, # floatbe is a synonym for float
11  'floatle': Bits._readfloatle,
12  'floatne': Bits._readfloatne,
13  'hex': Bits._readhex,
14  'oct': Bits._readoct,
15  'bin': Bits._readbin,
16  'bits': Bits._readbits,
17  'bytes': Bits._readbytes,
18  'ue': Bits._readue,
19  'se': Bits._readse,
20  'uie': Bits._readuie,
21  'sie': Bits._readsie,
22  'bool': Bits._readbool,
23  }

Definition at line 2889 of file bitstring.py.

◆ PACK_CODE_SIZE

dictionary PACK_CODE_SIZE
Initial value:
1 = {'b': 1, 'B': 1, 'h': 2, 'H': 2, 'l': 4, 'L': 4,
2  'q': 8, 'Q': 8, 'f': 4, 'd': 8}

Definition at line 502 of file bitstring.py.

◆ REPLACEMENTS_BE

dictionary REPLACEMENTS_BE
Initial value:
1 = {'b': 'intbe:8', 'B': 'uintbe:8',
2  'h': 'intbe:16', 'H': 'uintbe:16',
3  'l': 'intbe:32', 'L': 'uintbe:32',
4  'q': 'intbe:64', 'Q': 'uintbe:64',
5  'f': 'floatbe:32', 'd': 'floatbe:64'}

Definition at line 489 of file bitstring.py.

◆ REPLACEMENTS_LE

dictionary REPLACEMENTS_LE
Initial value:
1 = {'b': 'intle:8', 'B': 'uintle:8',
2  'h': 'intle:16', 'H': 'uintle:16',
3  'l': 'intle:32', 'L': 'uintle:32',
4  'q': 'intle:64', 'Q': 'uintle:64',
5  'f': 'floatle:32', 'd': 'floatle:64'}

Definition at line 495 of file bitstring.py.

◆ TOKEN_RE

TOKEN_RE
Initial value:
1 = re.compile(r'(?P<name>' + '|'.join(INIT_NAMES) +
2  r')((:(?P<len>[^=]+)))?(=(?P<value>.*))?$', re.IGNORECASE)

Definition at line 472 of file bitstring.py.