Table Of Contents

1. Introduction

1.1. Download

BitPacket is maintained in Savannah (and mirrored in github and gitorious). Savannah is the central point for development, maintenance and distribution of official GNU software (and other non-GNU software, like BitPacket).

You can download the latest BitPacket release from the project’s website, or alternatively, you can also clone the source repository.

git clone git://

Or, if you are behind a firewall, you might use the HTTP version:

git clone

1.2. Build and install

BitPacket is distributed as a Distribute (setuptools) module, so the usual commands for building and installing setuptools modules can be used. However, this means that you need setuptools installed in your system.

Once the BitPacket tarball is decompressed, you can build BitPacket as a non-root user:

python build

If the built is successful, you can then install it, as root, with the following command:

python install

1.3. Usage

Using BitPacket in your application is straightforward. You only need to add the following import in your Python scripts:

from BitPacket import *

1.4. History

The first version of BitPacket was released in 2007.

The validation guys from the project I was working on were building a test environment to validate a software which involved a lot of network packet management. They started by accessing packet fields with indexes. This was very error prone, hard to maintain, hard to read and hard to understand. So, I start digging through the web for something that could help us, but I only found the struct module. However, it does not solve the indexing problem neither it supports bit fields.

Then, I found the BitVector class which was able to work with bits given a byte array, and I built BitPacket in top of it. Initially, BitPacket consisted on three classes: BitField (for single bit fields), BitStructure (a BitField itself, to build packets as a sequence BitFields) and BitVariableStructure (something like a meta BitStructure).

At the end of 2009, a refactoring of the test environment was necessary, and I knew BitPacket was very slow and hard to extend. Between 2007 and 2009, I discovered a great Python library for building and parsing packets, construct. construct is great and performs its jobs very well. It is a very complete and powerful library for working with packets in a declarative way. The problem was that we had a lot of code that need to be reused written with BitPacket, so construct was not an option.

Finally, I decided I needed to refactor BitPacket, while learning more in the path, and create a small library, much simpler than struct and much more powerful and fast than the old BitPacket. This is how BitPacket 1.0.0 was born.