Library Documentation

This page contains the Library Package documentation.

The graph_test Module

class netbench.pattern_match.bin.library.graph_test.BasicGraphTest(methodName='runTest')

Bases: unittest.TestCase

This class tests the graph algorithms implemented in the class graph

testAddEdge()
Tests adding edge into the graph
testAddVertices()
Tests if it is possoble to add and get vertices from graph
testCreateEdge()
Tests if it is possible to create edge
testCreateGraph()
Tests if it is possible to create instance of the graph
testCreateVertex()
Tests if it is possible to create one vertex
testGetEdgePosition()
Tests if it is possible to get edge position in the graph
testSetGetFunctions()
Tests if it correctly sets properties of the graph
testSetGraphDegree()
This function sets the degree of vertex in the graph
testVertexEdge()
Tests addignand getting edges from vertex
testVertexNumber()
Test if the number of veritices is returned correctly
testVertexSetGet()
Tests setting and getting properties of the Vertex
testgetEdge()
Tests if it is possibel to get edge from the graph

The b_hash Module

exception netbench.pattern_match.bin.library.b_hash.NoData(message)

Bases: exceptions.Exception

This exceptipon is called if the hash function requires data, which was not set (for example if PHF is generated without setting set of keys

class netbench.pattern_match.bin.library.b_hash.b_hash

This is a base class for implementation of the hashing function. It defines the basic interface that every hash function in the pattern_match module has to implement

generate_seed()
The function generate and set random seed for the hash function. This is only correct way how the seed should be generate.
get_seed()
The function returns seed. The format of the returned data depends on the implemented method
get_size()
The size of the computed hash can differ. This function is able to return the size of the interval to which function hashes the data. The returned interval is in the form of two tuple (lower bound, high bound)
hash(key)
This function coputes hash value for the given key.
set_seed(seed)
The function allows to set the seed for the hash function. The format is specific for every method.
set_size(bounds)
This function is used for the settings of the size of the output interval of the hash function. The bounds has to be specified as a two tuple (low bound, high bound). However not every method has to support all possible ranges. If the hash function do not support selected interval, set_size returns fail and the interval is not set.

The hash_test Module

class netbench.pattern_match.bin.library.hash_test.BasicHashTest(methodName='runTest')

Bases: unittest.TestCase

Test basic functions of the hash function implemented in netbench library

testCreateBDZ()
Creates instance of the BDZ class to ensure that constructor works correctly
testCreateHash()
Creates instance of the b_Hash class to ensure that constructor works correctly
testCreateJenkins()
Creates Jenkins hash function and test if it works
testGenSeed()
Tests if generate_seed runs in BDZ class
testJenkinsGenSeed()
Test if the seed generation works
testJenkinsHash()
Computes the hash value for the given keys and tests its corectness
testJenkinsSeed()
Test function for seting and getting seed from jenkins hash
testJenkinsSetSize()
Tests if the set size fails on the jenkins.
testSeed()
Test function for seting and getting seed from b_Hash class
testSeedBDZ()
Test function for seting and getting seed from BDZ class
testSetGetFunction()
Tests setting and getting functions of BDZ class
testSetSize()
Tests if the set size fails on the b_Hash.
testSetSizeBDZ()
Tests if the set size fails on the BDZ.
testh3hash()
Tests h3 hash class

The padnums Module

Prints out a table, padded to make it pretty.

call pprint_table with an output (e.g. sys.stdout, cStringIO, file) and table as a list of lists. Make sure table is “rectangular” – each row has the same number of columns.

MIT License

netbench.pattern_match.bin.library.padnums.format_num(num)

Format a number according to given places. Adds commas, etc.

Will truncate floats into ints!

netbench.pattern_match.bin.library.padnums.get_max_width(table, index)
Get the maximum width of the given column index
netbench.pattern_match.bin.library.padnums.pprint_table(out, table)

Prints out a table of data, padded for alignment

@param out: Output stream (“file-like object”) @param table: The table to print. A list of lists. Each row must have the same number of columns.

The bdz Module

class netbench.pattern_match.bin.library.bdz.bdz

Bases: netbench.pattern_match.bin.library.b_hash.b_hash

Class for perfect hash function generated by the BDZ algorithm. This algorithms uses uniform random hypergraph.

generate_seed()
This function generates the PHF function according to the BDZ algorithm
get_g()
This function return values of the g array. It can not be called before the generate_seed, since it is part of the seed
get_iteration_limit()
The BDZ algorithm may have fail to create PHF. The iteration_limit is used to limit the number of attempts of PHF creation
get_order()
This function return the number of uniform hash function used to create hypergraph
get_range()
This function returns the size of the biggest possible hash value. If the range is not known yet, the -1 is returned
get_ratio()
Return ratio c between keyset and the size of the memory
hash(key)
is_key_set()
This function return information, if the set of keys is prepared for the generation of the PHF
set_iteration_limit(iteration_limit)
The BDZ algorithm may have fail to create PHF. The iteration_limit is used to limit the number of attempts of PHF creation
set_keys(key_set)
This is a perfect hash function. For the construction of the PHF, the set of keys has to be known. This function gives set of keys to the function, so generate_seed can build correct function
set_limit(limit)
Sets the size of the memory bank for one hash function. This function can be used instead of the set ratio. BDZ computes three hash functions with nonoverlapping outputs. Outputs of these hash functions are used as a pointers to the memory. If user know amount of the memory, he may set the limit as 1/3 of the available memory. The ration and other parameters are computed when the key set is given. The limit value always take precedents before the ratio. To stop using limit value, limit should be set to the negative value.
set_order(number)
This function sets the number of hash function used for the creation of the hypergraph. It can not be changed after generation of the PHF
set_ratio(ratio)
sets the ration and therefore size of the data structure of the PHF

The jenkins Module

class netbench.pattern_match.bin.library.jenkins.jenkins

Bases: netbench.pattern_match.bin.library.b_hash.b_hash

This class computes jenkins hash function. The key of the function has to be implemented as a string

generate_seed()
Seed of Jenkins hash function is a integer value. This works correctly on 32 bit platforms. DO NOT use if int has not 32 bits
hash(key)
class netbench.pattern_match.bin.library.jenkins.jenkins_compress(output_size)

Bases: netbench.pattern_match.bin.library.jenkins.jenkins_wrapper

get_output_size()

Return the size of output hash value.

Returns:The size in bits of the hash value.
Return type:int
hash(key)

Compute the hash value of input data and truncate the result to the size specified by output_size.

Parameter:key (tuple(int, int)) – input data to be hashed divided into two parts.
Returns:Hash value.
Return type:int
set_output_size(output_size)

Set the size of output hash value.

Parameter:output_size (int) – The size in bits of the hash value.
class netbench.pattern_match.bin.library.jenkins.jenkins_fast

Bases: netbench.pattern_match.bin.library.jenkins.jenkins

This class defines faster variant of the jenkins hash function. The idea is that tthe key is divided into two parts by the user of the function. First part is hashed by classical jenkins hash function while the other part is just xored to the output of the jenkins hash.

hash(key)

Key should be two tuple, where the first item is the key for jenkins hash while the second part is only xored to the first part.

Parameter:key (tuple(int, int)) – input data to be hashed divided into two parts.
Returns:Hash value.
Return type:int
class netbench.pattern_match.bin.library.jenkins.jenkins_wrapper

Bases: netbench.pattern_match.bin.library.jenkins.jenkins

This class enables usage of the base jenkins class with input key divided into two parts like in class jenkins_fast.

hash(key)

Concatenate the two parts of input key and return the result of jenkins hash function. Warning: the concatenation is per byte, the results is different then concatenation of BitArrays.

Parameter:key (tuple(int, int)) – input data to be hashed divided into two parts.
Returns:Hash value.
Return type:int

The graph Module

exception netbench.pattern_match.bin.library.graph.OrderMismatch

Bases: exceptions.Exception

This exception is generated if the order of edge does is not the same as an order of the graph.

exception netbench.pattern_match.bin.library.graph.OutofRange

Bases: exceptions.Exception

This exception indicates that the edge is trying to access nonexistent vertex

class netbench.pattern_match.bin.library.graph.edge(vertices)

This class represents the edge of the graph.

get_order()
Returns the order of the edge (number of vertices corresponding to the edge)
get_vertices()
This function returns list of vertices belonging to the edge. Every vertex is represented by its number
class netbench.pattern_match.bin.library.graph.graph

This is support class for the PHF functions and others algorithms working on graphs and hypergraphs. It contains only the graph algorithms used in the netbench library. It should behave as a common interface for connecting the netbench pattern matching module to any graph library simply by rewriting these methods.

add_edge(vertices)
This function creates a new edge connecting given vertices. The vertices are given by their numbers (positions).May raise OrderMismatch and OutofRange. The function returns reference to the edge, so the user can set additional rpoperties of the created edge
add_vertices(number)
This function creates given number of verrices and adds them into the graph
get_edge(position)
Return n-th edge of the graph. It is usefull for the algorithms requiring to go through all edges of the graph. The order of edges may change by other graph operation.
get_edge_number()
This function returns the number of edges in the graph
get_edge_position(edge)
This function return position of the edge in the graph. It is error if the edge is not in the graph. Positions of edges can be changed by other graph operations.
get_order()
This function returns the order of the hypergraph. See function set_order for more information.
get_vertex(position)
This function returns vertex from graph from the given position
get_vertices_number()
This function returns number of vertices in the graph. It counts all generated vertices (also vertices without edges). Vertices are named by the number from zero to number of verices.
set_order(order)
This function is used to set if this class represent graph or hypergraph. In case of the hypergraph, the order is the number of vertices belonging to the edge. In ordinary graph, order is set to 2. Do not change the order of the graph after inserting the edges or verices into it.
class netbench.pattern_match.bin.library.graph.vertex(number)

This class is used to represent vertices of the graph

add_edge(new_edge)
Every vertex may store its own edges to accelerate some algorithms. It is user responsibility to create add these edge to the vertex.
get_degree()
Returns the number of the edges corresponding to this vertex (degree of the vertex)
get_edges()
This function returns list of edges for the given vertex
get_number()
This function return unique number of the vertex in the graph
set_degree(degree)
This function sets the degree of the vertex (the number of the edges containing this vertex)

The h3_hash Module

class netbench.pattern_match.bin.library.h3_hash.h3_hash

Bases: netbench.pattern_match.bin.library.b_hash.b_hash

Fast hash in hardware. This hash uses only XOR and AND operation

generate_seed()
This function generates the new h3 hash function
get_input_size()
This function returns the number of bit in the key.
get_size()
This function returns bitsize of the output
hash(key)
This function computes hash values for the given key according to the H3 function family. The result is returned as an integer value on 32 bits. However if the hash function generates lower number of bits, higher positions are set to 0
set_bitsize(size)
this function sets the number of bits required for output
set_input_size(size)
This function sets in number of input bits

The bitstring Module

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.

http://python-bitstring.googlecode.com

netbench.pattern_match.bin.library.bitstring.ConstBitArray
alias of Bits
class netbench.pattern_match.bin.library.bitstring.ConstBitStream(auto=None, length=None, offset=None, **kwargs)

Bases: netbench.pattern_match.bin.library.bitstring.Bits

A container or stream holding an immutable sequence of bits.

For a mutable container use the BitStream class instead.

Methods inherited from Bits:

all() – Check if all specified bits are set to 1 or 0. any() – Check if any of specified bits are set to 1 or 0. count() – Count the number of bits set to 1 or 0. cut() – Create generator of constant sized chunks. endswith() – Return whether the bitstring ends with a sub-string. find() – Find a sub-bitstring in the current bitstring. findall() – Find all occurrences of a sub-bitstring in the current bitstring. join() – Join bitstrings together using current bitstring. rfind() – Seek backwards to find a sub-bitstring. split() – Create generator of chunks split by a delimiter. startswith() – Return whether the bitstring starts with a sub-bitstring. tobytes() – Return bitstring as bytes, padding if needed. tofile() – Write bitstring to file, padding if needed. unpack() – Interpret bits using format string.

Other methods:

bytealign() – Align to next byte boundary. peek() – Peek at and interpret next bits as a single item. peeklist() – Peek at and interpret next bits as a list of items. read() – Read and interpret next bits as a single item. readlist() – Read and interpret next bits as a list of items.

Special methods:

Also available are the operators [], ==, !=, +, *, ~, <<, >>, &, |, ^.

Properties:

bin – The bitstring as a binary string. bool – For single bit bitstrings, interpret as True or False. bytepos – The current byte position in the bitstring. bytes – The bitstring as a bytes object. float – Interpret as a floating point number. floatbe – Interpret as a big-endian floating point number. floatle – Interpret as a little-endian floating point number. floatne – Interpret as a native-endian floating point number. hex – The bitstring as a hexadecimal string. int – Interpret as a two’s complement signed integer. intbe – Interpret as a big-endian signed integer. intle – Interpret as a little-endian signed integer. intne – Interpret as a native-endian signed integer. len – Length of the bitstring in bits. oct – The bitstring as an octal string. pos – The current bit position in the bitstring. se – Interpret as a signed exponential-Golomb code. ue – Interpret as an unsigned exponential-Golomb code. sie – Interpret as a signed interleaved exponential-Golomb code. uie – Interpret as an unsigned interleaved exponential-Golomb code. uint – Interpret as a two’s complement unsigned integer. uintbe – Interpret as a big-endian unsigned integer. uintle – Interpret as a little-endian unsigned integer. uintne – Interpret as a native-endian unsigned integer.

bitpos
The position in the bitstring in bits. Read and write.
bytealign()

Align to next byte and return number of skipped bits.

Raises ValueError if the end of the bitstring is reached before aligning to the next byte.

bytepos
The position in the bitstring in bytes. Read and write.
find(bs, start=None, end=None, bytealigned=None)

Find first occurrence of substring bs.

Returns a single item tuple with the bit position if found, or an empty tuple if not found. The bit position (pos property) will also be set to the start of the substring if it is found.

bs – The bitstring to find. start – The bit position to start the search. Defaults to 0. end – The bit position one past the last bit to search.

Defaults to self.len.
bytealigned – If True the bitstring will only be
found on byte boundaries.

Raises ValueError if bs is empty, if start < 0, if end > self.len or if end < start.

>>> BitArray('0xc3e').find('0b1111')
(6,)
peek(fmt)

Interpret next bits according to format string and return result.

fmt – Token string describing how to interpret the next bits.

The position in the bitstring is not changed. If not enough bits are available then all bits to the end of the bitstring will be used.

Raises ReadError if not enough bits are available. Raises ValueError if the format is not understood.

See the docstring for ‘read’ for token examples.

peeklist(fmt, **kwargs)

Interpret next bits according to format string(s) and return list.

fmt – One or more strings with comma separated tokens describing
how to interpret the next bits in the bitstring.
kwargs – A dictionary or keyword-value pairs - the keywords used in the
format string will be replaced with their given value.

The position in the bitstring is not changed. If not enough bits are available then all bits to the end of the bitstring will be used.

Raises ReadError if not enough bits are available. Raises ValueError if the format is not understood.

See the docstring for ‘read’ for token examples.

pos
The position in the bitstring in bits. Read and write.
read(fmt)

Interpret next bits according to the format string and return result.

fmt – Token string describing how to interpret the next bits.

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’ : next bits as unsigned exp-Golomb code ‘se’ : next bits as signed exp-Golomb code ‘uie’ : next bits as unsigned interleaved exp-Golomb code ‘sie’ : next bits as signed interleaved exp-Golomb code ‘bits:5’ : 5 bits as a bitstring ‘bytes:10’ : 10 bytes as a bytes object ‘bool’ : 1 bit as a bool

fmt may also be an integer, which will be treated like the ‘bits’ token.

The position in the bitstring is advanced to after the read items.

Raises ReadError if not enough bits are available. Raises ValueError if the format is not understood.

readlist(fmt, **kwargs)

Interpret next bits according to format string(s) and return list.

fmt – A single string or list of strings with comma separated tokens
describing how to interpret the next bits in the bitstring. Items can also be integers, for reading new bitstring of the given length.
kwargs – A dictionary or keyword-value pairs - the keywords used in the
format string will be replaced with their given value.

The position in the bitstring is advanced to after the read items.

Raises ReadError is not enough bits are available. Raises ValueError if the format is not understood.

See the docstring for ‘read’ for token examples.

>>> h, b1, b2 = s.readlist('hex:20, bin:5, bin:3')
>>> i, bs1, bs2 = s.readlist(['uint:12', 10, 10])
readto(bs, bytealigned=None)

Read up to and including next occurrence of bs and return result.

bs – The bitstring to find. An integer is not permitted. bytealigned – If True the bitstring will only be

found on byte boundaries.

Raises ValueError if bs is empty. Raises ReadError if bs is not found.

rfind(bs, start=None, end=None, bytealigned=None)

Find final occurrence of substring bs.

Returns a single item tuple with the bit position if found, or an empty tuple if not found. The bit position (pos property) will also be set to the start of the substring if it is found.

bs – The bitstring to find. start – The bit position to end the reverse search. Defaults to 0. end – The bit position one past the first bit to reverse search.

Defaults to self.len.
bytealigned – If True the bitstring will only be found on byte
boundaries.

Raises ValueError if bs is empty, if start < 0, if end > self.len or if end < start.

class netbench.pattern_match.bin.library.bitstring.BitStream(auto=None, length=None, offset=None, **kwargs)

Bases: netbench.pattern_match.bin.library.bitstring.ConstBitStream, netbench.pattern_match.bin.library.bitstring.BitArray

A container or stream holding a mutable sequence of bits

Subclass of the ConstBitStream and BitArray classes. Inherits all of their methods.

Methods:

all() – Check if all specified bits are set to 1 or 0. any() – Check if any of specified bits are set to 1 or 0. append() – Append a bitstring. bytealign() – Align to next byte boundary. byteswap() – Change byte endianness in-place. count() – Count the number of bits set to 1 or 0. cut() – Create generator of constant sized chunks. endswith() – Return whether the bitstring ends with a sub-string. find() – Find a sub-bitstring in the current bitstring. findall() – Find all occurrences of a sub-bitstring in the current bitstring. insert() – Insert a bitstring. invert() – Flip bit(s) between one and zero. join() – Join bitstrings together using current bitstring. overwrite() – Overwrite a section with a new bitstring. peek() – Peek at and interpret next bits as a single item. peeklist() – Peek at and interpret next bits as a list of items. prepend() – Prepend a bitstring. read() – Read and interpret next bits as a single item. readlist() – Read and interpret next bits as a list of items. replace() – Replace occurrences of one bitstring with another. reverse() – Reverse bits in-place. rfind() – Seek backwards to find a sub-bitstring. rol() – Rotate bits to the left. ror() – Rotate bits to the right. set() – Set bit(s) to 1 or 0. split() – Create generator of chunks split by a delimiter. startswith() – Return whether the bitstring starts with a sub-bitstring. tobytes() – Return bitstring as bytes, padding if needed. tofile() – Write bitstring to file, padding if needed. unpack() – Interpret bits using format string.

Special methods:

Mutating operators are available: [], <<=, >>=, +=, *=, &=, |= and ^= in addition to [], ==, !=, +, *, ~, <<, >>, &, | and ^.

Properties:

bin – The bitstring as a binary string. bool – For single bit bitstrings, interpret as True or False. bytepos – The current byte position in the bitstring. bytes – The bitstring as a bytes object. float – Interpret as a floating point number. floatbe – Interpret as a big-endian floating point number. floatle – Interpret as a little-endian floating point number. floatne – Interpret as a native-endian floating point number. hex – The bitstring as a hexadecimal string. int – Interpret as a two’s complement signed integer. intbe – Interpret as a big-endian signed integer. intle – Interpret as a little-endian signed integer. intne – Interpret as a native-endian signed integer. len – Length of the bitstring in bits. oct – The bitstring as an octal string. pos – The current bit position in the bitstring. se – Interpret as a signed exponential-Golomb code. ue – Interpret as an unsigned exponential-Golomb code. sie – Interpret as a signed interleaved exponential-Golomb code. uie – Interpret as an unsigned interleaved exponential-Golomb code. uint – Interpret as a two’s complement unsigned integer. uintbe – Interpret as a big-endian unsigned integer. uintle – Interpret as a little-endian unsigned integer. uintne – Interpret as a native-endian unsigned integer.

prepend(bs)

Prepend a bitstring to the current bitstring.

bs – The bitstring to prepend.

class netbench.pattern_match.bin.library.bitstring.BitArray(auto=None, length=None, offset=None, **kwargs)

Bases: netbench.pattern_match.bin.library.bitstring.Bits

A container holding a mutable sequence of bits.

Subclass of the immutable Bits class. Inherits all of its methods (except __hash__) and adds mutating methods.

Mutating methods:

append() – Append a bitstring. byteswap() – Change byte endianness in-place. insert() – Insert a bitstring. invert() – Flip bit(s) between one and zero. overwrite() – Overwrite a section with a new bitstring. prepend() – Prepend a bitstring. replace() – Replace occurrences of one bitstring with another. reverse() – Reverse bits in-place. rol() – Rotate bits to the left. ror() – Rotate bits to the right. set() – Set bit(s) to 1 or 0.

Methods inherited from Bits:

all() – Check if all specified bits are set to 1 or 0. any() – Check if any of specified bits are set to 1 or 0. count() – Count the number of bits set to 1 or 0. cut() – Create generator of constant sized chunks. endswith() – Return whether the bitstring ends with a sub-string. find() – Find a sub-bitstring in the current bitstring. findall() – Find all occurrences of a sub-bitstring in the current bitstring. join() – Join bitstrings together using current bitstring. rfind() – Seek backwards to find a sub-bitstring. split() – Create generator of chunks split by a delimiter. startswith() – Return whether the bitstring starts with a sub-bitstring. tobytes() – Return bitstring as bytes, padding if needed. tofile() – Write bitstring to file, padding if needed. unpack() – Interpret bits using format string.

Special methods:

Mutating operators are available: [], <<=, >>=, +=, *=, &=, |= and ^= in addition to the inherited [], ==, !=, +, *, ~, <<, >>, &, | and ^.

Properties:

bin – The bitstring as a binary string. bool – For single bit bitstrings, interpret as True or False. bytepos – The current byte position in the bitstring. bytes – The bitstring as a bytes object. float – Interpret as a floating point number. floatbe – Interpret as a big-endian floating point number. floatle – Interpret as a little-endian floating point number. floatne – Interpret as a native-endian floating point number. hex – The bitstring as a hexadecimal string. int – Interpret as a two’s complement signed integer. intbe – Interpret as a big-endian signed integer. intle – Interpret as a little-endian signed integer. intne – Interpret as a native-endian signed integer. len – Length of the bitstring in bits. oct – The bitstring as an octal string. pos – The current bit position in the bitstring. se – Interpret as a signed exponential-Golomb code. ue – Interpret as an unsigned exponential-Golomb code. sie – Interpret as a signed interleaved exponential-Golomb code. uie – Interpret as an unsigned interleaved exponential-Golomb code. uint – Interpret as a two’s complement unsigned integer. uintbe – Interpret as a big-endian unsigned integer. uintle – Interpret as a little-endian unsigned integer. uintne – Interpret as a native-endian unsigned integer.

append(bs)

Append a bitstring to the current bitstring.

bs – The bitstring to append.

bin
The bitstring as a binary string. Read and write.
bool
The bitstring as a bool (True or False). Read and write.
bytes
The bitstring as a ordinary string. Read and write.
byteswap(fmt=None, start=None, end=None, repeat=True)

Change the endianness in-place. Return number of repeats of fmt done.

fmt – A compact structure string, an integer number of bytes or
an iterable of integers. Defaults to 0, which byte reverses the whole bitstring.

start – Start bit position, defaults to 0. end – End bit position, defaults to self.len. repeat – If True (the default) the byte swapping pattern is repeated

as much as possible.
float
The bitstring as a floating point number. Read and write.
floatbe
The bitstring as a big-endian floating point number. Read and write.
floatle
The bitstring as a little-endian floating point number. Read and write.
floatne
The bitstring as a native-endian floating point number. Read and write.
hex
The bitstring as a hexadecimal string. Read and write.
insert(bs, pos=None)

Insert bs at bit position pos.

bs – The bitstring to insert. pos – The bit position to insert at.

Raises ValueError if pos < 0 or pos > self.len.

int
The bitstring as a two’s complement signed int. Read and write.
intbe
The bitstring as a two’s complement big-endian signed int. Read and write.
intle
The bitstring as a two’s complement little-endian signed int. Read and write.
intne
The bitstring as a two’s complement native-endian signed int. Read and write.
invert(pos=None)

Invert one or many bits from 0 to 1 or vice versa.

pos – Either a single bit position or an iterable of bit positions.
Negative numbers are treated in the same way as slice indices.

Raises IndexError if pos < -self.len or pos >= self.len.

oct
The bitstring as an octal string. Read and write.
overwrite(bs, pos=None)

Overwrite with bs at bit position pos.

bs – The bitstring to overwrite with. pos – The bit position to begin overwriting from.

Raises ValueError if pos < 0 or pos + bs.len > self.len

prepend(bs)

Prepend a bitstring to the current bitstring.

bs – The bitstring to prepend.

replace(old, new, start=None, end=None, count=None, bytealigned=None)

Replace all occurrences of old with new in place.

Returns number of replacements made.

old – The bitstring to replace. new – The replacement bitstring. start – Any occurrences that start before this will not be replaced.

Defaults to 0.
end – Any occurrences that finish after this will not be replaced.
Defaults to self.len.
count – The maximum number of replacements to make. Defaults to
replace all occurrences.
bytealigned – If True replacements will only be made on byte
boundaries.

Raises ValueError if old is empty or if start or end are out of range.

reverse(start=None, end=None)

Reverse bits in-place.

start – Position of first bit to reverse. Defaults to 0. end – One past the position of the last bit to reverse.

Defaults to self.len.

Using on an empty bitstring will have no effect.

Raises ValueError if start < 0, end > self.len or end < start.

rol(bits, start=None, end=None)

Rotate bits to the left in-place.

bits – The number of bits to rotate by. start – Start of slice to rotate. Defaults to 0. end – End of slice to rotate. Defaults to self.len.

Raises ValueError if bits < 0.

ror(bits, start=None, end=None)

Rotate bits to the right in-place.

bits – The number of bits to rotate by. start – Start of slice to rotate. Defaults to 0. end – End of slice to rotate. Defaults to self.len.

Raises ValueError if bits < 0.

se
The bitstring as a signed exponential-Golomb code. Read and write.
set(value, pos=None)

Set one or many bits to 1 or 0.

value – If True bits are set to 1, otherwise they are set to 0. pos – Either a single bit position or an iterable of bit positions.

Negative numbers are treated in the same way as slice indices. Defaults to the entire bitstring.

Raises IndexError if pos < -self.len or pos >= self.len.

sie
The bitstring as a signed interleaved exponential-Golomb code. Read and write.
ue
The bitstring as an unsigned exponential-Golomb code. Read and write.
uie
The bitstring as an unsigned interleaved exponential-Golomb code. Read and write.
uint
The bitstring as a two’s complement unsigned int. Read and write.
uintbe
The bitstring as a two’s complement big-endian unsigned int. Read and write.
uintle
The bitstring as a two’s complement little-endian unsigned int. Read and write.
uintne
The bitstring as a two’s complement native-endian unsigned int. Read and write.
class netbench.pattern_match.bin.library.bitstring.Bits(auto=None, length=None, offset=None, **kwargs)

Bases: object

A container holding an immutable sequence of bits.

For a mutable container use the BitArray class instead.

Methods:

all() – Check if all specified bits are set to 1 or 0. any() – Check if any of specified bits are set to 1 or 0. count() – Count the number of bits set to 1 or 0. cut() – Create generator of constant sized chunks. endswith() – Return whether the bitstring ends with a sub-string. find() – Find a sub-bitstring in the current bitstring. findall() – Find all occurrences of a sub-bitstring in the current bitstring. join() – Join bitstrings together using current bitstring. rfind() – Seek backwards to find a sub-bitstring. split() – Create generator of chunks split by a delimiter. startswith() – Return whether the bitstring starts with a sub-bitstring. tobytes() – Return bitstring as bytes, padding if needed. tofile() – Write bitstring to file, padding if needed. unpack() – Interpret bits using format string.

Special methods:

Also available are the operators [], ==, !=, +, *, ~, <<, >>, &, |, ^.

Properties:

bin – The bitstring as a binary string. bool – For single bit bitstrings, interpret as True or False. bytes – The bitstring as a bytes object. float – Interpret as a floating point number. floatbe – Interpret as a big-endian floating point number. floatle – Interpret as a little-endian floating point number. floatne – Interpret as a native-endian floating point number. hex – The bitstring as a hexadecimal string. int – Interpret as a two’s complement signed integer. intbe – Interpret as a big-endian signed integer. intle – Interpret as a little-endian signed integer. intne – Interpret as a native-endian signed integer. len – Length of the bitstring in bits. oct – The bitstring as an octal string. se – Interpret as a signed exponential-Golomb code. ue – Interpret as an unsigned exponential-Golomb code. sie – Interpret as a signed interleaved exponential-Golomb code. uie – Interpret as an unsigned interleaved exponential-Golomb code. uint – Interpret as a two’s complement unsigned integer. uintbe – Interpret as a big-endian unsigned integer. uintle – Interpret as a little-endian unsigned integer. uintne – Interpret as a native-endian unsigned integer.

all(value, pos=None)

Return True if one or many bits are all set to value.

value – If value is True then checks for bits set to 1, otherwise
checks for bits set to 0.
pos – An iterable of bit positions. Negative numbers are treated in
the same way as slice indices. Defaults to the whole bitstring.
any(value, pos=None)

Return True if any of one or many bits are set to value.

value – If value is True then checks for bits set to 1, otherwise
checks for bits set to 0.
pos – An iterable of bit positions. Negative numbers are treated in
the same way as slice indices. Defaults to the whole bitstring.
bin
The bitstring as a binary string. Read only.
bool
The bitstring as a bool (True or False). Read only.
bytes
The bitstring as a bytes object. Read only.
count(value)

Return count of total number of either zero or one bits.

value – If True then bits set to 1 are counted, otherwise bits set
to 0 are counted.
>>> Bits('0xef').count(1)
7
cut(bits, start=None, end=None, count=None)

Return bitstring generator by cutting into bits sized chunks.

bits – The size in bits of the bitstring chunks to generate. start – The bit position to start the first cut. Defaults to 0. end – The bit position one past the last bit to use in the cut.

Defaults to self.len.
count – If specified then at most count items are generated.
Default is to cut as many times as possible.
endswith(suffix, start=None, end=None)

Return whether the current bitstring ends with suffix.

suffix – The bitstring to search for. start – The bit position to start from. Defaults to 0. end – The bit position to end at. Defaults to self.len.

find(bs, start=None, end=None, bytealigned=None)

Find first occurrence of substring bs.

Returns a single item tuple with the bit position if found, or an empty tuple if not found. The bit position (pos property) will also be set to the start of the substring if it is found.

bs – The bitstring to find. start – The bit position to start the search. Defaults to 0. end – The bit position one past the last bit to search.

Defaults to self.len.
bytealigned – If True the bitstring will only be
found on byte boundaries.

Raises ValueError if bs is empty, if start < 0, if end > self.len or if end < start.

>>> BitArray('0xc3e').find('0b1111')
(6,)
findall(bs, start=None, end=None, count=None, bytealigned=None)

Find all occurrences of bs. Return generator of bit positions.

bs – The bitstring to find. start – The bit position to start the search. Defaults to 0. end – The bit position one past the last bit to search.

Defaults to self.len.

count – The maximum number of occurrences to find. bytealigned – If True the bitstring will only be found on

byte boundaries.

Raises ValueError if bs is empty, if start < 0, if end > self.len or if end < start.

Note that all occurrences of bs are found, even if they overlap.

float
The bitstring as a floating point number. Read only.
floatbe
The bitstring as a big-endian floating point number. Read only.
floatle
The bitstring as a little-endian floating point number. Read only.
floatne
The bitstring as a native-endian floating point number. Read only.
hex
The bitstring as a hexadecimal string. Read only.
int
The bitstring as a two’s complement signed int. Read only.
intbe
The bitstring as a two’s complement big-endian signed int. Read only.
intle
The bitstring as a two’s complement little-endian signed int. Read only.
intne
The bitstring as a two’s complement native-endian signed int. Read only.
join(sequence)

Return concatenation of bitstrings joined by self.

sequence – A sequence of bitstrings.

len
The length of the bitstring in bits. Read only.
length
The length of the bitstring in bits. Read only.
oct
The bitstring as an octal string. Read only.
rfind(bs, start=None, end=None, bytealigned=None)

Find final occurrence of substring bs.

Returns a single item tuple with the bit position if found, or an empty tuple if not found. The bit position (pos property) will also be set to the start of the substring if it is found.

bs – The bitstring to find. start – The bit position to end the reverse search. Defaults to 0. end – The bit position one past the first bit to reverse search.

Defaults to self.len.
bytealigned – If True the bitstring will only be found on byte
boundaries.

Raises ValueError if bs is empty, if start < 0, if end > self.len or if end < start.

se
The bitstring as a signed exponential-Golomb code. Read only.
sie
The bitstring as a signed interleaved exponential-Golomb code. Read only.
split(delimiter, start=None, end=None, count=None, bytealigned=None)

Return bitstring generator by splittling using a delimiter.

The first item returned is the initial bitstring before the delimiter, which may be an empty bitstring.

delimiter – The bitstring used as the divider. start – The bit position to start the split. Defaults to 0. end – The bit position one past the last bit to use in the split.

Defaults to self.len.
count – If specified then at most count items are generated.
Default is to split as many times as possible.

bytealigned – If True splits will only occur on byte boundaries.

Raises ValueError if the delimiter is empty.

startswith(prefix, start=None, end=None)

Return whether the current bitstring starts with prefix.

prefix – The bitstring to search for. start – The bit position to start from. Defaults to 0. end – The bit position to end at. Defaults to self.len.

tobytes()

Return the bitstring as bytes, padding with zero bits if needed.

Up to seven zero bits will be added at the end to byte align.

tofile(f)

Write the bitstring to a file object, padding with zero bits if needed.

Up to seven zero bits will be added at the end to byte align.

ue
The bitstring as an unsigned exponential-Golomb code. Read only.
uie
The bitstring as an unsigned interleaved exponential-Golomb code. Read only.
uint
The bitstring as a two’s complement unsigned int. Read only.
uintbe
The bitstring as a two’s complement big-endian unsigned int. Read only.
uintle
The bitstring as a two’s complement little-endian unsigned int. Read only.
uintne
The bitstring as a two’s complement native-endian unsigned int. Read only.
unpack(fmt, **kwargs)

Interpret the whole bitstring using fmt and return list.

fmt – A single string or a list of strings with comma separated tokens
describing how to interpret the bits in the bitstring. Items can also be integers, for reading new bitstring of the given length.
kwargs – A dictionary or keyword-value pairs - the keywords used in the
format string will be replaced with their given value.

Raises ValueError if the format is not understood. If not enough bits are available then all bits to the end of the bitstring will be used.

See the docstring for ‘read’ for token examples.

netbench.pattern_match.bin.library.bitstring.BitString
alias of BitStream
netbench.pattern_match.bin.library.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
>>> 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)
exception netbench.pattern_match.bin.library.bitstring.Error(*params)

Bases: exceptions.Exception

Base class for errors in the bitstring module.

exception netbench.pattern_match.bin.library.bitstring.ReadError(*params)

Bases: netbench.pattern_match.bin.library.bitstring.Error, exceptions.IndexError

Reading or peeking past the end of a bitstring.

exception netbench.pattern_match.bin.library.bitstring.InterpretError(*params)

Bases: netbench.pattern_match.bin.library.bitstring.Error, exceptions.ValueError

Inappropriate interpretation of binary data.

exception netbench.pattern_match.bin.library.bitstring.ByteAlignError(*params)

Bases: netbench.pattern_match.bin.library.bitstring.Error

Whole-byte position or length needed.

exception netbench.pattern_match.bin.library.bitstring.CreationError(*params)

Bases: netbench.pattern_match.bin.library.bitstring.Error, exceptions.ValueError

Inappropriate argument during bitstring creation.

netbench.pattern_match.bin.library.bitstring.bytealigned
Determines whether a number of methods default to working only on byte boundaries.