Module pychrysalide.common
Documentation
This module provides some tiny helpers for different use cases.
The code for these features is shared between various parts of Chrysalide.
Classes
Methods
build_absolute_filename(reference, target)
Compute the absolute path for a target
file from a reference
location.
Both arguments must be strings.
The result is a string on success. A ValueError
exception is raised on failure.
build_relative_filename(reference, target)
Compute the relative path between two files: a reference
location as point of view and a target
file.
Both arguments must be strings.
The result is also a string.
decode_hex_digit(chr)
Convert a string character to an integer value.
The chr
can be a string character of length 1.
The result is an integer value on success or None
in case of failure.
encode_hex(data, lower=True)
Convert data to a hex string.
The data
has to be a string or a read-only bytes-like object. The lower
argument defines the case of the result string.
This method may be only usefull for the internal test suite as there is a native Python alternative:
b'ABC'.hex()
'414243'
fnv1a(str)
Compute the Fowler-Noll-Vo hash (version 1a) of a given string.
The result is 64-bit integer value.
itoa(n, base=10)
Construct a string representation of an integer n
according to a given base
.
Both arguments are expected to be integer values; the result is a string or None in case of failure.
pack_leb128(value, pbuf)
Pack a signed LEB128 value into a data buffer.
The value
is an integer value. The pbuf
argument has to be a PackedBuffer
instance where data will be appended.
The returned value is the operation status: True
for success, False
for failure.
pack_uleb128(value, pbuf)
Pack an unsigned LEB128 value into a data buffer.
The value
is an integer value. The pbuf
argument has to be a PackedBuffer
instance where data will be appended.
The returned value is the operation status: True
for success, False
for failure.
pearson(str, table)
Compute the Pearson hash of a given string.
The default pseudorandom permutations are used if no table
of 256 bytes is provided.
A table of permutations can be created with this call:
bytes(sample(list(range(0, 256)), k=256))
The result is 8-bit integer value.
pearson_permutations()
Provide the default pseudorandom permutations for the Pearson hash computation.
The result is 256-byte value.
unpack_leb128(pbuf)
Unpack a signed LEB128 value into a data buffer.
The pbuf
argument has to be a PackedBuffer
instance from where data will be read.
The returned value depends on the operation status: None
for failure or a integer value for success.
unpack_uleb128(pbuf)
Unpack an unsigned LEB128 value into a data buffer.
The pbuf
argument has to be a PackedBuffer
instance from where data will be read.
The returned value depends on the operation status: None
for failure or a integer value for success.
Class BitField
The BitField object describes a group of bits and provides operations on it.
Instances can be created using the following constructor:
BitField(length, state)
Where length
is the size of the bitfield and state
defines the initial state of each bits.
The object can be compared using rich methods (like <=
or !=
), provide some sequence methods (such as len()
or [n]
) and has some methods suitable for number operations (such as &
or |
).
Hierarchy
builtins.object ╰── pychrysalide.common.BitField
Methods
dup(self)
Duplicate a bitfield.
The result is a new BitField
with the same content.
or_at(self, src, first)
Perform an OR operation with another bitfield.
The src
argument is expected to be another BitField
instance. The area to process starts at bit first
from src
.
reset(self, first, count)
Switch to 0 a part of bits in a bitfield.
The area to process starts at bit first
and has a size of count
bits.
reset_all(self)
Switch to 0 all bits in a bitfield.
resize(self, length)
Resize a bitfield and fix its new size to length
.
The new bits get initialized to the same state used at the bitfield creation.
set(self, first, count)
Switch to 1 a part of bits in a bitfield.
The area to process starts at bit first
and has a size of count
bits.
set_all(self)
Switch to 1 all bits in a bitfield.
test(self, n)
Test if a given bit is set in a bitfield.
The result is a boolean value: True if the tested n
bit is set, False otherwise.
test_all(self, first, count)
Test a range of bits against 1.
The area to process starts at bit first
and has a size of count
bits.
The result is a boolean value: True if all tested bits are set, False otherwise.
test_none(self, first, count)
Test a range of bits against 0.
The area to process starts at bit first
and has a size of count
bits.
The result is a boolean value: True if all tested bits are unset, False otherwise.
test_ones_with(self, first, mask)
Test a range of bits against another bit field.
The area to process starts at bit first
and the test relies on bits set within the mask
object.
The result is a boolean value: True if all tested bits are set, False otherwise.
test_zeros_with(self, first, mask)
Test a range of bits against another bit field.
The area to process starts at bit first
and the test relies on bits set within the mask
object.
The result is a boolean value: True if all tested bits are unset, False otherwise.
Attributes
popcount
Get the number of bits set to 1 in the bitfield.
size
Provide the size of the bitfield.
Class PackedBuffer
The PackedBuffer object is mainly used as helper for the storage of GLib objects over the network or into files.
The same kind of features as the Python struct
module are provided to store and retrieve data.
Instances can be created using the following constructor:
PackedBuffer()
Hierarchy
builtins.object ╰── pychrysalide.common.PackedBuffer
Methods
advance(self, len)
Advance the reader head inside the buffer.
The len
argument defines the quantity of data to skip.
extend(self, data, ntoh=False)
Append data to a buffer.
The data must be bytes. The ntoh
parameter forces the data to be converted from the network order to the host order.
This conversion is only relevant for 2, 4 and 8 bytes quantities.
The method returns True if the operation succeeded.
extract(self, len, ntoh=False)
Extract data from a buffer.
The len
argument defines the quantity of data to retrieve and the ntoh
parameter forces the data to be converted from the network order to the host order.
This conversion is only relevant for 2, 4 and 8 bytes quantities.
The method returns data as bytes or None in case of error.
peek(self, len, ntoh=False)
Extract data from a buffer. The reader head remains untouched during the operation.
The len
argument defines the quantity of data to retrieve and the ntoh
parameter forces the data to be converted from the network order to the host order.
This conversion is only relevant for 2, 4 and 8 bytes quantities.
The method returns data as bytes or None in case of error.
rewind(self)
Rewind the reader head to the beginning of the buffer.
Attributes
more_data
Tell if the buffer has more data for further reading.
payload_length
Size of the full data carried by the buffer.