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.