Classes

BitString and Bits

The bitstring module provides just two classes, BitString and Bits. These share many methods as Bits is the base class for BitString. The distinction between them is that Bits represents an immutable sequence of bits whereas BitString objects support many methods that mutate their contents.

If you need to change the contents of a bitstring then you must use the BitString class. If you need to use bitstrings as keys in a dictionary or members of a set then you must use the Bits class (Bits are hashable). Otherwise you can use whichever you prefer, but note that Bits objects can potentially be more efficent than BitString objects. In this section the generic term ‘bitstring’ means either a Bits or a BitString object.

Note that the bit position within the bitstring (the position from which reads occur) can change without affecting the equality operation. This means that the pos and bytepos properties can change even for a Bits object.

The public methods, special methods and properties of both classes are detailed in this section.

The auto initialiser

Note that in places where a bitstring can be used as a parameter, any other valid input to the auto initialiser can also be used. This means that the parameter can also be a format string which consists of tokens:

  • Starting with hex=, or simply starting with 0x implies hexadecimal. e.g. 0x013ff, hex=013ff
  • Starting with oct=, or simply starting with 0o implies octal. e.g. 0o755, oct=755
  • Starting with bin=, or simply starting with 0b implies binary. e.g. 0b0011010, bin=0011010
  • Starting with int: or uint: followed by a length in bits and = gives base-2 integers. e.g. uint:8=255, int:4=-7
  • To get big, little and native-endian whole-byte integers append be, le or ne respectively to the uint or int identifier. e.g. uintle:32=1, intne:16=-23
  • For floating point numbers use float: followed by the length in bits and = and the number. The default is big-endian, but you can also append be, le or ne as with integers. e.g. float:64=0.2, floatle:32=-0.3e12
  • Starting with ue= or se= implies an exponential-Golomb coded integer. e.g. ue=12, se=-4

Multiples tokens can be joined by separating them with commas, so for example se=4, 0b1, se=-1 represents the concatenation of three elements.

Parentheses and multiplicative factors can also be used, for example 2*(0b10, 0xf) is equivalent to 0b10, 0xf, 0b10, 0xf. The multiplying factor must come before the thing it is being used to repeat.

The auto parameter also accepts other types:

  • A list or tuple, whose elements will be evaluated as booleans (imagine calling bool() on each item) and the bits set to 1 for True items and 0 for False items.
  • A positive integer, used to create a bitstring of that many zero bits.
  • A file object, presumably opened in read-binary mode, from which the bitstring will be formed.
  • A bool (True or False) which will be converted to a single 1 or 0 bit respectively.
  • A bytearray object.
  • In Python 3 only, a bytes object. Note this won’t work for Python 2 as bytes is just a synonym for str.

Compact format strings

For the Bits.read, Bits.unpack, Bits.peek methods and pack function you can use compact format strings similar to those used in the struct and array modules. These start with an endian identifier: > for big-endian, < for little-endian or @ for native-endian. This must be followed by at least one of these codes:

Code Interpretation
b 8 bit signed integer
B 8 bit unsigned integer
h 16 bit signed integer
H 16 bit unsigned integer
l 32 bit signed integer
L 32 bit unsigned integer
q 64 bit signed integer
Q 64 bit unsigned integer
f 32 bit floating point number
d 64 bit floating point number

For more detail see Compact format strings.

The Bits class

class Bits([auto, length, offset, **kwargs])

Creates a new bitstring. You must specify either no initialiser, just an auto value, or one of the keyword arguments bytes, bin, hex, oct, uint, int, uintbe, intbe, uintle, intle, uintne, intne, se, ue, float, floatbe, floatle, floatne or filename. If no initialiser is given then a zeroed bitstring of length bits is created.

The initialiser for the Bits class is precisely the same as for BitString.

offset is optional for most initialisers, but only really useful for bytes and filename. It gives a number of bits to ignore at the start of the bitstring.

Specifying length is mandatory when using the various integer initialisers. It must be large enough that a bitstring can contain the integer in length bits. It must also be specified for the float initialisers (the only valid values are 32 and 64). It is optional for the bytes and filename initialisers and can be used to truncate data from the end of the input value.

>>> s1 = Bits(hex='0x934')
>>> s2 = Bits(oct='0o4464')
>>> s3 = Bits(bin='0b001000110100')
>>> s4 = Bits(int=-1740, length=12)
>>> s5 = Bits(uint=2356, length=12)
>>> s6 = Bits(bytes='\x93@', length=12)
>>> s1 == s2 == s3 == s4 == s5 == s6
True

For information on the use of the auto initialiser see the introduction to this section.

>>> s = Bits('uint:12=32, 0b110')
>>> t = Bits('0o755, ue:12, int:3=-1')
allset(value, pos)

Returns True if all of the specified bits are all set to value, otherwise returns False.

If value is True then 1 bits are checked for, otherwise 0 bits are checked for.

pos should be an iterable of bit positions. Negative numbers are treated in the same way as slice indices and it will raise an IndexError if pos < -s.len or pos > s.len

anyset(value, pos)

Returns True if any of the specified bits are set to value, otherwise returns False.

If value is True then 1` bits are checked for, otherwise ``0 bits are checked for.

pos should be an iterable of bit positions. Negative numbers are treated in the same way as slice indices and it will raise an IndexError if pos < -s.len or pos > s.len

bytealign()

Aligns to the start of the next byte (so that pos is a multiple of 8) and returns the number of bits skipped.

If the current position is already byte aligned then it is unchanged.

>>> s = Bits('0xabcdef')
>>> s.pos += 3
>>> s.bytealign()
5
>>> s.pos
8
cut(bits[, start, end, count])

Returns a generator for slices of the bitstring of length bits.

At most count items are returned and the range is given by the slice [start:end], which defaults to the whole bitstring.

>>> s = BitString('0x1234')
>>> for nibble in s.cut(4):
...     s.prepend(nibble)
>>> print(s)
0x43211234
endswith(bs[, start, end])

Returns True if the bitstring ends with the sub-string bs, otherwise returns False.

A slice can be given using the start and end bit positions and defaults to the whole bitstring.

>>> s = Bits('0x35e22')
>>> s.endswith('0b10, 0x22')
True
>>> s.endswith('0x22', start=13)
False
find(bs[, start, end, bytealigned=False])

Searches for bs in the current bitstring and sets pos to the start of bs and returns True if found, otherwise it returns False.

If bytealigned is True then it will look for bs only at byte aligned positions (which is generally much faster than searching for it in every possible bit position). start and end give the search range and default to the whole bitstring.

>>> s = Bits('0x0023122')
>>> s.find('0b000100', bytealigned=True)
True
>>> s.pos
16
findall(bs[, start, end, count, bytealigned=False])

Searches for all occurrences of bs (even overlapping ones) and returns a generator of their bit positions.

If bytealigned is True then bs will only be looked for at byte aligned positions. start and end optionally define a search range and default to the whole bitstring.

The count paramater limits the number of items that will be found - the default is to find all occurences.

>>> s = Bits('0xab220101')*5
>>> list(s.findall('0x22', bytealigned=True))
[8, 40, 72, 104, 136]
join(sequence)

Returns the concatenation of the bitstrings in the iterable sequence joined with self as a separator.

>>> s = Bits().join(['0x0001ee', 'uint:24=13', '0b0111'])
>>> print(s)
0x0001ee00000d7

>>> s = Bits('0b1').join(['0b0']*5)
>>> print(s.bin)
0b010101010
peek(fmt)

Reads from the current bit position pos in the bitstring according to the fmt string or integer and returns the result.

The bit position is unchanged.

For information on the format string see the entry for the Bits.read method.

peeklist(fmt, **kwargs)

Reads from current bit position pos in the bitstring according to the fmt string(s) and returns a list of results.

A dictionary or keyword arguments can also be provided. These will replace length identifiers in the format string. The position is not advanced to after the read items.

See the entries for Bits.read and Bits.readlist for more information.

read(fmt)

Reads from current bit position pos in the bitstring according the the format string and returns a single result. If not enough bits are available then all bits to the end of the bitstring will be used.

fmt is either a token string that describes how to interpret the next bits in the bitstring or an integer. If it’s an integer then that number of bits will be read, and returned as a new bitstring. Otherwise the tokens are:

int:n n bits as a signed integer.
uint:n n bits as an unsigned integer.
float:n n bits as a floating point number.
intbe:n n bits as a big-endian signed integer.
uintbe:n n bits as a big-endian unsigned integer.
floatbe:n n bits as a big-endian float.
intle:n n bits as a little-endian signed int.
uintle:n n bits as a little-endian unsigned int.
floatle:n n bits as a little-endian float.
intne:n n bits as a native-endian signed int.
uintne:n n bits as a native-endian unsigned int.
floatne:n n bits as a native-endian float.
hex:n n bits as a hexadecimal string.
oct:n n bits as an octal string.
bin:n n bits as a binary string.
ue next bits as an unsigned exp-Golomb.
se next bits as a signed exp-Golomb.
bits:n n bits as a new bitstring.
bytes:n n bytes as bytes object.
bool next bit as a boolean.

For example:

>>> s = Bits('0x23ef55302')
>>> s.read('hex12')
'0x23e'
>>> s.read('bin:4')
'0b1111'
>>> s.read('uint:5')
10
>>> s.read('bits:4')
Bits('0xa')

The Bits.read method is useful for reading exponential-Golomb codes.

>>> s = Bits('se=-9, ue=4')
>>> s.read('se')
-9
>>> s.read('ue')
4
readlist(fmt, **kwargs)

Reads from current bit position pos in the bitstring according to the fmt string(s)/integer(s) and returns a list of results. If not enough bits are available then all bits to the end of the bitstring will be used.

A dictionary or keyword arguments can also be provided. These will replace length identifiers in the format string. The position is advanced to after the read items.

See the entry for Bits.read for information on the format strings.

For multiple items you can separate using commas or given multiple parameters:

>>> s = Bits('0x43fe01ff21')
>>> s.readlist('hex:8, uint:6')
['0x43', 63]
>>> s.readlist(['bin:3', 'intle:16'])
['0b100', -509]
>>> s.pos = 0
>>> s.readlist('hex:b, uint:d', b=8, d=6)
['0x43', 63]
rfind(bs[, start, end, bytealigned=False])

Searches backwards for bs in the current bitstring and returns True if found, otherwise returns False.

If bytealigned is True then it will look for bs only at byte aligned positions. start and end give the search range and default to 0 and len respectively.

Note that as it’s a reverse search it will start at end and finish at start.

>>> s = Bits('0o031544')
>>> s.rfind('0b100')
True
>>> s.pos
15
>>> s.rfind('0b100', end=17)
True
>>> s.pos
12
split(delimiter[, start, end, count, bytealigned=False])

Splits the bitstring into sections that start with delimiter. Returns a generator for bitstring objects.

The first item generated is always the bits before the first occurrence of delimiter (even if empty). A slice can be optionally specified with start and end, while count specifies the maximum number of items generated.

If bytealigned is True then the delimiter will only be found if it starts at a byte aligned position.

>>> s = Bits('0x42423')
>>> [bs.bin for bs in s.split('0x4')]
['', '0b01000', '0b01001000', '0b0100011']
startswith(bs[, start, end])

Returns True if the bitstring starts with the sub-string bs, otherwise returns False.

A slice can be given using the start and end bit positions and defaults to the whole bitstring.

tobytes()

Returns the bitstring as a bytes object (equivalent to a str in Python 2.6).

The returned value will be padded at the end with between zero and seven 0 bits to make it byte aligned.

The Bits.tobytes method can also be used to output your bitstring to a file - just open a file in binary write mode and write the function’s output.

>>> s = Bits(bytes='hello')
>>> s += '0b01'
>>> s.tobytes()
'hello@'
tofile(f)

Writes the bitstring to the file object f, which should have been opened in binary write mode.

The data written will be padded at the end with between zero and seven 0 bits to make it byte aligned.

>>> f = open('newfile', 'wb')
>>> Bits('0x1234').tofile(f)
unpack(fmt, **kwargs)

Interprets the whole bitstring according to the fmt string(s) and returns a list of bitstring objects.

A dictionary or keyword arguments can also be provided. These will replace length identifiers in the format string.

fmt is one or more strings with comma separated tokens that describe how to interpret the next bits in the bitstring. See the entry for Bits.read for details.

>>> s = Bits('int:4=-1, 0b1110')
>>> i, b = s.unpack('int:4, bin')

If a token doesn’t supply a length (as with bin above) then it will try to consume the rest of the bitstring. Only one such token is allowed.

__add__(bs)
__radd__(bs)

s1 + s2

Concatenate two bitstring objects and return the result. Either bitstring can be ‘auto’ initialised.

s = Bits(ue=132) + '0xff'
s2 = '0b101' + s
__and__(bs)
__rand__(bs)

s1 & s2

Returns the bit-wise AND between two bitstrings, which must have the same length otherwise a ValueError is raised.

>>> print(Bits('0x33') & '0x0f')
0x03
__contains__(bs)

bs in s

Returns True if bs can be found in the bitstring, otherwise returns False.

Equivalent to using Bits.find, except that pos will not be changed so you don’t know where it was found.

>>> '0b11' in Bits('0x06')
True
>>> '0b111' in Bits('0x06')
False
__copy__()

s2 = copy.copy(s1)

This allows the copy module to correctly copy bitstrings. Other equivalent methods are to initialise a new bitstring with the old one or to take a complete slice.

>>> import copy
>>> s = Bits('0o775')
>>> s_copy1 = copy.copy(s)
>>> s_copy2 = Bits(s)
>>> s_copy3 = s[:]
>>> s == s_copy1 == s_copy2 == s_copy3
True
__eq__(bs)

s1 == s2

Compares two bitstring objects for equality, returning True if they have the same binary representation, otherwise returning False.

>>> Bits('0o7777') == '0xfff'
True
>>> a = Bits(uint=13, length=8)
>>> b = Bits(uint=13, length=10)
>>> a == b
False
__getitem__(key)

s[start:end:step]

Returns a slice of the bitstring.

The usual slice behaviour applies except that the step parameter gives a multiplicative factor for start and end (i.e. the bits ‘stepped over’ are included in the slice).

>>> s = Bits('0x0123456')
>>> s[0:4]
Bits('0x1')
>>> s[0:3:8]
Bits('0x012345')

If a single element is asked for then either True or False will be returned.

>>> s[0]
False
>>> s[-1]
True
__hash__()

hash(s)

Returns an integer hash of the Bits.

This method is not available for the BitString class, as only immutable objects should be hashed. You typically won’t need to call it directly, instead it is used for dictionary keys and in sets.

__invert__()

~s

Returns the bitstring with every bit inverted, that is all zeros replaced with ones, and all ones replaced with zeros.

If the bitstring is empty then an Error will be raised.

>>> s = Bits(‘0b1110010’)
>>> print(~s)
0b0001101
>>> print(~s & s)
0b0000000
__len__()

len(s)

Returns the length of the bitstring in bits if it is less than sys.maxsize, otherwise raises OverflowError.

It’s recommended that you use the len property rather than the len function because of the function’s behaviour for large bitstring objects, although calling the special function directly will always work.

>>> s = Bits(filename='11GB.mkv')
>>> s.len
93944160032
>>> len(s)
OverflowError: long int too large to convert to int
>>> s.__len__()
93944160032
__lshift__(n)

s << n

Returns the bitstring with its bits shifted n places to the left. The n right-most bits will become zeros.

>>> s = Bits('0xff')
>>> s << 4
Bits('0xf0')
__mul__(n)
__rmul__(n)

s * n / n * s

Return bitstring consisting of n concatenations of another.

>>> a = Bits('0x34')
>>> b = a*5
>>> print(b)
0x3434343434
__ne__(bs)

s1 != s2

Compares two bitstring objects for inequality, returning False if they have the same binary representation, otherwise returning True.

__or__(bs)
__ror__(bs)

s1 | s2

Returns the bit-wise OR between two bitstring, which must have the same length otherwise a ValueError is raised.

>>> print(Bits('0x33') | '0x0f')
0x3f
__repr__()

repr(s)

A representation of the bitstring that could be used to create it (which will often not be the form used to create it).

If the result is too long then it will be truncated with ... and the length of the whole will be given.

>>> Bits(‘0b11100011’)
Bits(‘0xe3’)
__rshift__(n)

s >> n

Returns the bitstring with its bits shifted n places to the right. The n left-most bits will become zeros.

>>> s = Bits(‘0xff’)
>>> s >> 4
Bits(‘0x0f’)
__str__()

print(s)

Used to print a representation of of the bitstring, trying to be as brief as possible.

If the bitstring is a multiple of 4 bits long then hex will be used, otherwise either binary or a mix of hex and binary will be used. Very long strings will be truncated with ....

>>> s = Bits('0b1')*7
>>> print(s)
0b1111111
>>> print(s + '0b1')
0xff
__xor__(bs)
__rxor__(bs)

s1 ^ s2

Returns the bit-wise XOR between two bitstrings, which must have the same length otherwise a ValueError is raised.

>>> print(Bits('0x33') ^ '0x0f')
0x3c

The BitString class

class BitString

The Bits class is the base class for BitString and so (with the exception of Bits.__hash__) all of its methods are also available for BitString objects. The initialiser is also the same as for Bits and so won’t be repeated here.

A BitString is a mutable Bits, and so the one thing all of the methods listed here have in common is that they can modify the contents of the bitstring.

append(bs)

Join a BitString to the end of the current BitString.

>>> s = BitString('0xbad')
>>> s.append('0xf00d')
>>> s
BitString('0xbadf00d')
byteswap(fmt[, start, end, repeat=True])

Change the endianness of the BitString in-place according to fmt. Return the number of swaps done.

The fmt can be an integer, an iterable of integers or a compact format string similar to those used in pack (described in Compact format strings). It gives a pattern of byte sizes to use to swap the endianness of the BitString. Note that if you use a compact format string then the endianness identifier (<, > or @) is not needed, and if present it will be ignored.

start and end optionally give a slice to apply the transformation to (it defaults to the whole BitString). If repeat is True then the byte swapping pattern given by the fmt is repeated in its entirety as many times as possible.

>>> s = BitString('0x00112233445566')
>>> s.byteswap(2)
3
>>> s
BitString('0x11003322554466')
>>> s.byteswap('h')
3
>>> s
BitString('0x00112233445566')
>>> s.byteswap([2, 5])
1
>>> s
BitString('0x11006655443322')
insert(bs[, pos])

Inserts bs at pos. After insertion the property pos will be immediately after the inserted bitstring.

The default for pos is the current position.

>>> s = BitString('0xccee')
>>> s.insert('0xd', 8)
>>> s
BitString('0xccdee')
>>> s.insert('0x00')
>>> s
BitString('0xccd00ee')
invert(pos)
Inverts one or many bits from 1 to 0 or vice versa. pos can be either a single bit position or an iterable of bit positions. Negative numbers are treated in the same way as slice indices and it will raise IndexError if pos < -s.len or pos > s.len.
overwrite(bs[, pos])

Replaces the contents of the current BitString with bs at pos. After overwriting pos will be immediately after the overwritten section.

The default for pos is the current position.

>>> s = BitString(length=10)
>>> s.overwrite('0b111', 3)
>>> s
BitString('0b0001110000')
>>> s.pos
6
prepend(bs)

Inserts bs at the beginning of the current BitString.

>>> s = BitString('0b0')
>>> s.prepend('0xf')
>>> s
BitString('0b11110')
replace(old, new[, start, end, count, bytealigned=False])

Finds occurrences of old and replaces them with new. Returns the number of replacements made.

If bytealigned is True then replacements will only be made on byte boundaries. start and end give the search range and default to 0 and len respectively. If count is specified then no more than this many replacements will be made.

>>> s = BitString('0b0011001')
>>> s.replace('0b1', '0xf')
3
>>> print(s.bin)
0b0011111111001111
>>> s.replace('0b1', '', count=6)
6
>>> print(s.bin)
0b0011001111
reverse([start, end])

Reverses bits in the BitString in-place.

start and end give the range and default to 0 and len respectively.

>>> a = BitString('0b10111')
>>> a.reversebits()
>>> a.bin
'0b11101'
reversebytes([start, end])

Reverses bytes in the BitString in-place.

start and end give the range and default to 0 and len respectively. Note that start and end are specified in bits so if end - start is not a multiple of 8 then a Error is raised.

Can be used to change the endianness of the BitString.

>>> s = BitString('uintle:32=1234')
>>> s.reversebytes()
>>> print(s.uintbe)
1234
rol(bits[, start, end])

Rotates the contents of the BitString in-place by bits bits to the left.

start and end define the slice to use and default to 0 and len respectively.

Raises ValueError if bits < 0.

>>> s = BitString('0b01000001')
>>> s.rol(2)
>>> s.bin
'0b00000101'
ror(bits[, start, end])

Rotates the contents of the BitString in-place by bits bits to the right.

start and end define the slice to use and default to 0 and len respectively.

Raises ValueError if bits < 0.

set(value, pos)

Sets one or many bits to either 1 (if value is True) or 0 (if value isn’t True). pos can be either a single bit position or an iterable of bit positions. Negative numbers are treated in the same way as slice indices and it will raise IndexError if pos < -s.len or pos > s.len.

Using s.set(True, x) can be more efficent than other equivalent methods such as s[x] = 1, s[x] = "0b1" or s.overwrite('0b1', x), especially if many bits are being set.

>>> s = BitString('0x0000')
>>> s.set(True, -1)
>>> print(s)
0x0001
>>> s.set(True, (0, 4, 5, 7, 9))
>>> s.bin
'0b1000110101000001'
__delitem__(key)

del s[start:end:step]

Deletes the slice specified.

After deletion pos will be at the deleted slice’s position.

__iadd__(bs)

s1 += s2

Return the result of appending bs to the current bitstring.

Note that for BitString objects this will be an in-place change, whereas for Bits objects using += will not call this method - instead a new object will be created (it is equivalent to a copy and an Bits.__add__).

>>> s = BitString(ue=423)
>>> s += BitString(ue=12)
>>> s.read('ue')
423
>>> s.read('ue')
12
__setitem__(key, value)

s1[start:end:step] = s2

Replaces the slice specified with a new value.

>>> s = BitString('0x00112233')
>>> s[1:2:8] = '0xfff'
>>> print(s)
0x00fff2233
>>> s[-12:] = '0xc'
>>> print(s)
0x00fff2c

Class properties

Bitstrings use a wide range of properties for getting and setting different interpretations on the binary data, as well as accessing bit lengths and positions.

The different interpretations such as bin, hex, uint etc. are not stored as part of the object, but are calculated as needed. Note that these are only available as ‘getters’ for Bits objects, but can also be ‘setters’ for the mutable BitString objects.

bin

Property for the representation of the bitstring as a binary string starting with 0b.

When used as a getter, the returned value is always calculated - the value is never cached. For BitString objects it can also be used as a setter, in which case the length of the BitString will be adjusted to fit its new contents.

if s.bin == '0b001':
    s.bin = '0b1111'
# Equivalent to s.append('0b1'), only for BitStrings, not Bits.
s.bin += '1'
bool

Property for representing the bitstring as a boolean (True or False).

If the bitstring is not a single bit then the getter will raise an InterpretError.

bytepos
Property for setting and getting the current byte position in the bitstring. When used as a getter will raise a ByteAlignError if the current position in not byte aligned.
bytes

Property representing the underlying byte data that contains the bitstring.

For BitString objects it can also be set using an ordinary Python string - the length will be adjusted to contain the data.

When used as a getter the bitstring must be a whole number of byte long or a ValueError will be raised.

An alternative is to use the tobytes method, which will pad with between zero and seven 0 bits to make it byte aligned if needed.

>>> s = BitString(bytes='\x12\xff\x30')
>>> s.bytes
'\x12\xff0'
>>> s.hex = '0x12345678'
>>> s.bytes
'\x124Vx'
hex

Property representing the hexadecimal value of the bitstring.

When used as a getter the value will be preceded by 0x, which is optional when setting the value of a BitString. If the bitstring is not a multiple of four bits long then getting its hex value will raise a InterpretError.

>>> s = BitString(bin='1111 0000')
>>> s.hex
'0xf0'
>>> s.hex = 'abcdef'
>>> s.hex
'0xabcdef'
int

Property for the signed two’s complement integer representation of the bitstring.

When used on a BitString as a setter the value must fit into the current length of the BitString, else a ValueError will be raised.

>>> s = BitString('0xf3')
>>> s.int
-13
>>> s.int = 1232
ValueError: int 1232 is too large for a BitString of length 8.
intbe

Property for the byte-wise big-endian signed two’s complement integer representation of the bitstring.

Only valid for whole-byte bitstrings, in which case it is equal to s.int, otherwise a ValueError is raised.

When used as a setter the value must fit into the current length of the BitString, else a ValueError will be raised.

intle

Property for the byte-wise little-endian signed two’s complement integer representation of the bitstring.

Only valid for whole-byte bitstring, in which case it is equal to s[::-8].int, i.e. the integer representation of the byte-reversed bitstring.

When used as a setter the value must fit into the current length of the BitString, else a ValueError will be raised.

intne

Property for the byte-wise native-endian signed two’s complement integer representation of the bitstring.

Only valid for whole-byte bitstrings, and will equal either the big-endian or the little-endian integer representation depending on the platform being used.

When used as a setter the value must fit into the current length of the BitString, else a ValueError will be raised.

float
floatbe

Property for the floating point representation of the bitstring.

The bitstring must be either 32 or 64 bits long to support the floating point interpretations, otherwise a ValueError will be raised.

If the underlying floating point methods on your machine are not IEEE 754 compliant then using the float interpretations is undefined (this is unlikely unless you’re on some very unusual hardware).

The float property is bit-wise big-endian, which as all floats must be whole-byte is exactly equivalent to the byte-wise big-endian floatbe.

floatle
Property for the byte-wise little-endian floating point representation of the bitstring.
floatne
Property for the byte-wise native-endian floating point representation of the bitstring.
len
length

Read-only property that give the length of the bitstring in bits (len and length are equivalent).

This is almost equivalent to using the len() built-in function, except that for large bitstrings len() may fail with an OverflowError, whereas the len property continues to work.

oct

Property for the octal representation of the bitstring.

When used as a getter the value will be preceded by 0o, which is optional when setting the value of a BitString. If the bitstring is not a multiple of three bits long then getting its octal value will raise a ValueError.

>>> s = BitString('0b111101101')
>>> s.oct
'0o755'
>>> s.oct = '01234567'
>>> s.oct
'0o01234567'
pos
bitpos

Read and write property for setting and getting the current bit position in the bitstring. Can be set to any value from 0 to len.

The pos and bitpos properties are exactly equivalent - you can use whichever you prefer.

if s.pos < 100:
    s.pos += 10
se

Property for the signed exponential-Golomb code representation of the bitstring.

The property is set from an signed integer, and when used as a getter an InterpretError will be raised if the bitstring is not a single code.

>>> s = BitString(se=-40)
>>> s.bin
0b0000001010001
>>> s += '0b1'
>>> s.se
Error: BitString is not a single exponential-Golomb code.
ue

Property for the unsigned exponential-Golomb code representation of the bitstring.

The property is set from an unsigned integer, and when used as a getter an InterpretError will be raised if the bitstring is not a single code.

uint

Property for the unsigned base-2 integer representation of the bitstring.

When used as a setter the value must fit into the current length of the BitString, else a ValueError will be raised.

uintbe

Property for the byte-wise big-endian unsigned base-2 integer representation of the bitstring.

When used as a setter the value must fit into the current length of the BitString, else a ValueError will be raised.

uintle

Property for the byte-wise little-endian unsigned base-2 integer representation of the bitstring.

When used as a setter the value must fit into the current length of the BitString, else a ValueError will be raised.

uintne

Property for the byte-wise native-endian unsigned base-2 integer representation of the bitstring.

When used as a setter the value must fit into the current length of the BitString, else a ValueError will be raised..

Exceptions

exception Error(Exception)

Base class for all module exceptions where built-in exception classes are not appropriate.

exception InterpretError(Error, ValueError)
exception ByteAlignError(Error)
exception CreationError(Error, ValueError)
exception ReadError(Error, IndexError)

Table Of Contents

Previous topic

Reference

Next topic

Module functions