A Python module to help you manage your bits
A Python module to help you manage your bits
by Scott Griffiths
version 3.1.7 July 20, 2021
python-logo.png scott-griffiths/bitstring
Contents
I User Manual
1
1 Walkthrough
3
1.1 A Brief Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.3 Modifying bitstrings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.4 Finding and Replacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.5 Constructing a bitstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1.6 Parsing bitstreams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2 Worked examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2.1 Hamming distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.2.2 Sieve of Eratosthenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2 Introduction
9
2.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3 Creation
11
3.1 The bitstring classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Using the constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2.1 From a hexadecimal string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2.2 From a binary string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2.3 From an octal string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2.4 From an integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2.5 Big and little-endian integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2.6 From a floating point number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2.7 Exponential-Golomb codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2.8 From raw byte data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2.9 From a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 The auto initialiser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4 Packing
17
4.1 Compact format strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5 Interpreting Bitstrings
21
5.1 bin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2 hex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.3 oct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.4 uint / uintbe / uintle / uintne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.5 int / intbe / intle / intne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.6 float / floatbe / floatle / floatne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.7 bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
i
5.8 ue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.9 se . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.10 uie / sie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6 Slicing, Dicing and Splicing
25
6.1 Slicing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.1.1 Stepping in slices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.2 Joining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.3 Truncating, inserting, deleting and overwriting . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.3.1 Deleting and truncating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.3.2 insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.3.3 overwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.4 The bitstring as a list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.5 Splitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.5.1 split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.5.2 cut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7 Reading, Parsing and Unpacking
29
7.1 Reading and parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.1.1 read / readlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.1.2 Reading using format strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.1.3 Peeking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.2 Unpacking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.3 Seeking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.4 Finding and replacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
7.4.1 find / rfind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
7.4.2 findall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
7.4.3 replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
7.5 Working with byte aligned data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8 Miscellany
35
8.1 Other Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.1.1 bytealign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.1.2 reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.1.3 tobytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.1.4 tofile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.1.5 startswith / endswith . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.1.6 ror / rol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.2 Special Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.2.1 __len__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.2.2 __str__ / __repr__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.2.3 __eq__ / __ne__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.2.4 __invert__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.2.5 __lshift__ / __rshift__ / __ilshift__ / __irshift__ . . . . . . . 37
8.2.6 __mul__ / __imul__ / __rmul__ . . . . . . . . . . . . . . . . . . . . . . . . 38
8.2.7 __copy__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
8.2.8 __and__ / __or__ / __xor__ / __iand__ / __ior__ / __ixor__ . 38
II Reference
39
9 Quick Reference
41
9.1 Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9.1.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9.1.2 Special methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.1.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.2 BitArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.2.1 Additional methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.2.2 Additional special methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
ii
9.2.3 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 9.3 ConstBitStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
9.3.1 Additional methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 9.3.2 Additional attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 9.4 BitStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
10 The bitstring module
45
10.1 The auto initialiser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
10.2 Compact format strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
10.3 Class properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
11 The Bits class
47
12 The BitArray class
57
13 The ConstBitStream class
63
14 The BitStream class
67
15 Functions
69
16 Exceptions
71
III Appendices
73
17 Examples
77
17.1 Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
17.2 Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
17.3 Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
18 Exponential-Golomb Codes
79
18.1 Interleaved exponential-Golomb codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
19 Optimisation Techniques
81
19.1 Use combined read and interpretation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
19.2 Choose the simplest class you can . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
19.3 Use dedicated functions for bit setting and checking . . . . . . . . . . . . . . . . . . . . . . . . 82
20 Release Notes
83
20.1 Full Version History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
20.1.1 May 5th 2020: version 3.1.7 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
20.1.2 Experimental LSB0 mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
20.1.3 July 9th 2019: version 3.1.6 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
20.1.4 May 17th 2016: version 3.1.5 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
20.1.5 March 19th 2016: version 3.1.4 released . . . . . . . . . . . . . . . . . . . . . . . . . . 84
20.1.6 March 4th 2014: version 3.1.3 released . . . . . . . . . . . . . . . . . . . . . . . . . . 84
20.1.7 April 18th 2013: version 3.1.2 released . . . . . . . . . . . . . . . . . . . . . . . . . . 84
20.1.8 March 21st 2013: version 3.1.1 released . . . . . . . . . . . . . . . . . . . . . . . . . . 84
20.1.9 February 26th 2013: version 3.1.0 released . . . . . . . . . . . . . . . . . . . . . . . . 84
20.1.10 November 21st 2011: version 3.0.0 released . . . . . . . . . . . . . . . . . . . . . . . . 85
20.1.11 Backwardly incompatible changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
20.1.12 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
20.1.13 June 18th 2011: version 2.2.0 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
20.1.14 February 23rd 2011: version 2.1.1 released . . . . . . . . . . . . . . . . . . . . . . . . 87
20.1.15 January 23rd 2011: version 2.1.0 released . . . . . . . . . . . . . . . . . . . . . . . . . 87
20.1.16 New class hierarchy introduced with simpler classes . . . . . . . . . . . . . . . . . . . 87
20.1.17 July 26th 2010: version 2.0.3 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
20.1.18 July 25th 2010: version 2.0.2 released . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
20.1.19 The backwardly incompatible changes are: . . . . . . . . . . . . . . . . . . . . . . . . 88
iii
20.1.20 The new features in this release are: . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 20.1.21 March 18th 2010: version 1.3.0 for Python 2.6 and 3.x released . . . . . . . . . . . . . . 93 20.1.22 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 20.1.23 January 19th 2010: version 1.2.0 for Python 2.6 and 3.x released . . . . . . . . . . . . . 94 20.1.24 New `Bits' class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 20.1.25 December 22nd 2009: version 1.1.3 for Python 2.6 and 3.x released . . . . . . . . . . . 95 20.1.26 December 18th 2009: version 1.1.2 for Python 2.6 and 3.x released . . . . . . . . . . . . 95 20.1.27 November 24th 2009: version 1.1.0 for Python 2.6 and 3.x released . . . . . . . . . . . 96 20.1.28 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 20.1.29 October 10th 2009: version 1.0.1 for Python 3.x released . . . . . . . . . . . . . . . . . 97 20.1.30 October 9th 2009: version 1.0.0 for Python 2.x released . . . . . . . . . . . . . . . . . . 97 20.1.31 API Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 20.1.32 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 20.1.33 September 11th 2009: version 0.5.2 for Python 2.x released . . . . . . . . . . . . . . . . 99 20.1.34 August 26th 2009: version 0.5.1 for Python 2.x released . . . . . . . . . . . . . . . . . 100 20.1.35 July 19th 2009: version 0.5.0 for Python 2.x released . . . . . . . . . . . . . . . . . . . 101 20.1.36 June 15th 2009: version 0.4.3 for Python 2.x released . . . . . . . . . . . . . . . . . . . 102 20.1.37 May 25th 2009: version 0.4.2 for Python 2.x released . . . . . . . . . . . . . . . . . . . 103 20.1.38 April 23rd 2009: Python 3 only version 0.4.1 released . . . . . . . . . . . . . . . . . . . 104 20.1.39 April 11th 2009: version 0.4.0 released . . . . . . . . . . . . . . . . . . . . . . . . . . 105 20.1.40 March 11th 2009: version 0.3.2 released . . . . . . . . . . . . . . . . . . . . . . . . . . 105 20.1.41 February 26th 2009: version 0.3.1 released . . . . . . . . . . . . . . . . . . . . . . . . 106 20.1.42 February 15th 2009: version 0.3.0 released . . . . . . . . . . . . . . . . . . . . . . . . 107 20.1.43 January 13th 2009: version 0.2.0 released . . . . . . . . . . . . . . . . . . . . . . . . . 108 20.1.44 December 29th 2008: version 0.1.0 released . . . . . . . . . . . . . . . . . . . . . . . . 108
Python Module Index
109
Index
111
iv
Part I
User Manual
1
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- best investment firms to manage your m
- how to manage your business
- how to manage your time
- you and your classmate are asssigned a project on which you will recieve one
- how to manage your company
- best investment firms to manage your money
- how to manage your finances
- how to manage your finance
- how to manage your money
- thank you for your help note examples
- 5 things to help you evaluate websites
- does a good websites help you to sale your product