README.rst
1
2
3.. image:: /doc/bitstring_logo_small.png
4
5**bitstring** is a pure Python module designed to help make
6the creation and analysis of binary data as simple and natural as possible.
7
8Bitstrings can be constructed from integers (big and little endian), hex,
9octal, binary, strings or files. They can be sliced, joined, reversed,
10inserted into, overwritten, etc. with simple functions or slice notation.
11They can also be read from, searched and replaced, and navigated in,
12similar to a file or stream.
13
14bitstring is open source software, and has been released under the MIT
15licence.
16
17This module works in both Python 2.7 and Python 3.6+.
18
19Installation
20------------
21
22Probably all you need to do is::
23
24 pip install bitstring
25
26
27Documentation
28-------------
29The manual for the bitstring module is available here
30<https://bitstring.readthedocs.org>. It contains a walk-through of all
31the features and a complete reference section.
32
33It is also available as a PDF at <https://readthedocs.org/projects/bitstring/downloads/pdf/latest/>.
34
35
36Simple Examples
37---------------
38Creation::
39
40 >>> a = BitArray(bin='00101')
41 >>> b = Bits(a_file_object)
42 >>> c = BitArray('0xff, 0b101, 0o65, uint:6=22')
43 >>> d = pack('intle:16, hex=a, 0b1', 100, a='0x34f')
44 >>> e = pack('<16h', *range(16))
45
46Different interpretations, slicing and concatenation::
47
48 >>> a = BitArray('0x1af')
49 >>> a.hex, a.bin, a.uint
50 ('1af', '000110101111', 431)
51 >>> a[10:3:-1].bin
52 '1110101'
53 >>> '0b100' + 3*a
54 BitArray('0x835e35e35, 0b111')
55
56Reading data sequentially::
57
58 >>> b = BitStream('0x160120f')
59 >>> b.read(12).hex
60 '160'
61 >>> b.pos = 0
62 >>> b.read('uint:12')
63 352
64 >>> b.readlist('uint:12, bin:3')
65 [288, '111']
66
67Searching, inserting and deleting::
68
69 >>> c = BitArray('0b00010010010010001111') # c.hex == '0x1248f'
70 >>> c.find('0x48')
71 (8,)
72 >>> c.replace('0b001', '0xabc')
73 >>> c.insert('0b0000', pos=3)
74 >>> del c[12:16]
75
76Unit Tests
77----------
78
79The 500+ unit tests should all pass for Python 2.7 and later. To run them, from the `test`
80directory run::
81
82 python -m unittest discover
83
84----
85
86The bitstring module has been released as open source under the MIT License.
87Copyright (c) 2006 Scott Griffiths
88
89For more information see the project's homepage on GitHub:
90<https://github.com/scott-griffiths/bitstring>
91
92
